ward-kdl: generated guardfile.md docs should link back to docs/ward-kdl.md (upstream surface.Markdown footer)

coilysiren commented

2026-06-25 05:10:01 +00:00

Owner

Follow-up from ward#271. docs/ward-kdl.md is now the authoritative build-time-vs-run-time writeup, and the hand-written index docs (ward-kdl-surface.md, ward-kdl-in-ward.md, FEATURES.md, architecture.md) link to it.

The per-area reference docs under docs/ward-kdl/*.guardfile.md could not be wired to link back: they are generated by ward-kdl's surface.Markdown() in upstream cli-guard, so any hand link would be wiped on the next make build-ward-kdl, and the documentation-layout cap excludes them from validation anyway. They stay reachable to the hub through ward-kdl-surface.md (the index), but the reverse link is missing.

The clean fix is an upstream cli-guard change: have surface.Markdown() emit an optional ## See also footer (e.g. a guardfile-level doc-link node, or a fixed pointer to the consumer's hub doc) so every generated reference doc points back to its parent. Then regenerate here.

Out of scope for ward#271 (upstream repo, generated artifact). Filing so the gap is tracked, not lost.

Follow-up from ward#271. docs/ward-kdl.md is now the authoritative build-time-vs-run-time writeup, and the hand-written index docs (ward-kdl-surface.md, ward-kdl-in-ward.md, FEATURES.md, architecture.md) link to it. The per-area reference docs under `docs/ward-kdl/*.guardfile.md` could not be wired to link back: they are generated by ward-kdl's `surface.Markdown()` in upstream cli-guard, so any hand link would be wiped on the next `make build-ward-kdl`, and the documentation-layout cap excludes them from validation anyway. They stay reachable *to* the hub through ward-kdl-surface.md (the index), but the reverse link is missing. The clean fix is an upstream cli-guard change: have `surface.Markdown()` emit an optional `## See also` footer (e.g. a guardfile-level `doc-link` node, or a fixed pointer to the consumer's hub doc) so every generated reference doc points back to its parent. Then regenerate here. Out of scope for ward#271 (upstream repo, generated artifact). Filing so the gap is tracked, not lost.

coilysiren added the

P2

headless

labels

2026-07-01 04:29:40 +00:00

coilyco-ops commented

2026-07-01 04:42:09 +00:00

Member

🛫 ward pre-flight: NO-GO

ward agent engineer --driver claude ran a pre-flight feasibility read on this issue before detaching a fire-and-forget run, and the agent judged it NO-GO - it should not be carried unattended until a human weighs in.

the substantive fix is an upstream cli-guard change to surface.Markdown() that can't be authored or merged from the ward clone, and the ward-side regeneration depends on it landing first - needs a human to sequence the two-repo change.

No container was launched. Review the issue (clarify the scope, resolve the unknown, or split it), then re-dispatch - ward agent engineer --driver claude <ref> --no-preflight skips this gate once you've decided it's good to go.

full pre-flight read

Context to front-load: the ward-kdl doc set and its generation wiring - docs/ward-kdl.md (the build-time-vs-run-time hub), docs/ward-kdl-surface.md (the index that already links to the guardfiles), docs/ward-kdl-in-ward.md, the make build-ward-kdl target, and how surface.Markdown() from upstream cli-guard produces docs/ward-kdl/*.guardfile.md. I would read each of these in the fresh ward clone before touching anything. But reading them will only confirm the blocker, not clear it.

Main risk / unknown: the issue's own "clean fix" is an upstream cli-guard change - teaching surface.Markdown() to emit a ## See also footer - and only then regenerating in ward. That source code does not live in the ward clone this run gets, so the detached run cannot author the fix, land it upstream, and regenerate downstream in a single fire-and-forget ward run. Any hand-edited link to the guardfiles gets wiped on the next make build-ward-kdl, which the issue explicitly warns about, so there is no safe ward-only shortcut. This is a cross-repo coordination task the author deliberately filed as a tracking issue ("filing so the gap is tracked, not lost"), not a self-contained ward change - and it's not WRONG-REPO either, since the ward-side regeneration genuinely belongs here once upstream lands.

NO-GO: the substantive fix is an upstream cli-guard change to surface.Markdown() that can't be authored or merged from the ward clone, and the ward-side regeneration depends on it landing first - needs a human to sequence the two-repo change.

Posted automatically by ward agent engineer --driver claude pre-flight (ward#147, ward#149).

— Claude (she/her), via ward agent

### 🛫 ward pre-flight: NO-GO `ward agent engineer --driver claude` ran a pre-flight feasibility read on this issue before detaching a fire-and-forget run, and the agent judged it **NO-GO** - it should not be carried unattended until a human weighs in. > the substantive fix is an upstream cli-guard change to `surface.Markdown()` that can't be authored or merged from the ward clone, and the ward-side regeneration depends on it landing first - needs a human to sequence the two-repo change. No container was launched. Review the issue (clarify the scope, resolve the unknown, or split it), then re-dispatch - `ward agent engineer --driver claude <ref> --no-preflight` skips this gate once you've decided it's good to go. <details><summary>full pre-flight read</summary> **Context to front-load:** the ward-kdl doc set and its generation wiring - `docs/ward-kdl.md` (the build-time-vs-run-time hub), `docs/ward-kdl-surface.md` (the index that already links *to* the guardfiles), `docs/ward-kdl-in-ward.md`, the `make build-ward-kdl` target, and how `surface.Markdown()` from upstream cli-guard produces `docs/ward-kdl/*.guardfile.md`. I would read each of these in the fresh ward clone before touching anything. But reading them will only confirm the blocker, not clear it. **Main risk / unknown:** the issue's own "clean fix" is an **upstream cli-guard change** - teaching `surface.Markdown()` to emit a `## See also` footer - and only *then* regenerating in ward. That source code does not live in the ward clone this run gets, so the detached run cannot author the fix, land it upstream, and regenerate downstream in a single fire-and-forget ward run. Any hand-edited link to the guardfiles gets wiped on the next `make build-ward-kdl`, which the issue explicitly warns about, so there is no safe ward-only shortcut. This is a cross-repo coordination task the author deliberately filed as a tracking issue ("filing so the gap is tracked, not lost"), not a self-contained ward change - and it's not WRONG-REPO either, since the ward-side regeneration genuinely belongs here once upstream lands. NO-GO: the substantive fix is an upstream cli-guard change to `surface.Markdown()` that can't be authored or merged from the ward clone, and the ward-side regeneration depends on it landing first - needs a human to sequence the two-repo change. </details> --- Posted automatically by `ward agent engineer --driver claude` pre-flight (ward#147, ward#149).   — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 17:00:19 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-309 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T17:00:17Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); --force overrides.

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-309` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T17:00:17Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilysiren commented

2026-07-02 17:24:42 +00:00

Author

Owner

WARD-OUTCOME: blocked - the prescribed upstream fix landed (cli-guard v0.67.0), but regenerating ward's docs here needs a generator migration + doc-link nodes in a non-granted sibling repo.

The upstream half felt clean. surface.Markdown() in both dialects (exec execverb and spec specverb) now emits an optional ## See also footer from a wrap-level doc-link node - href required, text defaults to href, optional trailing desc, fails closed on a block body or >3 args. The two describe renderers are near-symmetric, so the node + footer dropped in naturally with unit tests on both. The only friction was cli-guard's strict house caps (4000-char docs, 2-line comment blocks), which pushed the writeup into a new docs/doc-link.md. Landed and released as cli-guard v0.67.0 (verified HEAD == origin/main, tag at the merge; full suite + lint + godoc green).

The "then regenerate here" half is where it fought back, and it's why this is blocked rather than done. Two walls: (1) ward's doc pipeline still drives the retired specverb-gen@v0.48.0 - two renames behind today's kdl-specs and predating doc-link - so it can't emit footers; getting them needs a generator migration + a cli-guard dep bump, which is its own change, not a back-link tweak. (2) The forgejo/signoz/ollama guardfiles are sourced from the agentic-os/ward-specs bundle (read-only /substrate, not a granted repo), so their doc-link nodes must be authored upstream there. I did confirm make build-ward-kdl runs clean against the substrate bundle (committed docs are in sync), so once the generator is current and the nodes exist, the regen itself is mechanical.

Confidence in the shipped upstream change: high. Follow-up worth filing: migrate ward to the kdl-specs generator + bump cli-guard to v0.67.0, add doc-link nodes to every guardfile (ward-tracked ones in-repo, forgejo/signoz/ollama in agentic-os/ward-specs), then make build-ward-kdl to materialize the footers.

WARD-OUTCOME: blocked - the prescribed upstream fix landed (cli-guard v0.67.0), but regenerating ward's docs here needs a generator migration + doc-link nodes in a non-granted sibling repo. The upstream half felt clean. `surface.Markdown()` in both dialects (exec `execverb` and spec `specverb`) now emits an optional `## See also` footer from a wrap-level `doc-link` node - href required, text defaults to href, optional trailing desc, fails closed on a block body or >3 args. The two describe renderers are near-symmetric, so the node + footer dropped in naturally with unit tests on both. The only friction was cli-guard's strict house caps (4000-char docs, 2-line comment blocks), which pushed the writeup into a new `docs/doc-link.md`. Landed and released as cli-guard v0.67.0 (verified HEAD == origin/main, tag at the merge; full suite + lint + godoc green). The "then regenerate here" half is where it fought back, and it's why this is blocked rather than done. Two walls: (1) ward's doc pipeline still drives the *retired* `specverb-gen@v0.48.0` - two renames behind today's `kdl-specs` and predating doc-link - so it can't emit footers; getting them needs a generator migration + a cli-guard dep bump, which is its own change, not a back-link tweak. (2) The forgejo/signoz/ollama guardfiles are sourced from the `agentic-os/ward-specs` bundle (read-only `/substrate`, not a granted repo), so their doc-link nodes must be authored upstream there. I did confirm `make build-ward-kdl` runs clean against the substrate bundle (committed docs are in sync), so once the generator is current and the nodes exist, the regen itself is mechanical. Confidence in the shipped upstream change: high. Follow-up worth filing: migrate ward to the `kdl-specs` generator + bump cli-guard to v0.67.0, add `doc-link` nodes to every guardfile (ward-tracked ones in-repo, forgejo/signoz/ollama in `agentic-os/ward-specs`), then `make build-ward-kdl` to materialize the footers.

coilysiren commented

2026-07-02 17:25:16 +00:00

Author

Owner

⚠️ Reopened: a granted `--repo` push did not land

This run held --repo grants and closed against coilyco-flight-deck/ward, but the reaper could not confirm every granted repo's work reached its main. A secondary push can be silently rejected (a non-fast-forward on a busy main, a dead/rotated PAT) while the primary push succeeds, so the issue is reopened rather than left reading "done" with the cross-repo half lost.

`coilyco-flight-deck/cli-guard`

Verdict: 1 local commit(s) never reached origin/main.
Preserved on: ward-salvage/cli-guard-cab4f52e

git fetch https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard.git ward-salvage/cli-guard-cab4f52e
git checkout -b ward-salvage/cli-guard-cab4f52e FETCH_HEAD

Re-run the cross-repo half, or - per ward#291 - file it as a native issue in the granted repo so it becomes a single-repo run that sidesteps this failure mode.

— Claude (she/her), via ward agent

## ⚠️ Reopened: a granted `--repo` push did not land This run held `--repo` grants and closed against `coilyco-flight-deck/ward`, but the reaper could not confirm every granted repo's work reached its `main`. A secondary push can be silently rejected (a non-fast-forward on a busy `main`, a dead/rotated PAT) while the primary push succeeds, so the issue is **reopened** rather than left reading "done" with the cross-repo half lost. ### `coilyco-flight-deck/cli-guard` - **Verdict:** 1 local commit(s) never reached `origin/main`. - **Preserved on:** `ward-salvage/cli-guard-cab4f52e` ```bash git fetch https://forgejo.coilysiren.me/coilyco-flight-deck/cli-guard.git ward-salvage/cli-guard-cab4f52e git checkout -b ward-salvage/cli-guard-cab4f52e FETCH_HEAD ``` Re-run the cross-repo half, or - per ward#291 - file it as a native issue in the granted repo so it becomes a single-repo run that sidesteps this failure mode.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-04 17:26:07 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-309 on host KAI-DESKTOP-TOWER is carrying this issue (reserved 2026-07-04T17:26:01Z). Concurrent ward agent runs are blocked until it finishes or the reservation goes stale (2h0m0s 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).

— Claude (she/her), via ward agent

🔒 Reserved by `ward agent --driver claude` — container `engineer-claude-ward-309` on host `KAI-DESKTOP-TOWER` is carrying this issue (reserved 2026-07-04T17:26:01Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s 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).  — Claude (she/her), via `ward agent`

coilysiren referenced this issue from a commit

2026-07-04 17:45:40 +00:00

feat(ward-kdl): back-link generated guardfile docs to the ward-kdl hub (closes #309)

coilysiren closed this issue

2026-07-04 17:45:40 +00:00

coilysiren commented

2026-07-04 17:46:51 +00:00

Author

Owner

WARD-OUTCOME: done - every generated docs/ward-kdl/*.guardfile.md now carries a ## See also footer back to ward-kdl.md + ward-kdl-surface.md, regenerated via doc-link nodes at cli-guard v0.72.0.

The upstream half was already done: cli-guard shipped the doc-link -> ## See also footer in v0.67.0 and go.mod was already pinned to v0.72.0. So the real work was ward-side plumbing - drop a doc-link node into all 27 guardfiles and regenerate.

Two things fought back. The Makefile's build-time generator was stale in two ways at once: it named the retired specverb-gen binary (since renamed kdl-specs) AND pinned v0.48.0, old enough that it could not even parse the current guardfiles' doc-link/action nodes - the build was already broken before I touched it. Bumping the driver to kdl-specs@v0.72.0 fixed both. Separately, the /substrate aos bundle is older than ward's committed guardfiles (missing ward#570's delete-issue-comment grant), so I built against a temp bundle mirroring the committed sources instead of letting the overlay cp regress them.

Regeneration also corrected two pre-existing drifts: the forgejo reference doc had lost its delete-issue-comment verb, and the eco reference docs had never been committed. Both are now in sync, so make build-ward-kdl is idempotent again.

Fairly confident - build, vet, full test suite, and the whole pre-commit suite pass, and all 27 docs verifiably carry the footer. Follow-ups worth filing: (1) nothing enforces the Makefile REF and go.mod's cli-guard pin stay in lockstep, and they had already drifted far; (2) I tried a one-line "closes the loop" note in the ward-kdl.md hub doc but reverted it - that doc is already at its 4000-char cap, so the prose lives only in the commit message.

WARD-OUTCOME: done - every generated docs/ward-kdl/*.guardfile.md now carries a `## See also` footer back to ward-kdl.md + ward-kdl-surface.md, regenerated via doc-link nodes at cli-guard v0.72.0. The upstream half was already done: cli-guard shipped the `doc-link` -> `## See also` footer in v0.67.0 and go.mod was already pinned to v0.72.0. So the real work was ward-side plumbing - drop a doc-link node into all 27 guardfiles and regenerate. Two things fought back. The Makefile's build-time generator was stale in two ways at once: it named the retired `specverb-gen` binary (since renamed `kdl-specs`) AND pinned v0.48.0, old enough that it could not even parse the current guardfiles' `doc-link`/`action` nodes - the build was already broken before I touched it. Bumping the driver to `kdl-specs@v0.72.0` fixed both. Separately, the /substrate aos bundle is older than ward's committed guardfiles (missing ward#570's delete-issue-comment grant), so I built against a temp bundle mirroring the committed sources instead of letting the overlay `cp` regress them. Regeneration also corrected two pre-existing drifts: the forgejo reference doc had lost its delete-issue-comment verb, and the eco reference docs had never been committed. Both are now in sync, so `make build-ward-kdl` is idempotent again. Fairly confident - build, vet, full test suite, and the whole pre-commit suite pass, and all 27 docs verifiably carry the footer. Follow-ups worth filing: (1) nothing enforces the Makefile REF and go.mod's cli-guard pin stay in lockstep, and they had already drifted far; (2) I tried a one-line "closes the loop" note in the ward-kdl.md hub doc but reverted it - that doc is already at its 4000-char cap, so the prose lives only in the commit message.

coilysiren referenced this issue from a commit

2026-07-04 17:49:47 +00:00

fix(release): move tier-publish generator to kdl-specs@v0.72.0 (refs #309)

coilysiren commented

2026-07-04 17:53:33 +00:00

Author

Owner

Addendum (the retrospective above was posted before I watched the release run): my doc-link nodes actually did break something on first push. The publish-kdl-read/publish-kdl-write release jobs pin their own generator via KDL_GEN_REF in .forgejo/workflows/release.yml, and it was still specverb-gen@v0.48.0 - which fails-closed on the very doc-link node I added (unknown node "doc-link" in wrap body). So follow-up (1) from above was not hypothetical: the Makefile REF and the CI REF had drifted, and I only caught the CI copy by watching the run go red.

Fixed in a second commit (moved both tier-publish jobs to kdl-specs@v0.72.0), and I confirmed run 928's publish-kdl-read and publish-kdl-write both go green. Net lesson for next time: grep -rn KDL_GEN_REF .forgejo belongs in the pre-flight, not the post-mortem - a REF bump has more than one home.

Addendum (the retrospective above was posted before I watched the release run): my doc-link nodes actually *did* break something on first push. The `publish-kdl-read`/`publish-kdl-write` release jobs pin their own generator via `KDL_GEN_REF` in .forgejo/workflows/release.yml, and it was still `specverb-gen@v0.48.0` - which fails-closed on the very `doc-link` node I added (`unknown node "doc-link" in wrap body`). So follow-up (1) from above was not hypothetical: the Makefile REF and the CI REF had drifted, and I only caught the CI copy by watching the run go red. Fixed in a second commit (moved both tier-publish jobs to `kdl-specs@v0.72.0`), and I confirmed run 928's `publish-kdl-read` and `publish-kdl-write` both go green. Net lesson for next time: `grep -rn KDL_GEN_REF .forgejo` belongs in the pre-flight, not the post-mortem - a REF bump has more than one home.

coilysiren referenced this issue

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

ward-kdl: generated guardfile.md docs should link back to docs/ward-kdl.md (upstream surface.Markdown footer) #309

🛫 ward pre-flight: NO-GO

⚠️ Reopened: a granted --repo push did not land

coilyco-flight-deck/cli-guard

⚠️ Reopened: a granted `--repo` push did not land

`coilyco-flight-deck/cli-guard`