Skip to content

Commit 0182cda

Browse files
author
Test User
committed
Merge remote-tracking branch 'gitea/task/docs-stale-spec-annotations-2026-06-25'
2 parents 52b869e + d39642e commit 0182cda

7 files changed

Lines changed: 85 additions & 16 deletions

File tree

‎crates/terraphim_merge_coordinator/src/evaluator.rs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
//! PR evaluation + merge-and-close orchestration (#1805).
22
//!
3-
//! Sequential per spec Concurrency-2. Partial failure handling
4-
//! (merge ok, close fail -> CRITICAL) per Failure-1. Remediation
5-
//! atomicity per Failure-2.
3+
//! PRs are evaluated strictly sequentially within a run (no concurrency).
4+
//! Partial failure is surfaced as CRITICAL: a merge that succeeds but whose
5+
//! follow-up close call fails is not silently retried. Remediation
6+
//! (comment + exit) is applied atomically per PR.
67
78
use tracing::{error, info, warn};
89

‎crates/terraphim_merge_coordinator/src/gitea.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
//! Thin Gitea API wrapper for merge-coordinator.
22
//!
33
//! Reuses workspace `reqwest` instead of pulling in terraphim_tracker
4-
//! to keep the binary small. Provides retry/backoff per spec Failure-3
5-
//! (1 s / 2 s / 4 s) and never logs the token (Security-2).
4+
//! to keep the binary small. Provides retry/backoff (1 s / 2 s / 4 s)
5+
//! and never logs the token.
66
77
use std::time::Duration;
88

‎crates/terraphim_merge_coordinator/src/lib.rs‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
1-
//! Merge coordinator -- minimal skeleton (#1805).
1+
//! Merge coordinator library (#1805).
22
//!
3-
//! Full spec at .docs/spec-merge-coordinator.md will be implemented in
4-
//! follow-up commits. This skeleton proves the crate scaffolds correctly.
3+
//! Evaluates open PRs for auto-merge readiness, merges mergeable PRs, and
4+
//! auto-closes issues referenced via `Fixes #N`. Core logic lives in the
5+
//! [`evaluator`] module; shared types in [`types`].
56
67
pub mod evaluator;
78
pub mod gitea;

‎crates/terraphim_merge_coordinator/src/main.rs‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
//!
33
//! Cron-invoked. Reads env GITEA_URL + GITEA_TOKEN, evaluates open
44
//! PRs in OWNER/REPO (default terraphim/terraphim-ai), merges
5-
//! mergeable ones, auto-closes Fixes #N. Exit codes per
6-
//! Operational-1: 0 success, 1 evaluation failures, 2 critical.
5+
//! mergeable ones, auto-closes Fixes #N. Exit codes: 0 success,
6+
//! 1 evaluation failures, 2 critical.
77
88
use std::path::PathBuf;
99
use std::process;

‎crates/terraphim_merge_coordinator/src/pid_lock.rs‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
//! File-based PID lock for merge-coordinator (Concurrency-1 per spec).
1+
//! File-based PID lock for merge-coordinator.
22
//!
33
//! Prevents concurrent invocations from racing on Gitea API calls.
44
//! Lock file lives at /tmp/merge-coordinator.lock; if another process

‎crates/terraphim_merge_coordinator/src/types.rs‎

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,5 @@
1-
//! Core types for merge-coordinator (#1805).
2-
//!
3-
//! Mirrors the spec at .docs/spec-merge-coordinator.md. Lib code in
4-
//! follow-up commits will use these types in evaluate_all and
5-
//! merge_and_close.
1+
//! Merge-coordinator shared types (#1805): exit codes, evaluation
2+
//! verdicts, error variants, and merge outcomes.
63
74
use std::fmt;
85

‎reports/spec-stale-annotations-20260625-180451.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# Stale Spec-Annotation Sweep — 2026-06-25
2+
3+
**Agent:** documentation-generator (Ferrox, Rust Engineer)
4+
**Scope:** in-code doc comments referencing spec documents / spec decisions
5+
**Trigger:** `please action the stale-spec annotations`
6+
7+
---
8+
9+
## Method
10+
11+
Grepped all `.rs` for spec-reference patterns (`Per spec`, `spec at .docs/`,
12+
`per spec <Tag>-N`, `Mirrors the spec`, `[SPEC]`). For each hit, verified
13+
whether the referenced artefact (spec file / cross-repo plan / Gitea issue)
14+
actually exists and whether the surrounding code matches the described
15+
behaviour.
16+
17+
## Findings
18+
19+
### Stale — ACTIONED (1 cluster, 6 files)
20+
21+
**`crates/terraphim_merge_coordinator/`** — every module header referenced
22+
`.docs/spec-merge-coordinator.md`, a file that has **never existed in git
23+
history** (absent on `origin/main` too — a dangling pointer since the crate's
24+
inception, #1805). Headers also called the crate a "minimal skeleton" with
25+
logic "will be implemented in follow-up commits", but the crate is fully
26+
implemented (24 tests across 6 modules, real `evaluate_all` / `merge_and_close`
27+
/ PID-lock / retrying Gitea client).
28+
29+
| File | Old stale fragment | Fix |
30+
|------|-------------------|-----|
31+
| `src/lib.rs` | "minimal skeleton … Full spec at .docs/spec-merge-coordinator.md will be implemented in follow-up commits" | Rewritten as accurate library overview |
32+
| `src/types.rs` | "Mirrors the spec at .docs/spec-merge-coordinator.md. Lib code in follow-up commits will use these types" | Rewritten; "spec" pointer dropped |
33+
| `src/evaluator.rs` | "Sequential per spec Concurrency-2 … per Failure-1 … per Failure-2" | Behavioural facts retained, dangling tag refs dropped |
34+
| `src/pid_lock.rs` | "File-based PID lock … (Concurrency-1 per spec)" | Tag dropped; behavioural doc kept |
35+
| `src/gitea.rs` | "retry/backoff per spec Failure-3 … never logs the token (Security-2)" | Tag dropped; facts kept |
36+
| `src/main.rs` | "Exit codes per Operational-1" | Rewritten as plain list |
37+
38+
### Not stale — LEFT UNTOUCHED (surgical protocol)
39+
40+
- `crates/terraphim_rlm/src/executor/trait.rs:111` — `Per spec: "Ignore
41+
external state drift on restore"` is a self-contained inline quote of the
42+
behaviour, not a file pointer. Accurate. Left as-is.
43+
- `crates/terraphim_orchestrator/src/pr_dispatch.rs`, `pr_poller.rs`,
44+
`tests/auto_merge_execution_tests.rs` — reference
45+
`cto-executive-system/plans/adf-rate-of-change-design.md` §Step N plus real
46+
Gitea issues (`adf-fleet#32`, `#34`). These are **cross-repo** pointers to a
47+
separate design repo, not workspace-internal dangling refs. Accurate. Left.
48+
- `pr-spec-validator` identifiers in `lib_tests.rs` — those are agent / status
49+
names, not spec annotations. Left.
50+
51+
## Verification
52+
53+
```
54+
cargo fmt -p terraphim_merge_coordinator -- --check # clean
55+
cargo build -p terraphim_merge_coordinator # exit 0
56+
cargo clippy -p terraphim_merge_coordinator --tests # exit 0
57+
cargo test -p terraphim_merge_coordinator # 24 passed, 0 failed
58+
RUSTDOCFLAGS="-D warnings" cargo doc -p terraphim_merge_coordinator --no-deps # exit 0
59+
```
60+
61+
No remaining `spec-merge-coordinator` / `minimal skeleton` / `will be
62+
implemented in follow-up` references in the crate.
63+
64+
## Conclusion
65+
66+
6 stale annotations resolved across 1 crate. Zero regressions. The crate's
67+
headers now describe actual behaviour rather than a non-existent spec and a
68+
skeleton state that no longer applies.
69+
70+
Theme-ID: doc-gap

0 commit comments

Comments
 (0)