feat: add pod scenarios discovery command

[pepmach]

Add the pod scenarios discovery command

Slice 2 of the verification-controller plan: pod up --seed <scenario> (merged in #7841) accepts packaged scenario names, but nothing lists what those names are — an agent or operator had to read the fixtures tree. This adds the discovery verb and nothing else.

kirocrew pod scenarios [--json]

Behavior

• Deterministic, sorted listing of the packaged fixture registry: human output is a SCENARIO DESCRIPTION table ending with a copy-pasteable pod up --seed hint; --json emits a stable [{"name", "description"}] array.
• Descriptions come from the first line of each fixture manifest's description: scalar via a narrow dependency-free parser (plain scalars and |/> blocks). PyYAML stays out of the runtime dependency set — the recorded feat: seed pod homes from named scenarios #7841 decision — and a test pins this by nulling sys.modules["yaml"]. A missing or malformed description degrades to an empty field, never a command failure.
• Empty registry is explicit: [] in JSON mode, a one-line diagnostic in human mode, exit 0 either way. Unknown flags exit 2 via argparse.

Scope

Command + focused tests + command docs only (docs/system-specs/modules/cli.md row, pod README section). No fixture additions, no lifecycle changes, no auth or HTTP code, no recipes. pod/runtime.py is untouched; seed.py gains only the read-only fixture_summary helper. 6 files, +188/−3.

Verification

• Red-first: all 6 focused tests failed before the implementation, pass after. Coverage: sorted human table, stable JSON, unknown-flag rejection, sorting under a shuffled registry, empty-registry behavior in both modes, and the no-PyYAML pin.
• Subprocess tests run the real parser outside the checkout with isolated HOME/KIROCREW_HOME and pinned encoding.
• 335 focused tests passed, 1 skipped; Black ratchet, subprocess-encoding, isort, flake8, mypy (1,277 files), docs lint all green.

Next in the plan (sequential lane): pod api opens after this merges, per the one-pod-capability-PR-at-a-time rule.

[github-actions]

GPT 5.6 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

FINDING -- src/kiro_crew/pod/cli.py:925 -- function-local "from kiro_crew import seed as seed_mod" violates top-level-imports -> Fix: move it to the module import block.
[GPT-REVIEWED] fc53bb5

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

[github-actions]

Design Review (Fable 5) — ✅ PASS

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

All context gathered. The verb is per-verb gated (works cross-platform, correct for a read-only listing), the helper sits in the right layer (seed.py beside available_fixtures), the surface is additive and reversible, and docs/tests ship in the same commit. The one design-level observation: all three shipped manifests author description: as hard-wrapped block-scalar prose, so the "first line" extraction yields mid-sentence fragments ("…The gateway writes its", "…preferences/projects/semantic/") — the test even pins the truncated fragment. That's an actionable mismatch between the extraction contract and the data it reads, but not a design risk worth blocking on.

Design-Verdict: PASS

A real discovery gap, closed with a proportionate additive verb; layering, cross-platform behavior, and degradation story are all right.

Suggestions

• The first-physical-line contract clashes with the data: all three shipped manifests hard-wrap description: prose, so every table row is a mid-sentence fragment (the test pins "…preferences/projects/semantic/"). Either join lines up to the first blank line / sentence end, or give the three manifests a deliberate one-line opening — cheap, in-repo, and it makes the description column actually readable.

[DESIGN-REVIEWED] fc53bb5

[github-actions]

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of fc53bb52c2fb949c5f0e7cbbae18548d8ab4a6a0 — 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.

I have everything I need: the contract, the intent, the patch, seed.py, the frontmatter.py module (the repo's declared "single home" for hand-rolled YAML-subset parsing, including its one block-scalar recognizer), a fixture manifest, and the --json siblings on other pod verbs. Producing the review now.

First-Principles-Verdict: CONCERNS

fixture_summary re-introduces the bare-indicator block-scalar recognizer that frontmatter.py explicitly consolidated away, and re-sorts a registry that already guarantees sorted order.

What this change ships

Intent: let an operator or agent list the seed scenario names pod up --seed accepts, with descriptions — an ADDITION.

1. New pod scenarios verb prints a name/description table plus a seed hint — justified
2. --json emits a stable {name, description} array — justified
3. Empty registry exits 0 with [] / a one-line diagnostic — justified
4. New public seed.fixture_summary() description parser — declared; duplicates an existing recognizer
5. Handler re-sorts, with a test pinning the re-sort — duplicate of available_fixtures' own contract
6. Doc rows in cli.md and pod README — justified (AGENTS.md same-commit rule)

Watch

• seed.py's new block_markers = {"|", "|-", "|+", ">", ">-", ">+"} is byte-for-byte the "frozenset of the six BARE indicators" that src/kiro_crew/frontmatter.py:69-76 records removing so the repo would have "one matcher now" — parse_block_scalar_header() is public and does this job (grep: the set exists nowhere else; the recognizer exists once, there).
• available_fixtures() already returns sorted(...) (src/kiro_crew/seed.py:107, docstring "stable order"), and both prior consumers (pod/runtime.py:1838, the error path at seed.py:184) rely on it; the handler's sorted(...) and test_handler_sorts_even_if_registry_order_changes pin the ordering contract in a second place, which can now drift from the first.

Subtractions

• Replace the block_markers set in seed.fixture_summary with frontmatter.parse_block_scalar_header(value) is not None — one recognizer, per that module's own consolidation note.
• Drop sorted(...) in pod/cli.py:_scenarios and the re-sort test; the ordering guarantee already lives in available_fixtures().

[FIRST-PRINCIPLES-REVIEWED] fc53bb5

[github-actions]

Opus 4.8 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] fc53bb5

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

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

[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 #8222 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 #8222: KEEP. PR #8127 is the merged predecessor that created the defect; nothing in it or in current main covers the fix. Files: src/kiro_crew/seed.py, src/kiro_crew/pod/cli.py.

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