Registry Baseline: Target System Brainstorm

This is the brainstorm output for the target system after the user accepted the decisions in the registry architecture research report. It uses the ten flow failure lenses. Every observation traces to evidence or an explicit unknown. Candidates stay candidates until the user accepts them. The next consumer is requirements-grill, then create-architecture.

1. Boundary

System. Registry Baseline distribution: the registry publish step, the hi installer, Project settings, the installed record, the Drift check, the session-start hook, the edit hook, Harness adapters for subagents, built Managed Artifacts, and scaffold-once artifacts.

Operators. The coding agent (session start, edits, hi commands), the human (accepts updates, resolves conflicts), and the release publisher (CI).

Accepted decisions, used as constraints.

Constraints from repository guidance. Shared skills come from the skills repo main branch. apps/cli owns the executable. apps/api owns the control plane. Changed changelog paths select the release product.

Canonical terms kept. Baseline, Managed Artifact, Pack, Project settings, Harness adapter, Drift check, Update flow, Software Scope, Lint Route, Commit Gate. Terms this design retires are listed in section 6.

Unknowns.

• U1. Where the registry is hosted: static files on the existing Vercel deployment, a route in apps/api, or another static host. D1 says "over there" without a location.
• U2. Whether consumer repositories ignore .devpunks/. Issue #231 shows one that does; this repository tracks it.
• U3. Whether the current control-plane Baseline fetch needs credentials. baseline/resolve.ts builds the URL from configuration; no token handling was found in the traced code, but the server side was not read.
• U4. Whether any workspace in a consumer repository is published on its own and therefore needs its own copy of vendored lint files.
• U5. Whether D6 means the version comparison only, or also the local file comparison, at session start. This brainstorm assumes version comparison at session start and full comparison on demand.

2. The target system from the agent's seat

Intake

• Session start runs hi check --json. The command reads the installed version from the installed record, fetches the small registry catalog, and compares. Output has a structured status field: current, update-available, unavailable. The hook keys on that field. Evidence: the current hook keys on an issue code that the CLI never emits (.agents/hooks/scaffold-update-check.mjs:140-151).
• The edit hook reads the installed record for managed paths. Evidence: it needs paths only (.agents/hooks/format-edited-file.mjs:374-393).
• The agent or human runs hi init, hi update, hi diff, hi add <item>.
• A fallback path exists: npx shadcn add @hi/<item>. It writes tier 1 files only. It applies no symlinks, merges, or workspace dependencies.

State

Two local files, one writer each, no hashes. Evidence: the Project settings axiom "one writer per field" in the CLI context architecture glossary; the two-writer defect in #105.

Control

hi update runs one pipeline: fetch catalog, resolve selected Packs to items through registryDependencies, plan every file action, validate merge targets parse, apply content files, apply merges, apply symlinks, install workspace dependencies, write the installed record, run managed lint, report. hi diff runs the same pipeline up to plan and compares instead of writing. hi check runs fetch and compare only.

Subagent projection is a tier 2 render inside the same pipeline: body from manifest.mjs, envelope from the Harness adapter at the installed version. Evidence: the body is byte-identical across four harness outputs; only the envelope differs (packages-db in .claude, .cursor, .opencode, .codex).

Feedback

One JSON result for every command with status, the applied version, and one row per path: created, overwritten, skipped, merged, linked, copied, removed, conflict, missing, stale, shape-drift. Planned and applied are separate fields. Evidence: #41 and #215 conflated them.

Recovery

Re-running hi update converges: unchanged files are skipped by content compare, so a crash between two writes leaves a state that the next run completes. A conflict is resolved by hi update --overwrite <path> or by keeping the file. A corrupt cache entry fails the catalog sha256 check and is refetched. Offline, hi check reports unavailable and the cached installed version; it never reports "no drift confirmed" for a failed fetch.

Handoff

After update, the result lists tier 3 files whose template changed between the installed and applied versions. The agent reviews those by hand. The hi-cli operator skill and the scaffolding runbook describe this flow.

3. Flow failure lenses

4. Candidates

Each candidate lists evidence, consequence, and the unresolved tradeoff. Accepted decisions D1 to D7 are not repeated.

• K1. Two local files. settings.json for intent, installed.json for the installer's record (version, recorded shape, item to path map, link-or-copy per symlink). Evidence: one-writer axiom; edit hook needs paths; D2 needs the shape. Consequence: the edit hook and stale detection read one small tracked file; #231 and #204 cannot recur. Tradeoff: U2, a consumer that ignores .devpunks/ loses the record in fresh worktrees; the installer must then treat a missing record as "not installed" and offer hi update, not block edits.
• K2. Structured status. Every command returns status from a closed set; the session hook and the operator skill key on it. A failed fetch is unavailable with the cached installed version. Evidence: the dead drift-detected branch. Consequence: the hook message is always true. Tradeoff: none found.
• K3. Plan, validate, apply in fixed order; record last; no marker. Evidence: lens 4 and 7; the current marker scheme's failure codes. Consequence: re-run converges from any crash point. Tradeoff: a transient window where hi diff reports local edits on files that were just written.
• K4. Catalog carries per-item sha256. Used for cache integrity only, never for repository drift. Evidence: today's archive sha256 check (baseline/resolve.ts:486-493) is the useful part of the current verification. Consequence: offline hi diff at the installed version stays trustworthy. Tradeoff: none found.
• K5. Subagent projection trigger. Option A: only hi update and hi diff render and compare the 88 files. Option B: the edit hook also re-renders when manifest.mjs is saved. Evidence: D3; today the agent runs the sync script by hand. Consequence: A is simpler and keeps one writer; B keeps outputs fresh during authoring. Tradeoff: B puts a render inside every edit hook call.
• K6. shadcn fallback is files-only. Document it; hi diff reconciles. Evidence: lens 1. Consequence: shadcn mcp discovery works with no extra work. Tradeoff: an operator who only uses shadcn gets no merges or symlinks.
• K7. Removal policy. Tier 1 stale files are removed on update. Tier 3 stale files are reported, never removed. Stale devDependencies: unknown policy. Evidence: lens 9; shadcn removes nothing. Consequence: repositories do not accumulate dead managed files. Tradeoff: removing a devDependency that the project also uses directly would break it; the safe default is report-only.
• K8. Prompt-spec skeletons render on demand. hi prompt-spec <scope> prints the skeleton instead of persisting 17 tracked files. Evidence: they are authority: repository, consumed once, and produced noise in #122. Consequence: 17 fewer managed paths and no drift on them. Tradeoff: the operator skill's post-command flow changes.
• K9. Handoff and system prompt render on demand. hi handoff prints them; no tracked AGENT-HANDOFF.md or AGENT-SYSTEM-PROMPT.md. Evidence: no hook or script reads them; the handoff tells the agent to run hi check first. Consequence: two fewer managed paths. Tradeoff: the files are visible in git history today; on-demand output is not.
• K10. Registry hosting. U1. Options: static files under the existing Vercel deployment; a static route in apps/api; another host. Evidence: the baseline HTTP API group (resolve, artifact, promote) in packages/contract/src/baseline.ts:289-303 becomes obsolete under D1. Consequence: the control plane loses one API group or gains a static mount. Tradeoff: an apps/api route keeps auth and telemetry in one place; a static host is simpler and cacheable by any CDN.
• K11. Bundled fallback. Keep a bundled copy of the latest registry inside the npm package for offline hi init, or drop it. Evidence: today's bundled channel and its verified digest (baseline/bundled.ts:169-203); #43 shows a stale bundled copy applied by mistake. Consequence: dropping it removes one channel and one class of bug; keeping it allows offline first install. Tradeoff: offline first install versus one fewer source of truth.
• K12. Private registry auth. U3. If the registry needs credentials, the registries map carries headers with ${ENV} expansion as shadcn does. Evidence: shadcn authentication docs. Consequence: no new mechanism. Tradeoff: unknown until U3 is resolved.
• K13. Symlink fallback. When a symlink fails (Windows, #58), the installer copies and records copied in the installed record; hi diff then compares the copy by content. Evidence: today's receipt copyFallbacks. Consequence: Windows works without a separate code path in the hooks. Tradeoff: a copied hook drifts from its source until the next update.
• K14. Issue #232 mechanism (D5). The lint runner streams oxlint JSON to a temp file and reads it, removing maxBuffer. The commit-gate runner passes file sets through stdin or a response file, drops HI_STAGED_FILES, and sets an explicit buffer on git diff --cached. Evidence: managed-lint-runner.mjs:229, commit-gate-runner.mjs:35,59-62,186-238. Consequence: large Software Scopes lint and commit. Tradeoff: whether the "expand the whole owner set on config change" rule survives when a config change is an ordinary diff.
• K15. Anti-slop placement (D7). One root copy under tools/oxlint/anti-slop/ referenced by each workspace config with a relative path, instead of 26 vendored files. Evidence: the manifest lists 13 copies of LICENSE and index.mjs. Consequence: 24 fewer managed paths. Tradeoff: U4, a workspace published on its own would need its own copy.

5. Decisions recorded on 2026-09-27, second round

Consequences for the design above:

• With K11 dropped, hi init needs network access and a CLI login. Offline first install is out of scope.
• With K8 and K9 rejected, the tier 2 set keeps prompt specs, handoff, and system prompt. Their drift is handled by re-render at the installed version with the recorded shape, the same as lint configs.
• With K12 accepted, the shadcn fallback (npx shadcn add @hi/<item>) works only when the same credential is exposed through the registries map headers. That is optional, not required.

5a. Unresolved decisions

None. Every candidate has a recorded disposition. The stated risk under K7 (removing a devDependency the project also uses directly) is not a decision gap; it is a guard for requirements-grill to specify, for example, removing only when no first-party source imports the package.

6. Required design-document changes

These are proposals; none is applied.

• Retire in the manifest-driven update glossary: Scaffold Manifest, Validation Candidate, Prepared Installation, Validation Result, Cache Entry. Add: Registry, Registry Item, Installed Record, Recorded Shape, Tier. Route through requirements-grill.
• Update the CLI update enforcement glossary: "CLI version pin" and "Baseline version pin" become the installed version in the installed record.
• Rewrite docs/runbooks/hi-cli-scaffolding.md, docs/README.md, and the hi-cli operator skill post-command flow for the new commands and the structured status.
• Refresh .agents/rules/repository/baseline-release-entrypoint.md (HI-REPO-002) for the registry publish entrypoint.
• Record the release classification rule for the registry product under D1.

7. Validation of this brainstorm

• Every finding above cites a file and line from the research report, an issue number, a shadcn source path, or a user decision dated 2026-09-27.
• Lenses 5 and 9 carry explicit unknowns; both are judged non-material to the accepted scope and are listed in section 5.
• No new mechanism or guarantee is accepted here; all are candidates.