Issue 197 Scaffold Lifecycle Grill Log

Starting brief

Source: issue #197 and the user's architecture assessment request on 2026-09-05.

The user requests a complete reassessment of scaffold, update, and check, including Lefthook, lint configuration, working skill delivery, scoped guidance, and scoped subagent generation. Regeneration must be relevant to changed inputs, not routine work on every update. Define the deterministic CLI and dynamic Post-Command Handoff responsibilities explicitly.

Assessment branch: team/stefan/issue-197-scaffold-architecture, based on upstream main at b9bb213d. The primary checkout remains on its existing issue #194 branch. This assessment does not establish implementation, release, or provider changes.

Round R1: foundation decisions

Q1

Prerequisites: none.

Evidence anchors:

• docs/runbooks/hi-cli-scaffolding.md: Commit Gate lifecycle.
• apps/wiki/content/docs/project/grilling/lefthook-pre-commit-catalog-grill-status.md: materialization lifecycle and Q25-Q28.

Observed constraint: the runbook assigns deterministic Commit Gate artifacts to scaffold and installation/verification to the agent. Current source contradicts the first half: planCommitGate and mergeLefthookCommitGate have no production caller, and output.ts:renderAgentHandoffMarkdown omits commitGateHandoff. The R1 question initially described the documented boundary; this finding corrects that factual premise without changing the question or recommendation.

Question: should scaffold/update complete deterministic config, dependency, hook installation and verification when ownership and policy are clear, leaving the agent repository-specific authoring and ambiguous conflicts?

Recommendation: yes. Mechanically verifiable setup should have one executable owner; repository interpretation remains agent work. Existing hook-manager migration still requires a concrete accepted proposal.

Code consequence: executable lifecycle operations and their verification move behind CLI application boundaries; handoff entries identify only residual work. This changes part of the prior accepted installation boundary.

Accepted answer: CLI completes routine setup; agent handles interpretation. User accepted Q1 during R1. This supersedes routine installation being agent-owned in the earlier Commit Gate lifecycle contract. It does not authorize conflicting hook-manager migration or reinterpret repository policy.

Q2

Prerequisites: none.

Evidence anchors:

• apps/cli/src/integrations/repository-detector.ts:qualityCommandContractFor.
• apps/cli/src/features/context-planning/compiler.ts:commitGateContributionFor.
• Live hi check --json, CLI 4.0.4: incomplete Quality Command Contract for apps/api.

Observed constraint: command discovery recognizes selected package-script names; compilation rejects supported consumers when either command is absent.

Question: should selected baseline contributions provide supported lint/format defaults, preserving explicit repository contracts, with agent help only for ambiguous mappings?

Recommendation: yes. A supported scaffold should be able to plan its required quality tooling without requiring the consumer to pre-create the contract. Never infer that an arbitrary command is read-only or replace custom policy.

Code consequence: distinguish observed repository commands from resolved desired commands. Incomplete desired contracts remain blocked, but missing observed commands can become explicit planned changes. This revises the earlier compilation prerequisite; it does not disable the Commit Gate.

Accepted answer: baseline defaults with repository overrides. User accepted Q2 during R1. Missing observed scripts can be planned from supported baseline contributions; ambiguous or incomplete resolved commands still require action.

Q3

Prerequisites: none.

Evidence anchor: apps/cli/src/features/repository-check/application.ts:runRepositoryCheckApplication.

Observed constraint: check calls the update assessment before completing its other checks. The reproduced contract failure prevents a full health report.

Question: should check report independent areas when one area is blocked, mark unassessable areas unknown with their exact cause, and return nonzero while required state remains unresolved?

Recommendation: yes. Partial evidence must remain useful without turning an unassessed area into a clean result.

Code consequence: check becomes an aggregate observation result with component availability and cause, while write commands retain strict validity gates.

Accepted answer: complete report with explicit unknowns. User accepted Q3 during R1. Independent observations remain visible; unresolved required state returns nonzero and cannot be reported clean.

Preserved constraints

Q4: user-supplied requirement during brainstorm

Prerequisites: none; supplied directly after R1.

Question resolved by user: must check avoid reporting drift merely because scaffolded context intended for editing was edited?

Accepted answer: yes. The user reports frequent false drift on editable scaffolded context. Intentional edits to repository-authored context must not be classified as managed-byte drift.

Evidence status: the reported recurrence is user evidence; no concrete false-positive instance is reproduced yet. Readonly follow-up traced update/run.ts:isProjectAuthoredManagedFile, resolveFileOwnership, and compareObservedState: existing kind/path exemptions can also suppress missing required outputs. Separate editability from required presence and validity.

Code consequence: ownership determines the comparison. Baseline-owned bytes, deterministic generated mirrors, repository-authored context and mixed-ownership entries require distinct validation. Authored content should be checked for applicable structural/semantic contract obligations, not template byte equality. Exact ownership/migration rules remain brainstorm candidates. This does not authorize silently accepting all local edits or weakening generated-file checks.

Other preserved constraints

• Skills remain sourced through the existing canonical source-first workflow.
• Repository-owned content and explicit policy remain protected.
• Candidate dependency/configuration/cleanup failures block publication; ordinary lint findings remain adoption warnings under issue #181 AC-012.
• Prior completed receipt evidence remains validated; issue #194's fix must not be replaced by manufactured completion evidence.
• hi check is read-only. hi ensure remains settings-only unless explicitly reconsidered in a later decision.

Focused .devpunks/ brainstorm continuation

The user requested completion of the .devpunks/ portion, reporting that these artifacts often drift and cause check/update errors. The existing report now classifies concrete settings, receipts, context plans, specs, instruction views, workflow records and recovery copies by authority and lifecycle. It records candidates for semantic portability, generated-view rebuilding, truthful proof recovery, consumer-specific failures and ownership-preserving legacy migration.

This adds no accepted answer beyond Q1-Q4. Specific false-positive examples remain unreproduced. The detailed candidates and behavioral cases are ready for later requirements closure; no implementation or cleanup of .devpunks/ occurred.

Round R2: Requirements Phase entry

Q5: accepted .devpunks/ architecture

Prerequisites: Q1-Q4 and the completed focused brainstorm.

Question resolved by user: adopt the presented .devpunks/ responsibilities and recovery rules? Accepted answer: yes, through “ok good. i agree with this. now requirements-phase onto this”.

Accepted decisions:

• Keep existing artifact paths initially; define authority per artifact and per owned entry where applicable.
• Settings preserve user choices and validate CLI-calculated fields separately. Scaffold manifest records ownership and successfully adopted state rather than serving as a regenerated whole-document byte target.
• Context Plan remains a required synchronization input after canonical adoption. Compare semantic content and rebuild from intact authoritative inputs when needed. Its absence must not silently reactivate legacy behavior.
• Operational receipts prove completed, input-bound work. Missing proof requires fresh verification; neither file existence nor a reset manifest proves success.
• Authoring specs and handoff Markdown support identified active work. Retain authored material; stale prose cannot independently invalidate installation state or reactivate completed actions. Preserve workflow records and archives.
• Output publication, verification, receipt writing and manifest advancement form one recoverable operation. Record sufficient pending evidence to detect interruption, retain truthful state and resume safely without a producer loop.
• Semantic comparisons use portable identities and meaningful content. Exclude temporary roots, irrelevant order and formatting from semantic drift while revalidating genuinely local evidence such as installed hooks.
• Explain failures through the violated obligation and affected consumer; ownership uncertainty blocks dependent actions while independent checks remain visible. Migrate known legacy contracts once, retaining authored material.

Evidence anchors: research report's focused .devpunks/ consumer map; update/run.ts:readScaffoldManifest; sync-subagents.mjs:readContextPlan and projection receipt publication; project-settings/model.ts; shared receipt ownership schemas. These decisions supersede the earlier candidate-only status for the presented responsibilities and recovery rules. Exact serialization and implementation choreography remain downstream design detail.

Q6

Prerequisites: Q1, Q4, Q5.

Evidence anchors: scaffold/output.ts scoped prompt/spec generation; update/run.ts broad context planning; sync-subagents.mjs manifest/context scope and skill-closure validation.

Observed constraint: current planning/synchronization is broad; a repository workspace or skill-membership change can alter the required specialist set even without a new baseline.

Question: should relevant baseline changes and local workspace/selected-skill changes schedule only affected guidance/agent work, while ordinary source edits do not?

Recommendation: yes. Check reports pending work; update handles deterministic changes and emits a bounded handoff. New scopes do not require waiting for the next unrelated baseline release.

Code consequence: scope/skill identity is an explicit invalidation input; source file contents as a whole are not. Existing user-owned removed-scope guidance is preserved unless its cleanup is explicitly owned and authorized.

Accepted answer: baseline and scope changes trigger affected work. The user selected the recommended option in R2. Ordinary application-source edits do not automatically trigger scoped regeneration; check remains read-only.

Q7

Prerequisites: Q1, Q4, Q5.

Evidence anchors: packages/scaffold/src/context-plan.ts contribution identity and provenance; scaffold/output.ts prompt/subagent generation; existing skill content fingerprints and selective hi-cli post-command contract.

Observed constraint: content hashes detect changed bytes but cannot prove that the repository authoring or skill activation contract changed.

Question: should baseline producers declare an explicit authoring/activation contract revision separately from content hashes, with a bounded compatibility assessment for older baselines lacking that declaration?

Recommendation: yes. Ordinary skill-content refreshes then avoid repeated repository reauthoring while meaningful requirements changes remain explicit.

Code consequence: retain byte provenance for delivery and explicit contract identity for scoped invalidation. Baseline validation must prevent unsupported or ambiguous compatibility from being reported as current. Exact metadata shape and validation implementation belong in specification/planning.

Accepted answer: explicit contract revision plus content hashes. The user selected the recommended option in R2. Older baselines without declarations receive a bounded compatibility assessment; unresolved meaning is not current.

Requirements closure

Q1-Q7 are answered. The user's agreement to the completed brainstorm followed by explicit answers to both remaining R2 decisions confirms shared understanding. The accepted model was presented as current inputs → one Scaffold Plan → either read-only findings or apply/verify/record with scoped residual authoring.

No material product branch remains open. Exact schema field spelling, module layout and recovery implementation are downstream planning choices constrained by these requirements. The still-unproven #197 candidate root cause and reported false-drift examples are delivery verification work, not invented factual proof.

Requirements Phase now proceeds to a provider-neutral specification, immutable retention and delivery backlog projection. Product implementation and publication remain outside this phase. Configured provider root remains Devpunks/Harness; the currently connected Collective Intelligence workspace is not a substitute.

References

• Current status
• Consolidated research

Round R3: shared prompt baseline delivery

Q8

Prerequisites: Q1 and Q4-Q7, plus the readonly shared prompt baseline delivery research.

Question: should the complete consumer .agents/AGENTS.md be scaffold-owned and delivered by the selected baseline, with no installed-template fallback?

Accepted answer: yes. The user's correction is explicit: “.agents/AGENTS.md is NOT project owned. scaffold has total ownership.” The complete shared file is one scaffold-managed output through planning, check, update, candidate validation, replacement and receipt publication. Scoped repository-authored guidance, rules and custom roles remain separately owned and preserved.

The selected baseline declares the canonical data/shared-agents.md asset, its digest and compatible CLI capability. Missing or mismatched capability is an explicit compatibility/integrity result; installed CLI data cannot silently substitute for the selected baseline. This closes source authority while leaving exact metadata fields, module boundaries, migration release and implementation to the delivery plan.

Evidence: current runtime threads the selected baseline through stage/update planning, while shared prompt resolution reads installed process data; baseline archive construction omits the shared asset; update classifies existing agent-prompt files as project-authored and comparison skips them. These are confirmed code seams, not a reproduced historical consumer run. Collective- intelligence and ci-emera invocation details and the historical #197 cause remain unknown.

Decision consequence: add AC-037 through AC-045 and normative target seams to the specification. No new experiment, provider edge or runtime implementation is authorized by this requirements decision.