polish batch, run 2: yaml-config

coilyco-ops commented

2026-07-01 21:47:35 +00:00

Owner

Why

Non-gating friction hit during run 2 (the-agent-itself / yaml-config), batched per sweep rules:

AGENTS.md opens with "Workspace conventions load globally via ~/.claude/CLAUDE.md -> agentic-os-kai/AGENTS.md" — a pointer into a private workspace no external human or agent has. As the first line of the agent entry point, it tells a stranger's agent to load a file that does not exist for it. (Sibling of #429's broken docs/README.md link.)
docs/config-discovery.md is written as code commentary, not a user contract: it narrates repocfg.Load, preParseConfigFlag, os.Args scanning, and "legacy behavior" — none actionable by a config author. The three-line precedence list (--config > $WARD_CONFIG > walk-up) is the doc; the rest belongs in code comments.
Verb-list drift for a first-time config author: README "What it does" names six dev verbs (build, test, vet, lint, tidy, cover) while exec-verb.md's stated contract is the build/test/install triple. Two canonical-looking lists, neither marked as the requirement.

Deliverable / Done condition

Each checkbox is independently fixable; done when all three are checked.

Severity: polish · persona: the-agent-itself · angle: yaml-config
Filed by Claude Code during a cold-read release pressure test (run 2).

## Why Non-gating friction hit during run 2 (`the-agent-itself` / `yaml-config`), batched per sweep rules: - [ ] AGENTS.md opens with "Workspace conventions load globally via `~/.claude/CLAUDE.md` -> `agentic-os-kai/AGENTS.md`" — a pointer into a private workspace no external human or agent has. As the first line of the agent entry point, it tells a stranger's agent to load a file that does not exist for it. (Sibling of #429's broken docs/README.md link.) - [ ] docs/config-discovery.md is written as code commentary, not a user contract: it narrates `repocfg.Load`, `preParseConfigFlag`, `os.Args` scanning, and "legacy behavior" — none actionable by a config author. The three-line precedence list (`--config` > `$WARD_CONFIG` > walk-up) is the doc; the rest belongs in code comments. - [ ] Verb-list drift for a first-time config author: README "What it does" names six dev verbs (build, test, vet, lint, tidy, cover) while exec-verb.md's stated contract is the build/test/**install** triple. Two canonical-looking lists, neither marked as the requirement. ## Deliverable / Done condition Each checkbox is independently fixable; done when all three are checked. --- **Severity: polish** · persona: the-agent-itself · angle: yaml-config Filed by Claude Code during a cold-read release pressure test (run 2).

coilyco-ops added the

pressure-test

label

2026-07-01 21:47:35 +00:00

coilyco-ops referenced this issue

2026-07-01 21:48:05 +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:40 +00:00

coilyco-ops added the

labels

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

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 03:17:33 +00:00

Author

Owner

🔒 Reserved by ward agent --driver claude — container engineer-claude-ward-439 on host kais-macbook-pro-2.local is carrying this issue (reserved 2026-07-02T03:17:30Z). 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-439` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T03:17:30Z). 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 04:31:03 +00:00

Author

Owner

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

— Codex, via ward agent

🔒 Reserved by `ward agent --driver codex` — container `engineer-codex-ward-439` on host `kais-macbook-pro-2.local` is carrying this issue (reserved 2026-07-02T04:31:01Z). Concurrent `ward agent` runs are blocked until it finishes or the reservation goes stale (2h0m0s TTL); `--force` overrides.  — Codex, via `ward agent`

coilysiren referenced this issue from a commit

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

Polish yaml-config docs

coilysiren closed this issue

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

coilysiren commented

2026-07-02 04:33:30 +00:00

Owner

WARD-OUTCOME: done - clarified config precedence, aligned the README with the build/test/install contract, and removed the private-workspace pointer from AGENTS.md.\n\nThis was mostly straightforward; the only friction was making the config-discovery page read like a user contract instead of code notes. I’m reasonably confident in the wording, but the repo still has unrelated generated-asset drift in test output, so I did not try to entangle that with this docs pass.

coilyco-ops commented

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

Author

Owner

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

Author

Owner

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

Author

Owner

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

docs(config): finish config-discovery user-contract polish (ward#439)

coilysiren commented

2026-07-02 07:56:18 +00:00

Owner

WARD-OUTCOME: done - finished the config-discovery user-contract rewrite; the AGENTS.md pointer and README/exec-verb verb-triple alignment had already landed.

Walking in cold, I found most of this issue already resolved: a prior run 2 pass (commit 2c06290) had removed the private-workspace pointer from AGENTS.md (checkbox 1) and aligned the README "What it does" section with exec-verb.md on the build/test/install triple (checkbox 3). The surprise was checkbox 2 being only half done - that pass stripped the preParseConfigFlag / os.Args / "legacy behavior" narration but left docs/config-discovery.md still naming the internal repocfg.Load function twice, which is exactly one of the internal names the issue calls out. So the honest state was 2.5 of 3.

I recast the remaining prose as a user-observable contract: precedence, candidate filenames, and an Errors section phrased in terms of what a config author actually sees, no internal function names. Small, low-risk, docs-only. Confidence is high - pre-commit's dead-cross-links and layout hooks pass, and there's no runtime surface to regress.

No follow-ups worth filing. One meta-observation: this is the kind of issue where a second dispatch mostly verifies rather than builds, so the value was in reading the diff carefully enough to catch the one checkbox that looked done but wasn't.

WARD-OUTCOME: done - finished the config-discovery user-contract rewrite; the AGENTS.md pointer and README/exec-verb verb-triple alignment had already landed. Walking in cold, I found most of this issue already resolved: a prior run 2 pass (commit 2c06290) had removed the private-workspace pointer from AGENTS.md (checkbox 1) and aligned the README "What it does" section with exec-verb.md on the build/test/install triple (checkbox 3). The surprise was checkbox 2 being only *half* done - that pass stripped the `preParseConfigFlag` / `os.Args` / "legacy behavior" narration but left `docs/config-discovery.md` still naming the internal `repocfg.Load` function twice, which is exactly one of the internal names the issue calls out. So the honest state was 2.5 of 3. I recast the remaining prose as a user-observable contract: precedence, candidate filenames, and an Errors section phrased in terms of what a config author actually sees, no internal function names. Small, low-risk, docs-only. Confidence is high - pre-commit's dead-cross-links and layout hooks pass, and there's no runtime surface to regress. No follow-ups worth filing. One meta-observation: this is the kind of issue where a second dispatch mostly verifies rather than builds, so the value was in reading the diff carefully enough to catch the one checkbox that looked done but wasn't.

Rows
Columns

polish batch, run 2: yaml-config #439

Why

Deliverable / Done condition