Plan: Shared Verification Cache and Automatic Releases

Initial Situation

The repository already has signed development and protected Turborepo cache authorities, explicit CLI test inventories, release-shaped build evidence, idempotent npm-version detection, and durable stable-baseline promotion. Those foundations are incomplete at the product boundary.

Authenticated local work and trusted same-repository CI do not yet share every sound result. Broad uncached update and ambient groups contain replay-safe cases, generic repository tests have no trusted remote-cache partition, and the current deterministic identity intentionally includes host values that prevent portable macOS-to-Ubuntu reuse.

Publication remains a manual token-authenticated workflow. Pull requests do not produce complete exact-tree candidate evidence, main reruns the protected graph, no semantic product classifier exists, npm assembly can omit runtime dependency metadata and a built bundled baseline, and baseline publication is not separated cleanly enough for automatic mixed-release reconciliation. The repository is private on GitHub Free, so publication must enforce its own exact successful pull-request evidence guard.

The accepted spec and Linear projection are authoritative. This plan does not reopen product decisions, change the one-M11/one-epic/six-story shape, or invent the reviewed npm version, baseline tag/range, and changelog intent required to activate production publication.

Product Invariant

Every exact candidate is classified as none, baseline, npm, or mixed from semantic product evidence. Complete candidate proof is reusable only inside its declared trust and capability identity. A direct, red, cancelled, incomplete, mismatched, or unattested main tree performs no production mutation. An eligible tree converges only the reviewed stable products, serially and recoverably, without republishing immutable versions or widening credential scope.

Locked Decisions

• GitHub Free and a private repository remain the operating boundary; branch protection and human production approval are out of scope.
• Production stable is the only release channel. The existing beta/manual token route is removed from the automatic product path.
• One semantic classifier owns none, baseline, npm, and mixed; paths only route comparisons and unknown authority fails closed.
• Packaged-skill-only change means baseline required, npm not required, while literal npm drift remains observable.
• Every npm assembly includes one complete built baseline snapshot, runtime dependencies, pack controls, distribution outputs, frozen inventory, and attestation.
• Compatible CLI patches use a bounded same-minor baseline family; a failed proof or new minor requires mixed intent and a new family.
• Pull requests prove the prospective merge tree and complete artifacts. main verifies that exact evidence instead of rediscovering long-running product-test results.
• Development, fork, and protected authority remain separate. Forks and cache producers receive no publication credentials.
• Mixed release order is stable baseline publication before npm publication, as explicitly accepted by the final spec. Retry reconciles each completed external step before advancing.
• The automatic workflow lands dormant. npm Trusted Publishing is configured for the exact workflow and case-sensitive Production environment, then a later reviewed intent change enables one OIDC release. Legacy bypass authority is revoked only after that proof.
• One feature/spec branch targets main; intra-plan dependencies do not imply stacked pull requests.

Resolved Decision Ledger

Dependency Readiness

No Stack Required.

• Accepted base: origin/main@caee8be43d38bfaaaff4cc3c90cb14c8b82c245a.
• Spec and retained evidence branch: team/stefan/cache-release-diff-classification-requirements@044188cfa95682546f64a74cca041e6fad745775.
• Signed development/protected cache and grouped build-attestation foundations are already on main.
• Immutable research remains at research/cache-release-diff-classification@7e196b2223d39e8767fb76356f7c56fb0630d966 and research/cache-release-green-main-gaps@eabdd5f7206f0aeeb3a3aaba4ff31de5dc30d1f8.
• Vercel scope/project identifiers are accepted activation inputs; npm Trusted Publisher configuration is an in-capability activation step.
• The planning worktree is clean. Repository agent settings declare max_depth = 1; specialist coverage exists for CLI, source/data, wiki, docs, planning review, code review, and security review.
• hi update --write is currently blocked before mutation because published baseline 2026.08.10-cli-3.1.9-legacy-skill-compat omits frameworks/nestjs/nestjs-best-practices/.gitignore. This is direct IP-369 artifact-completeness evidence. No manual settings edit is allowed.

Branch/Base Intent

• Base: origin/main at caee8be43d38bfaaaff4cc3c90cb14c8b82c245a.
• Parent stack: none.
• Constraint: retain both immutable research refs and the confirmed grill, then use one feature/spec branch into main.

Codebase Findings

• .github/workflows/behavior-contract.yml is the sole workflow. It separates same-repository development, credential-free fork, and protected authorities, but generic CI has no trusted remote cache and publication still uses workflow_dispatch, beta, and NPM_TOKEN.
• apps/cli/scripts/release-test-policy.mjs, run-release-tests.mjs, host-test-capabilities.mjs, and turbo.json own the current exact-once CLI graph. Twenty-five update cases and the broad ambient file bypass cache without per-witness unreplayable rationale.
• scripts/behavior-contract/test-scope.ts is a test router only. It must remain outside semantic release authority.
• No pre-commit or pre-push repository hook exists. apps/cli/src/data/hooks/require-tests-for-pr.mjs is an unrelated obsolete agent-tool interceptor and must stay outside the candidate design.
• build-baseline.mjs owns complete scaffold payload assembly. build-dist.mjs writes the npm output inventory before a complete baseline build is included.
• release-dispatcher.mjs reconstructs publish metadata from a whitelist that omits runtime dependencies, relies on npm whoami, and skips full registry/installed-consumer proof on existing versions.
• publish-baseline.mjs combines immutable upload and stable promotion. Tag-target verification must be explicit because detached publication can otherwise tag the default branch instead of the manifest commit.
• GitHub concurrency is not a durable reviewed-version queue; an older pending run can be replaced. Serialized reconciliation needs explicit version-order state and external readback.

External Research Used

• npm Trusted Publishing requires GitHub-hosted runners, id-token: write, an exact workflow filename, and optional exact environment binding. npm recommends proving OIDC before revoking legacy tokens: https://docs.npmjs.com/trusted-publishers/
• GitHub OIDC includes the case-sensitive environment in the subject when a job references one, supporting the accepted Production selector: https://docs.github.com/en/actions/reference/security/oidc
• Pull-request workflows check out refs/pull/<number>/merge by default, and GITHUB_SHA is the prospective merge commit used for exact candidate evidence: https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows
• Workflow artifacts carry run and SHA identity but are distinct from dependency caches; cross-run download requires an explicit run id and token: https://docs.github.com/en/actions/concepts/workflows-and-actions/workflow-artifacts
• Current local Turborepo guidance confirms that complete inputs, hashed env, declared outputs, signature verification, and uncached external mutations are the soundness boundary. The official site returned an unsupported-content response during this run, so the repository-pinned skill and current source configuration are the implementation references.

Design Considered Twice

Rejected: one workflow script owns classification, verification, and publication

This would couple pure semantic comparison to GitHub event payloads and credentials, make local diagnosis difficult, and force tests through workflow mocks. The interface would expose the same complexity it claims to hide.

Rejected: path-classify first, then rebuild whatever the path suggests

This misses cross-directory scaffold inputs, treats release identity as product change, and misclassifies skills that are literal bytes in both products. Unknown ownership could silently become none.

Selected: three deep modules with narrow adapters

1. A verification inventory module exposes complete portable/capability/fresh task assignments and reasons.
2. A semantic candidate module accepts base/head or verified external product authority and returns classification plus exact artifact evidence without credentials.
3. A release reconciler consumes reviewed intent, exact eligible candidate evidence, and injected external adapters, then returns the first incomplete stable mutation and its readback.

Git hooks and GitHub Actions are thin adapters over these public seams. Package assembly remains one deep boundary shared by candidate proof and publication. This gives locality to cache identity, semantic authority, and external reconciliation while keeping provider credentials out of pure logic.

Assumptions And Constraints

• Workers are not alone in the repository. Each owns only the exact paths listed below and must preserve prior-wave changes and unrelated worktrees.
• Behavior-changing code follows RED then GREEN through public script/command seams. Tests written after production code are marked recovered and must capture honest RED evidence before advancing.
• New tasks live in apps/cli/package.json and turbo.json; root scripts only delegate with turbo run or invoke repo-wide orchestration that cannot truthfully belong to one package.
• External mutations, publishing, promotion, mutable aliases, and provider configuration are never cacheable.
• Release code must accept injected local/test adapters for registry, GitHub, Vercel/control-plane, and workflow-evidence readback. Production credentials remain step-scoped.
• Provider/runtime acceptance uses unique run/version identifiers and removes only task-created temporary resources. Immutable published versions and release assets are never deleted or overwritten.
• Reviewed-version order is reconstructed from exact eligible commits on first-parent main history and their reviewed repository intent. Provider readback proves which immutable and mutable steps are complete. GitHub concurrency is only mutual exclusion, never the durable queue.
• Baseline upload, immutable readback, and stable promotion remain contiguous, non-delayable substeps of one baseline convergence operation. Checkpoints make retry idempotent; they do not create a separately promotable candidate lifecycle.
• Planning used the fresh immutable research rather than rerunning parallel-research; a new mandatory durable report would duplicate same-day evidence without changing the graph.
• No prototype is required. The capability is exercised through scripts, tests, disposable repositories, local package trees, and GitHub Actions evidence rather than a throwaway UI/state demo.

Dependency Graph

T0
├── T1 ──┬── T2 ──────────┐
│        └── T3 ──────────┼── T6 ── T7 ── T8 ──┬── T9 ──┐
└── T4 ────── T5 ────────┘                     └── T10 ─┼── T11 ── T12 ── T13 ── T14 ── T15 ── T16

Parallel Execution Waves

Shared CLI Skill Set

Every task touching apps/cli/** uses: autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, and turborepo.

Tasks

T0: Establish The Execution Baseline

• depends_on: []
• location: spec lifecycle folder and clean requirements worktree
• owned_paths: [apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PLAN.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/meta.json]
• wave_boundary: W0; parent-owned preflight.
• description: Record exact refs, clean state, agent settings, specialist coverage, current product identities, and safe scaffold-remediation failure.
• validation: Git/config/manifest readback and fresh hi check --json evidence without manual settings repair.
• status: Complete
• log: 2026-08-10 — Recorded branch/base, agent routing, CLI 3.1.9 identity, independently approved plan, current remote-main drift, and the safe no-write scaffold-remediation failure.
• files edited/created: [apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PLAN.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PHASE-HANDOFF.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/meta.json]
• backlog_item_id: IP-366
• backlog_item_url: https://linear.app/devpunks/issue/IP-366/automate-trustworthy-cached-verification-and-stable-product-releases
• relation_mode: native
• assigned_skills: [create-spec, create-plan, implement-spec, simplify, swarm-planner, tdd, codebase-design]
• tdd_status: not_applicable
• tdd_target: Trusted execution and worktree-isolation preflight.
• red_command:
• expected_red_failure:
• green_command: git status --short --branch && git rev-parse HEAD origin/main
• reason_not_testable: Read-only preflight and lifecycle bookkeeping.
• red_evidence:
• green_evidence: git status --short --branch, git rev-parse HEAD origin/main, CLI version readback, git diff --check, and wiki content projection all completed; scaffold updater exited before mutation and the exact failure is recorded.
• codebase_design_notes: Preserve the scaffold failure as T4 evidence; never edit settings around it.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T1: Make The CLI Test Inventory Exact

• depends_on: [T0]
• location: CLI release-test policy and exact title/update assignments
• owned_paths: [apps/cli/scripts/release-test-policy.mjs, apps/cli/scripts/release-test-policy.d.mts, apps/cli/scripts/run-release-tests.mjs, apps/cli/scripts/host-cache-test-title-inventory.json, apps/cli/scripts/verify-test-title-inventory.mjs, apps/cli/scripts/verify-test-title-inventory.d.mts, apps/cli/src/scripts/release-test-policy.test.ts, apps/cli/src/scripts/run-release-tests.test.ts, apps/cli/src/scripts/verify-test-title-inventory.test.ts, apps/cli/src/update/run.shard-3.test.ts, apps/cli/src/update/run.test-cases.test.ts, apps/cli/src/update/run.shards.test.ts]
• wave_boundary: W1; runs with T4.
• description: Assign every CLI verification test exactly once to portable, capability-keyed, or fresh; give every fresh witness one unreplayable-property reason and preserve the accepted schedule.
• validation: Missing, duplicate, or unexplained assignments fail; accepted title/update inventory remains exact once.
• status: Complete
• log: 2026-08-11 — Added one fail-closed portable/capability/fresh inventory, split the mixed ambient file into 39 capability titles and six reasoned fresh witnesses, classified all 96 controlled update cases as capability-keyed, exposed separate capability/fresh runner actions for T2, reconciled W2 additions, and completed the public declarations.
• files edited/created: [apps/cli/scripts/release-test-policy.mjs, apps/cli/scripts/release-test-policy.d.mts, apps/cli/scripts/run-release-tests.mjs, apps/cli/scripts/host-cache-test-title-inventory.json, apps/cli/scripts/verify-test-title-inventory.mjs, apps/cli/scripts/verify-test-title-inventory.d.mts, apps/cli/src/scripts/release-test-policy.test.ts, apps/cli/src/scripts/run-release-tests.test.ts, apps/cli/src/scripts/verify-test-title-inventory.test.ts, apps/cli/src/update/run.shard-3.test.ts, apps/cli/src/update/run.test-cases.test.ts, apps/cli/src/update/run.shards.test.ts]
• backlog_item_id: IP-368
• backlog_item_url: https://linear.app/devpunks/issue/IP-368/reuse-every-sound-verification-result-across-local-and-trusted-ci
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: One omitted test title makes the public inventory validator fail.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-test-policy.test.ts src/scripts/verify-test-title-inventory.test.ts src/update/run.shards.test.ts
• expected_red_failure: The new omitted-title fixture is not rejected because current policy validates broad file groups, not one classified assignment per test.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-test-policy.test.ts src/scripts/run-release-tests.test.ts src/scripts/verify-test-title-inventory.test.ts src/update/run.shards.test.ts && node apps/cli/scripts/verify-test-title-inventory.mjs --current
• reason_not_testable:
• red_evidence: The omitted-title tracer failed because verifyClassifiedTestTitleInventory did not exist. Parent review then recovered a second RED because ambient capability/fresh selector actions did not exist and both new actions failed as unknown.
• green_evidence: Parent validation passed 9 focused files/52 tests across T1/T4. After rebasing onto CLI 3.1.12, final inventory preserved 428 baseline titles and verified 442/442 protected and collected titles exactly once as 119 portable, 317 capability-keyed, and 6 fresh. The integrated CLI release suite passed 13 files/156 tests; CLI check-types and git diff --check passed.
• codebase_design_notes: One inventory seam owns classification, fail-closed discovery, and complementary ambient title selectors. T2 can cache ordinary:ambient:capability independently while ordinary:ambient:fresh always executes; the combined action is a compatibility adapter only.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T2: Prove Portable And Capability Cache Identity

• depends_on: [T1]
• location: host identity, verification runner, Turbo task identities, and cache replay contracts
• owned_paths: [turbo.json, apps/cli/package.json, apps/cli/scripts/host-test-capabilities.mjs, apps/cli/scripts/host-test-capabilities.d.mts, apps/cli/scripts/run-cli-verification.mjs, apps/cli/scripts/run-cli-verification.d.mts, apps/cli/src/scripts/host-test-capabilities.test.ts, apps/cli/src/scripts/host-test-capabilities.native.test.ts, apps/cli/src/scripts/run-cli-verification.test.ts, apps/cli/src/scripts/run-cli-verification.native.test.ts, scripts/behavior-contract/cli-verification-cache-fixture.mjs, scripts/behavior-contract/cli-verification-cache-fixture.d.mts, scripts/behavior-contract/cli-verification-cache.test.ts, scripts/behavior-contract/cli-host-capability-cache-fixture.mjs, scripts/behavior-contract/cli-host-capability-cache-fixture.d.mts, scripts/behavior-contract/cli-host-capability-cache.test.ts]
• wave_boundary: W2; runs with T3/T5.
• description: Remove host values only from proven portable tasks, retain complete capability identity for host-shaped tasks, declare restorable outputs, and prove local/trusted-compatible replay without crossing signature authority.
• validation: Forced execution, first miss, compatible hit, deleted-output restoration, each input invalidation, byte equality, signature rejection, and fresh-witness execution.
• status: Complete
• log: 2026-08-11 — Removed host-only values from proven portable hashes, retained complete capability and tool identity for update/native/ambient work, made ambient capability cacheable and fresh witnesses uncached, declared restorable outputs, and scheduled all four update shards explicitly in full/protected verification.
• files edited/created: [turbo.json, apps/cli/package.json, apps/cli/scripts/host-test-capabilities.mjs, apps/cli/scripts/run-cli-verification.mjs, apps/cli/scripts/run-cli-verification.d.mts, apps/cli/scripts/run-release-tests.mjs, apps/cli/src/scripts/host-test-capabilities.test.ts, apps/cli/src/scripts/run-cli-verification.test.ts, apps/cli/src/scripts/run-release-tests.test.ts, scripts/behavior-contract/cli-verification-cache-fixture.mjs, scripts/behavior-contract/cli-verification-cache-fixture.d.mts, scripts/behavior-contract/cli-verification-cache.test.ts, scripts/behavior-contract/cli-host-capability-cache-fixture.mjs, scripts/behavior-contract/cli-host-capability-cache-fixture.d.mts, scripts/behavior-contract/cli-host-capability-cache.test.ts]
• backlog_item_id: IP-368
• backlog_item_url: https://linear.app/devpunks/issue/IP-368/reuse-every-sound-verification-result-across-local-and-trusted-ci
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: A platform-only change does not invalidate one proven portable test task.
• red_command: bun test ./scripts/behavior-contract/cli-verification-cache.test.ts -t "reuses portable output across compatible platforms"
• expected_red_failure: Current portable task hash includes platform/architecture and misses.
• green_command: bun run --cwd apps/cli test -- src/scripts/host-test-capabilities.test.ts src/scripts/host-test-capabilities.native.test.ts src/scripts/run-cli-verification.test.ts src/scripts/run-cli-verification.native.test.ts && bun test ./scripts/behavior-contract/cli-verification-cache.test.ts ./scripts/behavior-contract/cli-host-capability-cache.test.ts
• reason_not_testable:
• red_evidence: The platform-reuse tracer reported six executions because portable hashes still included platform/architecture. Runner REDs proved the full path omitted explicit update-shard invocation and unprofiled capability tasks could enter Turbo.
• green_evidence: Parent validation passed 26/26 focused host/release runner tests and 26/26 generic cache acceptance scenarios. Worker runtime passed 23/23 host capability/fresh scenarios in 441.50s, targeted full/protected scheduling and native runner tracers, CLI typecheck, exact title inventory, and diff hygiene. The optional consolidated runner file was stopped after its update child exited and Vitest became idle; every changed runner behavior had already passed its targeted test.
• codebase_design_notes: Runtime profiling remains an adapter; versioned portable/capability identity is the Turbo task interface. Full/protected runners schedule capability shards explicitly, and fresh ambient execution stays a distinct uncached public action.
• review_mode: cli
• runtime_validation: required
• runtime_target: disposable macOS/local and fresh Ubuntu-equivalent cache producers
• runtime_evidence: Disposable same-SHA local-macOS and Ubuntu-equivalent runs proved compatible portable hits, output restoration, all declared invalidations, byte equality, fresh execution, capability invalidation, and development/protected plus tampered-signature rejection.
• runtime_cleanup: Worker verified no owned cache/fixture roots or dangling runner processes remained after retaining summaries.

T3: Partition Generic Repository Verification

• depends_on: [T1]
• location: root test inventory and generic task runner
• owned_paths: [scripts/behavior-contract/repository-test-inventory.mjs, scripts/behavior-contract/repository-test-inventory.test.ts, scripts/behavior-contract/run-test-scope.ts, scripts/behavior-contract/run-test-scope.test.ts, scripts/behavior-contract/test-scope.ts, scripts/behavior-contract/test-scope.test.ts]
• wave_boundary: W2; runs with T2/T5.
• description: Classify generic package/root tests as portable, capability-keyed, or minimal live/fresh and preserve exact-one schedule; leave workflow authority to T13.
• validation: Pure, process/filesystem/container, and live cases route once; missing/duplicate assignment fails.
• status: Complete
• log: 2026-08-11 — Added a public exact-once repository inventory and routed the generic runner through 87 targets: 12 portable, 72 capability-keyed, and three reasoned fresh title witnesses.
• files edited/created: [scripts/behavior-contract/repository-test-inventory.mjs, scripts/behavior-contract/repository-test-inventory.test.ts, scripts/behavior-contract/run-test-scope.ts, scripts/behavior-contract/run-test-scope.test.ts, scripts/behavior-contract/test-scope.ts, scripts/behavior-contract/test-scope.test.ts]
• backlog_item_id: IP-368
• backlog_item_url: https://linear.app/devpunks/issue/IP-368/reuse-every-sound-verification-result-across-local-and-trusted-ci
• relation_mode: native
• assigned_skills: [codebase-design, quality-types, tdd, turborepo]
• tdd_status: required
• tdd_target: One pure package test absent from the repository inventory fails the public inventory contract.
• red_command: bun test ./scripts/behavior-contract/repository-test-inventory.test.ts
• expected_red_failure: No generic portable/capability/fresh inventory exists.
• green_command: bun test ./scripts/behavior-contract/repository-test-inventory.test.ts ./scripts/behavior-contract/run-test-scope.test.ts ./scripts/behavior-contract/test-scope.test.ts
• reason_not_testable:
• red_evidence: The public inventory tracer failed because repository-test-inventory.mjs did not exist; a second RED proved missing fresh-witness reasons were accepted.
• green_evidence: Focused inventory and runner validation passed 14 tests and 104 assertions. All 87 targets are assigned exactly once; the three fresh witnesses are limited to overlapping consumer execution, concurrent failure aggregation/cleanup, and concurrent manifest-writer contention.
• codebase_design_notes: Root routing consumes one public inventory and never infers cache class from package name. Mixed root files use complementary title selectors at the same seam.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T4: Freeze Complete Compatible Baseline And npm Assemblies

• depends_on: [T0]
• location: baseline/dist builders, isolated assembler, compatibility and installed-package proof
• owned_paths: [apps/cli/scripts/build-baseline.mjs, apps/cli/scripts/build-dist.mjs, apps/cli/scripts/assert-package-surface.mjs, apps/cli/scripts/package-evidence-report.mjs, apps/cli/scripts/package-bundled-gitignore.mjs, apps/cli/scripts/package-bundled-gitignore.d.mts, apps/cli/scripts/release-artifact-assembly.mjs, apps/cli/scripts/release-artifact-assembly.d.mts, apps/cli/src/scripts/release-artifact-assembly.test.ts, apps/cli/src/scripts/build-dist.test.ts, apps/cli/src/scripts/build-dist.native.test.ts, apps/cli/src/baseline/compatibility-range.mjs, apps/cli/src/baseline/compatibility-range.d.mts, apps/cli/src/baseline/compatibility-range.test.ts, apps/cli/src/baseline/bundled.test.ts, apps/cli/src/data/bundled-baseline-identity.generated.ts, scripts/behavior-contract/packaged-product.test.ts, scripts/behavior-contract/packaged-runtime-product.test.ts]
• wave_boundary: W1; runs with T1.
• description: Build the bundled baseline before freezing one npm tree containing runtime dependencies, pack controls, outputs, nested dotfiles, manifest/archive, inventory, and bounded same-minor consumer proof.
• validation: Packed/installed consumer proves exact tree/tarball/baseline/compatibility; any missing declared file or metadata fails before publication.
• status: Complete
• log: 2026-08-10 — Added the canonical artifact assembler; build now produces a complete bundled baseline before freezing dist inventory, pack controls, runtime metadata, package/baseline identities, and bounded consumer compatibility. Installed package proof uses an owned npm cache and correlates frozen and installed artifacts.
• files edited/created: [apps/cli/scripts/assert-package-surface.mjs, apps/cli/scripts/build-baseline.mjs, apps/cli/scripts/build-dist.mjs, apps/cli/scripts/package-bundled-gitignore.mjs, apps/cli/scripts/package-evidence-report.mjs, apps/cli/scripts/release-artifact-assembly.mjs, apps/cli/scripts/release-artifact-assembly.d.mts, apps/cli/src/scripts/release-artifact-assembly.test.ts, apps/cli/src/scripts/build-dist.test.ts, apps/cli/src/baseline/compatibility-range.mjs, apps/cli/src/baseline/compatibility-range.d.mts, apps/cli/src/baseline/compatibility-range.test.ts, apps/cli/src/data/bundled-baseline-identity.generated.ts, scripts/behavior-contract/packaged-product.test.ts, scripts/behavior-contract/packaged-runtime-product.test.ts]
• backlog_item_id: IP-369
• backlog_item_url: https://linear.app/devpunks/issue/IP-369/preserve-complete-and-compatible-npm-and-baseline-artifacts
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: The assembler rejects a package missing the nested managed .gitignore.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-artifact-assembly.test.ts -t "rejects a missing nested managed gitignore"
• expected_red_failure: No shared complete assembler enforces the missing published baseline asset.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-artifact-assembly.test.ts src/scripts/build-dist.test.ts src/scripts/build-dist.native.test.ts src/baseline/compatibility-range.test.ts src/baseline/bundled.test.ts && bun run --cwd apps/cli build && node apps/cli/scripts/assert-package-surface.mjs && bun test ./scripts/behavior-contract/packaged-product.test.ts ./scripts/behavior-contract/packaged-runtime-product.test.ts
• reason_not_testable:
• red_evidence: The required missing-nested-.gitignore tracer first failed because the shared assembler module did not exist. Recovered REDs then exposed absent cleanup, same-minor range/matrix, undeclared dist rejection, and packaged-runtime timeout behavior.
• green_evidence: Parent focused validation passed 9 files/52 tests; CLI build passed and produced the complete baseline before inventory freeze. The installed-CLI consumer test passed outside the restricted sandbox in 56.9s, and the packaged API runtime tracer passed in 4.2s. Worker evidence also passed 5 focused files/18 tests, package surface, and 10 behavior tests.
• codebase_design_notes: Candidate and publisher share one deep assembler; neither rebuilds package metadata independently.
• review_mode: cli
• runtime_validation: required
• runtime_target: local packed/installed CLI in disposable consumer repositories
• runtime_evidence: Exact tarball/tree/bundled-baseline identities and consumer matrix match frozen authority.
• runtime_cleanup: Unique pack/install roots; remove only owned roots.

T5: Classify Exact Product Change Semantically

• depends_on: [T4]
• location: new readonly classifier, intent decoder, command and fixtures
• owned_paths: [apps/cli/scripts/release-impact-classifier.mjs, apps/cli/scripts/release-impact-classifier.d.mts, apps/cli/scripts/classify-release-impact.mjs, apps/cli/src/scripts/release-impact-classifier.test.ts, apps/cli/src/scripts/classify-release-impact.test.ts, apps/cli/src/scripts/test-fixtures/release-impact/**]
• wave_boundary: W2; runs with T2/T3.
• description: Compare normalized baseline payload/schema/compatibility and executable/public package surfaces; report literal drift separately; validate reviewed intent only when required; fail additions/deletions/renames with unknown authority.
• validation: Full accepted none/baseline/npm/mixed and intent matrix.
• status: Complete
• log: 2026-08-11 — Implemented the pure semantic none|baseline|npm|mixed classifier and readonly CLI adapter with repository-bound reviewed intent, exact old/new ownership, compatibility, literal drift, and fail-closed authority.
• files edited/created: [apps/cli/scripts/release-impact-classifier.mjs, apps/cli/scripts/release-impact-classifier.d.mts, apps/cli/scripts/classify-release-impact.mjs, apps/cli/src/scripts/release-impact-classifier.test.ts, apps/cli/src/scripts/classify-release-impact.test.ts, apps/cli/src/scripts/test-fixtures/release-impact/none.json, apps/cli/src/scripts/test-fixtures/release-impact/packaged-skill.json, apps/cli/src/scripts/test-fixtures/release-impact/npm.json, apps/cli/src/scripts/test-fixtures/release-impact/mixed.json]
• backlog_item_id: IP-370
• backlog_item_url: https://linear.app/devpunks/issue/IP-370/classify-each-exact-candidate-by-semantic-product-change
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: A packaged-skill-only fixture classifies as baseline while reporting literal npm drift.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-impact-classifier.test.ts -t "classifies packaged skill only"
• expected_red_failure: No semantic classifier exists.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-impact-classifier.test.ts src/scripts/classify-release-impact.test.ts && node apps/cli/scripts/classify-release-impact.mjs --help
• reason_not_testable:
• red_evidence: The packaged-skill tracer failed because the classifier module did not exist. Later vertical REDs covered missing, mismatched, and unchanged intent; unknown rename ownership; unavailable authority; incompatible CLI; unchanged baseline tags; and absent semantic reasons.
• green_evidence: Focused classifier and CLI tests passed 2 files/23 tests; packaged-skill-only returns semantic baseline while retaining literal npm drift. Scoped lint, formatting, CLI --help, and diff hygiene passed.
• codebase_design_notes: The pure classifier owns comparison and policy; injected git, artifact, intent, and authority readers are narrow adapters. Intent is read only for products whose semantic comparison requires publication.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T6: Select Staged Work For Pre-commit

• depends_on: [T1, T3, T5]
• location: staged selector, pre-commit hook and tests
• owned_paths: [apps/cli/scripts/staged-verification-selector.mjs, apps/cli/scripts/staged-verification-selector.d.mts, apps/cli/src/scripts/staged-verification-selector.test.ts, .githooks/pre-commit]
• wave_boundary: W3; only task newly unblocked.
• description: Add worktree-aware staged selection for fast pre-commit checks. Keep candidate/pre-push integration out until T7 creates the complete candidate command.
• validation: Disposable repositories cover additions/deletions/renames, unstaged isolation, worktrees, and direct pre-commit delegation.
• status: Complete
• log: 2026-08-11 — Added one worktree-aware staged selector and a thin executable pre-commit delegate. The selector handles additions, deletions, cross-owner renames, unstaged isolation, linked-worktree indexes, and global fallback without mutating Git configuration.
• files edited/created: [apps/cli/scripts/staged-verification-selector.mjs, apps/cli/scripts/staged-verification-selector.d.mts, apps/cli/src/scripts/staged-verification-selector.test.ts, .githooks/pre-commit]
• backlog_item_id: IP-367
• backlog_item_url: https://linear.app/devpunks/issue/IP-367/prove-the-exact-release-candidate-before-publication
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: A staged deletion selects the owning focused check from the old path.
• red_command: bun run --cwd apps/cli test -- src/scripts/staged-verification-selector.test.ts -t "selects the old owner for a staged deletion"
• expected_red_failure: No staged worktree-aware selector exists.
• green_command: bun run --cwd apps/cli test -- src/scripts/staged-verification-selector.test.ts && bun test ./scripts/install-git-hooks.test.ts
• reason_not_testable:
• red_evidence: The staged-deletion tracer failed because staged-verification-selector.mjs did not exist; the direct-hook tracer then failed because .githooks/pre-commit did not exist.
• green_evidence: Parent validation passed all 5 staged-selector tests, CLI check-types, executable-hook check, and git diff --check. Runtime fixtures covered staged additions/deletions/renames, unstaged isolation, linked-worktree index selection, direct --json, hook delegation, and no global Git configuration mutation.
• codebase_design_notes: Git index parsing, owner derivation, and command selection sit behind one selector interface. The four-line hook only resolves the physical worktree root and delegates, including macOS /var path aliases.
• review_mode: cli
• runtime_validation: required
• runtime_target: pre-commit selector in disposable worktrees
• runtime_evidence: Disposable repository and linked-worktree fixtures ran the intended owner-scoped/global checks and direct hook delegation without global configuration mutation.
• runtime_cleanup: Exact task-prefixed cleanup checks found no retained disposable repositories.

T7: Emit Exact Eligible Candidate Evidence

• depends_on: [T2, T3, T4, T5, T6]
• location: candidate/evidence module, direct command and tests
• owned_paths: [apps/cli/scripts/release-candidate.mjs, apps/cli/scripts/release-candidate.d.mts, apps/cli/scripts/run-release-candidate.mjs, apps/cli/src/scripts/release-candidate.test.ts, apps/cli/src/scripts/run-release-candidate.test.ts]
• wave_boundary: W4; only task newly unblocked.
• description: Run the release-shaped repository graph, classifier and required assemblies for an exact committed/prospective tree; emit eligibility only after complete success and matching identities.
• validation: Exact tree, direct invocation, failed/timed-out/cancelled/incomplete/mismatched cases, and artifact identity binding.
• status: Complete
• log: 2026-08-11 — Added a credential-free exact-candidate seam, direct command, and canonical complete eligible-evidence validator. Generation and all production consumers now share the same strict transported JSON boundary.
• files edited/created: [apps/cli/scripts/release-candidate.mjs, apps/cli/scripts/release-candidate.d.mts, apps/cli/scripts/run-release-candidate.mjs, apps/cli/src/scripts/release-candidate.test.ts, apps/cli/src/scripts/run-release-candidate.test.ts]
• backlog_item_id: IP-367
• backlog_item_url: https://linear.app/devpunks/issue/IP-367/prove-the-exact-release-candidate-before-publication
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: One artifact identity mismatch leaves no eligible evidence.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-candidate.test.ts -t "rejects an artifact identity mismatch"
• expected_red_failure: No exact candidate evidence seam exists.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-candidate.test.ts src/scripts/run-release-candidate.test.ts && node apps/cli/scripts/run-release-candidate.mjs --help
• reason_not_testable:
• red_evidence: The exact artifact-identity mismatch tracer failed at the public import because release-candidate.mjs did not exist.
• green_evidence: Parent final security validation across T7/T8/T11 passed 5 files/55 tests, direct help, CLI typecheck, and diff hygiene. T7's 26 cases cover exact positive baseline/npm transport plus unknown/missing/malformed/mismatched schema, refs, classification, intent, counts, and digests; generation revalidates before emission.
• codebase_design_notes: Candidate returns one evidence record through a credential-free deep seam; verifier, classifier, and assembler are injected dependencies. The executable owns only Git/process/filesystem adaptation.
• review_mode: cli
• runtime_validation: required
• runtime_target: direct candidate command in disposable exact-tree worktrees
• runtime_evidence: Direct executable in a disposable linked worktree emitted exactly one matching record; an artifact mismatch exited 1 with empty stdout.
• runtime_cleanup: All task-created hi-release-candidate-* roots were removed.

T8: Reconstruct Reviewed Release Order From Git

• depends_on: [T7]
• location: first-parent intent/order module and tests
• owned_paths: [apps/cli/scripts/release-state.mjs, apps/cli/scripts/release-state.d.mts, apps/cli/src/scripts/release-state.test.ts, apps/cli/src/scripts/test-fixtures/release-history/**]
• wave_boundary: W5; only task newly unblocked after candidate evidence exists.
• description: Walk exact eligible first-parent main commits after the last completed product evidence, decode reviewed repository intent per tree, and return the first incomplete version using provider readback. Never use workflow pending order as durable state.
• validation: Queued versions, partial completion, missing candidate evidence, rewritten/mismatched intent, none commits, and later-version blocking.
• status: Complete
• log: 2026-08-11 — Added a first-parent Git release-state seam that binds canonical candidate evidence to tree-decoded reviewed intent. Reviewed product intent with missing or invalid evidence now blocks at the first commit; later versions are never consulted.
• files edited/created: [apps/cli/scripts/release-state.mjs, apps/cli/scripts/release-state.d.mts, apps/cli/src/scripts/release-state.test.ts, apps/cli/src/scripts/test-fixtures/release-history/queued.json]
• backlog_item_id: IP-371
• backlog_item_url: https://linear.app/devpunks/issue/IP-371/converge-eligible-main-trees-automatically-and-recoverably
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: Two reviewed versions return the earlier incomplete version even when the later workflow starts first.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-state.test.ts -t "keeps the first incomplete reviewed version"
• expected_red_failure: No git-backed reviewed-order authority exists.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-state.test.ts
• reason_not_testable:
• red_evidence: The earlier-incomplete-version tracer failed at public import because release-state.mjs did not exist.
• green_evidence: Parent final security validation across T7/T8/T11 passed 5 files/55 tests, CLI typecheck, and diff hygiene. T8's 7 cases prove missing/invalid product evidence blocks immediately with no later provider call while none intent remains skippable.
• codebase_design_notes: First-parent Git history and tree-decoded reviewed intent are the durable order seam; candidate evidence binds exact authority and provider adapters contribute completion readback only. Sequential reads preserve order deliberately.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T9: Converge One Baseline Contiguously

• depends_on: [T4, T7, T8]
• location: baseline publisher, promotion, rollback/readback and tests
• owned_paths: [apps/cli/scripts/publish-baseline.mjs, apps/cli/scripts/promote-baseline-authority.mjs, apps/cli/scripts/promote-baseline-authority.d.mts, apps/cli/scripts/rollback-baseline.mjs, apps/cli/scripts/rollback-baseline.d.mts, apps/cli/src/baseline/baseline-release-scripts.test.ts, apps/cli/src/baseline/baseline-release-scripts.native.test.ts]
• wave_boundary: W6; runs with T10.
• description: Make upload, immutable tag/asset readback, and stable promotion contiguous non-delayable substeps with retry checkpoints; verify tag target equals manifest commit and production readback completes before success.
• validation: Existing exact/mismatched assets, tag mismatch, upload failure, promotion failure, production-readback failure, retry, and immutable no-overwrite.
• status: Complete
• log: 2026-08-11 — Strengthened the shared baseline release-inspection seam so creation targets manifest.commit, immutable tag target and assets are read back before upload/promotion, and promotion plus production readback remain contiguous and retry-safe without overwrite.
• files edited/created: [apps/cli/scripts/publish-baseline.mjs, apps/cli/scripts/promote-baseline-authority.mjs, apps/cli/src/baseline/baseline-release-scripts.test.ts, apps/cli/src/baseline/baseline-release-scripts.native.test.ts]
• backlog_item_id: IP-371
• backlog_item_url: https://linear.app/devpunks/issue/IP-371/converge-eligible-main-trees-automatically-and-recoverably
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: A tag whose target differs from manifest.commit blocks baseline convergence.
• red_command: bun run --cwd apps/cli test -- src/baseline/baseline-release-scripts.test.ts -t "rejects a mismatched tag target"
• expected_red_failure: Current publisher does not prove the immutable tag target.
• green_command: bun run --cwd apps/cli test -- src/baseline/baseline-release-scripts.test.ts src/baseline/baseline-release-scripts.native.test.ts
• reason_not_testable:
• red_evidence: The mismatched-tag tracer proved current code skipped immutable tag-target lookup and reached promotion (requestCount=1).
• green_evidence: Parent W6 validation passed 4 files/37 tests, including T9's 22 cases, then CLI typecheck and diff hygiene. Coverage includes exact/mismatched assets, target mismatch before mutation, upload failure/retry, promotion/readback indeterminacy, rollback/CAS reconciliation, exact creation target, and no edit/--clobber.
• codebase_design_notes: One shared release-inspection seam owns exact target and immutable asset readback. The contiguous baseline operation checkpoints retry state without creating a delayed-promotion lifecycle.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: Live provider proof is reserved for controlled T16 activation.
• runtime_cleanup: not_applicable

T10: Converge One npm Version And Consumer Proof

• depends_on: [T4, T7, T8]
• location: npm dispatcher/publisher, registry/install proof and tests
• owned_paths: [apps/cli/scripts/release-dispatcher.mjs, apps/cli/scripts/release-dispatcher.d.mts, apps/cli/scripts/publish-release.mjs, apps/cli/src/scripts/release-dispatcher.test.ts, apps/cli/src/scripts/publish-release.test.ts]
• wave_boundary: W6; runs with T9.
• description: Publish or reconcile one reviewed npm version without whoami assumptions, never republish, align latest/next, verify GitHub release, registry tarball, installed tree, and consumer matrix, then expose exact completion.
• validation: Existing exact/mismatch, alias drift, GitHub release drift, post-publish consumer failure/retry, and immutable no-overwrite.
• status: Complete
• log: 2026-08-11 — Added exact convergeNpmVersion(reviewed, adapters) reconciliation, removed npm whoami assumptions, prohibited immutable republish, aligned stable aliases and GitHub release, and required registry tarball, installed tree, and six-scenario consumer proof before completion.
• files edited/created: [apps/cli/scripts/release-dispatcher.mjs, apps/cli/scripts/release-dispatcher.d.mts, apps/cli/src/scripts/release-dispatcher.test.ts, apps/cli/src/scripts/publish-release.test.ts]
• backlog_item_id: IP-371
• backlog_item_url: https://linear.app/devpunks/issue/IP-371/converge-eligible-main-trees-automatically-and-recoverably
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: An existing registry version with a different tarball identity blocks without publishing.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-dispatcher.test.ts -t "rejects an existing mismatched registry tarball"
• expected_red_failure: Current existing-version route does not verify exact tarball/installed tree.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-dispatcher.test.ts src/scripts/publish-release.test.ts
• reason_not_testable:
• red_evidence: The mismatched existing-version tracer failed because convergeNpmVersion did not exist; a second RED proved the legacy command still invoked npm whoami.
• green_evidence: Parent W6 validation passed 4 files/37 tests, including T10's 15 cases, then CLI typecheck and diff hygiene. Existing mismatch publishes nothing; exact/retry paths reconcile aliases and GitHub release, verify installed tree/consumer matrix, and never republish.
• codebase_design_notes: One deep convergence interface owns a single reviewed npm version through injected registry, GitHub, install, and consumer adapters. Durable version order remains outside this module.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: Live registry proof is reserved for controlled T16 activation.
• runtime_cleanup: not_applicable

T11: Reconcile The First Incomplete Stable Release

• depends_on: [T7, T8, T9, T10]
• location: release reconciler and tests
• owned_paths: [apps/cli/scripts/release-convergence.mjs, apps/cli/scripts/release-convergence.d.mts, apps/cli/scripts/run-release-convergence.mjs, apps/cli/scripts/run-release-convergence.d.mts, apps/cli/src/scripts/release-convergence.test.ts, apps/cli/src/scripts/run-release-convergence.test.ts]
• wave_boundary: W7; only task newly unblocked.
• description: Combine exact eligibility, git-backed order, semantic kind, contiguous baseline convergence, npm convergence, and none evidence. Mixed always completes baseline before npm; later versions wait.
• validation: All kinds, partial retries, direct/red/cancelled/mismatched evidence, mixed ordering, concurrent starts, and later blocking.
• status: Complete
• log: 2026-08-11 — Added one ordered release-policy seam and direct adapter. The runner applies T7's canonical validator before locking, derives intent from Git trees, and gives baseline/npm children mutually exclusive authority.
• files edited/created: [apps/cli/scripts/release-convergence.mjs, apps/cli/scripts/release-convergence.d.mts, apps/cli/scripts/run-release-convergence.mjs, apps/cli/scripts/run-release-convergence.d.mts, apps/cli/src/scripts/release-convergence.test.ts, apps/cli/src/scripts/run-release-convergence.test.ts]
• backlog_item_id: IP-371
• backlog_item_url: https://linear.app/devpunks/issue/IP-371/converge-eligible-main-trees-automatically-and-recoverably
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: Retry of a mixed version resumes the first incomplete baseline substep before invoking npm.
• red_command: bun run --cwd apps/cli test -- src/scripts/release-convergence.test.ts -t "resumes baseline before npm"
• expected_red_failure: No exact-evidence ordered reconciler exists.
• green_command: bun run --cwd apps/cli test -- src/scripts/release-convergence.test.ts
• reason_not_testable:
• red_evidence: The mixed-retry tracer failed because release-convergence.mjs did not exist. Later REDs proved mixed advanced on incomplete baseline evidence and current none evidence was omitted while an earlier version converged.
• green_evidence: Parent final security validation across T7/T8/T11 passed 5 files/55 tests, direct-command help, CLI typecheck, and diff hygiene. T11's 22 cases prove malformed transport and intent contradiction invoke no lock/command/write, Git-tree intent is authoritative, child credentials are mutually exclusive, and stable lock/mixed order/atomic output remain intact.
• codebase_design_notes: Reconciler owns release policy through one interface; the direct runner contains only CLI/Git/file/process adapters. Durable order, exclusive serialization, baseline/npm convergence, and evidence remain narrow injected seams; product completion requires explicit {complete:true}.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: Provider-backed end-to-end proof is T16.
• runtime_cleanup: not_applicable

T12: Register Package Commands And Task Graph

• depends_on: [T2, T3, T5, T7, T11]
• location: CLI/root package scripts, Turbo tasks and graph contracts
• owned_paths: [apps/cli/package.json, package.json, turbo.json, .githooks/pre-push, scripts/install-git-hooks.mjs, scripts/install-git-hooks.test.ts, scripts/behavior-contract/cli-release-task-graph.test.ts, scripts/behavior-contract/root-suite.test.ts, scripts/behavior-contract/cache-trust.test.ts, scripts/behavior-contract/run-test-scope.ts, scripts/behavior-contract/run-test-scope.test.ts, scripts/behavior-contract/test-scope.ts, scripts/behavior-contract/test-scope.test.ts]
• wave_boundary: W8; serialized manifest and local-gate integration.
• description: Register package-owned cache/candidate/classifier/reconciler tasks, root delegates, outputs/env/uncached mutation policy, and direct local commands without duplicating graph logic. Install repository-local hooks idempotently and make pre-push a thin call to the now-existing complete candidate command.
• validation: Task graph contract proves dependencies, outputs, env and cache flags; commands are directly callable; disposable worktrees prove idempotent local hook setup and pre-push delegation.
• status: Complete
• log: 2026-08-11 — Registered direct classifier/candidate/convergence commands, root delegates, and local hooks. After the T13 pre-audit, added package-specific capability hashes and CLI-owned portable/capability/fresh repository tasks driven by the exact inventory and one host profile; incomplete authority disables capability cache use.
• files edited/created: [apps/cli/package.json, package.json, turbo.json, .githooks/pre-push, scripts/install-git-hooks.mjs, scripts/install-git-hooks.test.ts, scripts/behavior-contract/cli-release-task-graph.test.ts, scripts/behavior-contract/root-suite.test.ts, scripts/behavior-contract/cache-trust.test.ts]
• backlog_item_id: IP-367
• backlog_item_url: https://linear.app/devpunks/issue/IP-367/prove-the-exact-release-candidate-before-publication
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, effect, effect-backend-structure, effect-recoverable-actions, effect-service-design, improve-codebase-architecture, parallel-research, prototype, quality-types, review, simplify, swarm-planner, tdd, turborepo]
• tdd_status: required
• tdd_target: The graph rejects a release mutation task that is cacheable.
• red_command: bun test ./scripts/behavior-contract/cli-release-task-graph.test.ts -t "keeps every release mutation uncached"
• expected_red_failure: New classifier/candidate/reconciler tasks are absent from the graph.
• green_command: bun test ./scripts/behavior-contract/cli-release-task-graph.test.ts ./scripts/behavior-contract/root-suite.test.ts ./scripts/install-git-hooks.test.ts && bun run --cwd apps/cli check-types
• reason_not_testable:
• red_evidence: The graph tracer failed because release:classify was absent. Later REDs proved hook installer/pre-push/root command and direct reconciler registration were absent, and authority scoping was incomplete.
• green_evidence: Parent final graph validation passed 40 tests/919 assertions, CLI typecheck, and diff hygiene; post-T13 aggregate reconciliation passed 43 tests/1095 assertions and typecheck. Earlier direct-help and disposable hook proofs passed. Turbo evidence proves portable hash stability, capability invalidation, fresh cache:false, complete profiled identity, scoped authority, and exact-once repository class routing.
• codebase_design_notes: Package tasks own logic and root scripts only delegate through Turbo. Hooks delegate to package-owned public commands; the workflow-facing reconciler remains a thin adapter over T11 policy.
• review_mode: cli
• runtime_validation: not_required
• runtime_target: not_applicable
• runtime_evidence: not_applicable
• runtime_cleanup: not_applicable

T13: Activate Trusted Development Cache In CI

• depends_on: [T12]
• location: behavior workflow and cache/fork contracts
• owned_paths: [.github/workflows/behavior-contract.yml, scripts/behavior-contract/cache-trust.test.ts, scripts/behavior-contract/test-scope.test.ts]
• wave_boundary: W9; only task newly unblocked.
• description: Give same-repository generic CI signed development-cache authority after inventory enforcement, retain credential-free forks, preserve fast diff feedback, and upload exact prospective-tree candidate evidence. Remove obsolete manual release dispatch from this workflow.
• validation: YAML contracts and live internal/fork PR runs prove authority, task routing, candidate artifact tree identity, and no fork secrets.
• status: Blocked on pull-request runtime evidence
• log: 2026-08-11 — Split trusted and fork generic CI, enabled signed development authority only for same-repository commands, pinned every action, removed the manual token publisher, and added success-only exact prospective-merge candidate JSON upload. Static implementation is complete; same-repository cache/candidate runtime evidence remains pending the single feature-branch pull request. Fork isolation is proven statically because the one-PR constraint precludes a second live fork PR.
• files edited/created: [.github/workflows/behavior-contract.yml, scripts/behavior-contract/cache-trust.test.ts, scripts/behavior-contract/test-scope.test.ts]
• backlog_item_id: IP-368
• backlog_item_url: https://linear.app/devpunks/issue/IP-368/reuse-every-sound-verification-result-across-local-and-trusted-ci
• relation_mode: native
• assigned_skills: [audit-cicd-security, codebase-design, tdd, turborepo]
• tdd_status: required
• tdd_target: The trusted generic CI job has signed development-cache authority while the fork job has none.
• red_command: bun test ./scripts/behavior-contract/cache-trust.test.ts -t "authorizes trusted generic CI only"
• expected_red_failure: Current generic CI has no remote-cache authority.
• green_command: bun test ./scripts/behavior-contract/cache-trust.test.ts ./scripts/behavior-contract/test-scope.test.ts
• reason_not_testable:
• red_evidence: The trusted-generic tracer failed because no same-repository generic job with signed development-cache authority existed.
• green_evidence: Parent static validation passed 25 tests/607 assertions, non-executing YAML parse (15 jobs), and diff hygiene. Contracts prove immutable action pins, mutually exclusive trusted/fork paths, zero fork authority, scoped development signing, no manual publisher/token/write scope, preserved fast feedback, and a fixed success-only candidate artifact.
• codebase_design_notes: Workflow remains a thin authority adapter over T12 commands. Candidate JSON is transport only; T14 must verify workflow/run/event/conclusion/head/tree/artifact provenance before mutation.
• review_mode: cli
• runtime_validation: required
• runtime_target: same-repository and fork pull-request Actions runs
• runtime_evidence: Pending the single feature-branch pull request. Same-repository run must prove signed reuse and exact candidate evidence; the user-mandated one-PR constraint precludes a second live fork PR, so fork isolation is currently proven statically and will remain an explicit runtime-evidence limitation unless equivalent existing live evidence is found.
• runtime_cleanup: Retain run/artifact ids; remove no shared provider state.

T14: Add Dormant Protected Release Authority

• depends_on: [T13]
• location: dedicated release workflow and authority contracts
• owned_paths: [.github/workflows/release.yml, scripts/behavior-contract/release-authority.test.ts, apps/cli/scripts/release-authority.mjs, apps/cli/scripts/release-authority.d.mts, apps/cli/scripts/run-release-authority.mjs, apps/cli/scripts/run-release-authority.d.mts, apps/cli/src/scripts/release-authority.test.ts, apps/cli/src/scripts/run-release-authority.test.ts, apps/cli/package.json, package.json, turbo.json, scripts/behavior-contract/cli-release-task-graph.test.ts]
• wave_boundary: W10; only task newly unblocked.
• description: On every exact main tree classify, require matching successful candidate evidence, and invoke non-cancelling serial convergence only when a reviewed enable input is present. Use Production, id-token: write, no npm token, Vercel variables only in the baseline child, immutable action pins, and uncached external mutations. Add a pull-request-triggered non-mutating guard-verification path so the new workflow can prove its dormant boundaries before merge.
• validation: Static contract plus the pull-request guard path proves exact workflow/environment/permission/secret boundaries and direct/unattested mutation refusal without pushing to main.
• status: Blocked on pull-request runtime evidence
• log: 2026-08-11 — Implemented the dormant release-authority module, runner, uncached task graph, and dedicated workflow. Static and local validation is complete; the literal-disabled Production job performed no provider action. The non-mutating release pull-request guard remains the final T14 runtime gate.
• files edited/created: [.github/workflows/release.yml, scripts/behavior-contract/release-authority.test.ts, apps/cli/scripts/release-authority.mjs, apps/cli/scripts/release-authority.d.mts, apps/cli/scripts/run-release-authority.mjs, apps/cli/scripts/run-release-authority.d.mts, apps/cli/src/scripts/release-authority.test.ts, apps/cli/src/scripts/run-release-authority.test.ts, apps/cli/package.json, package.json, turbo.json, scripts/behavior-contract/cli-release-task-graph.test.ts]
• backlog_item_id: IP-372
• backlog_item_url: https://linear.app/devpunks/issue/IP-372/confine-and-activate-release-authority-on-github-free
• relation_mode: native
• assigned_skills: [audit-cicd-security, codebase-design, tdd, turborepo]
• tdd_status: required
• tdd_target: The release workflow uses Production OIDC and contains no long-lived npm publication token.
• red_command: bun test ./scripts/behavior-contract/release-authority.test.ts -t "uses Production OIDC without an npm token"
• expected_red_failure: Dedicated release workflow is absent and manual token publication remains elsewhere.
• green_command: bun test ./scripts/behavior-contract/release-authority.test.ts ./scripts/behavior-contract/cache-trust.test.ts ./scripts/behavior-contract/cli-release-task-graph.test.ts
• reason_not_testable:
• red_evidence: The public workflow contract failed because .github/workflows/release.yml did not exist.
• green_evidence: CLI authority tests passed 6/6; workflow/cache/task-graph validation passed 34/34 with 808 assertions; CLI typecheck, direct help, targeted Oxlint/Oxfmt, Ruby YAML parse of three jobs, and diff hygiene passed. Static contracts prove exact run/artifact provenance, canonical evidence validation, first-parent serial convergence from a durable anchor, mutually exclusive product authority, immutable action pins, and the literal-disabled sole Production job.
• codebase_design_notes: Workflow grants narrowly confined authority. Scripts own validation, provider readback, ordering, and convergence; the workflow stays a thin trigger/permission adapter.
• review_mode: cli
• runtime_validation: required
• runtime_target: non-mutating guard-verification job on the feature-branch pull request
• runtime_evidence: The pull-request run proves dormant/exact-evidence refusal and job boundaries without changing main or provider products.
• runtime_cleanup: Retain run id; no product/provider cleanup required.

T15: Document, Review, And Close Dormant Delivery

• depends_on: [T14]
• location: operator docs, lifecycle evidence, routed metadata, Unreleased changelogs and dormant provider readback
• owned_paths: [docs/README.md, docs/runbooks/hi-cli-scaffolding.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PLAN.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PHASE-HANDOFF.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/meta.json, CHANGELOG.md, BASELINE_CHANGELOG.md]
• wave_boundary: W11; completes dormant repository delivery.
• description: Document proven cache, hook, candidate, classifier, assembly, retry, authority and recovery behavior; update Unreleased without inventing versions. Run full validation, implementation review, security audit, and docs ingest. Read back existing npm/GitHub provider configuration when access permits, but do not mutate remote settings. Record the exact reviewed-intent, provider-configuration, and authorization blockers for T16.
• validation: Docs/content/full repo/consumer/review gates and pull-request guard evidence. Non-mutating provider readback is optional diagnostic evidence only.
• status: In Progress; docs ingest complete, pull-request runtime pending
• log: 2026-08-11 — Updated operator docs and Unreleased ledgers, synchronized the routed runbook, retained review/security/provider evidence, and completed private docs ingest. Final task closure waits for the T13/T14 pull-request runtime gates.
• files edited/created: [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/cache-release-diff-classification/SPEC.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PLAN.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/IMPLEMENTATION-NOTES.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/PHASE-HANDOFF.md, apps/wiki/content/docs/project/specs/cli/cache-release-diff-classification/meta.json, apps/wiki/log.md, CHANGELOG.md, BASELINE_CHANGELOG.md]
• backlog_item_id: IP-372
• backlog_item_url: https://linear.app/devpunks/issue/IP-372/confine-and-activate-release-authority-on-github-free
• relation_mode: native
• assigned_skills: [autoreview, codebase-design, create-spec, create-plan, docs-onboarding, implement-spec, improve-codebase-architecture, parallel-research, review, simplify, tdd, writing-beats, writing-for-agents, writing-fragments, writing-shape]
• tdd_status: not_applicable
• tdd_target: Durable docs and activation evidence state only proven behavior and explicit blockers.
• red_command:
• expected_red_failure:
• green_command: bun run --cwd apps/wiki check:content && bun run check && bun run check-types && bun run build && bun run test && bun run validate:consumer-repositories && git diff --check
• reason_not_testable: Documentation and lifecycle bookkeeping use content, format, and diff validation; controlled external activation remains separately blocked.
• red_evidence:
• green_evidence: Docs projection, scoped formatting, and diff hygiene passed. After rebasing onto CLI 3.1.12, final title authority preserved 428 baseline titles and classified 442/442 protected and collected titles as 119 portable, 317 capability-keyed, and 6 fresh. The integrated CLI release suite passed 13 files/156 tests. The final authority/cache gate passed 4 files/37 tests/864 assertions; its task-graph subset passed 18/18 and the corrected 15-second multi-dry-run budget completed in 4.71 seconds. CLI typecheck and YAML parsing passed. Final structured review exited 0 with findings=[], patch correct, confidence 0.99; security review found no reachable Critical, High, or Medium issue while Production remains literal-disabled.
• codebase_design_notes: One runbook links machine evidence; policy remains in code.
• review_mode: cli
• runtime_validation: required
• runtime_target: dormant GitHub workflow pull-request guard
• runtime_evidence: Pull-request guard evidence proves dormant authority. Any provider readback only records whether exact workflow/Production trust is already configured and is not required to complete T15.
• runtime_cleanup: Never delete immutable products; remove only temporary validation roots.

T16: Activate One Production Release When Separately Authorized

• depends_on: [T15]
• location: npm/GitHub provider configuration and one reviewed production release
• owned_paths: []
• wave_boundary: W12; starts only with separately reviewed release intent and explicit production authorization.
• description: Configure the exact npm Trusted Publisher and case-sensitive Production environment if still absent, establish script-free Production installation and durable release-tag namespace provenance/protection, remove unused Vercel authority, enable only the reviewed npm version and/or baseline tag/range/changelog intent, merge through the normal reviewed path, prove one OIDC release and exact registry/install/consumer/baseline readbacks, then revoke legacy bypass authority in a later verified step. If intent or authorization is absent, leave this task blocked without weakening dormant guards.
• validation: Exact provider readback, successful eligible candidate identity, OIDC publication with no npm token, immutable product/readback equality, installed consumer matrix, and post-proof legacy-authority absence.
• status: Blocked
• log: 2026-08-11 — No production authority or provider mutation was authorized. Activation requires reviewed product intent, exact npm Trusted Publisher/workflow binding, reviewed Production configuration and protections, explicit authorization, and PR runtime evidence. Accepted lower-severity hardening also requires a script-free Production install, removal of unused Vercel authority, and durable release-tag namespace provenance/protection.
• files edited/created:
• backlog_item_id: IP-372
• backlog_item_url: https://linear.app/devpunks/issue/IP-372/confine-and-activate-release-authority-on-github-free
• relation_mode: native
• assigned_skills: [audit-cicd-security, review]
• tdd_status: not_applicable
• tdd_target: Provider-backed activation proves the already-tested dormant authority against reviewed production intent.
• red_command:
• expected_red_failure:
• green_command:
• reason_not_testable: External provider configuration and immutable publication are approval-gated operations, not a code TDD slice.
• red_evidence:
• green_evidence:
• codebase_design_notes: T16 supplies authority and reviewed intent only; it does not change release policy.
• review_mode: cli
• runtime_validation: required
• runtime_target: one explicitly authorized OIDC production release and subsequent legacy-authority revocation
• runtime_evidence: Exact workflow/Production identity, no npm token, registry/install/consumer and baseline production readbacks, then verified legacy-token revocation.
• runtime_cleanup: Never delete or overwrite immutable products; remove only task-created temporary validation roots.

Testing Strategy

1. Each behavior task starts with one failing public-interface tracer bullet and advances vertically.
2. Inventory and classifier matrices are table-driven, but each new row is added only after the previous behavior reaches GREEN.
3. External systems are injected behind read/write adapters. Unit and integration tests use real local package trees, git worktrees, filesystems, processes, and installed consumers; provider mutations use deterministic adapters until controlled activation.
4. Cache acceptance proves execution, misses, compatible hits, restoration, invalidation, signature rejection, byte equality, fresh witnesses, and clean state.
5. Candidate acceptance proves exact tree and complete artifact identities plus every terminal failure mode.
6. Convergence acceptance proves serial order, partial retry, immutable readback, mutable alias repair, tag target, installed consumers, and later-version blocking.
7. Workflow acceptance parses committed YAML and uses real pull-request Actions runs for fork/internal isolation, exact candidate evidence, and the non-mutating dormant guard. Direct/unattested main refusal is proven pre-merge through static contracts and injected local evidence; a live main run is observed only after normal reviewed merge.
8. Validation widens from task tests to CLI checks/build, root behavior contracts, repository checks/types/build/tests, consumer repositories, wiki content, diff hygiene, structured review, and final Actions evidence.

Validation Gates

Gate A: Verification soundness

• T1 inventory is complete and exact once.
• Portable and capability identities have explicit inputs/outputs.
• Every fresh witness states the unreplayable property.
• Fork-shaped execution is credential-free.

Gate B: Product authority

• T4 assembly is complete and compatible.
• T5 classifier matrix is semantic and fail closed.
• T7 eligible evidence binds exact tree, intent, and artifacts.

Gate C: Stable convergence

• T9 through T11 reconcile all partial states without overwriting immutable versions.
• T12 through T14 keep external mutations uncached and authority step-scoped.
• Direct/red/cancelled/unattested main paths demonstrably mutate nothing.

Gate D: Repository closeout

• Focused and full local validation are green.
• Mandatory review-phase covers spec and standards; security-review covers workflow authority; autoreview returns no accepted/actionable finding.
• docs-ingest-phase updates durable implemented knowledge or records an explicit no-op.
• Linear story state changes only after each story's mapped evidence exists. IP-366 completes only when all six child outcomes are proven; controlled activation remains open if reviewed release intent or provider authority is absent.

Review Routing

• Mandatory implementation review compares origin/main...HEAD against this SPEC.md and every IP-367 through IP-372 acceptance mapping.
• Standards review uses root/scoped AGENTS.md, TDD evidence, Turborepo task ownership, and external-mutation cache boundaries.
• Security review focuses on fork isolation, artifact trust separation, OIDC/environment identity, action pinning, step-scoped Vercel variables, token absence, artifact download verification, and publisher guard bypasses.
• Findings are fixed in the owning task scope, focused tests rerun, then review repeats until no accepted actionable finding remains.

Docs-Ingest Expectations

• Update docs/README.md and docs/runbooks/hi-cli-scaffolding.md because operator workflow, hooks, release architecture, credentials, and recovery all change.
• Write IMPLEMENTATION-NOTES.md throughout execution and retain review, runtime, provider, deviations, and activation blockers.
• Run docs-ingest-phase after implementation/review. Update routed wiki knowledge only from proven behavior; otherwise record a no-op in implementation notes.

Backlog Sync

Backlog sync was verified and requires no mutation. The authoritative immutable spec remains attached to IP-366 through IP-372; one epic, six child stories, one M11 milestone, native parent hierarchy, labels, primary story coverage, and all 51 acceptance criteria remain correct. Plan tasks reference existing stories and do not create task-level Linear issues or native blockers.

Risks And Mitigations

Unresolved Questions

• No product-design question remains open.
• External activation remains intentionally pending until a separately reviewed change supplies the exact npm version/changelog and/or baseline tag/range/changelog intent required by the classifier, and the user explicitly authorizes production publication.
• npm Trusted Publisher and GitHub environment configuration are read back without mutation during T15 when access permits. Missing reviewed release intent, provider configuration, or explicit production authorization blocks T16 only, not dormant delivery.