Repair stale source-comment documentation references #964

New issue

Closed

opened 2026-07-10 07:22:41 +00:00 by coilyco-ops · 3 comments

coilyco-ops commented

2026-07-10 07:22:41 +00:00

Member

AOS now ships source-doc-refs, a pre-commit hook that validates path-like documentation references in source comments. Running it against current ward main reports 95 stale source-doc-reference violations after the documentation burndown. Repair the source comments by pointing them at surviving docs, dropping obsolete doc pointers, or adding durable replacement docs only where the source comment still needs a real long-form anchor. Then adopt the new AOS hook when the released AOS rev is available.

AOS now ships `source-doc-refs`, a pre-commit hook that validates path-like documentation references in source comments. Running it against current ward main reports 95 stale source-doc-reference violations after the documentation burndown. Repair the source comments by pointing them at surviving docs, dropping obsolete doc pointers, or adding durable replacement docs only where the source comment still needs a real long-form anchor. Then adopt the new AOS hook when the released AOS rev is available.

coilyco-ops commented

2026-07-10 07:22:57 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-964 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T07:22:54Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

Do not comment on or edit this issue to steer the run while it is reserved. The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a new issue, dispatched fresh. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494).

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#964 · branch issue-964 · harness codex · workflow pull-requests
Run: engineer-codex-ward-964 · ward v0.555.0 · dispatched 2026-07-10T07:22:54Z
Comment thread: 0 included in the pre-flight read, 0 stripped (ward's own automated comments).

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.555.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-964` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T07:22:54Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#964` · branch `issue-964` · harness `codex` · workflow `pull-requests` - **Run:** `engineer-codex-ward-964` · ward `v0.555.0` · dispatched `2026-07-10T07:22:54Z` - **Comment thread:** 0 included in the pre-flight read, 0 stripped (ward's own automated comments). Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.555.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops commented

2026-07-10 07:34:23 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-ward-964 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-10T07:34:22Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (1h TTL). --force overrides.

run seed context — what this run is carrying (ward#609)

Resolved: coilyco-flight-deck/ward#964 · branch issue-964 · harness codex · workflow pull-requests
Run: engineer-codex-ward-964 · ward v0.555.0 · dispatched 2026-07-10T07:34:22Z
Comment thread: 0 included in the pre-flight read, 1 stripped (ward's own automated comments).
- stripped: @coilyco-ops (2026-07-10T07:22:57Z)

Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.555.0).

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-ward-964` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-10T07:34:22Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (1h TTL). `--force` overrides. **Do not comment on or edit this issue to steer the run while it is reserved.** The engineer seeded the body once at launch and never re-reads it, so a comment or edit reaches only human readers, never the running engineer. A correction goes to a **new issue, dispatched fresh**. That is the only channel that reaches a run in flight. Where the forge supports it, ward locks this conversation to make that a road-block rather than a convention (ward#494). <details><summary>run seed context — what this run is carrying (ward#609)</summary> - **Resolved:** `coilyco-flight-deck/ward#964` · branch `issue-964` · harness `codex` · workflow `pull-requests` - **Run:** `engineer-codex-ward-964` · ward `v0.555.0` · dispatched `2026-07-10T07:34:22Z` - **Comment thread:** 0 included in the pre-flight read, 1 stripped (ward's own automated comments). - stripped: @coilyco-ops (2026-07-10T07:22:57Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.555.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a pull request that will close it,

2026-07-10 07:55:26 +00:00

docs: repair stale source doc refs #966

coilyco-ops commented

2026-07-10 07:56:49 +00:00

Author

Member

WARD-OUTCOME: submitted

details

workflow: pull-requests; review summary: review gate skipped because --skip-preflight / --no-preflight also skips review implemented by repairing stale source-comment docs, adding durable replacement anchors where the code still needed them, and wiring in the new source-doc-refs hook felt mostly mechanical once the stale references were mapped; the only surprise was how many comments needed durable anchors instead of direct swaps confidence: high follow-ups: none

WARD-OUTCOME: submitted <details><summary>details</summary> workflow: pull-requests; review summary: review gate skipped because --skip-preflight / --no-preflight also skips review implemented by repairing stale source-comment docs, adding durable replacement anchors where the code still needed them, and wiring in the new source-doc-refs hook felt mostly mechanical once the stale references were mapped; the only surprise was how many comments needed durable anchors instead of direct swaps confidence: high follow-ups: none </details>