Registry Baseline Grill Log

Durable decision record for replacing the manifest-driven hi scaffold, update, and check flow with a registry-based Baseline. Q1 to Q13 record decisions the user made during the brainstorm on 2026-09-27 before this grill opened. Later entries record grill rounds. Ids are stable; a changed decision gets a new superseding entry.

Branch A: Registry as Baseline distributor

Q1

Prerequisites:

none

Evidence anchor:

apps/cli/src/baseline/resolve.ts:512-580 (bundled, local, control-plane resolution order)
packages/contract/src/baseline.ts:289-303 (resolve, artifact, promote endpoints)
apps/api/src/baseline-registry.ts:366-420 (durable promotion store)

Observed constraint:

Nine issues (43, 49, 50, 55, 62, 63, 91, 94, 143) come from Baseline resolution and authority across three sources and a promotion step.

Question: What distributes the Baseline?

Accepted answer:

A registry in the shadcn registry format is the only Baseline distributor. GitHub release artifacts and the control-plane promotion path stop.
The registry is also the source for drift management.

Code consequence:

The baseline HTTP API group, the archive digest pipeline, and the verified baseline cache are retired or replaced by registry fetches.

Q2

Prerequisites:

Evidence anchor:

apps/cli/src/scaffold/managed-lint-generation.ts:157-266 (per-workspace render inputs)
apps/cli/src/scaffold/output.ts:2386,2418,2680 (prompt spec, subagent spec, workspace prompt renders)

Observed constraint:

Built Managed Artifacts depend on repository shape. Without the shape used at install time, a Drift check cannot separate a local edit from a shape change.

Question: How does the Drift check tell a local edit from a repository shape change on a built Managed Artifact?

Accepted answer:

The installer records the install-time repository shape (workspace paths, Pack ids, detected technologies) in Project settings. The Drift check re-renders at the installed version with that recorded shape.

Code consequence:

The installed record carries a Recorded Shape. No output hash is stored.

Q3

Prerequisites:

Evidence anchor:

.claude/agents/packages-db.md, .cursor/agents/packages-db.md, .opencode/agents/packages-db.md, .codex/agents/packages-db.toml (byte-identical body, different envelope)
.agents/scripts/sync-subagents.mjs (3,265 lines; also writes the manifest)

Observed constraint:

One authored manifest produces 88 files through a shipped script that is a second writer of CLI state (#105).

Question: Who produces the per-harness subagent files?

Accepted answer:

The hi CLI builds each subagent body once from .agents/subagents/manifest.mjs and wraps it in each harness envelope through a Harness adapter. sync-subagents.mjs and .agents/scripts/harness-projection/* are removed.

Code consequence:

Harness adapters are installer code, not consumer-repository scripts. One writer for all built files.

Q4

Prerequisites:

Evidence anchor:

shadcn packages/shadcn/src/utils/updaters/update-files.ts:144-260 (overwrite prompt ignores --yes)
shadcn packages/shadcn/src/registry/resolver.ts:148-400 (resolver under 400 lines)

Observed constraint:

shadcn writes content files only, prompts on existing files even with --yes, merges only .env, and installs dependencies at one directory.

Question: Does hi depend on the shadcn package or carry its own installer?

Accepted answer:

hi carries its own small installer. Registry item JSON stays byte-compatible with the shadcn schema so npx shadcn add and shadcn mcp remain fallbacks.

Code consequence:

Extensions live under item meta: symlinks, structured merges, workspace dependencies, templates with declared inputs.

Q5

Prerequisites:

none

Evidence anchor:

apps/cli/src/data/scripts/managed-lint-runner.mjs:225-230 (maxBuffer 10 MiB)
apps/cli/src/data/scripts/commit-gate-runner.mjs:32-36,59-62,163-238

Observed constraint:

Issue #232: 13.5 MB of oxlint JSON overflows the buffer; the full owner file set is inlined into one shell string and an env var, exceeding ARG_MAX.

Question: When is issue #232 fixed?

Accepted answer:

Inside the release that ships the registry implementation, not before.

Code consequence:

The lint runner and commit-gate runner are registry items in that release; the fix ships with them.

Q6

Prerequisites:

Evidence anchor:

.agents/hooks/scaffold-update-check.mjs:140-151 (keys on drift-detected, never emitted)
apps/cli/src/features/repository-check/application.ts:592-597 (forced stable refetch)

Observed constraint:

Session start runs a network-bound full check whose drift branch is dead.

Question: What does the session-start hook check?

Accepted answer:

The hook stays. It checks the Baseline version only: is a newer registry version available than the installed one. It does not run the full drift comparison.

Code consequence:

hi check fetches the catalog and compares versions; full comparison is hi diff on demand.

Q7

Prerequisites:

none

Evidence anchor:

apps/cli/src/data/catalog/lint.ts (typescript-anti-slop asset, sourceFiles copied per workspace)
.devpunks/scaffold-manifest.json (13 workspace copies of LICENSE and index.mjs)

Question: Does the anti-slop lint asset stay a default, and where do its files live?

Accepted answer:

Anti-slop rules stay the default lint asset for TypeScript Software Scopes.
Its files stay scoped to each app and package, like the per-package lint rules. Per-workspace copies remain.

Q8

Prerequisites:

Question: Where is the registry hosted?

Accepted answer:

With the existing HI API on Vercel. "Whatever is easiest." The exact mount, static files or an apps/api route, is delivery detail.

Q9

Prerequisites:

Q1, Q2

Question: Do prompt specs, AGENT-HANDOFF.md, and AGENT-SYSTEM-PROMPT.md stay tracked files or become on-demand output?

Accepted answer:

They stay tracked Managed Artifacts. They are tied to the Baseline and are built from registry templates with the Recorded Shape.

Q10

Prerequisites:

Evidence anchor:

apps/cli/src/baseline/bundled.ts:169-203 (bundled digest verification)
Issue #43 (stale bundled Baseline applied by mistake)

Question: Does a bundled offline Baseline stay inside the npm package?

Accepted answer:

No. The bundled fallback is dropped. The registry is the only source.

Code consequence:

hi init needs network access and registry credentials.

Q11

Prerequisites:

Q1, Q8

Evidence anchor:

apps/cli/src/control-plane/client.ts:53-60 (optional headers, no credential source)
apps/api/src/baseline-registry.ts:127-161 (server-side GitHub token for release inventory)

Observed constraint:

The CLI sends no credential to the control plane today. The API holds a GitHub token server-side to read release assets. No hi login exists in apps/cli/src/cli/.

Question: Does the registry require credentials?

Accepted answer:

Yes. The user's stated premise was that Baseline access is already limited to a CLI with its login. Code shows no such login; the credential mechanism is an open question (Q19).

Q12

Prerequisites:

Question: When are the per-harness subagent files rebuilt?

Accepted answer:

Only by hi update and hi diff. The edit hook does not rebuild them.

Q13

Prerequisites:

Evidence anchor:

.devpunks/scaffold-manifest.json managedDependencies (105 pins across 13 workspaces)
shadcn never removes dependencies (absence in packages/shadcn/src)

Question: What happens to a devDependency that is no longer required by any installed lint asset?

Accepted answer:

hi update removes it from the workspace package.json. The user accepted this with the stated risk that a project may use the same package directly. A guard is asked in Q26.

Round 1 (2026-09-27)

The user agreed to every R1 recommendation except Q19, Q27, Q30, and Q31.

Q14

Prerequisites:

Question: What identifies a registry version?

Accepted answer:

The existing Baseline version format YYYY.MM.DD-<short sha>, for example 2026.09.15-1ee7f8b7.

Q15

Prerequisites:

Q1, Q14

Evidence anchor:

packages/contract/src/baseline.ts:303 (promote endpoint)
Issues 49, 91, 94 (promotion and authority failures)

Observed constraint:

A separate promotion step made the CLI depend on server-side state that was stale or unavailable.

Question: Is there one latest pointer or a promotion step?

Accepted answer:

One latest pointer in the catalog that moves on publish. No promotion step.

Code consequence:

The promote endpoint and the durable promotion store are retired.

Q16

Prerequisites:

Q1, Q15

Evidence anchor:

.github/workflows/release.yml; apps/cli/scripts/publish-baseline.mjs; apps/cli/scripts/classify-release-impact.mjs

Question: What builds and publishes the registry, and which changelog selects it?

Accepted answer:

The existing release workflow builds the registry from apps/cli/skills and apps/cli/src/data and publishes it. BASELINE_CHANGELOG.md stays the product selector. The skills repository stays the source of truth through the existing sync.

Q17

Prerequisites:

Evidence anchor:

apps/cli/src/baseline/compatibility-range.mjs; session check output "Baseline requires CLI >=5.2.2 <5.3.0"

Question: Does a registry version declare a compatible CLI range?

Accepted answer:

Yes. The CLI refuses a registry version outside its range and tells the user to upgrade.

Q18

Prerequisites:

Question: Does the catalog carry a per-item content hash?

Accepted answer:

Yes, a sha256 per item, used only to verify the download cache. Never used for repository drift.

Q19

Prerequisites:

Evidence anchor:

apps/cli/src/control-plane/client.ts:53-60 (no credential source)
apps/api/src/baseline-registry.ts:127-161 (server-side GitHub token only)

Observed constraint:

No CLI login exists. A registry credential would be a new mechanism.

Question: Which credential mechanism does the registry use?

Accepted answer:

None. The registry stays public. No credential mechanism is introduced.
This supersedes Q11.

Code consequence:

No hi login, no registries headers, no token storage. hi init needs network access only.

Q20

Prerequisites:

Evidence anchor:

.agents/hooks/format-edited-file.mjs:374-393; apps/cli/src/features/project-settings/service.ts:464-530

Question: Is local state two files, one writer each?

Accepted answer:

Yes. settings.json holds intent and is edited by a human, or by the agent on request. installed.json holds the installed Baseline version, the Recorded Shape, and the item-to-path map; only the installer writes it.

Code consequence:

The edit hook and stale detection read installed.json. No hashes anywhere.

Q21

Prerequisites:

Evidence anchor:

.agents/hooks/format-edited-file.mjs:873-881,1158-1165; issue 231

Question: What does the edit hook do when the Installed Record is missing?

Accepted answer:

It treats the repository as having nothing managed and does not block edits. hi check reports "not installed".

Q22

Prerequisites:

Evidence anchor:

apps/cli/src/update/run.ts:818-827 (hasActionablePackDrift); issues 50, 62

Question: Are selected Packs explicit in settings, with detection as proposal only?

Accepted answer:

Yes. Settings lists selected Packs. Detection runs at hi init and on request and only proposes. A detected but unselected Pack is information, never drift.

Q23

Prerequisites:

Evidence anchor:

apps/cli/src/update/run.ts:6417-6456 (pending marker), 6473-6550 (apply order)

Question: What is the apply order?

Accepted answer:

Plan; validate that every merge target parses; write files; apply merges; create symlinks; install workspace dependencies; write the Installed Record last. No pending-publication marker.

Code consequence:

A re-run after any failure converges by content compare.

Q24

Prerequisites:

Question: What does a non-interactive update do on a Copied Artifact conflict?

Accepted answer:

With --yes, it overwrites the Copied Artifact and reports the path. Git keeps the local version. Authored Artifacts are never overwritten.

Q25

Prerequisites:

Question: How are text files compared?

Accepted answer:

Normalize line endings and trailing whitespace only. No formatter-aware comparison.

Q26

Prerequisites:

Question: What guard applies before removing a stale devDependency?

Accepted answer:

Remove only when no first-party source file in that workspace imports the package. Otherwise report and keep.

Q27

Prerequisites:

Evidence anchor:

Issue 58 (Windows fs.symlink EPERM); today's receipt copyFallbacks

Question: What happens when a symlink cannot be created?

Accepted answer:

No copy fallback. The installer reports the failed symlink and its intended target to the user so it can be fixed later. The Drift Check reports it as link-failed until it exists; hi update retries on every run.

Q28

Prerequisites:

Evidence anchor:

apps/cli/src/data/scripts/commit-gate-runner.mjs:163-238

Question: Does the Commit Gate keep the full-owner expansion on config change?

Accepted answer:

Yes. The rule stays; the file list is passed through stdin, not argv.

Q29

Prerequisites:

Question: Is the harness set fixed?

Accepted answer:

Yes: Claude, Codex, Cursor, OpenCode, always all four. A selectable set per repository is parked.

Q30

Prerequisites:

Question: Which commands remain?

Accepted answer:

hi init for first install, hi update, hi diff, hi check. hi scaffold is retired into init. There is no hi add; the user rejected it as a command that never existed.

Q31

Prerequisites:

Evidence anchor:

apps/cli/src/scaffold/skill-snapshot.ts:19-50 (snapshotPreExistingSkillHomes); .devpunks/pre-existing-skills (6.7 MB, 496 files in this repository)

Observed constraint:

The archive existed only to keep skills that were present before scaffold and that scaffold then removed from the harness directories.

Question: What happens to the replaced-scaffold, replaced-skills, and pre-existing-skills archives?

Accepted answer:

replaced-scaffold and replaced-skills are retired; a conflict shows as a git diff.
Scaffold does not remove pre-existing skills. It copies them into .agents/skills/<id> and they are reachable through the existing harness symlinks. They are Authored Artifacts. The pre-existing-skills archive is no longer needed.

Code consequence:

The skill snapshot step becomes a move-into-place step. Project Skills are never compared or overwritten.

Q32

Prerequisites:

Question: Which canonical terms are added and which are retired?

Accepted answer:

Added: Registry, Registry Item, Baseline (one Registry version), Installed Record, Recorded Shape, Copied Artifact, Built Artifact, Authored Artifact.
Kept: Pack, Software Scope, Harness Adapter, Drift Check (new meaning).
Retired: Scaffold Manifest, Validation Candidate, Prepared Installation, Validation Result, Cache Entry, Context Plan as a persisted file.

Glossary Q32a

Question: What is a skill that the repository had before Harness and that no Registry Item provides?

Accepted answer:

Canonical term: Project Skill — a skill under .agents/skills/<id> that no Registry Item provides; it is an Authored Artifact.
Avoid: pre-existing skill, local skill, replaced skill
Relationship: a Project Skill is an Authored Artifact.
Axiom: the installer never removes, compares, or overwrites a Project Skill.

Round 2 (2026-09-27)

Q33

Prerequisites:

Q20, Q31

Evidence anchor:

.devpunks/scaffold-manifest.json, harness-projection-receipt.json, context-plan.json, specs/lint/assets.json, replaced-scaffold/, replaced-skills/, pre-existing-skills/ (current consumer state)
apps/cli/src/features/project-settings/service.ts:464-530 (settings fields)

Observed constraint:

Every consumer repository carries manifest-era state that the new installer neither reads nor writes.

Question: How does an existing manifest-based repository migrate?

Accepted answer:

The first registry-based hi update migrates in the same run. It reads the old settings.json for Packs, Software Scopes, providers, and required tools; runs detection once to build the Recorded Shape; writes installed.json; moves skills from the pre-existing-skills archive into .agents/skills as Project Skills; deletes the manifest, receipt, context plan, specs/lint/assets.json, replaced-scaffold, replaced-skills, and the emptied archive; keeps every Authored Artifact; then continues as a normal update and reports each deletion. No separate migrate command.

Code consequence:

Migration is a branch inside hi update, keyed on the presence of the old manifest and the absence of installed.json.

Q34

Prerequisites:

Evidence anchor:

.claude/skills -> ../.agents/skills (symlink; every harness lists the same directory)

Question: What happens when a Registry Item later provides a skill with a Project Skill's id?

Accepted answer:

The Baseline skill wins. The installer renames the Project Skill to [DEPRECATED] <name> and installs the Registry Item under the original id. The command reports every such case to the user.
Consequence noted: the renamed directory stays visible in every harness's skill list under the deprecated name, through the shared symlink.

Code consequence:

The Project Skill axiom becomes: never removed or overwritten; renamed only on id collision with a Registry Item, and reported.

Q35

Prerequisites:

Q22, Q30

Question: Can settings select individual Registry Items outside Packs?

Accepted answer:

No. Packs are the only selection unit. Single-item selection is parked with the resume trigger: a real request for one skill that no Pack contains.

Registry Baseline Grill Log

On this page