SpecsCLICache and Release Diff Classification
Shared Verification Cache and Automatic Releases Implementation Notes
Implementation Notes
Summary
- Delivery started from independently reviewed
PLAN.mdon branchteam/stefan/cache-release-diff-classification-requirementsat044188cfa95682546f64a74cca041e6fad745775. - The accepted implementation base remains
origin/main@caee8be43d38bfaaaff4cc3c90cb14c8b82c245a; the local remote-tracking ref advanced after planning and will be reconciled through the recorded branch/stack closeout rather than silently changing the execution contract. - Automatic release authority lands dormant. T16 production activation remains separately blocked by reviewed version intent, provider configuration, explicit authorization, and live evidence.
- T1 through T12 are complete. T13 and T14 implementation/static validation are complete, but same-repository candidate/cache evidence and the dormant release guard still require the single feature-branch pull request. T15 private docs ingest is complete; final delivery closure waits on those PR gates.
Deviations From the Plan
- T2 ownership now includes
apps/cli/package.jsonfor the two minimal ambient capability/fresh task scripts. Turbo cannot assign separate cache policy to T1's runner actions without package task entrypoints; T12 remains the later serialized manifest integration owner and must preserve them. - T1 ownership now includes the coupled
verify-test-title-inventory.d.mtsdeclaration after W2 typecheck exposed that the new public classified-inventory exports were undeclared. - T11 ownership now includes a thin
run-release-convergenceadapter and focused test. T12 proved the pure policy seam alone could not be registered as a directly callable task without forcing T14 to duplicate release policy in workflow YAML. - T14 ownership now includes release-authority modules, focused tests, and their package/root/Turbo registration because verified provenance and ordered state construction cannot safely live in workflow shell or bypass the uncached task graph.
- T12 ownership now includes the minimal
cache-trust.test.tsreconciliation required by its root-suite gate after T2 split the combined ambient fallback into explicit capability and fresh calls. - T12 ownership now includes generic test-scope runner files. The T13 security pre-audit found capability-keyed package tests shared the portable
testhash and root classes bypassed Turbo, so generic remote authority cannot activate until class-specific task identity and exact-once routing are repaired. - Final review repairs added one public-package manifest projection, credential-free historical build and consumer boundaries, fresh post-child provider readback, and a non-importable mutation entrypoint. These keep pending-tree lifecycle scripts and release credentials outside historical installation and verification.
Surprises and Decisions
- Supported scaffold remediation failed before mutation because baseline
2026.08.10-cli-3.1.9-legacy-skill-compatomitsframeworks/nestjs/nestjs-best-practices/.gitignore. This is preserved as T4 artifact-completeness evidence;.devpunks/settings.jsonwas not edited manually. - T4's existing
build-dist.mjsseam regeneratesapps/cli/src/data/bundled-baseline-identity.generated.ts. The tracked identity is a coupled output of the changed canonical packaged asset set, so T4 ownership was amended to retain the regenerated digest rather than restore stale identity bytes. - A fresh 2026-08-11
hi check --json --input .made no changes and reported onlybaseline-authority-unavailable; supported scaffold convergence remains authority-blocked without local drift evidence. - Direct user approval cleared the T2 mutation gate. A fresh worker inherited that user message directly and landed the approved Turbo/cache/scheduling policy in the same shared tree.
- Host runtime exposed that manifest titles use
suite > titlewhile Vitest matchessuite title; pattern construction now normalizes only that delimiter, preserving manifest evidence and restoring the exact 39 capability/6 fresh split. - T13's read-only CI/CD pre-audit verdict was
UNSAFEfor the current workflow: mutable action tags, the legacy token/manual publisher without exact candidate evidence, overbroad signing-key scope, and generic capability hashes. T12 resolved the generic task-identity blocker; T13 must pin actions, remove the publisher, isolate forks, scope credentials, and upload candidate JSON only after exact success. - T14's read-only pre-audit verdict is
CONDITIONALLY SAFE. T7 must provide complete transported-evidence validation, T8 must block reviewed product intent with missing evidence, T11 must separate baseline from npm OIDC, and T14 must own a narrow run/artifact provenance plus first-parent queue adapter. - Final structured review exited 0 with
findings=[],patch is correct, and confidence0.99after its accepted fixes were applied. - Final security review remained
CONDITIONALLY SAFEwith no reachable Critical, High, or Medium finding because the soleProductionjob retains the literal&& falseguard. Its accepted lower-severity hardening belongs to T16: use a script-free Production install, remove unused Vercel authority, and establish durable tag-namespace provenance/protection. - Read-only provider inspection found the case-sensitive GitHub
Productionenvironment but no protection rules or deployment-branch policy. Repository variables contain onlyTURBO_TEAM; repository secrets cover only development/protected Turbo cache authority, with no control-plane, baseline-publication, or Vercel configuration. npmlatestandnextresolve to3.1.10; npm Trusted Publisher configuration remains unknown. No provider mutation occurred.
Sanity Checks
| Check | Result | Notes |
|---|---|---|
| Plan review | PASS | Independent rereview reported no actionable findings. |
| Wiki content projection | PASS | bun run --cwd apps/wiki check:content. |
| Diff hygiene | PASS | git diff --check. |
| Execution preflight | PASS | Branch, HEAD, agent settings, specialist coverage, and CLI 3.1.9 read back. |
| Scaffold convergence | BLOCKED | hi update --write failed before writing on a missing bundled baseline asset; subsequent authority check degraded with baseline-authority-unavailable. |
| W1 focused contracts | PASS | Parent run: 9 files and 52 tests across inventory, runner, assembly, build, compatibility, and bundled-baseline contracts. |
| T1 current inventory | PASS | After the CLI 3.1.12 rebase, 428 baseline titles are preserved; 442/442 protected and collected; 119 portable, 317 capability-keyed, 6 fresh. |
| T1 CLI typecheck | PASS | Public classified-inventory declarations are complete. |
| T2 portable cache acceptance | PASS | Parent run: 26/26 generic scenarios; worker host runtime: 23/23 in 441.50s; focused runner and type checks passed. |
| T3 repository inventory | PASS | 87/87 targets: 12 portable, 72 capability-keyed, 3 fresh; 14 tests and 104 assertions passed. |
| T4 CLI build | PASS | Complete baseline archive/manifest/tree built before release-output inventory freeze. |
| T4 packaged runtimes | PASS | Installed CLI consumer passed in 56.9s and packaged API runtime tracer passed in 4.2s outside sandbox restrictions. |
| T5 semantic classifier | PASS | 2 files and 23 tests plus CLI help, scoped lint/format, and diff hygiene. |
| T6 staged selector | PASS | Parent run: 5/5 tests, CLI typecheck, executable hook, and diff hygiene. |
| T7 candidate evidence | PASS | Parent run: 2 files/11 tests, direct CLI help, CLI typecheck, and diff hygiene. |
| T8 reviewed order | PASS | Parent run: 1 file/6 tests, CLI typecheck, and diff hygiene. |
| T9/T10 product convergence | PASS | Parent run: 4 files/37 tests in 56.99s, CLI typecheck, and diff hygiene. |
| T11 ordered reconciliation | PASS | Parent final run: 2 files/19 tests, direct CLI help, CLI typecheck, and diff hygiene. |
| T12 command/task graph | PASS | Parent final run: 40 tests/919 assertions, CLI typecheck, class-specific hash/fresh policy proof, and diff hygiene. |
| T13 workflow static contract | PASS | Parent run: 25 tests/607 assertions, 15-job YAML parse, immutable pins, fork isolation, publisher removal, candidate artifact contract, and diff hygiene. |
| T14 authority static contract | PASS | Exact workflow/run/artifact provenance, canonical candidate validation, first-parent ordering, mutually exclusive product authority, immutable action pins, and the literal-disabled sole Production job passed focused local/static validation. |
| Integrated CLI release suite | PASS | Final release-focused run passed 13 files and 156 tests after review repairs. |
| Final authority/cache gate | PASS | 4 files, 37 tests, and 864 assertions passed; the exact task-graph subset passed 18/18, and the corrected 15-second multi-dry-run budget completed in 4.71 seconds. CLI typecheck, YAML parse, and diff hygiene passed. |
| Final structured review | PASS | Exit 0; findings=[]; patch correct with confidence 0.99. |
| Final security review | CONDITIONAL PASS | No reachable Critical, High, or Medium finding while Production remains literal-disabled; accepted lower-severity hardening is assigned to blocked T16. |
UI Evidence Links
No UI surface changes are planned. Delivery changes CLI, repository hooks, CI workflows, release automation, and operator documentation.
Runtime Validation Evidence
| Task | Scenario and target | Public action | Correlation or provenance | Expected result | Observed result and durable evidence | Cleanup | Status or exact blocker |
|---|---|---|---|---|---|---|---|
| T4 | Local packed/installed CLI in disposable consumer roots | Build, assemble, npm pack, install, invoke hi/hint, run fresh-init consumer lifecycle | Tarball d162ef63ab871d77fd844ac1908c92b6331a56fcedcf3dc02b1925ce77ec2a89; baseline archive 1cdb2b332c0085eeaafa90d2270459e9957b659ec9a905613f68d5f3f23e9232 | Frozen and installed package/baseline identities match and bounded consumer matrix accepts 3.1.9/3.1.10 only | Package @punks/cli@3.1.9; 1405-file frozen tree, 1403-file installed tree, 704-file baseline tree; installed CLI and fresh-init consumer passed | Worker removed all unique evidence/install roots after retaining summary; parent test cleanup completed | PASS |
| T6 | Pre-commit selector in disposable repositories and a linked worktree | Stage additions, deletion, cross-owner rename, and unstaged changes; invoke selector and hook | Task-prefixed disposable roots | Select only staged owners, use the linked-worktree index, delegate directly, and leave global Git config unchanged | Five focused runtime tests passed; physical worktree-root assertion covers macOS /var aliases | Exact task-prefix checks found no retained roots | PASS |
| T2 | Portable and capability cache replay in disposable local-macOS and Ubuntu-equivalent producers | Invoke public CLI verification tasks across forced, miss, hit, restoration, invalidation, fresh, and signature scenarios | Same disposable HEAD and signed development/protected cache summaries | Restore only compatible signed results; execute fresh witnesses every time; invalidate every declared input | Generic cache 26/26; host capability/fresh 23/23; output bytes, task hashes, signatures, and current inventory correlated | No owned cache/fixture roots or runner processes remained | PASS |
| T7 | Direct candidate command in a disposable linked exact-tree worktree | Run matching candidate then artifact-identity mismatch | Exact linked-worktree commit and two independent assembly identities | Emit one record only for complete matching success; emit none on mismatch | Matching run emitted one record; mismatch exited 1 with empty stdout; terminal-state matrix passed | All hi-release-candidate-* roots removed | PASS |
| T13 | Same-repository candidate/cache path | Run the trusted behavior workflow on the single feature-branch pull request | Pending pull-request run and candidate artifact ids | Signed development reuse and exact prospective-tree candidate evidence succeed | Static workflow and fork-isolation contracts pass; no run or artifact exists before the pull request | Retain future run/artifact ids; mutate no provider state | BLOCKED: single PR not created yet |
| T14 | Dormant release guard | Run the non-mutating guard job on the single feature-branch pull request | Pending release-workflow run id | Exact-evidence refusal and dormant job boundaries pass without provider mutation | Local/static refusal and literal-disable contracts pass; no PR guard run exists yet | Retain future run id; no provider cleanup required | BLOCKED: single PR not created yet |
Acceptance Criteria Status
- All dormant repository behavior has local or static implementation evidence. AC-001, AC-002, AC-015, and AC-017 still require the single pull-request cache/candidate runtime. AC-034 through AC-048 remain unproven in production because the release job is literal-disabled and T16 lacks reviewed intent, provider configuration, and authorization. No blocked criterion was marked met from static evidence alone.
Manual Review Checklist
| Area | Check | How to perform | Expected result |
|---|---|---|---|
| Local gates | Inspect installed hook selection and the exact-tree candidate command | Run bun run hooks:install, stage a representative workspace-only change, inspect node apps/cli/scripts/staged-verification-selector.mjs --json, then run bun run release:candidate -- --help | The staged selector names only affected owners; the candidate help exposes the package-owned exact-tree boundary. |
| Release intent | Inspect semantic classification and reviewed intent requirements | Run bun run release:classify -- --help, then read the Unreleased entries in CHANGELOG.md and BASELINE_CHANGELOG.md | The classifier exposes none, baseline, npm, and mixed; Unreleased notes do not invent a product version or baseline tag. |
| Dormant authority | Verify the production guard and permission boundary | Read .github/workflows/release.yml and the T14/T16 plan records | The sole Production job retains literal && false; T16 remains blocked and no provider mutation is claimed. |
| Pull-request runtime | Capture the remaining T13/T14 evidence | After the single feature-branch PR exists, retain trusted behavior-workflow run, candidate artifact, and release guard run ids | Same-repository cache/candidate and dormant guard evidence close only their mapped runtime criteria. |
Pre-existing Issues
- Published baseline asset completeness prevents supported scaffold convergence before any local write.
Out of Scope Observations
- None.
Remaining Work
- Create the single feature-branch pull request and retain T13 same-repository cache/candidate evidence plus the T14 non-mutating release guard run. T15 closes after those runtime gates. Keep T16 blocked until reviewed intent, provider configuration, explicit authorization, and accepted hardening conditions are satisfied.
Steering
| Date | Feedback | Changes |
|---|---|---|
| 2026-08-10 | Execute the accepted M11 scope through the latest safely reachable step | Wrote and independently reviewed the plan; began plan-derived implementation. |