spec-kitty-cli 3.2.0rc15__tar.gz → 3.2.0rc16__tar.gz

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/CHANGELOG.md

@@ -9,6 +9,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.2.0rc16] - 2026-05-20
+
+Ships the Phase 4 canary launch-gate unblock: the actual root-cause fix for
+`#1141` and the parser/classification fix for `#1182`.
+
+- Closes `#1182`: `_parse_event_results` in `src/specify_cli/sync/batch.py`
+  now routes per-event `status="queued"` / `status="pending"` responses to a
+  new `pending_count` bucket on `BatchSyncResult` instead of folding them
+  into the rejected catch-all with `category=unknown`. `sync now` previously
+  reported durably-queued events as `Errors: N (unknown: N)` and exited
+  non-zero when the in-process final-sync hit its 5s timeout; pending-only
+  drains now exit 0 and surface as `Pending: N` in the summary. Queue
+  mutation policy unchanged (pending rows are left for the next daemon tick,
+  same disposition as `failed_transient`).
+- Closes `#1141` (companion fix in `spec-kitty-end-to-end-testing#45`): the
+  canary scenario 4 `move-task --to planned` invocation was omitting
+  `--review-feedback-file`, so the CLI hard-rejected the command at the
+  argument-validation layer before reaching `emit_status_transition`. The
+  rc15 diagnostic breadcrumb in `fire_saas_fanout` could never fire because
+  the codepath never reached fan-out. The e2e fix passes a structured
+  feedback markdown so the backward emit actually lands. No CLI change is
+  required; the events #32 force-required contract and the CLI's
+  review-feedback hardening are both intentional and remain in force.
+- New unit coverage in `tests/sync/test_batch_error_surfacing.py` pins the
+  contract: per-event `queued` / `pending` are not errors, never count
+  toward `success_count` (they are durable in-flight, not terminal), but
+  do count toward sync activity so the "no progress" guard does not fire
+  on a pending-only drain.
+
 ## [3.2.0rc15] - 2026-05-19
 
 Ships the Phase 4 canary unblock work landed via PR `#1180`:

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-kitty-cli
-Version: 3.2.0rc15
+Version: 3.2.0rc16
 Summary: Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation.
 Project-URL: Repository, https://github.com/Priivacy-ai/spec-kitty
 Project-URL: Issues, https://github.com/Priivacy-ai/spec-kitty/issues
@@ -136,6 +136,7 @@ It is probably overkill for one-off edits, tiny scripts, or teams that do not us
 | Avoid branch chaos | Isolated git worktrees under `.worktrees/` |
 | See progress | Optional local kanban dashboard with `spec-kitty dashboard` |
 | Integrate agents | Slash commands or skills for common AI coding tools |
+| Learn from missions | Every completed mission generates a retrospective by default. Tune via `.kittify/config.yaml#retrospective` or charter; see [how-to](docs/how-to/use-retrospective-learning.md). |
 
 ## Quick Start
 

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/README.md

@@ -37,6 +37,7 @@ It is probably overkill for one-off edits, tiny scripts, or teams that do not us
 | Avoid branch chaos | Isolated git worktrees under `.worktrees/` |
 | See progress | Optional local kanban dashboard with `spec-kitty dashboard` |
 | Integrate agents | Slash commands or skills for common AI coding tools |
+| Learn from missions | Every completed mission generates a retrospective by default. Tune via `.kittify/config.yaml#retrospective` or charter; see [how-to](docs/how-to/use-retrospective-learning.md). |
 
 ## Quick Start
 

spec_kitty_cli-3.2.0rc16/architecture/2.x/adr/README.md

@@ -0,0 +1,25 @@
+# 2.x ADRs
+
+Architectural Decision Records for the 2.x track. **Not the current track —
+see [`architecture/3.x/adr/`](../../3.x/adr/README.md) for current decisions.**
+
+## Naming
+
+- `YYYY-MM-DD-N-descriptive-title-with-dashes.md`
+
+## Source of Truth
+
+This folder is canonical for 2.x decisions (dates before 2026-03-30, the
+3.0.0 release). ADRs dated on or after 2026-03-30 were moved to
+[`architecture/3.x/adr/`](../../3.x/adr/README.md); back-compat symlinks at
+the old `architecture/2.x/adr/<filename>` paths point at the new location so
+existing references in CHANGELOG entries, test snapshots, and shipped docs
+continue to resolve.
+
+Legacy links through `architecture/adrs/` are 1.x compatibility aliases.
+
+## Status Conventions
+
+- `Accepted` means the decision remains current policy.
+- `Superseded` means a newer ADR replaced the decision; keep the file for history, but do not implement from it.
+- `Deprecated` means the direction is in active retirement and should not receive new work.

spec_kitty_cli-3.2.0rc16/architecture/3.x/README.md

@@ -0,0 +1,39 @@
+# Architecture 3.x
+
+This directory is the current architecture track for Spec Kitty, starting with
+the 3.0.0 release on 2026-03-30.
+
+## What This Track Captures
+
+1. Core architecture decisions and constraints (`adr/`).
+2. (Future) End-to-end behavior expectations, initiatives, and layered C4
+   documentation analogous to the 2.x track.
+
+The 2.x track (`architecture/2.x/`) captured the architecture through the
+2.x → 3.x cutover. ADRs dated on or after 2026-03-30 live here in 3.x; older
+ADRs remain in `architecture/2.x/adr/`. Back-compat symlinks at the old
+`architecture/2.x/adr/<filename>` paths point at the new 3.x location so
+existing references — in CHANGELOG entries, test snapshots, and shipped
+docs — continue to resolve.
+
+## ADR Authoring
+
+Use the shared template at `architecture/adr-template.md`. The same template
+serves all tracks (1.x, 2.x, 3.x) — there is no per-track template fork.
+
+Naming: `YYYY-MM-DD-N-descriptive-title-with-dashes.md` where `N` increments
+per ADR landed on a given date (1, 2, 3…).
+
+## Cutover Note
+
+The 3.x track formally exists from this commit forward. ADRs landed before
+this restructuring that thematically belong to 3.x architecture (e.g. the
+shared-package-boundary cutover, mission-identity-uses-ULID, retrospective
+gate work) were moved here with their history preserved via `git mv`.
+
+## See Also
+
+- [3.x ADR Index](adr/README.md)
+- [2.x README](../2.x/README.md) — prior architecture track
+- [Top-level architecture README](../README.md)
+- [Shared ADR template](../adr-template.md)

spec_kitty_cli-3.2.0rc16/architecture/3.x/adr/README.md

@@ -0,0 +1,53 @@
+# 3.x ADRs
+
+Architectural Decision Records for the 3.x track (starting 3.0.0, released 2026-03-30).
+
+## Naming
+
+- `YYYY-MM-DD-N-descriptive-title-with-dashes.md` where `N` is `1, 2, 3, …` per ADR landed on a given date.
+
+## Source of Truth
+
+This folder is canonical for 3.x decisions. Back-compat symlinks at the old
+`architecture/2.x/adr/<filename>` paths point here so legacy references (in
+CHANGELOG entries, test snapshots, etc.) continue to resolve.
+
+## Status Conventions
+
+- `Accepted` means the decision remains current policy.
+- `Superseded` means a newer ADR replaced the decision; keep the file for history, but do not implement from it.
+- `Deprecated` means the direction is in active retirement and should not receive new work.
+
+## Template
+
+Use the shared template at [`../../adr-template.md`](../../adr-template.md).
+
+## Index
+
+| Date | Title |
+|---|---|
+| 2026-04-03 | [Execution lanes own worktrees and mission branches](2026-04-03-1-execution-lanes-own-worktrees-and-mission-branches.md) |
+| 2026-04-03 | [Review approval and integration completion are distinct](2026-04-03-2-review-approval-and-integration-completion-are-distinct.md) |
+| 2026-04-03 | [Feature acceptance runs on the integrated mission branch](2026-04-03-3-feature-acceptance-runs-on-the-integrated-mission-branch.md) |
+| 2026-04-04 | [Tracker binding context is discovered, not user-supplied](2026-04-04-1-tracker-binding-context-is-discovered-not-user-supplied.md) |
+| 2026-04-04 | [Mission type, mission, and mission run terminology boundary](2026-04-04-2-mission-type-mission-and-mission-run-terminology-boundary.md) |
+| 2026-04-06 | [WP state pattern for lane behavior](2026-04-06-1-wp-state-pattern-for-lane-behavior.md) |
+| 2026-04-07 | [Global slash command installation](2026-04-07-1-global-slash-command-installation.md) |
+| 2026-04-09 | [Mission identity uses ULID, not sequential prefix](2026-04-09-1-mission-identity-uses-ulid-not-sequential-prefix.md) |
+| 2026-04-09 | [CLI SaaS auth is browser-mediated OAuth, not password](2026-04-09-2-cli-saas-auth-is-browser-mediated-oauth-not-password.md) |
+| 2026-04-11 | [SaaS rollout and readiness](2026-04-11-1-saas-rollout-and-readiness.md) |
+| 2026-04-15 | [Explicit empty charter selections remain empty](2026-04-15-2-explicit-empty-charter-selections-remain-empty.md) |
+| 2026-04-19 | [CLI auth uses encrypted file-only session storage](2026-04-19-1-cli-auth-uses-encrypted-file-only-session-storage.md) |
+| 2026-04-19 | [Ticket delivery is CLI plumbing; specification is LLM content](2026-04-19-2-ticket-delivery-is-cli-plumbing-specification-is-llm-content.md) |
+| 2026-04-20 | [Mutation testing as a local-only quality gate](2026-04-20-1-mutation-testing-as-local-only-quality-gate.md) |
+| 2026-04-21 | [Private teamspace and repository sharing boundary](2026-04-21-1-private-teamspace-and-repository-sharing-boundary.md) |
+| 2026-04-25 | [Shared package boundary cutover](2026-04-25-1-shared-package-boundary.md) |
+| 2026-04-26 | [Contract pinning resolved version](2026-04-26-1-contract-pinning-resolved-version.md) |
+| 2026-04-26 | [Auth transport boundary](2026-04-26-2-auth-transport-boundary.md) |
+| 2026-04-26 | [E2E hard gate](2026-04-26-3-e2e-hard-gate.md) |
+| 2026-04-27 | [Retrospective gate shared module](2026-04-27-1-retrospective-gate-shared-module.md) |
+| 2026-05-01 | [Atomic work-package start lifecycle](2026-05-01-1-atomic-work-package-start-lifecycle.md) |
+| 2026-05-10 | [Deterministic historical mission-state repair](2026-05-10-1-deterministic-historical-mission-state-repair.md) |
+| 2026-05-14 | [Stale-lane auto-rebase classifier policy](2026-05-14-1-stale-lane-auto-rebase-classifier-policy.md) |
+| 2026-05-16 | [Doctrine layer merge semantics](2026-05-16-1-doctrine-layer-merge-semantics.md) |
+| 2026-05-19 | [Retrospective default-on policy architecture](2026-05-19-1-retrospective-default-policy-architecture.md) |

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/architecture/README.md

@@ -7,17 +7,20 @@ This directory is the canonical architecture corpus for Spec Kitty.
 | Path | Purpose |
 |---|---|
 | `architecture/1.x/` | Legacy architecture track (1.x), including 1.x ADRs |
-| `architecture/2.x/` | Current architecture track (2.x), including ADRs, user journeys, initiatives, and C4/domain models |
+| `architecture/2.x/` | Prior architecture track (2.x), captures the 2.x → 3.x cutover |
+| `architecture/3.x/` | Current architecture track (3.x), starting with the 3.0.0 release (2026-03-30) |
 | `architecture/audience/` | Persona catalog for architecture audiences and actor links |
 | `architecture/glossary/` | Architecture-level glossary landing page and pointers |
-| `architecture/adrs/` | Backward-compatibility links to moved ADR files |
-| `architecture/adr-template.md` | ADR template used by both tracks |
+| `architecture/adrs/` | Backward-compatibility links to moved 1.x ADR files (legacy compat shim) |
+| `architecture/adr-template.md` | Shared ADR template used by all tracks |
 
 ## Versioned ADR Locations
 
 - 1.x ADRs: `architecture/1.x/adr/`
-- 2.x ADRs: `architecture/2.x/adr/`
-- Legacy path compatibility: `architecture/adrs/` (symlink aliases)
+- 2.x ADRs: `architecture/2.x/adr/` (pre-3.0 dates only; 3.x-era moves live under `3.x/`)
+- 3.x ADRs: `architecture/3.x/adr/` (canonical for the current track)
+- Legacy 1.x path compatibility: `architecture/adrs/` (symlink aliases)
+- 2.x → 3.x move compatibility: each moved ADR retains a symlink at its old `architecture/2.x/adr/<filename>` path pointing into `architecture/3.x/adr/`, so CHANGELOG entries, test snapshots, and shipped docs that reference the old path continue to resolve.
 
 ## 2.x Architecture Model
 

spec_kitty_cli-3.2.0rc16/kitty-specs/unblock-sync-identity-boundary-canary-01KRZJ07/tasks/README.md

@@ -0,0 +1,64 @@
+# Tasks Directory
+
+This directory contains work package (WP) prompt files.
+
+## Directory Structure (v0.9.0+)
+
+```
+tasks/
+├── WP01-setup-infrastructure.md
+├── WP02-user-authentication.md
+├── WP03-api-endpoints.md
+└── README.md
+```
+
+All WP files are stored flat in `tasks/`. Status is tracked in `status.events.jsonl`, not in WP frontmatter.
+
+## Work Package File Format
+
+Each WP file **MUST** use YAML frontmatter:
+
+```yaml
+---
+work_package_id: "WP01"
+title: "Work Package Title"
+dependencies: []
+planning_base_branch: "main"
+merge_target_branch: "main"
+branch_strategy: "Planning artifacts were generated on main; completed changes must merge back into main."
+subtasks:
+  - "T001"
+  - "T002"
+phase: "Phase 1 - Setup"
+assignee: ""
+agent: ""
+shell_pid: ""
+history:
+  - timestamp: "2025-01-01T00:00:00Z"
+    agent: "system"
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+
+# Work Package Prompt: WP01 – Work Package Title
+
+[Content follows...]
+```
+
+## Status Tracking
+
+Status is tracked via the canonical event log (`status.events.jsonl`), not in WP frontmatter.
+Use `spec-kitty agent tasks move-task` to change WP status:
+
+```bash
+spec-kitty agent tasks move-task <WPID> --to <lane>
+```
+
+Example:
+```bash
+spec-kitty agent tasks move-task WP01 --to doing
+```
+
+## File Naming
+
+- Format: `WP01-kebab-case-slug.md`
+- Examples: `WP01-setup-infrastructure.md`, `WP02-user-auth.md`

spec_kitty_cli-3.2.0rc16/kitty-specs/unified-charter-bundle-chokepoint-01KP5Q2G/tasks/README.md

@@ -0,0 +1,64 @@
+# Tasks Directory
+
+This directory contains work package (WP) prompt files.
+
+## Directory Structure (v0.9.0+)
+
+```
+tasks/
+├── WP01-setup-infrastructure.md
+├── WP02-user-authentication.md
+├── WP03-api-endpoints.md
+└── README.md
+```
+
+All WP files are stored flat in `tasks/`. Status is tracked in `status.events.jsonl`, not in WP frontmatter.
+
+## Work Package File Format
+
+Each WP file **MUST** use YAML frontmatter:
+
+```yaml
+---
+work_package_id: "WP01"
+title: "Work Package Title"
+dependencies: []
+planning_base_branch: "main"
+merge_target_branch: "main"
+branch_strategy: "Planning artifacts were generated on main; completed changes must merge back into main."
+subtasks:
+  - "T001"
+  - "T002"
+phase: "Phase 1 - Setup"
+assignee: ""
+agent: ""
+shell_pid: ""
+history:
+  - timestamp: "2025-01-01T00:00:00Z"
+    agent: "system"
+    action: "Prompt generated via /spec-kitty.tasks"
+---
+
+# Work Package Prompt: WP01 – Work Package Title
+
+[Content follows...]
+```
+
+## Status Tracking
+
+Status is tracked via the canonical event log (`status.events.jsonl`), not in WP frontmatter.
+Use `spec-kitty agent tasks move-task` to change WP status:
+
+```bash
+spec-kitty agent tasks move-task <WPID> --to <lane>
+```
+
+Example:
+```bash
+spec-kitty agent tasks move-task WP01 --to doing
+```
+
+## File Naming
+
+- Format: `WP01-kebab-case-slug.md`
+- Examples: `WP01-setup-infrastructure.md`, `WP02-user-auth.md`

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "spec-kitty-cli"
-version = "3.2.0rc15"
+version = "3.2.0rc16"
 description = "Spec Kitty, a tool for Specification Driven Development (SDD) agentic projects, with kanban and git worktree isolation."
 readme = "README.md"
 license = { file = "LICENSE" }

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/charter/_drg_helpers.py

@@ -32,7 +32,7 @@ from doctrine.drg.models import DRGGraph
 from doctrine.drg.validator import assert_valid
 
 
-def _resolve_org_root(repo_root: Path) -> Path | None:  # noqa: ARG001
+def _resolve_org_root(_repo_root: Path) -> Path | None:
     """Return the configured org doctrine snapshot path, or ``None`` if absent.
 
     The charter-layer implementation is intentionally inert — it always returns

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/charter/neutrality/language_scoped_allowlist.yaml

@@ -34,6 +34,11 @@ paths:
     owner: "charter team"
     reason: "Spec Kitty itself is a Python package; setup-doctor skill necessarily references Python tooling."
     added_in: "3.2.0"
+  - path: "src/doctrine/skills/spec-kitty-setup-doctor/references/common-failure-signatures.md"
+    scope: python
+    owner: "charter team"
+    reason: "Setup-doctor failure-signature catalog intentionally documents Python interpreter and pip recovery commands."
+    added_in: "3.3.3"
   - path: "src/charter/corpus/python.corpus.yaml"
     scope: python
     owner: "charter team"

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/doctrine/agent_profiles/built-in/retrospective-facilitator.agent.yaml

@@ -36,16 +36,21 @@ purpose: >
 
 specialization:
   primary-focus: >
-    Mission retrospective facilitation: structured capture of helped / not-helpful /
-    gaps / proposals from a completed or terminated mission run, expressed as
-    schema-valid structured findings with provenance.
+    Human-mediated mission retrospective facilitation: structured capture of helped /
+    not-helpful / gaps / proposals from a completed or terminated mission run,
+    expressed as schema-valid structured findings with provenance. This profile is for
+    operator-initiated rich post-mortems. The runtime default generator (pure-Python
+    module) runs automatically at mission completion without invoking this profile.
   secondary-awareness: >
     Active DRG slice used during the mission, charter and doctrine artifacts surfaced,
     glossary terms in scope, mission output artifacts, lifecycle event stream.
   avoidance-boundary: >
     General code implementation, architectural decisions, product roadmap, planning,
     specifying, implementing, or reviewing mission work. This profile is ONLY active
-    at mission terminus and MUST NOT be invoked mid-mission.
+    at mission terminus or via explicit operator invocation. It MUST NOT be invoked
+    mid-mission. No structural auto-apply of doctrine, DRG, or glossary changes
+    (FR-010): proposals are data; application is a separate human-approved step via
+    `agent retrospect synthesize`.
   success-definition: >
     A complete, schema-valid retrospective.yaml that captures mission findings with
     provenance, proposes actionable governance improvements, and allows the mission
@@ -54,6 +59,7 @@ specialization:
 collaboration:
   handoff-to:
     - human-in-charge
+    - synthesize-command  # `agent retrospect synthesize` is the explicit ACL for proposal application
   handoff-from:
     - implementer
     - reviewer
@@ -72,7 +78,6 @@ collaboration:
     - retrospect
     - capture
     - propose
-    - synthesize
 
 mode-defaults:
   - mode: retrospective

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/doctrine/agent_profiles/repository.py

@@ -28,6 +28,7 @@ from .validation import reject_agent_profile_inline_refs
 
 _MAX_LOW_WORKLOAD = 2
 _MAX_MEDIUM_WORKLOAD = 4
+_AGENT_PROFILE_GLOB = "*.agent.yaml"
 
 
 def _filter_candidates_by_role(candidates: list[AgentProfile], required_role: str | None) -> list[AgentProfile]:
@@ -234,7 +235,7 @@ class AgentProfileRepository:
         shipped_profiles: dict[str, AgentProfile] = {}
 
         if self._shipped_dir.exists():
-            for yaml_file in self._shipped_dir.rglob("*.agent.yaml"):
+            for yaml_file in self._shipped_dir.rglob(_AGENT_PROFILE_GLOB):
                 try:
                     data = yaml.load(yaml_file)
                     if data is None:
@@ -264,7 +265,7 @@ class AgentProfileRepository:
 
         # Load and merge project profiles
         if self._project_dir and self._project_dir.exists():
-            for yaml_file in self._project_dir.glob("*.agent.yaml"):
+            for yaml_file in self._project_dir.glob(_AGENT_PROFILE_GLOB):
                 try:
                     data = yaml.load(yaml_file)
                     if data is None:
@@ -329,7 +330,7 @@ class AgentProfileRepository:
         """
         if not org_dir.exists():
             return
-        for yaml_file in org_dir.glob("*.agent.yaml"):
+        for yaml_file in org_dir.glob(_AGENT_PROFILE_GLOB):
             try:
                 data = yaml.load(yaml_file)
                 if data is None:

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/doctrine/skills/spec-kitty-implement-review/SKILL.md

@@ -754,6 +754,37 @@ for wp in WP01 WP02 WP03 WP04 WP05 WP06; do
 done
 ```
 
+### Post-Merge Retrospective Sequence
+
+After WPs are marked done, follow the canonical post-merge sequence:
+
+**1. Mission review** — dispatch the `spec-kitty-mission-review` skill to confirm spec→code
+fidelity and FR coverage.
+
+**2. Author or verify the retrospective** — under default 3.2.0 policy the record is written
+during merge. Verify:
+
+```bash
+cat .kittify/missions/$(jq -r .mission_id kitty-specs/<slug>/meta.json)/retrospective.yaml
+```
+
+If absent (older mission or generation failed), author it:
+
+```bash
+spec-kitty retrospect create --mission <mission-slug>
+```
+
+**3. Surface findings**:
+
+```bash
+spec-kitty retrospect summary                              # cross-mission aggregation (read-only)
+spec-kitty agent retrospect synthesize --mission <slug> --preview  # inspect proposals
+spec-kitty agent retrospect synthesize --mission <slug> --apply <id>  # apply a proposal
+```
+
+`summary` aggregates; it does NOT author. `synthesize` previews and applies proposals from an
+existing record; it does NOT author. Use `retrospect create` to author.
+
 ---
 
 ## Key Rules

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/doctrine/skills/spec-kitty-mission-review/SKILL.md

@@ -39,9 +39,11 @@ do not fix anything. You document.
 
 This is not the pre-merge acceptance gate. Run `spec-kitty accept --mission
 <slug>` before merge; use this skill after merge for final spec-to-code review.
-After this mission review, remind the operator to review the retrospective
-that was captured at terminus (`spec-kitty retrospect summary` /
-`spec-kitty agent retrospect synthesize`) while the work is still fresh.
+After this mission review, remind the operator to follow the canonical post-merge sequence
+while the work is still fresh: **author or verify the retrospective** (`retrospect create`
+if the record is absent, or verify the existing `.kittify/missions/<mission_id>/retrospective.yaml`);
+**surface findings** (`spec-kitty retrospect summary` for cross-mission aggregation;
+`spec-kitty agent retrospect synthesize --mission <slug> --preview` to inspect proposals).
 
 ---
 
@@ -770,17 +772,31 @@ follow-up mission.]
 
 ## Retrospective Reminder
 
-The mission's `retrospective.yaml` is authored at the runtime terminus (HiC
-prompt or autonomous facilitator), not after merge. Before context decays,
-review the captured retrospective and apply any staged proposals:
+The canonical post-merge sequence is: **mission review → author or verify retrospective
+(`retrospect create`) → surface findings (`summary` aggregates; `synthesize` reviews proposals)**.
 
-- `spec-kitty retrospect summary` — cross-mission view (read-only)
-- `spec-kitty agent retrospect synthesize --mission <slug>` — apply staged
-  proposals from the authored `retrospective.yaml` (dry-run by default;
-  add `--apply` to mutate)
+Under default 3.2.0 policy, the `retrospective.yaml` record is authored automatically during
+merge. Verify it exists:
 
-If the record does not exist, escalate — the terminus facilitator either did
-not run or was skipped without a recorded reason.
+```bash
+cat .kittify/missions/$(jq -r .mission_id kitty-specs/<slug>/meta.json)/retrospective.yaml
+```
+
+If the file is absent (older mission, or generation failed), author it:
+
+```bash
+spec-kitty retrospect create --mission <slug>
+```
+
+Then surface findings:
+
+- `spec-kitty retrospect summary` — cross-mission aggregation (read-only; does NOT author)
+- `spec-kitty agent retrospect synthesize --mission <slug> --preview` — inspect proposals
+- `spec-kitty agent retrospect synthesize --mission <slug> --apply <id>` — apply a proposal
+
+If the record is absent and `retrospect create` fails, escalate — the terminus facilitator
+either did not run or was skipped without a recorded reason. Check `status.events.jsonl` for
+`RetrospectiveCaptureFailed` events and their `remediation_hint` field.
 ```
 
 ---

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/doctrine/skills/spec-kitty-program-orchestrate/SKILL.md

@@ -211,17 +211,31 @@ races on external side effects).
 
 ### 2i. Phase 8 — Retrospective
 
-The mission's `retrospective.yaml` is captured earlier at the runtime
-terminus. After mission review, review what was captured and apply staged
-proposals every time:
+The canonical post-merge sequence is: **mission review → author or verify retrospective
+(`retrospect create`) → surface findings (`summary` aggregates; `synthesize` reviews proposals)**.
+
+Under default 3.2.0 policy, the `retrospective.yaml` is authored during merge. Verify it:
+
+```bash
+cat .kittify/missions/$(jq -r .mission_id kitty-specs/<slug>/meta.json)/retrospective.yaml
+```
+
+If the record is absent (older mission or generation failed), author it now — context decays fast:
+
+```bash
+spec-kitty retrospect create --mission <slug>
+```
+
+Then surface findings:
 
 ```bash
-spec-kitty retrospect summary                       # cross-mission view
-spec-kitty agent retrospect synthesize --mission <slug>  # dry-run; --apply to mutate
+spec-kitty retrospect summary                              # cross-mission aggregation (read-only)
+spec-kitty agent retrospect synthesize --mission <slug> --preview  # inspect proposals
+spec-kitty agent retrospect synthesize --mission <slug> --apply <id>  # apply a proposal
 ```
 
-If `retrospective.yaml` is missing for the mission, escalate — the terminus
-facilitator either did not run or was skipped without a recorded reason.
+If `retrospective.yaml` is missing and `retrospect create` fails, escalate — check
+`status.events.jsonl` for `RetrospectiveCaptureFailed` events and their `remediation_hint`.
 
 ### 2j. Phase 9 — Post-Merge Remediation
 

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/doctrine/skills/spec-kitty-runtime-next/SKILL.md

@@ -117,7 +117,7 @@ Every call to `spec-kitty next` returns exactly one decision kind:
 | `step` | Normal action available | Read `prompt_file` and execute |
 | `decision_required` | Runtime needs input | Answer with `--answer` and `--decision-id` |
 | `blocked` | Guards failing, cannot proceed | Read `reason` + `guard_failures`, resolve blockers |
-| `terminal` | Mission complete | Run `/spec-kitty.accept`; if it passes, merge and continue to mission review + retrospective |
+| `terminal` | Mission complete | Run `/spec-kitty.accept`; if it passes, merge, then: mission review → author or verify retrospective (`retrospect create`) → surface findings (`summary` aggregates; `synthesize` reviews proposals) |
 
 ### Decision Output Fields
 
@@ -471,13 +471,19 @@ while [ "$KIND" = "step" ] || [ "$KIND" = "decision_required" ]; do
   KIND=$(echo "$DECISION" | jq -r '.kind')
 done
 
-# 3. Handle terminal state
+# 3. Handle terminal state — canonical post-merge sequence
 if [ "$KIND" = "terminal" ] || [ "$DONE" -eq "$TOTAL" ]; then
   # Run /spec-kitty.accept.
   # If acceptance passes, run /spec-kitty.merge.
-  # After merge, run /spec-kitty-mission-review and:
-  #   spec-kitty retrospect summary
-  #   spec-kitty agent retrospect synthesize --mission 042-mission
+  # After merge, follow the canonical post-merge sequence:
+  #   a. Mission review: /spec-kitty-mission-review
+  #   b. Author or verify retrospective:
+  #      spec-kitty retrospect create --mission 042-mission  # if record absent
+  #      OR verify: cat .kittify/missions/<mission_id>/retrospective.yaml
+  #   c. Surface findings:
+  #      spec-kitty retrospect summary                                   # read-only aggregation
+  #      spec-kitty agent retrospect synthesize --mission 042-mission --preview
+  # Note: summary aggregates; synthesize applies proposals — neither authors records.
 fi
 ```
 

{spec_kitty_cli-3.2.0rc15 → spec_kitty_cli-3.2.0rc16}/src/specify_cli/cli/commands/__init__.py

@@ -110,8 +110,8 @@ def register_commands(app: typer.Typer) -> None:
     app.command(name="do", help="Route a request to the best-matching profile (anonymous dispatch).")(do_cmd_module.do)
     app.add_typer(invocations_cmd_module.app, name="invocations")
 
-    from specify_cli.retrospective.cli import app as retrospect_app  # WP09
-    app.add_typer(retrospect_app, name="retrospect", help="Cross-mission retrospective summary")
+    from specify_cli.cli.commands.retrospect import app as retrospect_app  # WP05 (replaces WP09 single-command registration)
+    app.add_typer(retrospect_app, name="retrospect", help="Retrospective authoring and summary (create / backfill / summary)")
 
 
 __all__ = ["register_commands"]