SpecsCLIIssue 207 Verification Recovery Skills
Implementation Notes: Issue 207 Verification Recovery Skill Distribution
Implementation Notes
Execution and Reconciliation
| Task | Task Result and input identities | Parent Task Gate | Reconciliation | Summary blocker / next action | Final acceptance | Code Review |
|---|---|---|---|---|---|---|
| T1 / IP-473 | W1 catalog, pack, scaffold-test, docs, and release slice against issue #207 SPEC/PLAN | Final #205/#206 ancestry and 5.0.2 parent verified | Restacked, released as 5.0.3, and validated | Frozen issue #207 delta is ready for delivery review | Passed | Review due |
Summary
Rebase Reconciliation
The initial #207 catalog change is inherited from issue #206 after rebasing onto b85ac1eca7b88935ef35d6337ed983ec55ea546b. The current #207 delta removes its duplicate registration, retains #206's verification-pack ordering, and changes the focused public assertion from the planning pack to the verification pack. Its scaffold test continues to prove that default selection installs all four cooperating skills and that verifier references remain project-owned. Earlier planning-pack and release-completion statements below are historical evidence, not current publication claims.
- Registered the existing
create-verification-skillandupdate-verification-skillpackaged directories and added both IDs to the default planning pack. - Added focused public registry/pack coverage and extended the built public Project Verifier test to require all four cooperating skills, byte-identical recovery-skill materialization, and unchanged existing-or-absent verifier references.
- Updated the CLI scaffolding docs to describe recovery-skill installation and project ownership of verifier references.
- Restacked on final issue #206
b949b3d6, advanced the CLI from5.0.2to5.0.3, finalized both changelogs, and rebuilt the bundled identity for mixed release classification.
Deviations From the Plan
bun --cwd apps/cli run buildunder Bun 1.4.0 printed Bun usage instead of invoking the quoted Node script, so validation used the package script's exact Node payload directly./tmpwas exhausted and the default agent-browser cache was not writable; final validation used a disk-backedTMPDIRand the healthy installed Chromium path. Runtime evidence then proved an inherited semantic-file mode mismatch in issue #203; after that parent repair, the unchanged second update and the complete issue #207 public suite passed.
Surprises and Decisions
- Kept production behavior unchanged and retained the existing scaffold test contract. No test-only tool override remains after the bounded diagnostic retry.
- Kept the existing catalog and
skillsForPackinterfaces as the only CLI seams; the issue implementation is data-only apart from the bounded wiki rendering repair described below.
Debugging Evidence
| Hypothesis | Status | Evidence |
|---|---|---|
| Expected wiki-sync hash was stale after staging | Rejected | Pre-fix log lines 1–2 show recorded, generated, and live hashes all equal. |
| Live bytes or file type differed from staged output | Rejected | The same lines show identical content identities; the retained fixture was a regular file before and after update. |
| Duplicate wiki-alignment output supplied different bytes | Rejected | Both byte-comparison calls produced the same SHA-256 identity. |
Semantic comparison invented an undeclared 0644 mode | Confirmed | Pre-fix line 2 records desired mode 420 versus observed 436; post-fix lines 6–7 and 13–14 record mode-neutral equal fingerprints and no raw or assessed change. |
The repaired flow is:
semantic file without declared mode
compare content and file type
preserve the live permission mode
second update returns applied: falseRetained review report rendering repair
tdd_status: recovered- RED: GitHub Actions run
34970943670, job104386810752, failed while building the retained pass-one report withShikiError: Language review-report-json not found. - Root cause: Fumadocs passed the review authority fence to a fresh lazy Shiki highlighter without the underlying JSON grammar loaded.
- Repair:
apps/wiki/source.config.tspreserves the Fumadocs defaults, preloads the JSON and shell grammars, and aliasesreview-report-jsonto JSON. - GREEN:
TMPDIR=/home/stefan/.cache/issue207-wiki-build.BJnsTf bun run --cwd apps/wiki buildexited 0 after compiling, passing TypeScript, and generating 1,431 of 1,431 static pages. Focused formatting andgit diff --checkalso passed. - Runtime evidence:
/home/stefan/.cache/issue207-debug-server.5SGavg/debug-agent/debug-8e24a4.logcontains the pre-fix and post-fix records.
Sanity Checks
| Check | Result | Notes |
|---|---|---|
| Focused RED | Passed | Command exited 1 because the creator registry entry was undefined. |
| Focused GREEN | Passed | 1 file and 1 test passed. |
| Direct distribution build | Passed | /usr/bin/node ./scripts/build-dist.mjs produced dist/index.js and bundled baseline artifacts. |
| CLI typecheck | Passed | Direct Node equivalent completed with no diagnostics; the Bun package-script wrapper printed Bun usage on this host. |
| Built public Project Verifier test | Passed | 3/3 tests and 85 assertions passed for handoff rendering plus existing/absent verifier knowledge across scaffold and two updates. |
| Focused formatting | Passed | bunx oxfmt --check passed for all ten issue-owned code, test, docs, plan, notes, and route files. |
| Runbook body parity | Passed | Public runbook equals the routed wiki body after its required six-line frontmatter. |
| Diff whitespace | Passed | git diff --check exited 0. |
| Runtime validation | Not applicable | runtime_validation: not_required; no process/infrastructure runtime contract changed. |
| UI validation | Not applicable | No UI surface changed. |
| Interactive behavior verification | Not applicable | Acceptance is exercised through automated CLI catalog/scaffold contracts; no browser/computer-use scenario applies. |
| Retained report wiki build | Passed | Recovered RED from CI; post-fix production build compiled and generated 1,431/1,431 static pages. |
Skill Application Evidence
| Task | Skill | Status | How/where | Not-applicable reason and assessment location |
|---|---|---|---|---|
| T1 | codebase-design | applied | Retained bundledSkillRegistryById and skillsForPack as the public seam; added catalog data without a new adapter or abstraction. | |
| T1 | quality-types | applied | Used the existing inferred catalog/pack types and Effect Schema decoding while testing real bundled and scaffold outputs without mocks. | |
| T1 | tdd | applied | Added verification-recovery-skills.test.ts, captured its actual missing-registry RED, then made the minimal catalog/pack change and recorded focused GREEN. | |
| T1 | simplify | applied | Reviewed only the issue #207 delta after focused GREEN; retained two shared skill-ID tuples and the existing inventory helper without adding pass-through helpers. |
UI Evidence Links
Not applicable; no UI changed.
Runtime Validation Evidence
Not applicable; the plan records runtime_validation: not_required and runtime_target: not_applicable.
Behavior Verification Evidence
Not applicable; the accepted CLI contracts are automated and have no interactive visible-behavior scenario.
Visual Evidence Acceptance Map
Not applicable; no visual surface or asset changed.
Acceptance Criteria Status
| Criterion | Status | Notes |
|---|---|---|
| AC-001 | Passed | Both parameterized cases install all four cooperating planning skills and converge on the second update. |
| AC-002 | Passed | Both creator/updater materialized inventories exactly match their packaged sources. |
| AC-003 | Passed | Existing verifier-reference bytes remain identical and absent references remain absent across scaffold and both updates. |
| AC-004 | Passed | Focused GREEN resolves both lifecycle IDs to their exact packaged directories. |
| AC-005 | Passed | Focused GREEN proves planning-pack membership alongside verify-behavior and implement-spec. |
Manual Review Checklist
| Area | Check | How to perform | Expected result |
|---|---|---|---|
| Catalog | Inspect both new entries | Review apps/cli/src/data/catalog/skills.ts | IDs map to exact existing planning directories with no required tools. |
| Pack | Inspect planning membership | Review apps/cli/src/data/catalog/packs.ts | All four cooperating skill IDs are in the planning pack only. |
| Public scaffold | Rerun built preservation gate on a host with supported tool bootstrap | Run the PLAN green_command | 3 tests pass for generated handoff plus existing/absent verifier states. |
| References | Inspect preservation assertions | Review project-verifier-preservation.test.ts | Existing bytes are identical; absent references remain absent after every command. |
| Docs | Compare mirrored body content | Run diff -u docs/runbooks/hi-cli-scaffolding.md <(tail -n +7 apps/wiki/content/docs/project/runbooks/hi-cli-scaffolding.md) | No body difference. |
| Release | Resolve final parent and classify | Follow PLAN stack/release gates after final issue #206 exists | Exact next patch, deterministic lockfile, matching notes, and mixed classification pass. |
Pre-existing Issues
- Bun 1.4.0 does not execute the quoted Node fallback in the CLI
buildandcheck-typespackage scripts on this host; direct Node invocation is the bounded validation alternative. - Repository-wide hook output still includes inherited wiki lint debt; no issue #207-owned lint or format finding remains.
Out of Scope Observations
- None.
Remaining Work
- Retain the final clean review pass, republish PR #212, and verify the full PR stack plus required checks.
Steering
| Date | Feedback | Changes |
|---|---|---|
| 2026-09-15 | Stop environment investigation after one supported retry; finish docs and execution artifacts while holding release metadata. | Preserved the test contract, recorded the exact blocker, and left package/version/changelog files untouched. |