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

coilyco-ops commented

2026-07-01 21:55:59 +00:00

Member

Why

Persona: drive-by-critic, angle front-page. Reading only the description + README, hunting for the dunk. The actual thread comment this invites:

"Four paragraphs in and I still dont know what problem this solves. 'ward is a harness driver'... driving WHAT into WHERE for WHY? 'warded agent', 'protective circle', bare issue refs (ward#247, ward#282) like Im supposed to already know your tracker. Reads like internal wiki copy-pasted into a README."

Sorted: fair. The concrete, plain-English answer exists - ## What it does: "Wraps a project's dev verbs (build, test, vet, lint, tidy, cover) behind cli-guards policy gate." - but it is the fifth thing on the page, after: (1) a naming-metaphor paragraph ("protective circle... not warded off"), (2) a sudo/firejail analogy paragraph citing two bare issue numbers (ward#247, ward#282) with no link or context, (3) a paragraph about absorbing "the retiring coily"s operator surface - a migration detail meaningless to a first-time reader, and only then (4) the three-layer cli-guard/ward-kdl/ward split. A skimming stranger (exactly this persona's reading style) hits four paragraphs of internal naming rationale before the one sentence that says what the tool concretely does.

Deliverable

Lead the README with the "What it does" sentence (or an equivalent one-liner), then follow with the naming/architecture context for readers who want it. The metaphor paragraphs, the coily-migration note, and the bare issue refs belong after the concrete description, not before it - or in architecture.md, which already exists for this.

Done condition

A reader hits a plain-English, jargon-free statement of what ward concretely does within the first paragraph, before any internal naming rationale or unexplained issue references.

Severity: major-friction · persona: drive-by-critic · angle: front-page
Filed by Claude Code during a cold-read release pressure test (run 5).

## Why Persona: `drive-by-critic`, angle `front-page`. Reading only the description + README, hunting for the dunk. The actual thread comment this invites: > "Four paragraphs in and I still dont know what problem this solves. 'ward is a harness driver'... driving WHAT into WHERE for WHY? 'warded agent', 'protective circle', bare issue refs (ward#247, ward#282) like Im supposed to already know your tracker. Reads like internal wiki copy-pasted into a README." Sorted: **fair**. The concrete, plain-English answer exists - `## What it does`: "Wraps a project's dev verbs (build, test, vet, lint, tidy, cover) behind cli-guards policy gate." - but it is the *fifth* thing on the page, after: (1) a naming-metaphor paragraph ("protective circle... not warded off"), (2) a `sudo`/`firejail` analogy paragraph citing two bare issue numbers (`ward#247, ward#282`) with no link or context, (3) a paragraph about absorbing "the retiring coily"s operator surface - a migration detail meaningless to a first-time reader, and only then (4) the three-layer cli-guard/ward-kdl/ward split. A skimming stranger (exactly this persona's reading style) hits four paragraphs of internal naming rationale before the one sentence that says what the tool concretely does. ## Deliverable Lead the README with the "What it does" sentence (or an equivalent one-liner), then follow with the naming/architecture context for readers who want it. The metaphor paragraphs, the coily-migration note, and the bare issue refs belong after the concrete description, not before it - or in architecture.md, which already exists for this. ## Done condition A reader hits a plain-English, jargon-free statement of what ward concretely does within the first paragraph, before any internal naming rationale or unexplained issue references. --- **Severity: major-friction** · persona: drive-by-critic · angle: front-page Filed by Claude Code during a cold-read release pressure test (run 5).

coilyco-ops added the

pressure-test

label

2026-07-01 21:55:59 +00:00

coilyco-ops referenced this issue

2026-07-01 21:56:40 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops referenced this issue

2026-07-01 21:59:11 +00:00

polish batch, run 16: jargon-audit (internal hostnames, cross-repo bare refs, unlinked insider tools) #449

coilyco-ops commented

2026-07-01 21:59:11 +00:00

Author

Member

+1 — independently hit via github-only-dev/jargon-audit, run 16. Run 2 of this sweep also stumbled on the same wall from a different persona (the README's definition of warded leans on ward#247/ward#282 as explanation).
Filed by Claude Code during a cold-read release pressure test (run 16).

+1 — independently hit via github-only-dev/jargon-audit, run 16. Run 2 of this sweep also stumbled on the same wall from a different persona (the README's definition of warded leans on ward#247/ward#282 as explanation). Filed by Claude Code during a cold-read release pressure test (run 16).

coilyco-ops referenced this issue

2026-07-01 21:59:13 +00:00

meta: release pressure-test run log (cold-read usability sweeps) #428

coilyco-ops added this to the ward launch milestone

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

coilyco-ops added the

consult

P1

labels

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

coilyco-ops referenced this issue

2026-07-01 23:57:01 +00:00

README instructs warded engineer #98 --watch, a flag retired in ward#356 that now errors as unknown #474

coilyco-ops added

headless

and removed

consult

labels

2026-07-01 23:57:23 +00:00

coilyco-ops commented

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

Author

Member

DECISION - this is the canonical README-rewrite epic (one agent, one PR; the cluster does NOT dispatch in parallel). Folds in: #445 (stage honesty - approved framing: early-stage, single-maintainer, going public; 242 releases = automated per-merge pipeline, not 242 milestones), #482 (boundary honesty - approved framing: for containerized agents, container isolation + repo-scoped push token IS the boundary; the deny-list belongs to the dev-verb gate), #468/#474 (drop the retired --watch example), #461 (see its comment: ALL external copy goes GitHub-only; Forgejo appears only in contributor-facing surfaces / source). Explicitly declined: a front-page denial demo, and a structural forge-agnostic split section. Sequencing: #427 (length-cap lift) lands FIRST; note honesty constraint - until #489 (warded on GitHub issues) lands, copy must state GitHub support status truthfully, not claim it. Recorded by Claude Code (Fable) during the 2026-07-01 ward launch triage session with Kai.

coilyco-ops referenced this issue

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

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

coilyco-ops referenced this issue

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

front page gives a hostile reader zero context for v0.x + 242 releases + 0 stars/forks #445

coilyco-ops referenced this issue

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

README defines 'warded' as a deny-list bounding the agent's reach; container-permissions.md says no deny wall exists anywhere and isolation is the sole boundary #482

coilyco-ops referenced this issue

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

README's first sentence conflates dev-verb wrapping (forge-agnostic) with agent-carries-a-Forgejo-issue (Forgejo-only), losing GitHub-only adopters of the half that would actually work for them #461

coilyco-ops referenced this issue

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

README still advertises retired warded engineer --watch even though the flag now errors #468

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 referenced this issue

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

Human readable feature list #192

coilyco-ops commented

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

Author

Member

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

docs(readme): lead with what ward concretely does, not naming lore (closes #444)

coilysiren closed this issue

2026-07-02 02:44:02 +00:00

coilysiren commented

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

Owner

WARD-OUTCOME: done - README now opens with a plain-English statement of what ward does; the naming metaphor, sudo/firejail analogy, and bare ward#247/ward#282 refs moved out of the lead.

Straightforward fix in the end, but the honest part is that it fought back at the framing level, not the editing level. The narrow ask ("lead with what it does") was a five-minute edit. The friction was the triage DECISION in the thread reframing #444 as the canonical README-rewrite epic that folds in #445/#482/#461/#468 with sequencing and honesty constraints. I chose to keep to the dispatched deliverable - the opening fix - and only pull in the approved framings where they touched the lines I was already rewriting (dropped the retired engineer --watch example, kept the deny-list out of the agent's boundary claim per #482). I'm fairly confident that was the right call, but a human should confirm they didn't want the whole epic landed here.

Two rough edges worth naming: (1) the new lead paragraph and the later ## What it does section now say nearly the same sentence - deliberate (punchy lead + detailed section) but a reviewer may want the section trimmed. (2) Landing raced against concurrent pushes to main twice; both were clean merges (no README overlap), but it's a reminder the epic siblings are moving in parallel despite the DECISION saying they shouldn't. The forge-honesty items (#461 GitHub-only external copy, #445 stage honesty) are untouched and still open - they need their own pass.

WARD-OUTCOME: done - README now opens with a plain-English statement of what ward does; the naming metaphor, sudo/firejail analogy, and bare ward#247/ward#282 refs moved out of the lead. Straightforward fix in the end, but the honest part is that it fought back at the framing level, not the editing level. The narrow ask ("lead with what it does") was a five-minute edit. The friction was the triage DECISION in the thread reframing #444 as the canonical README-rewrite epic that folds in #445/#482/#461/#468 with sequencing and honesty constraints. I chose to keep to the dispatched deliverable - the opening fix - and only pull in the approved framings where they touched the lines I was already rewriting (dropped the retired `engineer --watch` example, kept the deny-list out of the agent's boundary claim per #482). I'm fairly confident that was the right call, but a human should confirm they didn't want the whole epic landed here. Two rough edges worth naming: (1) the new lead paragraph and the later `## What it does` section now say nearly the same sentence - deliberate (punchy lead + detailed section) but a reviewer may want the section trimmed. (2) Landing raced against concurrent pushes to main twice; both were clean merges (no README overlap), but it's a reminder the epic siblings are moving in parallel despite the DECISION saying they shouldn't. The forge-honesty items (#461 GitHub-only external copy, #445 stage honesty) are untouched and still open - they need their own pass.

coilysiren referenced this issue

2026-07-02 02:48:14 +00:00

README still advertises retired warded engineer --watch even though the flag now errors #468

coilysiren referenced this issue

2026-07-02 02:48:15 +00:00

README defines 'warded' as a deny-list bounding the agent's reach; container-permissions.md says no deny wall exists anywhere and isolation is the sole boundary #482

coilysiren referenced this issue

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

README's first sentence conflates dev-verb wrapping (forge-agnostic) with agent-carries-a-Forgejo-issue (Forgejo-only), losing GitHub-only adopters of the half that would actually work for them #461

coilysiren referenced this issue

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

front page gives a hostile reader zero context for v0.x + 242 releases + 0 stars/forks #445

coilysiren referenced this issue

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

README's first sentence names qwen as a harness; it is a deprecated alias for opencode with no doc at the expected path #448

coilysiren referenced this issue

2026-07-02 03:01:43 +00:00

README carries a front-page denial demo that the 2026-07-01 triage explicitly declined - relocate it #502

coilysiren referenced this issue

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

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

coilyco-ops commented

2026-07-02 07:51:41 +00:00

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-444 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:51:39Z). 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-444` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:51:39Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

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

Author

Member

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-444 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T07:51:39Z). 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-444` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T07:51:39Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Claude (she/her), via `ward agent`

coilyco-ops commented

2026-07-02 07:51:48 +00:00

Author

Member

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

Owner

WARD-OUTCOME: done - README already leads with the concrete "what ward does" sentence; fix (b0ce6d5, closes #444) was already on main before this run.

Honest retro: this one was already finished when I arrived. I walked in expecting the four-paragraphs-of-naming-lore opening the issue describes, but the README already leads with the bold, plain-English "ward wraps a project's dev verbs ... behind a policy gate" sentence on line 3, with the "protective circle / not warded off" metaphor and the coily-migration note pushed down to the agent-driver paragraph and the "three layers" section, and the former bare ward#395/#396 refs now full links. The done-condition is met.

Verified rather than assumed: commit b0ce6d5 ("lead with what ward concretely does, not naming lore") is an ancestor of origin/main, the issue is already closed, and my branch is 0/0 against origin/main - nothing to implement, commit, or push. So I made no changes; manufacturing a redundant commit would have been noise.

Confidence high that the deliverable is satisfied. The only rough edge is process, not content: this was a stale/duplicate dispatch of an already-closed issue. The earlier resolution comment noted related follow-ups (#445 stage honesty, #461 GitHub-only external copy) left open for separate passes - those, not #444, are where any remaining front-page work lives.

WARD-OUTCOME: done - README already leads with the concrete "what ward does" sentence; fix (b0ce6d5, closes #444) was already on main before this run. Honest retro: this one was already finished when I arrived. I walked in expecting the four-paragraphs-of-naming-lore opening the issue describes, but the README already leads with the bold, plain-English "ward wraps a project's dev verbs ... behind a policy gate" sentence on line 3, with the "protective circle / not warded off" metaphor and the coily-migration note pushed down to the agent-driver paragraph and the "three layers" section, and the former bare ward#395/#396 refs now full links. The done-condition is met. Verified rather than assumed: commit b0ce6d5 ("lead with what ward concretely does, not naming lore") is an ancestor of origin/main, the issue is already closed, and my branch is 0/0 against origin/main - nothing to implement, commit, or push. So I made no changes; manufacturing a redundant commit would have been noise. Confidence high that the deliverable is satisfied. The only rough edge is process, not content: this was a stale/duplicate dispatch of an already-closed issue. The earlier resolution comment noted related follow-ups (#445 stage honesty, #461 GitHub-only external copy) left open for separate passes - those, not #444, are where any remaining front-page work lives.

coilysiren referenced this issue

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

README's first sentence names qwen as a harness; it is a deprecated alias for opencode with no doc at the expected path #448

coilysiren referenced this issue from a commit

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

docs(readme): retire the last --watch cue, point interactive work at director

coilysiren referenced this issue

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

README still advertises retired warded engineer --watch even though the flag now errors #468

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