docs: add worktree verification recipes

[pepmach]

Add worktree verification recipes and discoverability wiring

Slice 5 — the final slice — of the verification-controller plan. An agent that changed Kiro Crew code can now follow a documented, copy-pasteable trace to prove the change against a real running Kiro Crew instead of rediscovering the command sequence. No new verbs, no new CLI code, no new fixtures: documentation and discoverability only.

The doc

docs/guides/worktree-verification-recipes.md — four end-to-end traces, each stating what it asserts, not just what it runs:

1. Prove a backend change — pod scenarios → pod up --seed minimal --json → pod api GET <endpoint> with a jq assertion against the seeded state → pod down. Shows how the feature map turns a user-facing feature into the handler and endpoint to hit, with the Schedule → /api/crons row as the worked example.
2. Prove a frontend change — same boot with rich, then the pod-e2e harness (real invocation, including --no-suppress-first-run from fix: forward --no-suppress-first-run through the pod-e2e harness #8087), verdict-file and screenshot-evidence assertions, and the PLAYWRIGHT_SPEC hook for feature-specific assertions.
3. Drive an agent inside the pod — the pre-existing /api/session-control/{create,send,read,stop,close} routes with payload shapes verified against the dashboard server source.
4. Diagnose and reclaim — pod ls/status/logs/prune.

Discoverability: a root AGENTS.md "Read before you touch" row, the docs/guides/README.md index entry, and a section in the packaged kirocrew-worktree-dev skill (under src/kiro_crew/builtin_skills/, the path that reaches installed users).

Honest finding recorded in the doc

Recipe 3 is not executable through #8218 as implemented: the session-control routes require a validated X-Internal-Secret and take the caller from X-Session-Key, while pod api sends only the dashboard query token. A live probe returned HTTP 403 internal_secret_required. The doc says so plainly and keeps the trace as the acceptance criteria for closing that gap, rather than presenting it as working. Whether to extend pod api for it is a scope decision deliberately not made here.

Accuracy discipline

Every command was verified against CLI source; the lifecycle and diagnostic traces were additionally executed live: scenario listing, seeded minimal boot, /api/crons returning 200 with both fixture jobs, health 200, zero-residue teardown. pod api syntax was verified against PR #8218's implementation; because this doc may merge first, it states which commands are on main today and which arrive with #8218, and its recipes preflight for the verb's presence. Only the three packaged scenarios (empty, minimal, rich) are used; the ten specialized payloads stay deferred until a recipe demonstrates need.

Verification

Docs lint (259 files), brand, and harness-parity gates green; all seven bash blocks pass bash -n; the 33 skill-wiring tests pass. 4 files, +273/−0, docs and skill only.

[github-actions]

Design Review (Fable 5) — 🟡 CONCERNS

Design-level review of 9414480aa7ca363c8a675daa8df62a2cd1f65c6a — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

Solid, honest verification guide — but it bakes an unmerged PR's interface and number into main and a shipped skill, held in sync only by prose.

Watch

• Merge-order coupling with no enforcement. PR feat(pod): add the authenticated pod api command #8218 is still open, yet this doc instructs "do not merge it first" and duplicates pod api's contract (--allow-write, the name/method/path/status/ok/body JSON shape, token minting) in prose. The preflight (grep -qw api) catches the verb's absence, not interface drift — if feat(pod): add the authenticated pod api command #8218's flags or JSON shape change in review, recipes 1 and 3 diverge silently and nothing goes red. Either land this inside/after feat(pod): add the authenticated pod api command #8218, or move the pod api contract description into that PR's own doc and link it, keeping one owner per interface.
• Stale-by-construction prose in shipped bytes. "arrives with PR feat(pod): add the authenticated pod api command #8218" appears in both the guide and the packaged kirocrew-worktree-dev skill (which reaches installed users via ~/.kiro/crew/skills/); it becomes wrong the day feat(pod): add the authenticated pod api command #8218 merges, and no gate forces the reconciling edit. Recipe 3 additionally ships as an admittedly non-executable acceptance trace with its closing scope decision deferred — fine as a recorded gap, but it has no owner or trigger, so plan the follow-up that either closes or removes it.

Suggestions

• Phrase availability by capability ("if pod api is installed") rather than by PR number, so the doc self-heals when feat(pod): add the authenticated pod api command #8218 lands instead of needing a same-round edit.

[DESIGN-REVIEWED] 9414480

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

Reviewed 9414480aa7ca363c8a675daa8df62a2cd1f65c6a — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 9414480

Verdict parsed from the review's SHA-scoped output markers for commit 9414480aa7ca363c8a675daa8df62a2cd1f65c6a.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 9414480aa7ca363c8a675daa8df62a2cd1f65c6a: <one-sentence reason>

[github-actions]

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 9414480aa7ca363c8a675daa8df62a2cd1f65c6a — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

All references verified: the feature map, fixtures, and pod-e2e skill exist; docs/system-specs/modules/session-control.md already carries the authoritative session-control route table; pod api appears nowhere in the repo (it lives in unmerged PR #8218). I have what I need to emit the review.

First-Principles-Verdict: CONCERNS

A guide of "copy-pasteable proof traces" ships one trace documented as failing and pins an unmerged PR's interface, with merge choreography baked into permanent docs.

What this change ships

Intent: let an agent prove a code change against an isolated running gateway by following documented traces. ADDITION.

1. Backend proof recipe (pod up → pod api → jq assert) — justified; depends on unmerged feat(pod): add the authenticated pod api command #8218
2. Frontend proof recipe deferring to the pod-e2e skill — justified
3. Agent-driving recipe, documented as non-executable (HTTP 403) — dead trace; table duplicate of session-control.md
4. Diagnose/reclaim recipe (pod ls/status/logs/prune) — justified; recipe form, not a spec restatement
5. "Command availability" section with feat(pod): add the authenticated pod api command #8218 sequencing narrative and preflight guards — task-log content, stale on merge
6. AGENTS.md router row — justified (mandated index discipline)
7. docs/guides/README.md index entry — justified (docs-lint mandate)
8. Packaged SKILL.md section citing "PR feat(pod): add the authenticated pod api command #8218" — reaches installed users who cannot act on a PR number

Watch

• Recipe 3's route table restates docs/system-specs/modules/session-control.md:19-23 (grepped session-control/(create|send|read|stop|close): 2 docs now carry it); a payload change must be synced twice, and one copy sits inside a recipe that cannot run.
• The doc specifies pod api's JSON fields and --allow-write semantics from an unmerged PR, guarded only by prose ("do not merge it first") no gate checks — if feat(pod): add the authenticated pod api command #8218's interface shifts in review, main documents a command that never existed in that shape.

Subtractions

• Defer recipe 3's 36-line bash block to the PR that closes the pod api session-control gap (the same-commit spec rule puts it there); keep at most a one-line pointer to session-control.md.
• Since the guide already forbids merging before feat(pod): add the authenticated pod api command #8218, land it in/after feat(pod): add the authenticated pod api command #8218 and delete the "Command availability" not-on-main scaffolding and both duplicate preflight blocks.
• Drop the "arrives with PR feat(pod): add the authenticated pod api command #8218" paragraph from the packaged kirocrew-worktree-dev/SKILL.md — that copy ships to ~/.kiro/crew/skills/ where the PR number is noise.

[FIRST-PRINCIPLES-REVIEWED] 9414480

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 9414480aa7ca363c8a675daa8df62a2cd1f65c6a and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 9414480

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 9414480aa7ca363c8a675daa8df62a2cd1f65c6a: <one-sentence reason>

[pepmach]

• FIXED — pod-api contract sequencing is explicit. span=a31cc19c358c

  The guide now says it must not merge before feat(pod): add the authenticated pod api command #8218 and requires recipes 1 and 3 to update in the same review round if that interface changes; both recipes also fail closed when the verb is absent.

[pepmach]

• REBUTTED — the failed session-control trace is deliberately executable acceptance criteria. span=a31cc19c358c

  Making it look green would be false: session-control requires internal authentication plus caller identity that pod api does not provide. The guide identifies the expected 403 and forbids claiming success; closing that compatibility contract requires a separate owner ruling, so the exact route/body assertions remain as the measurable acceptance trace.

[pepmach]

• FIXED — fixture-owned cron names now link to their source. span=a31cc19c358c

  Recipe 1 now links the asserted names directly to src/kiro_crew/tests_fixtures/minimal/crons.json, so a fixture edit has an adjacent discoverability path back to the assertion.

[pepmach]

• FIXED — the smaller sequencing invariant prevents premature authority. span=be9e003f030b

  Recipes 1 and 3 remain in the final discoverability slice, but the guide now explicitly depends on feat(pod): add the authenticated pod api command #8218 landing first, requires same-round updates for interface drift, and preflights the verb before either trace runs.

[pepmach]

• REBUTTED — deleting the failing trace would discard the compatibility acceptance bar. span=be9e003f030b

  The trace has zero claimed green value today: the guide labels it non-executable, names both missing capabilities, and records the expected internal_secret_required response. Keeping the exact create/send/read/stop/close assertions prevents a future partial authentication fix from being mistaken for agent-driving support; no new verb or protocol is added here.

[pepmach]

• FIXED — recipe 2 now contains only the worktree-proof delta. span=be9e003f030b

  The guide links the owning pod-e2e skill for flags, manifest syntax, authenticated Playwright context, and artifact semantics; duplicate PLAYWRIGHT_SPEC and harness-contract prose was removed. The recipe retains only seeded boot, invocation, verdict, and screenshot assertions.

[bolichen97]

Open PR relationship audit

This is a consolidated, point-in-time code-level audit note. It compares complete merge-base diffs and current/merged code; it does not treat a shared topic as duplication or partial coverage as completion.

Relationship findings

• PR #8218 is OVERLAPPING relative to this PR. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #8218: KEEP. 8223 consumes and documents this verb. Keep both and land 8218 first, or 8223 ships a recipe naming a command that does not exist. Files: docs/guides/worktree-verification-recipes.md.
• This PR is OVERLAPPING with PR #8213. The goals differ or the implementations can complement each other; this is not a duplicate claim. Recommended action for PR #8223: MERGE_DISCUSSION. Complementary and non-conflicting: the merged PR sets up the preview path this PR turns into a proof step. Files: src/kiro_crew/builtin_skills/kirocrew-dev/kirocrew-worktree-dev/SKILL.md.

No PR, Issue, label, branch, or review state was changed by the relationship-note portion of this audit.

[bolichen97]

Docs + packaged-skill only (0 deletions, no code), and the factual claims hold up against the source rather than just reading plausibly: the minimal fixture's job names are exactly "daily minimal fixture ping" and "paused weekly recap", the five session-control routes and their methods match handlers/session_control.py, and the recorded 403 code: internal_secret_required is that module's real denial. The part I'd normally push back on is instead the best thing here — Recipe 3 is documented as NOT executable through #8218 and kept as an acceptance trace, rather than shipped as a green recipe that returns 403. Non-blocking: the guide is explicitly sequenced after #8218 and its pod api recipes preflight on the verb's presence, so landing this first degrades to a self-describing failure rather than a silently wrong instruction — but it should still merge after #8218 as the doc asks.