Scaffold Output Normalization Grill Log

Research Baseline

• The live Collective Intelligence hi check --json reports ten local-edited paths: lint selection, eight workspace Oxlint configs, and the Effect source guide.
• None currently has an independent, version-controlled, byte-identical repository producer, so none qualifies for RepositoryMirror ownership.
• Harness renders all ten. Repository Oxfmt subsequently rewrites lint selection and the eight Oxlint configs in place.
• The Effect guide is genuinely behind the already accepted Effect v4 guide and is not a formatter-only mismatch.
• CLI 3.1.4 contains the ownership classifier, but production desired-output planning supplies no real projectProducer declarations.

Branch: Ownership Model

Q1

Prerequisites:

• none

Question: Should the follow-up keep these ten paths strictly scaffold-managed and fix the formatter/adoption mismatch, or deliberately introduce new canonical repository sources and copy producers so they can become project-generated mirrors?

Accepted answer:

• Keep the ten paths scaffold-managed.
• Fix deterministic normalization for the nine formatter-rewritten outputs.
• Adopt the accepted Effect v4 guide as a separate stale-output correction.

Recommendation:

• Keep them scaffold-managed. Fix deterministic normalization for the nine formatter-rewritten outputs and adopt the accepted Effect v4 guide separately. Creating canonical copies only to satisfy RepositoryMirror would introduce a second authority that does not exist today.

Branch: Canonical Desired Bytes

Q2

Prerequisites:

• Q1

Question: For scaffold-managed text that the repository formatter rewrites, should formatter-normalized bytes become the desired bytes, or should managed output be excluded from repository formatting?

Accepted answer:

• Formatter-normalized bytes are the canonical desired bytes.
• Desired state, written output, and receipt evidence must use the same deterministic bytes.
• hi check remains read-only.

Recommendation:

• Make formatter-normalized bytes canonical. Desired state, written output, and the receipt must use the same deterministic bytes. hi check must remain read-only.

Branch: Effect Guide Adoption

Q3

Prerequisites:

• Q1

Question: Should the next reconciliation replace the old generic opensrc/effect.md with the already accepted Effect v4 guide?

Accepted answer:

• Yes, and the rule is not specific to opensrc/effect.md.
• For every scaffold-managed path under opensrc/, reconciliation replaces an older guide when current desired content has changed.
• Source guides remain strictly scaffold-managed; no guide-specific ownership exception is added.

Recommendation:

• Yes. This is stale scaffold content, not formatter drift or repository-produced output.

Branch: Normalization Scope

Q4

Prerequisites:

• Q2

Question: Should formatter normalization apply through one shared scaffold-output boundary for every supported scaffold-managed text file, or only to the nine files that exposed this defect?

Accepted answer:

• Apply normalization at one shared scaffold-output boundary for every supported scaffold-managed text file.
• Do not maintain a path list for the nine files that exposed the defect.

Recommendation:

• Use one shared boundary for every supported scaffold-managed text file. Do not add a list of the nine current paths.

Branch: Formatter Authority

Q5

Prerequisites:

• Q2

Question: Should normalization use the consumer repository's checked-in formatter configuration and pinned formatter version, or one fixed Harness formatting policy?

Accepted answer:

• Use the consumer repository's checked-in formatter configuration and pinned formatter version as formatter authority.
• Desired bytes must match the bytes that the repository's own tooling will produce.

Recommendation:

• Use the consumer repository's checked-in configuration and pinned formatter version. Those inputs define the bytes that repository tooling will produce after a scaffold write.

Branch: Formatter Failure

Q6

Prerequisites:

• Q5

Question: If the checked-in formatter configuration or pinned formatter version cannot be resolved, should hi stop before comparison or writes, or fall back to raw scaffold bytes?

Accepted answer:

• Stop before comparison or writes when formatter authority cannot be resolved.
• Do not fall back to raw scaffold bytes.
• Baseline distribution owns the formatting configuration, so normal operation should already have the required desired configuration.

Recommendation:

• Stop before comparison or writes. A raw-byte fallback would recreate false drift and could write bytes that repository tooling immediately changes.

Branch: Read-Only Normalization

Q7

Prerequisites:

• Q4
• Q5

Question: May hi check run the pinned formatter against staged or in-memory content when it never changes the consumer working tree?

Accepted answer:

• Yes. hi check may normalize staged or in-memory content without changing the consumer working tree.
• Normalize each planned artifact immediately, before comparison, writing, or receipt generation.

Recommendation:

• Yes. Read-only means no consumer-repository mutation. The same deterministic normalizer must produce desired bytes for check, write planning, and receipt generation.

Branch: Supported Files

Q8

Prerequisites:

• Q4

Question: Should formatter capability decide which scaffold-managed text files are normalized, while unsupported files, binaries, and symlinks keep their existing byte contract?

Accepted answer:

• Yes. Formatter capability selects supported scaffold-managed text files.
• Unsupported text, binary files, and symlinks retain their existing byte contracts.

Recommendation:

• Yes. Do not invent a second extension list in Harness. Normalize only files the selected formatter reports or proves it supports.

Branch: Baseline Formatter Authority

Q9

Prerequisites:

• Q5
• Q6

Question: Should baseline authority own the formatter contract and exact Oxfmt version while each repository's committed formatter configuration owns its style, or should baseline authority also own one complete formatter configuration for every repository?

Accepted answer:

• The repository's own format command is formatter authority.
• Harness does not pin or inspect Oxfmt, its version, or its configuration separately.
• The repository command resolves its own formatter tools and policy.
• This supersedes the pinned-version part of Q5. Q5 still establishes that repository formatting, not one fixed Harness style, defines normalized bytes.

Recommendation:

• Use the hybrid contract. Baseline authority owns normalization behavior and an exact Oxfmt version. Each repository's committed formatter configuration owns its style. Desired state records the formatter version and configuration fingerprint used to derive bytes.

Verified current state:

• Baseline authority distributes only the format-edited-file hook bytes and catalog membership.
• It does not distribute or read .oxfmtrc, require Oxfmt for general consumers, or pin its version.
• Hook execution currently resolves Oxfmt through the consumer package manager and lockfile.
• Wiki scaffolding has incomplete Oxfmt dependency coverage and still uses latest in one path.

Steering:

• The recommendation above was rejected. The accepted contract invokes the repository format command as one opaque repository-owned operation.

Q10

Prerequisites:

• Q9

Question: Should the CLI avoid repository formatter execution entirely and instead make the distributed format hook skip every path listed as managed in .devpunks/scaffold-manifest.json?

Accepted answer:

• Yes. Do not run a repository format command from hi check, hi update, or scaffold desired-state compilation.
• Raw scaffold bytes remain authoritative.
• The distributed format hook reads .devpunks/scaffold-manifest.json and skips every managed path.
• This decision supersedes Q2 and Q4-Q9. Their investigation remains useful evidence for rejecting CLI-owned formatter normalization.

Recommendation:

• Yes. Keep raw scaffold bytes authoritative. Generalize the hook's existing scaffold-owned exclusion from a hard-coded partial path rule to the managed-file receipt. This supersedes Q2 and Q4-Q9 if accepted.

Verified current state:

• The hook formats individual JavaScript, JSON, and Python paths, not a repository format script.
• It already calls isScaffoldOwnedPath, but that function recognizes only scaffold evidence, .agents assets, and selected agent mirrors.
• Lint selection and workspace Oxlint configs are managed receipt entries but are absent from that hard-coded exclusion.
• The manifest is the existing complete managed-path source of truth.
• Planning discovery confirmed that .devpunks/scaffold-manifest.json cannot list or hash itself without recursive evidence. The manifest file therefore remains the sole bootstrap exclusion; every other scaffold-owned exclusion comes from its managedFiles receipt. This is not a fallback when the receipt is invalid.

Branch: Manifest-Unavailable Safety

Q11

Prerequisites:

• Q10

Question: If the format hook cannot read a valid scaffold manifest, should it skip formatting for that invocation instead of using its incomplete hard-coded ownership rule?

Accepted answer:

• Yes. If the hook cannot read a valid scaffold manifest, it performs no formatting mutation for that invocation.
• It does not fall back to the incomplete hard-coded ownership rule.

Recommendation:

• Yes. Fail closed by making no formatting mutation. A missed format is safer and reversible; formatting an unknown managed file recreates false drift.

Branch: One-Time Reconciliation

Q12

Prerequisites:

• Q11

Question: After the fixed hook is distributed, should the Collective Intelligence migration replace only the nine files proven to differ solely because of automatic formatting with their raw desired scaffold bytes, while all other local edits remain conflicts?

Accepted answer:

• Yes. After the fixed hook is distributed, perform one explicit, reviewed reconciliation of only the nine files proven formatter-only.
• Other local edits remain conflicts. No general force-overwrite behavior is added.

Recommendation:

• Yes. Use an explicit, reviewed one-time adoption. Do not add a general force-overwrite rule.

Branch: Manual Repository Formatting

Q13

Prerequisites:

• Q11

Question: Should this fix govern only the distributed automatic format hook and leave manually run repository-wide format commands outside Harness control?

Accepted answer:

• Yes. Harness governs only its distributed automatic format hook.
• Manually run repository-wide format commands remain repository responsibility. If they change managed bytes, hi check reports drift.
• Harness does not manage formatter-specific ignore files in this follow-up.

Recommendation:

• Yes. If a manual format command changes managed bytes, hi check reports that change. Formatter-specific ignore-file management would add the complexity this design is avoiding.

Branch: Release Carrier

Q14

Prerequisites:

• Q12
• Q13

Question: Should this fix ship as a new stable baseline without another npm CLI patch, unless implementation proves that executable CLI code or a schema must change?

Accepted answer:

• Yes. Ship the hook fix through a new stable baseline.
• Do not publish another npm CLI patch unless implementation proves that executable CLI code or a schema must change.

Recommendation:

• Yes. The distributed hook is a baseline asset, and CLI 3.1.4 can already consume a new compatible baseline. Avoid another npm release when the behavior can move through the owning release surface.

Verified current state:

• Baseline build copies hook source bytes into the baseline archive.
• Baseline publication requires a clean worktree, changelog entry, explicit compatibility range, GitHub assets, control-plane promotion, and stable readback.
• The current baseline publisher has no candidate channel; publication promotes directly to stable.

Branch: Consumer Rollout

Q15

Prerequisites:

• Q14

Question: After stable baseline publication, should Collective Intelligence be the immediate first consumer: pin the exact new baseline, preview, perform the approved one-time reconciliation, prove an exact and stable clean check, then allow broader adoption?

Accepted answer:

• Parked outside this change scope.
• Collective Intelligence is not an implementation or release gate for the hook change.
• The user will run hi check there after the Harness work is complete and decide any consumer reconciliation separately.

Recommendation:

• Yes. If the pilot fails, roll stable authority back before broader adoption and revert the reviewed Collective Intelligence migration diff. Do not continue to other repositories.

Steering:

• The recommendation above was rejected because it expanded the change into consumer rollout.
• The hook fix is preventive. It does not rewrite the nine existing formatter-changed files or replace stale opensrc/ guides. A later read-only check can still report those until a separately authorized reconciliation.

Branch: Shared Understanding

Q16

Prerequisites:

• Q15

Question: Do we confirm the bounded change: fix and test the distributed hook, publish its baseline, do not mutate Collective Intelligence, and treat any existing consumer drift as separate follow-up work?

Accepted answer:

• Confirmed.
• Implement and test only the manifest-backed distributed-hook boundary and its documentation.
• Publish the hook through a new stable baseline.
• Do not mutate Collective Intelligence or perform consumer reconciliation in this change.
• Do not publish an npm patch unless executable CLI code or a schema must change.

Recommendation:

• Yes, with the explicit expectation that a read-only consumer check diagnoses remaining drift but does not reconcile it.

Requirements Closure

• Shared understanding confirmed on 2026-08-06.
• Active requirements are closed.
• Collective Intelligence reconciliation is parked as a separate user-owned follow-up.
• The requirements are ready for bounded backlog or delivery planning; no provider backlog write or sync was authorized.