release: lift the README length cap so the README can grow into the launch-grade front page

coilyco-ops commented

2026-07-01 20:23:46 +00:00

Member

Why

Standing TODO from Kai that keeps getting re-remembered and not landing: the README is held under a length cap, and the cap now works against the release. The README is the single highest-leverage adoption surface - a cold visitor (human or agent) decides in under a minute whether ward is for them - and ~4.4KB is not enough room to (a) say up front who the tool is for and what it requires (a running Forgejo instance - the omission that lets a GitHub-only visitor conclude "useless" in seconds, cf. ward#414), (b) show a denial, per the launch doctrine in ward#255 ("every demo and one-liner must show a denial, not just capability"), and (c) route humans and agents into the 60+ files under docs/.

Deliverable

Locate the cap. It is not in ward's .pre-commit-config.yaml or .golangci.yaml (checked 2026-07-01), and no obvious rule surfaced in aos AGENTS.md - candidates are an aos-side docs rule or the README/AGENTS/FEATURES trifecta doctrine that keeps READMEs terse. Name the enforcement point explicitly in the closing PR.
Lift or raise it (rule change, or repo-exemption for ward).
Regrow the README against the release bar, not the old cap. The regrowth itself may be split to a follow-up issue if the lift + agreed outline lands first.

Done condition

Whatever enforced the cap no longer constrains ward's README, and the closing PR names what it was.
README regrown, or a follow-up issue filed carrying the agreed outline.

Severity: major-friction - blocks fixing the top adoption surface. Part of the release pressure-test burndown (pressure-test label).

Filed by Claude Code during the release pressure-test setup session, from Kai's standing TODO.

## Why Standing TODO from Kai that keeps getting re-remembered and not landing: the README is held under a length cap, and the cap now works against the release. The README is the single highest-leverage adoption surface - a cold visitor (human or agent) decides in under a minute whether ward is for them - and ~4.4KB is not enough room to (a) say up front who the tool is for and what it requires (a running Forgejo instance - the omission that lets a GitHub-only visitor conclude "useless" in seconds, cf. ward#414), (b) show a denial, per the launch doctrine in ward#255 ("every demo and one-liner must show a denial, not just capability"), and (c) route humans and agents into the 60+ files under docs/. ## Deliverable 1. **Locate the cap.** It is not in ward's `.pre-commit-config.yaml` or `.golangci.yaml` (checked 2026-07-01), and no obvious rule surfaced in aos AGENTS.md - candidates are an aos-side docs rule or the README/AGENTS/FEATURES trifecta doctrine that keeps READMEs terse. Name the enforcement point explicitly in the closing PR. 2. **Lift or raise it** (rule change, or repo-exemption for ward). 3. **Regrow the README against the release bar**, not the old cap. The regrowth itself may be split to a follow-up issue if the lift + agreed outline lands first. ## Done condition - Whatever enforced the cap no longer constrains ward's README, and the closing PR names what it was. - README regrown, or a follow-up issue filed carrying the agreed outline. --- **Severity: major-friction** - blocks fixing the top adoption surface. Part of the release pressure-test burndown (`pressure-test` label). Filed by Claude Code during the release pressure-test setup session, from Kai's standing TODO.

coilyco-ops added the

pressure-test

label

2026-07-01 20:23:46 +00:00

coilyco-ops added this to the ward launch milestone

2026-07-01 23:29:45 +00:00

coilyco-ops added the

headless

P1

labels

2026-07-01 23:30:35 +00:00

coilyco-ops referenced this issue

2026-07-01 23:58:15 +00:00

README opening buries what ward actually does under four paragraphs of naming lore and unexplained bare issue refs #444

coilyco-ops commented

2026-07-01 23:58:16 +00:00

Author

Member

DECISION - runs FIRST, before the #444 README epic; the epic is blocked on this cap lift. Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops referenced this issue

2026-07-02 00:01:42 +00:00

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops commented

2026-07-02 02:20:01 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-427 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T02:19:59Z). 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-427` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T02:19:59Z). 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 02:36:53 +00:00

docs(readme): regrow the README into the launch-grade front page

coilysiren closed this issue

2026-07-02 02:36:53 +00:00

coilysiren commented

2026-07-02 02:38:32 +00:00

Owner

WARD-OUTCOME: done - lifted the README cap (added a bounded per-repo readme_max_* opt-up upstream in agentic-os + reframed ward's blanket README exclude) and regrew the README into a launch-grade front page.

Honest retro: the "cap" was the agentic-os documentation-layout hook, but the real find was that ward pins that hook at a stale v0.65.0 - before the trifecta cap existed, so it enforces a flat 4000-char markdown cap, which is why ward has carried a blanket README.md exclude framed as temporary debt (ward#274). So the fix split cleanly in two: (1) upstream, add a per-repo readme_max_lines / readme_max_chars opt-up that mirrors the existing AGENTS.md one - the durable, bounded rule change - and (2) in ward, reframe the exclude from "debt to shrink" to an intentional front-page exemption, then grow the README against the release bar (who it's for + the Forgejo-canonical requirement, an actual denial demo per ward#255, and a themed map into the 60+ docs).

What fought back: main moved under me mid-run - the ward ci watch removal (#491) and a ward doctor contract rewrite landed while I was working - so I hit a README rebase conflict and had to resync the copy (doctor not lint for the allowlist contract, drop the deleted ci watch). I also tried bumping ward's hook pin to actually consume the new opt-up, but the managed hook block has drifted hard since v0.65.0 (merge-conflicts gone, new hooks added), so that's a much bigger, separate change - I reverted it and left the opt-up to bind when ward's pin next advances, noted inline in pyproject.

Confidence: high. Both repos verified landed (local HEAD == fresh origin/main on each), full pre-commit run --all-files green on ward, aos suite green except 6 pre-existing failures in an unrelated retired hook's tests.

Follow-ups worth filing: ward#274 is now superseded and should be closed; and modernizing ward's stale agentic-os pin is the thing that would let the readme_max_* opt-up actually bind and narrow the blanket exclude to a real bounded cap.

WARD-OUTCOME: done - lifted the README cap (added a bounded per-repo `readme_max_*` opt-up upstream in agentic-os + reframed ward's blanket README exclude) and regrew the README into a launch-grade front page. Honest retro: the "cap" was the agentic-os `documentation-layout` hook, but the real find was that ward pins that hook at a stale **v0.65.0** - before the trifecta cap existed, so it enforces a flat 4000-char markdown cap, which is why ward has carried a blanket `README.md` exclude framed as temporary debt (ward#274). So the fix split cleanly in two: (1) upstream, add a per-repo `readme_max_lines` / `readme_max_chars` opt-up that mirrors the existing AGENTS.md one - the durable, bounded rule change - and (2) in ward, reframe the exclude from "debt to shrink" to an intentional front-page exemption, then grow the README against the release bar (who it's for + the Forgejo-canonical requirement, an actual denial demo per ward#255, and a themed map into the 60+ docs). What fought back: `main` moved under me mid-run - the `ward ci watch` removal (#491) and a `ward doctor` contract rewrite landed while I was working - so I hit a README rebase conflict and had to resync the copy (doctor not lint for the allowlist contract, drop the deleted `ci watch`). I also tried bumping ward's hook pin to actually consume the new opt-up, but the managed hook block has drifted hard since v0.65.0 (`merge-conflicts` gone, new hooks added), so that's a much bigger, separate change - I reverted it and left the opt-up to bind when ward's pin next advances, noted inline in pyproject. Confidence: high. Both repos verified landed (local HEAD == fresh origin/main on each), full `pre-commit run --all-files` green on ward, aos suite green except 6 pre-existing failures in an unrelated retired hook's tests. Follow-ups worth filing: ward#274 is now superseded and should be closed; and modernizing ward's stale agentic-os pin is the thing that would let the `readme_max_*` opt-up actually bind and narrow the blanket exclude to a real bounded cap.

coilysiren referenced this issue

2026-07-02 02:45:45 +00:00

advance the aos documentation-layout pin so the per-file caps bind (post-#427), narrow the README exclude #500

coilysiren referenced this issue

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

meta: jul 1st evening sprint - launch burndown session 1 #492

coilyco-ops referenced this issue

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

Fix residual reap landing path that can push work without closing the carried issue #515