Plan: Issue 207 Verification Recovery Skill Distribution

Initial Situation

Rebase Reconciliation

Issue #206 supersedes this plan's former production-catalog step: it registers both lifecycle IDs and makes the verification pack their only pack owner. T1/IP-473 now preserves that inherited registry ordering, adapts the public registry assertion to the verification pack, and verifies that the combined default scaffold still installs implement-spec with the three verification skills without changing verifier-reference ownership. Historical planning-pack statements below remain evidence of the original branch state.

The bundled planning pack includes verify-behavior and implement-spec, but the CLI skill catalog and planning pack omit create-verification-skill and update-verification-skill even though both packaged source directories exist. A fresh scaffold therefore installs a workflow that cannot recover an Uncovered Surface or Uncovered Behavior as directed by implement-spec.

GitHub issue #207 is compiled into the immutable agent-ready specification. Linear Story IP-472 and Task IP-473 retain the same authority, CLI placement, V4.3 Delivery Flow and Scaffold Reliability milestone, and empty blocker graph.

Solution Shape

Register both existing lifecycle skill sources in the CLI catalog and add both IDs to the planning pack. Protect the behavior first through the public bundled skill/pack seam, then extend the existing end-to-end Project Verifier scaffold test to prove the generated manifest contains all four cooperating planning skills without changing project-owned verifier-reference bytes. Update the required scaffold documentation and baseline release notes. No new abstraction or architecture boundary is needed.

Decision Ledger

The issue #207 delta is a mixed baseline/npm release because the catalog and pack ship in both artifacts. The next CLI patch version is derived from the final issue #206 head. The ambiguity frontier is empty: actor, outcome, non-goals, public verification seam, release surface, and branch topology are fixed by the issue, specification, repository guidance, and user instruction. No plan-shaping question remains.

Architecture Applicability

architecture_applicability: local

Evidence: the change adds two entries to existing data catalogs and exercises existing scaffold resolution/materialization. It does not change an owner, public seam, composition root, cross-domain dependency, or caller contract. The existing catalog is the module interface, skillsForPack/the bundled registry are the test seam, and scaffold output remains the consumer.

Dependency Readiness

Dependency gate passed. Branch team/stefan/issue-207-verification-recovery-skills is restacked on final issue #206 commit b949b3d6aec0f65e6ec09aeb865f006e3e4c4629, which contains final issue #205 commit 79fd44b7935162db83aca72f42c0f6f967bd1081. The parent version is 5.0.2, so issue #207 correctly advances the CLI to 5.0.3 and carries mixed baseline/npm notes.

Branch/Base Intent

• Child branch: team/stefan/issue-207-verification-recovery-skills.
• Pull-request base: team/stefan/issue-206-skill-activation-boundaries.
• Stack constraint: issue #206 retains its issue #205 ancestry; issue #207 must contain the final issue #206 head.
• Proof after git fetch origin --prune: resolve immutable issue205_sha and issue206_sha from origin/team/stefan/issue-205-effect-backend-structure and origin/team/stefan/issue-206-skill-activation-boundaries; both git merge-base --is-ancestor "$issue205_sha" "$issue206_sha" and git merge-base --is-ancestor "$issue206_sha" HEAD must pass immediately before pull-request creation/update.

Intra-Task Release Gate

T1 has no provider blocker and may execute its RED/GREEN catalog, scaffold, and documentation slice immediately. The worker must stop before version selection, changelog finalization, release classification, or pull-request publication until both issue #205 and issue #206 branches are pushed and the fetched issue #206 head contains the fetched issue #205 head. Once that condition passes, rebase issue #207-only commits onto the immutable issue #206 SHA, derive the npm version as exactly one patch above apps/cli/package.json at that SHA, finalize both changelogs and deterministic lockfile output, and rerun all validation on the restacked tree.

Codebase Findings

• apps/cli/src/data/catalog/skills.ts registers implement-spec and verify-behavior but not the two lifecycle skill IDs.
• apps/cli/src/data/catalog/packs.ts defines the default planning pack and currently stops at implement-spec, verify-behavior, and the remaining planning capabilities.
• apps/cli/src/content/skills.ts and apps/cli/src/content/packs.ts expose the bundled registry and skillsForPack, providing a small public test seam without duplicating implementation details.
• apps/cli/src/scaffold/project-verifier-preservation.test.ts already runs built public scaffold/update commands for both existing and absent verifier references and inventories project-owned bytes.
• docs/README.md, docs/runbooks/hi-cli-scaffolding.md, and apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md describe planning-pack verification behavior and must reflect the installed recovery capabilities.
• The catalog and pack ship in both the npm CLI and scaffold baseline. BASELINE_CHANGELOG.md and CHANGELOG.md receive issue #207 notes, and apps/cli/package.json plus any deterministic lockfile version entry advance to the next patch relative to the final issue #206 head.

Dependency Graph

T1 / IP-473
  RED: public bundled planning capability lacks recovery skills
  GREEN: catalog + pack + scaffold manifest include both skills
  PROOF: verifier references unchanged; docs, types, and release classification pass

Parallel Execution Waves

A one-task wave is required because IP-473 is the only provider Task and all implementation files participate in the same catalog-to-scaffold behavior slice.

Tasks

T1: Register, distribute, and verify lifecycle recovery skills

• depends_on: []
• location: apps/cli/src/data/catalog, apps/cli/src/content, apps/cli/src/scaffold, docs, apps/wiki/content/docs/project/runbooks, BASELINE_CHANGELOG.md, and this spec folder
• owned_paths: apps/cli/src/data/catalog/skills.ts, apps/cli/src/data/catalog/packs.ts, apps/cli/src/content/verification-recovery-skills.test.ts, apps/cli/src/scaffold/project-verifier-preservation.test.ts, docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md, BASELINE_CHANGELOG.md, CHANGELOG.md, apps/cli/package.json, bun.lock, apps/wiki/content/docs/project/specs/cli/issue-207-verification-recovery-skills/PLAN.md, apps/wiki/content/docs/project/specs/cli/issue-207-verification-recovery-skills/IMPLEMENTATION-NOTES.md
• wave_boundary: W1
• description: Test-drive the planning-pack behavior through the bundled registry and pack seam, minimally register both packaged lifecycle skill sources and add them to the planning pack, then extend the existing public CLI preservation scenario to prove the generated manifest installs all four cooperating skills while verifier-reference bytes remain unchanged. Document the corrected operator behavior and baseline impact, retain evidence in the execution artifacts, and keep all issue #207 commits ready to restack onto issue #206.
• validation: The focused catalog/pack test passes; the built public Project Verifier scaffold/update preservation test passes for existing and absent references while asserting all four skill IDs in the generated manifest and byte-matching materialized creator/updater sources to their packaged directories; CLI typecheck passes; mirrored runbooks agree; changed files format cleanly; release classification against the immutable final issue #206 SHA selects mixed and accepts non-empty baseline plus exact next-patch npm notes.
• status: Complete — implementation and focused validation passed; review due
• log: 2026-09-15 — Captured RED through the public bundled registry/pack seam, added both existing packaged lifecycle skills to the catalog and planning pack, and reached focused GREEN. Restacked on final issue #206, advanced 5.0.2 to 5.0.3, finalized both changelogs, and rebuilt the bundled identity. The full public preservation suite passed 3/3 after the inherited issue #203 semantic-mode convergence repair; registry/pack, build, typecheck, lint, format, runbook parity, ancestry, and mixed-release gates also passed.
• files edited/created: apps/cli/src/data/catalog/skills.ts, apps/cli/src/data/catalog/packs.ts, apps/cli/src/content/verification-recovery-skills.test.ts, apps/cli/src/scaffold/project-verifier-preservation.test.ts, docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/specs/cli/issue-207-verification-recovery-skills/PLAN.md, apps/wiki/content/docs/project/specs/cli/issue-207-verification-recovery-skills/IMPLEMENTATION-NOTES.md
• task_identity_mode: provider-task
• backlog_item_id: IP-473
• backlog_item_url: https://linear.app/devpunks/issue/IP-473/register-distribute-and-verify-lifecycle-recovery-skills
• relation_mode: native
• backlog_sync_skip_reason:
• assigned_skills: [codebase-design, quality-types, tdd, simplify]
• implementation_skill_guidance:
  • skill: codebase-design applicable_behavior: Keep the existing catalog and skillsForPack interfaces as the seam; add data rather than a new pass-through abstraction.
  • skill: quality-types applicable_behavior: Preserve inferred catalog and SkillId types end to end and test real bundled/scaffold behavior without mocks.
  • skill: tdd applicable_behavior: Add and run one public-result failing test before production catalog edits, record the actual RED, then make the smallest catalog/pack change for GREEN.
  • skill: simplify applicable_behavior: Review only the issue #207 delta after GREEN and remove unnecessary duplication without changing behavior.
• tdd_status: required
• tdd_target: skillsForPack("planning") and the bundled skill registry expose both verification recovery skills before scaffold materialization consumes them.
• red_command: bun --cwd apps/cli test -- src/content/verification-recovery-skills.test.ts
• expected_red_failure: Assertions show bundledSkillRegistryById["create-verification-skill"] and bundledSkillRegistryById["update-verification-skill"] are absent and skillsForPack("planning") omits both IDs.
• green_command: bun --cwd apps/cli test -- src/content/verification-recovery-skills.test.ts && bun --cwd apps/cli run build && bun --cwd apps/cli test -- src/scaffold/project-verifier-preservation.test.ts
• reason_not_testable:
• red_evidence: bun --cwd apps/cli test -- src/content/verification-recovery-skills.test.ts exited 1 with 1 failed file / 1 failed test: bundledSkillRegistryById["create-verification-skill"] was undefined, expected source directory skills/agnostic/planning/create-verification-skill.
• green_evidence: The focused registry/pack command exited 0 with 1 passed test. A disk-backed TMPDIR plus /usr/bin/node ./scripts/build-dist.mjs produced dist/index.js and the bundled baseline artifacts. With AGENT_BROWSER_EXECUTABLE_PATH=/home/stefan/.cache/ms-playwright/chromium-1234/chrome-linux64/chrome and an extended Bun test timeout, the public preservation suite passed 3/3 with 85 assertions, including both existing and absent verifier-reference cases across scaffold and two updates.
• codebase_design_notes: The catalog is the owning data module, bundledSkillRegistryById plus skillsForPack form the small read interface, and the public CLI scaffold test is the integration seam. No adapter, state, or new abstraction is introduced.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

Testing Strategy

1. Create only the focused public catalog/pack test and run it before production edits to capture RED.
2. Add the two catalog entries and planning-pack memberships, then rerun the focused test for GREEN.
3. Build the CLI and run the existing public scaffold/update Project Verifier scenarios with generated-manifest assertions for all four skills and exact materialized lifecycle source inventories: bun --cwd apps/cli run build && bun --cwd apps/cli test -- src/scaffold/project-verifier-preservation.test.ts.
4. Run CLI type checking with bun --cwd apps/cli run check-types.
5. Prove runbook parity with cmp docs/runbooks/hi-cli-scaffolding.md apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md. Run bunx oxfmt --check apps/cli/src/data/catalog/skills.ts apps/cli/src/data/catalog/packs.ts apps/cli/src/content/verification-recovery-skills.test.ts apps/cli/src/scaffold/project-verifier-preservation.test.ts apps/cli/package.json BASELINE_CHANGELOG.md CHANGELOG.md docs/README.md docs/runbooks/hi-cli-scaffolding.md apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md apps/wiki/content/docs/project/specs/cli/issue-207-verification-recovery-skills/PLAN.md apps/wiki/content/docs/project/specs/cli/issue-207-verification-recovery-skills/IMPLEMENTATION-NOTES.md and retain git diff --check.
6. After git fetch origin --prune, set issue205_sha and issue206_sha from their remote branches and require both ancestry commands in Branch/Base Intent to pass after restacking.
7. Set issue206_version=$(git show "$issue206_sha":apps/cli/package.json | jq -r .version) and issue207_version=$(jq -r .version apps/cli/package.json), then run node -e 'const [base, head] = process.argv.slice(1); const [major, minor, patch] = base.split(".").map(Number); if (head !== [major, minor, patch + 1].join(".")) process.exit(1)' "$issue206_version" "$issue207_version". Require a matching non-empty CHANGELOG.md heading and non-empty BASELINE_CHANGELOG.md Unreleased note, then run bun run release:classify -- --base "$issue206_sha" --head HEAD and retain the expected mixed classification.

Review and Docs-Ingest Expectations

• Review the frozen issue #207 delta against the immutable spec, TDD evidence, stack ancestry, scaffold preservation, generated manifest, release notes, and documentation parity.
• The primary review should treat missing lifecycle sources, incorrect pack placement, generated reference mutation, stale mirrored docs, and incorrect release classification as blocking findings.
• Docs ingest must update the spec/implementation bookkeeping and durable CLI scaffolding knowledge, or retain an evidence-backed no-op if the implementation docs already express the final behavior.

Risks and Mitigations

• Issue #205/#206 ancestry assembled: final #205 79fd44b7 is an ancestor of final #206 b949b3d6, and #207 is restacked directly on that #206 head.
• Catalog membership passes but packaged source is absent: assert exact source directories through the bundled registry and prove materialization through the public CLI test.
• Managed skill copying overwrites project verifier knowledge: retain byte inventories for existing references before and after scaffold/update.
• Release stack inherits version and changelog changes: derive the next patch and edit both changelogs only after reading the final issue #206 head; classify against that head, not origin/main, so only issue #207 impact is evaluated.
• Broad repository gates expose unrelated failures: retain focused passing evidence and exact unrelated failure output; do not weaken or silently bypass required issue-owned validation.

Validation Gates

• Task gate: RED captured before production edits; GREEN command passes; changed-file formatting and CLI typecheck pass; implementation notes contain exact commands and results.
• Review gate: retained review of the frozen commit reports clean or routes bounded repair without exceeding the delivery review budget.
• Docs gate: root and project-wiki runbooks agree, docs index points to the current behavior, and spec/implementation bookkeeping is current.
• Stack gate: after a fresh fetch, immutable final issue #205 is an ancestor of immutable final issue #206, final issue #206 is an ancestor of issue #207 HEAD, and the issue #207 PR targets the issue #206 branch.
• Release gate: the npm version is exactly one patch above the package version at immutable final issue #206, the lockfile is deterministic, both changelogs contain matching non-empty notes, and release classification against that SHA passes with the expected mixed selection.

Unresolved Questions

None. The final issue #206 commit SHA is an external moving value, not a product decision; implementation must resolve and verify it at the stack gate.