Fix issue-reference guard before mass rollout

coilyco-ops commented

2026-07-08 18:26:19 +00:00

Member

Review of commit ae3677c83d found that enabling issue-reference-guard in aos produced false-positive cleanup and mangled valid command examples.

Concrete failures:

.agents/skills/coding-git/references/push-and-create-pr.md had valid sample PR bodies changed from Closes #42 to Closes issue, which is not a correct CLI/API example.
warp/tab_configs/claude-agent-work.md had valid owner/repo#N ward CLI examples rewritten to owner/repo/issue-N, which does not match the documented ref syntax.
tests/test_check_commit_closes_issue.py and tests/test_check_text_guards.py now construct issue-ref strings dynamically just to avoid the literal pattern, which means the guard is constraining tests that intentionally exercise the syntax.
Upstream issue links like warpdotdev/Warp#2579 and GitHub/Forgejo issue URLs were removed from docs even where the issue link is the stable upstream reference, not a stale local planning breadcrumb.

Root cause from code inspection:

agentic_os/pre_commit/check_issue_references.py scans raw text with broad regexes.
It has only file-level excludes / allow_globs. It does not distinguish durable prose from fenced code, inline code, quoted command strings, test fixtures, or third-party upstream issue links.
The hook message says to replace issue refs with durable docs or stable links, but the implementation also flags stable issue URLs and command examples where the issue syntax itself is the subject.

Request before mass rollout:

Narrow issue-reference-guard so it does not flag issue syntax inside fenced code blocks, inline code spans, quoted command examples, or test fixtures that intentionally exercise issue parsing.
Decide and encode the policy for external upstream issue links. At minimum, do not force removal of third-party issue links that are the stable source of truth for an upstream limitation.
Add regression tests covering Closes #42 in a fenced gh pr create example, owner/repo#88 in a ward CLI example, test fixture strings, and a third-party upstream issue URL.
Repair the examples/doc lines mangled by ae3677c83d.
Keep the hook useful for actual durable-prose breadcrumbs like See #337 for the draft in ordinary prose.
Validate with ward exec test and pre-commit run issue-reference-guard --all-files --hook-stage manual.

This should land before the issue-reference guard is mass-rolled across repos.

Review of commit ae3677c83d758a26ded19083034a5a690498cd0b found that enabling issue-reference-guard in aos produced false-positive cleanup and mangled valid command examples. Concrete failures: * `.agents/skills/coding-git/references/push-and-create-pr.md` had valid sample PR bodies changed from `Closes #42` to `Closes issue`, which is not a correct CLI/API example. * `warp/tab_configs/claude-agent-work.md` had valid `owner/repo#N` ward CLI examples rewritten to `owner/repo/issue-N`, which does not match the documented ref syntax. * `tests/test_check_commit_closes_issue.py` and `tests/test_check_text_guards.py` now construct issue-ref strings dynamically just to avoid the literal pattern, which means the guard is constraining tests that intentionally exercise the syntax. * Upstream issue links like `warpdotdev/Warp#2579` and GitHub/Forgejo issue URLs were removed from docs even where the issue link is the stable upstream reference, not a stale local planning breadcrumb. Root cause from code inspection: * `agentic_os/pre_commit/check_issue_references.py` scans raw text with broad regexes. * It has only file-level excludes / `allow_globs`. It does not distinguish durable prose from fenced code, inline code, quoted command strings, test fixtures, or third-party upstream issue links. * The hook message says to replace issue refs with durable docs or stable links, but the implementation also flags stable issue URLs and command examples where the issue syntax itself is the subject. Request before mass rollout: * Narrow `issue-reference-guard` so it does not flag issue syntax inside fenced code blocks, inline code spans, quoted command examples, or test fixtures that intentionally exercise issue parsing. * Decide and encode the policy for external upstream issue links. At minimum, do not force removal of third-party issue links that are the stable source of truth for an upstream limitation. * Add regression tests covering `Closes #42` in a fenced `gh pr create` example, `owner/repo#88` in a ward CLI example, test fixture strings, and a third-party upstream issue URL. * Repair the examples/doc lines mangled by ae3677c83d758a26ded19083034a5a690498cd0b. * Keep the hook useful for actual durable-prose breadcrumbs like `See #337 for the draft` in ordinary prose. * Validate with `ward exec test` and `pre-commit run issue-reference-guard --all-files --hook-stage manual`. This should land before the issue-reference guard is mass-rolled across repos.

coilyco-ops commented

2026-07-08 18:26:50 +00:00

Author

Member

🔒 Reserved by ward agent --harness claude — container engineer-claude-agentic-os-341 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-08T18:26:48Z). 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/agentic-os#341 · branch issue-341 · harness claude · workflow direct-main
Run: engineer-claude-agentic-os-341 · ward v0.463.0 · dispatched 2026-07-08T18:26:48Z
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.463.0).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --harness claude` — container `engineer-claude-agentic-os-341` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-08T18:26:48Z). 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/agentic-os#341` · branch `issue-341` · harness `claude` · workflow `direct-main` - **Run:** `engineer-claude-agentic-os-341` · ward `v0.463.0` · dispatched `2026-07-08T18:26:48Z` - **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.463.0). </details>  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-08 18:27:40 +00:00

Author

Member

Additional concrete regression from the same commit: .agents/skills/coding-git/references/conventional-commits.md was also mangled.

The commit example changed:

Closes #42

to:

Closes issue

And the "Linking Issues" examples changed:

Closes #42          ← closes the issue when merged
Fixes #42           ← same effect
Refs #42            ← references without closing

to invalid placeholder-like syntax:

Closes issue        ← closes the issue when merged
Fixes issue         ← same effect
Refs issue          ← references without closing

This is slightly different from the PR-body example but the same root policy bug: the guard is firing on examples where issue-reference syntax is the subject being taught. The fix should include a regression that fenced commit-message examples keep their literal Closes #42 / Fixes #42 / Refs #42 lines.

Additional concrete regression from the same commit: `.agents/skills/coding-git/references/conventional-commits.md` was also mangled. The commit example changed: ```text Closes #42 ``` to: ```text Closes issue ``` And the "Linking Issues" examples changed: ```text Closes #42 ← closes the issue when merged Fixes #42 ← same effect Refs #42 ← references without closing ``` to invalid placeholder-like syntax: ```text Closes issue ← closes the issue when merged Fixes issue ← same effect Refs issue ← references without closing ``` This is slightly different from the PR-body example but the same root policy bug: the guard is firing on examples where issue-reference syntax is the subject being taught. The fix should include a regression that fenced commit-message examples keep their literal `Closes #42` / `Fixes #42` / `Refs #42` lines.

coilyco-ops commented

2026-07-08 19:29:29 +00:00

Author

Member

🔒 Reserved by ward agent --harness codex — container engineer-codex-agentic-os-341 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-08T19:29:28Z). 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/agentic-os#341 · branch issue-341 · harness codex · workflow direct-main
Run: engineer-codex-agentic-os-341 · ward v0.463.0 · dispatched 2026-07-08T19:29:28Z
Comment thread: 1 included in the pre-flight read, 1 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-08T18:27:40Z)
- stripped: @coilyco-ops (2026-07-08T18:26:50Z)

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

— Codex, via ward agent

🔒 Reserved by `ward agent --harness codex` — container `engineer-codex-agentic-os-341` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-08T19:29:28Z). 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/agentic-os#341` · branch `issue-341` · harness `codex` · workflow `direct-main` - **Run:** `engineer-codex-agentic-os-341` · ward `v0.463.0` · dispatched `2026-07-08T19:29:28Z` - **Comment thread:** 1 included in the pre-flight read, 1 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-08T18:27:40Z) - stripped: @coilyco-ops (2026-07-08T18:26:50Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.463.0). </details>  — Codex, via `ward agent`

coilyco-ops added the

headless

P1

labels

2026-07-09 06:38:30 +00:00

coilyco-ops commented

2026-07-09 18:25:31 +00:00

Author

Member

Readiness check from 2026-07-09: not ready for rollout, and not ready for normal N+1 enforcement yet.

Live AOS main (v0.227.0) has issue-reference-guard enabled for itself and PYTHONPATH=/scratch/aos-readiness python3 -m agentic_os.pre_commit.check_issue_references $(git ls-files) passes on AOS. But the implementation is still the broad raw-text scanner from this issue body: it does not distinguish prose from code/test fixtures/examples/generated surfaces.

Scratch N+1 opt-in results:

coilyco-flight-deck/ward, with only [tool.agentic-os.issue-reference-guard] enabled = true, fails with 799 violations. The hits include tests, CLI examples, issue syntax fixtures, generated/openapi guardfiles, and stable docs links.
coilyco-flight-deck/infrastructure, same scratch opt-in, fails with 241 violations. The hits include Ansible role comments, docs change logs, workflow commit messages, scripts, service files, and stable issue URLs.

Conclusion: the hook is OK as an AOS dogfood guard after its local scrub, but N+1 should be report-only/research until this issue narrows the parser/policy. Minimum next fix: skip fenced code, inline code, quoted/test fixture strings, generated files, and encode a policy for stable upstream issue URLs. After that, rerun scratch opt-in on ward and infrastructure before any repo-owned rollout issue.

Readiness check from 2026-07-09: not ready for rollout, and not ready for normal N+1 enforcement yet. Live AOS main (`v0.227.0`) has `issue-reference-guard` enabled for itself and `PYTHONPATH=/scratch/aos-readiness python3 -m agentic_os.pre_commit.check_issue_references $(git ls-files)` passes on AOS. But the implementation is still the broad raw-text scanner from this issue body: it does not distinguish prose from code/test fixtures/examples/generated surfaces. Scratch N+1 opt-in results: * `coilyco-flight-deck/ward`, with only `[tool.agentic-os.issue-reference-guard] enabled = true`, fails with 799 violations. The hits include tests, CLI examples, issue syntax fixtures, generated/openapi guardfiles, and stable docs links. * `coilyco-flight-deck/infrastructure`, same scratch opt-in, fails with 241 violations. The hits include Ansible role comments, docs change logs, workflow commit messages, scripts, service files, and stable issue URLs. Conclusion: the hook is OK as an AOS dogfood guard after its local scrub, but N+1 should be report-only/research until this issue narrows the parser/policy. Minimum next fix: skip fenced code, inline code, quoted/test fixture strings, generated files, and encode a policy for stable upstream issue URLs. After that, rerun scratch opt-in on `ward` and `infrastructure` before any repo-owned rollout issue.

coilyco-ops commented

2026-07-09 18:25:38 +00:00

Author

Member

WARD-RESERVATION: held 🔒

reservation details

Holder: container engineer-codex-agentic-os-341 on host kais-macbook-pro-2.local.

Reserved by ward agent --harness codex (reserved 2026-07-09T18:25:35Z). 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/agentic-os#341 · branch issue-341 · harness codex · workflow direct-to-main
Run: engineer-codex-agentic-os-341 · ward v0.493.0 · dispatched 2026-07-09T18:25:35Z
Comment thread: 2 included in the pre-flight read, 2 stripped (ward's own automated comments).
- included: @coilyco-ops (2026-07-08T18:27:40Z), @coilyco-ops (2026-07-09T18:25:31Z)
- stripped: @coilyco-ops (2026-07-08T18:26:50Z), @coilyco-ops (2026-07-08T19:29:29Z)

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

— Codex, via ward agent

WARD-RESERVATION: held 🔒 <details><summary>reservation details</summary> Holder: container `engineer-codex-agentic-os-341` on host `kais-macbook-pro-2.local`. Reserved by `ward agent --harness codex` (reserved 2026-07-09T18:25:35Z). 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/agentic-os#341` · branch `issue-341` · harness `codex` · workflow `direct-to-main` - **Run:** `engineer-codex-agentic-os-341` · ward `v0.493.0` · dispatched `2026-07-09T18:25:35Z` - **Comment thread:** 2 included in the pre-flight read, 2 stripped (ward's own automated comments). - included: @coilyco-ops (2026-07-08T18:27:40Z), @coilyco-ops (2026-07-09T18:25:31Z) - stripped: @coilyco-ops (2026-07-08T18:26:50Z), @coilyco-ops (2026-07-08T19:29:29Z) Static container doctrine and seed boilerplate are identical every run and omitted here (they ride ward v0.493.0). </details> </details>  — Codex, via `ward agent`

coilyco-ops referenced this issue from a commit

2026-07-09 18:32:09 +00:00

fix: narrow issue-reference guard

coilyco-ops closed this issue

2026-07-09 18:32:09 +00:00

coilyco-ops commented

2026-07-09 18:32:37 +00:00

Author

Member

WARD-OUTCOME: done ✅

details

workflow: direct-to-main; review summary: skipped by ~/.ward/config.yaml default
felt: narrow and mechanical
confidence: high
surprises: the policy note needed its example on one line
follow-ups: none

WARD-OUTCOME: done ✅ <details><summary>details</summary> workflow: direct-to-main; review summary: skipped by ~/.ward/config.yaml default felt: narrow and mechanical confidence: high surprises: the policy note needed its example on one line follow-ups: none </details>

coilyco-ops referenced this issue

2026-07-09 18:44:04 +00:00

Stage issue-reference guard N+1 rollout after parser narrowing #381

coilysiren referenced this issue from coilyco-flight-deck/ward

2026-07-10 04:03:12 +00:00

ward release race condition #935

coilysiren referenced this issue from coilyco-flight-deck/ward

2026-07-14 15:27:09 +00:00

director should emit colorized, space buffered, visually distinct messages about the categories of actions its performing on startup #1283

Rows
Columns

Fix issue-reference guard before mass rollout #341