[markuswondrak]

Summary

Fixes #27. In the Feature Flow, analyze could not influence anything: no gate followed it, core speckit.analyze is strictly read-only so it wrote no report, and the engine persists no stdout for command steps. The cross-artifact consistency check — the last safety net before code is written — was unreachable, and nothing survived the run.

This persists the report and gates on it.

Changes

• New preset analysis-report. Wraps speckit.analyze so its report is written to FEATURE_DIR/analysis.md, explicitly superseding the command's read-only constraint for that single file.
  • A wrap, not a third prepend: the command's own contract has to change, and the wrap composes as the outermost layer so the persistence instruction is the last thing the command reads.
  • A separate preset because Spec-Kit rejects a second declaration of the same command in one preset (Duplicate template name 'speckit.analyze'). Both the main preset and sub-agent-delegation already declare it.
  • Installed at priority 5, below the main preset's 10, so the wrap encloses the runtime and delegation prepends rather than the reverse.
• analyze-gate in workflows/workflow.yml, between analyze and implement, shaped exactly like spec-gate and plan-gate.
• Plumbing for the new component: bundle.yml, catalog/preset-catalog.json, scripts/build-catalog.py, scripts/check-release.py, scripts/release-version.py.
• Docs: docs/flows.md, docs/reference.md, README.md, AGENTS.md.

analysis.md is a run artifact: finish removes it with the rest of the feature directory, like review-findings.md and doc-check.md. It exists to be read at the gate, not to outlive the run.

No new runtime scripts. No hand-edited versions — release-version.py owns those.

Testing

python3 -m unittest discover -s tests -t . → 74 passed (was 69; +5).

New coverage:

• AnalysisReportStaticContracts: speckit.analyze declared exactly once with wrap; wrapper carries {CORE_TEMPLATE}, FEATURE_DIR/analysis.md, and the supersede clause; bundle priority < 10; gate and preset documented.
• Feature Flow ordering: analyze → analyze-gate → implement, with options: [approve, reject] and on_reject: abort.
• Maintenance: 5 catalog archives, bundle.yml pin count 8, new catalog pin.

Verified against real specify 1.0.13 in a scratch project:

Composition chain for speckit.analyze:
  1. [base]    core
  2. [prepend] sub-agent-delegation v0.20.0
  3. [prepend] spec-kit-extended-flow v0.20.0
  4. [wrap]    analysis-report v0.20.0

Composed file order: persistence head → runtime preamble → delegation preamble → core read-only clause → core report format → persistence tail.

The Feature Flow installs as 16 steps with analyze-gate between analyze and implement. python3 scripts/check-release.py 0.20.0 passes.

Not covered by an automated end-to-end run: the gate actually pausing in a live Feature Flow run — that needs a dispatched agent session.

Documentation

docs/flows.md gains the gate in the mermaid diagram and step table, and its "human gates let you inspect and approve each phase" claim is now true. docs/reference.md gains a ### Analysis report section covering the wrap/prepend choice, the priority constraint, and the artifact lifecycle. README.md gains a feature bullet and the manual-install step. AGENTS.md records the new component and the split between preset and gate.

Closes #27