trim the 31 char-capped design docs so their issue refs can be linked (ward#446 follow-up) #521

New issue

Closed

opened 2026-07-02 08:16:32 +00:00 by coilysiren · 2 comments

coilysiren commented

2026-07-02 08:16:32 +00:00

Owner

Follow-up to ward#446. The issue-ref linter (scripts/lint_issue_refs.py, gate: ward exec lint-refs + pre-commit) rewrites every terse issue ref in a public-facing doc into a full-URL Markdown link, because a bare ward#123 never autolinks in a rendered Markdown file on the GitHub mirror.

31 deep design docs under docs/ are exempted (CONTRIBUTOR_DOCS in the linter) because they are hand-tuned to the documentation-layout 4000-char cap (many sit at 3997-3999), and expanding their ~330 terse refs into ~76-char links would bust that cap. They are treated like source (terse Forgejo refs allowed per ward#443).

The durable fix: trim the provenance-ref noise in those docs (much of it is trailing (ward#NNN) citations that read as internal-wiki clutter - see ward#444) so each doc fits the cap with its remaining refs linked, then drop it from CONTRIBUTOR_DOCS. This is editorial per-doc work, not a mechanical pass, which is why it was split out of the ward#446 scrub.

The exempt list lives in scripts/lint_issue_refs.py (CONTRIBUTOR_DOCS). Done when the set is empty and the linter is clean across all of docs/.

Follow-up to ward#446. The issue-ref linter (`scripts/lint_issue_refs.py`, gate: `ward exec lint-refs` + pre-commit) rewrites every terse issue ref in a public-facing doc into a full-URL Markdown link, because a bare `ward#123` never autolinks in a rendered Markdown file on the GitHub mirror. 31 deep design docs under `docs/` are **exempted** (`CONTRIBUTOR_DOCS` in the linter) because they are hand-tuned to the documentation-layout 4000-char cap (many sit at 3997-3999), and expanding their ~330 terse refs into ~76-char links would bust that cap. They are treated like source (terse Forgejo refs allowed per ward#443). The durable fix: trim the provenance-ref noise in those docs (much of it is trailing `(ward#NNN)` citations that read as internal-wiki clutter - see ward#444) so each doc fits the cap **with** its remaining refs linked, then drop it from `CONTRIBUTOR_DOCS`. This is editorial per-doc work, not a mechanical pass, which is why it was split out of the ward#446 scrub. The exempt list lives in `scripts/lint_issue_refs.py` (`CONTRIBUTOR_DOCS`). Done when the set is empty and the linter is clean across all of `docs/`.

coilysiren referenced this issue

2026-07-02 08:17:23 +00:00

every single hardcoded issue ref (ex ward#123) is wrong when you are on the wrong git remote #446

coilyco-ops added the

consult

labels

2026-07-02 08:33:15 +00:00

coilyco-ops commented

2026-07-02 17:59:06 +00:00

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-521 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T17:59:04Z). 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-521` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T17:59:04Z). 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 referenced this issue from a commit

2026-07-02 18:16:08 +00:00

docs: trim provenance-ref clutter so design-doc refs can be linked (ward#521)

coilysiren closed this issue

2026-07-02 18:16:08 +00:00

coilysiren commented

2026-07-02 18:16:35 +00:00

Author

Owner

This one felt satisfying because the verification was fully objective - trim, run the linter's --fix, check wc -c <= 4000 and the linter exits clean - so I could fan the editorial pass out across the docs in parallel and trust the gate rather than my own eyeballing. The trailing (ward#NNN) citations really were pure clutter: on most docs removing them alone dropped the char count and erased the refs that would have needed linking, a double win. The genuinely fiddly cases were the low-ref-but-near-cap docs (architecture.md at 3999 with a single load-bearing ref, agent-local-model.md at 3997 with none to spare) where I had to tighten real prose, not just delete citations.

What fought back: nothing in the edits, but the container disk was pinned at 100% and pre-commit couldn't clone the agentic-os hooks repo to run the mandated gate - the first commit aborted mid-fetch. Clearing the failed partial pack freed just enough headroom to let it initialize and pass. Worth flagging that these feature containers are running close to the disk edge. The other wrinkle was integration: while I worked, ward#526 and ward#153 each landed a fresh terse ref into two of my docs (still exempt at the time), so the merge reintroduced two violations I had to resolve - a reminder that emptying the exempt set makes every future doc ref in those files load-bearing for the linter.

Confidence is high: the full linter is green across docs/, documentation-layout passes on every trimmed doc, and I spot-read the heaviest edits (agent-director.md went 25 refs -> 0) for prose coherence. Rough edge / possible follow-up: a couple of the touched docs still carry pre-existing house-style nits (an inline *why* italic, some structural semicolons) that were out of scope here but a future style sweep could clean.

WARD-OUTCOME: done - emptied CONTRIBUTOR_DOCS after trimming provenance-ref clutter from all 33 exempt design docs so every one fits the 4000-char cap with its remaining refs linked; linter clean across docs/, landed on main. This one felt satisfying because the verification was fully objective - trim, run the linter's `--fix`, check `wc -c <= 4000` and the linter exits clean - so I could fan the editorial pass out across the docs in parallel and trust the gate rather than my own eyeballing. The trailing `(ward#NNN)` citations really were pure clutter: on most docs removing them alone dropped the char count *and* erased the refs that would have needed linking, a double win. The genuinely fiddly cases were the low-ref-but-near-cap docs (architecture.md at 3999 with a single load-bearing ref, agent-local-model.md at 3997 with none to spare) where I had to tighten real prose, not just delete citations. What fought back: nothing in the edits, but the container disk was pinned at 100% and pre-commit couldn't clone the agentic-os hooks repo to run the mandated gate - the first commit aborted mid-fetch. Clearing the failed partial pack freed just enough headroom to let it initialize and pass. Worth flagging that these feature containers are running close to the disk edge. The other wrinkle was integration: while I worked, ward#526 and ward#153 each landed a fresh terse ref into two of my docs (still exempt at the time), so the merge reintroduced two violations I had to resolve - a reminder that emptying the exempt set makes every future doc ref in those files load-bearing for the linter. Confidence is high: the full linter is green across docs/, documentation-layout passes on every trimmed doc, and I spot-read the heaviest edits (agent-director.md went 25 refs -> 0) for prose coherence. Rough edge / possible follow-up: a couple of the touched docs still carry pre-existing house-style nits (an inline `*why*` italic, some structural semicolons) that were out of scope here but a future style sweep could clean.