Spec: Reliable Scaffold, Update and Check Lifecycle

Context

Repository maintainers and coding agents use hi scaffold, hi update and hi check to adopt and maintain baseline context: quality tooling, Lefthook, skills, scoped coding guidance and native subagents. They need complete routine setup, preservation of authored context, and a truthful account of remaining work.

Issue #197 reports candidate validation failing to resolve workspace-local effect-tsgo although ordinary installation works. Its exact cause remains unproven. Separately, the user reports frequent false drift on editable context and .devpunks/ artifacts. Current hi check --json was observed stopping at an incomplete Quality Command Contract for apps/api; that result proves neither managed drift nor the candidate failure's cause.

This specification compiles accepted Q1-Q7 from the decision log and closed status. The research report contains current-code evidence. Its earlier candidate/open-decision language is historical; the closed status and this specification govern the target behavior.

Non-Goals

• Implement or release the product during Requirements Phase.
• Replace working source-first skill delivery or introduce a background agent scheduler.
• Redesign the .devpunks/ directory layout, reset the directory wholesale, or delete project workflow history, recovery evidence or authored material.
• Reauthor every scoped agent on each update or treat ordinary source edits as an automatic reauthoring trigger.
• Change hi ensure from settings-only reconfiguration or weaken existing hook-manager conflict/migration policy.
• Claim a reproduced root cause for #197 or repair other consumer repositories as part of specification compilation.

Requirements Outcomes

OUT-001: One coherent desired state across commands

Context Plan expresses neutral per-scope contribution intent. Scaffold Plan resolves desired files, links, configuration/dependency actions and ownership. Scaffold, update and check consume the same model and obligation rules. They separate desired state, observed state, successfully adopted state, and pending work. Check observes only; scaffold/update apply authorized deterministic actions.

OUT-002: Routine quality and hook setup completes in the CLI

For supported unambiguous selections, scaffold/update plan and materialize lint configuration, package commands/dependencies, Lefthook configuration, installation and operational verification. Baseline defaults fill missing supported Quality Command Contracts; explicit repository commands and choices take precedence. Ambiguity or conflicting ownership leaves only dependent work unresolved and produces an actionable Post-Command Handoff. Format checking remains read-only; the existing default-on/opt-out Commit Gate policy and hook-manager migration boundaries remain in force.

OUT-003: Check reports actual obligations without false drift

Check reports all independent areas, distinguishing verified current state, actual managed drift, invalid/missing required artifacts, pending work, and unknown state. A required unresolved obligation returns nonzero. A blocker names its cause and affected consumer; failure in one area does not erase independent results or imply unassessed state is clean.

Artifact editability, required presence, structural/semantic validity, and CLI-owned byte equality are separate obligations. Editable repository content is never drift merely because it differs from its initial template. Generated owned content remains checked against its applicable contract. Mixed ownership is assessed at the declared entry/region boundary. Location or broad file kind alone cannot establish ownership or waive required presence.

OUT-004: .devpunks/ artifacts have explicit authority and retention

Keep existing paths initially and classify each artifact and, when applicable, each owned entry. Settings preserve user policy while validating CLI-calculated fields separately. The scaffold manifest records adopted ownership and state; it is not a whole-document template-equality target. Once canonical context is adopted, missing context cannot silently select legacy behavior.

Generated instruction views describe structured active work. Specs and authored handoff notes remain protected; stale prose alone cannot invalidate installed state or reactivate completed work. Required current consumers determine which inputs/views must exist. Workflow records and recovery archives retain their project/run authority and are excluded from baseline-byte comparison and automatic pruning. Known legacy migration is finite and preserves authored material.

OUT-005: Publication and recovery preserve truthful progress

Coupled outputs, verification, receipts and manifest advancement form one recoverable operation. Durable pending evidence exposes interruption; this does not assume atomic multi-file renames. Completed independent actions survive unrelated failures. Dependent actions and adopted state cannot advance beyond verified completion.

Receipts attest input-bound completed work. Missing or corrupt proof produces an explicit unresolved obligation. Authorized recovery verifies actual current state before writing fresh proof; it cannot manufacture historical success or demand the receipt being repaired as a circular prerequisite. Resume converges for unchanged inputs without unrelated reauthoring.

Semantic identities use meaningful portable content. Irrelevant formatting, set order, timestamps, checkout locations and temporary paths do not cause drift. Ordering that changes behavior remains significant. Machine-local installation facts, including live hooks, are reverified in the current worktree.

OUT-006: Skill delivery and scoped work respond only to relevant inputs

Preserve working canonical source-first skill delivery. Track skill-content identity separately from explicit Generated Authoring Contract and activation contract revisions. Ordinary skill fixes refresh delivered files without requiring scoped reauthoring. Relevant declared contract changes and workspace or selected- skill membership changes invalidate only dependency-affected guidance and agent outputs. Ordinary source edits alone do not trigger automatic reauthoring.

Scoped Coding Standards are repository-authored. Native agent mirrors are mechanical projections of accepted scoped state. The complete shared .agents/AGENTS.md is scaffold-owned and is delivered by the selected baseline; it is not project-owned and is replaced as one managed file under its declared baseline contract. Adding/removing a scope does not authorize deletion of repository-authored scoped guidance or custom roles. Older baselines without the shared-prompt capability receive a bounded compatibility assessment; unknown compatibility is never reported as current, and the CLI never silently falls back to an installed-template copy.

OUT-007: Post-Command Handoff is bounded and verifiable

The CLI completes routine setup whose ownership and policy are clear. The agent interprets actual repository evidence, authors scoped guidance and resolves ambiguous conflicts. Each residual action identifies affected scope, current input/contract identity, reason, allowed outputs and completion evidence. It separates authoring from deterministic validation, native projection and receipt publication. A handoff's presence is not completion proof.

Check reports pending work without executing it. Update applies safe mechanical changes and emits only required residual actions. Completed current work is not rescheduled because old handoff prose remains or an unrelated baseline changed. Changed relevant inputs invalidate stale completion only for affected actions.

OUT-008: Candidate validation faithfully represents planned adoption

Isolated validation uses the planned manifests, lockfiles, configurations and workspace dependency/binary topology. A supported workspace command available under that planned ordinary installation must resolve in the candidate. Preserve issue #181 containment, disabled dependency lifecycle scripts, bounded executable resolution, cleanup and separation from live consumer state. No unsafe symlink or live-state mutation is permitted to make candidate validation pass.

Ordinary lint findings are adoption warnings under the existing contract. Installation, dependency/configuration, process and cleanup failures block the relevant publication. Evidence must distinguish a source lint finding from a broken candidate or failed command environment.

Acceptance Criteria

• AC-001: Given identical inputs and observations, scaffold/update/check agree on desired managed state and obligation classification. Covers: OUT-001.
• AC-002: Running check leaves repository files, dependencies, hooks, receipts and authored guidance unchanged. Covers: OUT-001, OUT-003, OUT-007.
• AC-003: A fresh supported selection with missing quality scripts plans baseline defaults and reaches verified quality/hook setup without routine agent installation. Covers: OUT-002.
• AC-004: Explicit repository quality commands and hook policy survive scaffold/update; ambiguous mapping or manager ownership yields an affected consumer blocker instead of replacement by guessed defaults. Covers: OUT-002.
• AC-005: The resolved format-check command is read-only and opt-out consumers do not receive an enabled Commit Gate. Covers: OUT-002.
• AC-006: With one unavailable component, check still reports every independently assessable component and names the blocked component's exact cause. Covers: OUT-003.
• AC-007: Any required unknown, missing, invalid, drifted or pending obligation produces nonzero check status and is never represented as verified current. Covers: OUT-003.
• AC-008: Intentional valid edits to repository-authored scoped guidance, authored handoff notes or custom roles produce no template-byte drift and survive an unrelated update. Covers: OUT-003, OUT-004, OUT-006.
• AC-009: Deleting or invalidating a required editable artifact reports its presence/validity obligation despite its editable status. Covers: OUT-003.
• AC-010: Changing a managed generated entry is detected while changing an allowed user-owned entry in the same mixed artifact is preserved and produces no managed-byte drift. Covers: OUT-003, OUT-004.
• AC-011: Unknown ownership blocks only dependent writes/verification and preserves independent findings and authored bytes. Covers: OUT-003, OUT-004.
• AC-012: Editing an allowed settings choice is treated as policy input; invalid CLI-calculated settings fields yield a specific contract error. Covers: OUT-004.
• AC-013: Removing required canonical context after adoption reports the affected consumer and does not select the legacy synchronization path. Covers: OUT-004.
• AC-014: An absent optional view with no active required consumer creates no required-state failure; an absent required consumed input names that consumer. Covers: OUT-003, OUT-004.
• AC-015: Editing/archive retention of workflow records, specs and recovery copies creates no baseline-byte drift or automatic deletion. Explicitly active workflow/recovery obligations remain visible. Covers: OUT-004.
• AC-016: A known legacy state migrates once without losing authored material; the next unchanged update schedules no repeat migration. Covers: OUT-004.
• AC-017: Interruption at each coupled output/verification/receipt/manifest publication boundary leaves detectable pending or prior valid state, with no false completion. Covers: OUT-005.
• AC-018: Resuming an interrupted operation with unchanged inputs converges without a missing-producer loop or unrelated scoped reauthoring. Covers: OUT-005.
• AC-019: Missing/corrupt receipt recovery publishes fresh completion only after actual current-state verification; file existence or stale prose alone cannot satisfy it. Covers: OUT-005.
• AC-020: Failure in one action preserves completed independent actions and prevents unverified dependent receipt/manifest advancement. Covers: OUT-005.
• AC-021: Relocation, irrelevant JSON formatting/set order and diagnostic path changes create no semantic drift, while behavior-significant ordering changes remain observable. Covers: OUT-003, OUT-005.
• AC-022: Moving to another worktree causes local hook proof to be reverified before current operational health is asserted. Covers: OUT-005.
• AC-023: A skill-body-only baseline fix refreshes the skill without new scoped authoring when contract and scope identities are unchanged. Covers: OUT-006.
• AC-024: An explicit relevant authoring/activation revision schedules only dependency-affected work; unrelated guidance/custom roles remain intact. Covers: OUT-006.
• AC-025: Adding/removing a workspace or changing selected skills schedules only affected scoped guidance/native projection obligations and preserves user-authored content for removed scopes. Covers: OUT-006.
• AC-026: Ordinary source edits with unchanged scope, selection and contracts produce no automatic scoped authoring action. Covers: OUT-006.
• AC-027: A legacy baseline without declarations receives one input-bound compatibility assessment; unresolved meaning stays explicit and cannot become current through a content hash alone. Covers: OUT-006.
• AC-028: Native mirrors agree with accepted scoped state and skill membership; routine projection does not replace repository-authored Scoped Coding Standards. Covers: OUT-006, OUT-007.
• AC-029: Every emitted residual action identifies scope, trigger, input/contract identity, allowed outputs and required completion evidence. Covers: OUT-007.
• AC-030: For unchanged verified state, a repeated update emits no new authoring work and stale handoff prose cannot reactivate a completed action. Covers: OUT-007.
• AC-031: Agent-authored completion returns through deterministic validation and projection before the applicable receipt records success. Covers: OUT-005, OUT-007.
• AC-032: Relevant changed inputs make prior action evidence stale only for affected work; check reports it and update emits its bounded handoff. Covers: OUT-006, OUT-007.
• AC-033: In a disposable supported Bun monorepo, a planned workspace-local executable resolves equivalently under ordinary planned installation and isolated candidate validation, including the #197 effect-tsgo scenario. Covers: OUT-008.
• AC-034: Candidate validation reads the proposed manifests/lockfiles/configs and preserves workspace binary topology without mutating live consumer state. Covers: OUT-008.
• AC-035: Candidate dependency lifecycle scripts stay disabled; executable resolution and symlinks satisfy the existing containment rules. Covers: OUT-008.
• AC-036: Lint findings yield warnings while installation, configuration, execution and cleanup failures block relevant publication with distinct causes. Covers: OUT-008.
• AC-037: A selected baseline declaring the shared-prompt capability supplies the complete .agents/AGENTS.md from its declared asset and digest; scaffold, check, update and candidate validation use that same selected asset identity. Covers: OUT-006, OUT-007.
• AC-038: A prompt-only baseline change refreshes the scaffold-owned shared file without reauthoring repository-owned scoped AGENTS.md, rules, custom roles or unrelated native projections. Covers: OUT-006.
• AC-039: An existing, missing or locally edited shared file is classified as scaffold-owned; authorized update replaces the complete file, while check is read-only and reports stale or missing state with its baseline identity. Covers: OUT-003, OUT-006.
• AC-040: A second update with unchanged selected baseline bytes and verified receipt state is a no-op and records no new authoring or replacement action. Covers: OUT-005, OUT-006, OUT-007.
• AC-041: A baseline lacking the shared-prompt capability returns an explicit unsupported-capability result; a declared asset that is absent or digest-mismatched returns an integrity result. Neither case adopts the installed CLI template as a substitute. Covers: OUT-006, OUT-007.
• AC-042: Authorized update may replace the scaffold-owned consumer file; regular files, copies and safe symlink cases never follow an unexpected target or mutate unrelated/candidate-external live state. Authored scoped files remain byte-preserved. Covers: OUT-003, OUT-005, OUT-006.
• AC-043: Shared-prompt desired state carries baseline/template identity, producer identity and dependency identity through the common Scaffold Plan; check, apply, candidate validation and receipts bind observations to those identities. Covers: OUT-001, OUT-005, OUT-006.
• AC-044: Recovery after interrupted shared-prompt publication re-verifies current bytes before writing fresh proof, converges on unchanged inputs and cannot treat a handoff, stale file or manifest alone as completion evidence. Covers: OUT-005, OUT-007.
• AC-045: A first compatible CLI reader can consume the versioned shared-prompt baseline capability, and subsequent prompt-only baseline publication remains compatible without requiring a CLI package release. Covers: OUT-006.

Constraints

• Preserve prior completed receipt validation and producer ordering established by issue #194; recovery cannot manufacture proof to bypass those checks.
• Preserve issue #181 candidate isolation and warning-versus-failure semantics.
• Preserve explicit repository ownership, user settings, custom roles and authored context across adoption, migration, refresh and recovery.
• Source-first changes to reusable skills use the canonical Devpunks skill repository, followed by exact-revision synchronization into consumers.
• Unsupported/ambiguous contracts remain explicit; broad ignore rules and blanket baseline hash invalidation cannot substitute for ownership/dependency contracts.

Dependency Readiness

No Stack Required. The assessment branch was created from upstream main at b9bb213dc490753020501ef81f42978d1caee89e, which contains the prior #194 fix. No unlanded dependency or other active backlog item is required by this spec. Existing related work is compatibility context, not an invented blocker.

Branch/Base Intent

Retain the assessment on team/stefan/issue-197-scaffold-architecture, based on main at the SHA above. The existing primary checkout's issue #194 branch remains separate. Downstream planning preserves this base intent and verifies then-current ancestry; it must not silently stack on unrelated unlanded work.

Accepted Technical Decisions

• One Context Plan/Scaffold Plan model separates authority, desired state, observation, adopted state and pending work.
• Artifact contracts declare ownership/editability separately from required presence/validity; mixed documents need entry/region authority.
• Portable semantic identities distinguish delivered content from explicit authoring/activation revisions and genuinely machine-local facts.
• Publication is recoverable with durable pending evidence and input-bound proof. Exact schema names, module boundaries and commit choreography remain plan-owned.
• Structured Post-Command Handoff describes residual interpretation/authoring; CLI validation/projection verifies its outputs and records completion.
• Keep existing artifact locations and working source-first skill delivery.
• Extend existing baseline metadata and publisher/resolver seams with a versioned shared-prompt capability and canonical data/shared-agents.md asset. Exact field names and module boundaries are plan-owned. The selected baseline is the sole authority for the shared .agents/AGENTS.md; installed CLI data is only a bundled source for an explicitly resolved bundled baseline.

Normative target seams

• packages/scaffold owns schemas for baseline capability metadata, asset identity, ownership and dependency/provenance; it does not own filesystem behavior.
• Existing baseline publisher and loader/resolver own archive inclusion, metadata validation, compatibility and digest checks.
• The common Scaffold Plan owns selected baseline/template identity and the shared-file action; scaffold, update, check and candidate validation consume that action without rebuilding a second desired state.
• CLI observers/writers own safe read, replacement, verification, manifest and receipt publication. Native projection remains a mechanical downstream view.
• Shared prompt capability support is a compatibility dependency of baseline selection. A missing or invalid declared asset blocks dependent adoption and cannot be repaired by falling back to installed-template authority.

Accepted Testing Decisions

Prove behavior through public command flows in disposable supported repositories. Use a fresh project, authored and mixed ownership, custom overrides, monorepo workspace binaries, legacy state, moved worktrees and interrupted publication. Check both expected success and preservation of user data. Trace the original #197 failure before claiming its cause; retained fixture evidence must distinguish an actual reproduction from an equivalent regression scenario.

No new product behavior or passing runtime verification is claimed by this Requirements Phase. Detailed test files/commands and task choreography belong to planning. Coverage must include no-op update, lint-only and skill-body-only changes, relevant contract/scope changes, missing/corrupt proof, and independent partial failure.

Verification Seams

• Public scaffold/update/check results, JSON findings and exit status.
• Before/after repository bytes, settings, manifests, required artifacts and hooks.
• Context/Scaffold Plan identity and planned-versus-observed quality commands.
• Isolated candidate installation, workspace executable resolution and cleanup.
• Pending action identity, agent-authored outputs, native projections and receipts.
• Restart at publication boundaries; compare prior valid, partial and recovered state.

Decision Log