Architecture: Registry Baseline

Context and Scope

• Capability identity: apps/wiki/content/docs/project/specs/cli/registry-baseline. The capability is registry-based Baseline distribution for the hi CLI: publish, install, update, diff, check, and migration from the manifest-driven flow, including the issue #232 fix in the same release.
• Actors and outcome: the coding agent and the human operator need the harness content in a repository to be current, to know when it is not, and to update it without manual repair. The release publisher needs one publish step. Today 47 issues trace to persisted derived state, a temporary update candidate, and generator overwrites (S4, research report, "Facts").
• In scope: Q1 to Q35 and Glossary Q32a in the grill log (S2). Non-goals: hi report, the backoffice, implementation order, task breakdown, backlog projection (S1, "Scope and authority").
• Spec: sibling path apps/wiki/content/docs/project/specs/cli/registry-baseline/SPEC.md, retained in the commit that follows this architecture's retention.

Canonical Terms

Exact terms from the Registry Baseline Glossary (S3). Registry, Registry Item, Baseline, Installed Record, Recorded Shape, Copied Artifact, Built Artifact, Authored Artifact, Project Skill, Harness Adapter, Drift Check. Kept from earlier glossaries: Pack, Software Scope, Commit Gate, Project settings, Managed Artifact.

Axioms used below: no content hash of a Managed Artifact is stored in the repository; each local state file has one writer; a Baseline is immutable; the Registry is the only and public Baseline source; a Project Skill is never removed or overwritten, only renamed on id collision; a Pack is the only selection unit.

Sources

Git blob ids are abbreviated to 12 characters and were computed with git hash-object on 2026-09-27. Full ids resolve in this repository.

Source Disposition

Whole System

Context. Today the CLI is the authority for both "what should exist" and "what does exist", and it proves the second with 654 recorded hashes (S4). In the accepted design the Registry owns "what should exist" at every version, the repository owns intent and authored files, and the installer derives everything else on demand. Nothing derived is persisted except the Installed Record.

Anchors: Q1, Q8, Q10, Q19 (Registry, hosting, public); Q20 (two files); Q2, Q9 (Built Artifacts and Recorded Shape); Q31, Q34 (Project Skills); Q6, Q21 (hooks); Q18 (cache). Conclusion: one public source, two local files with one writer each, three artifact kinds with three rules. The installer is the only writer of anything derived. Accepted design; not yet implemented.

Critical Flows and Boundaries

FLOW-001 Publish a Baseline

Context. Today a tarball is built, uploaded as a GitHub release artifact, then promoted through the control plane (S6 apps/cli/scripts/publish-baseline.mjs, packages/contract/src/baseline.ts:303). Accepted: one build, one upload, one pointer move.

FLOW-001-STEP-001  sync skills repo main into apps/cli/skills            (existing, Q16)
FLOW-001-STEP-002  release workflow classifies product by changed changelog paths;
                   BASELINE_CHANGELOG.md selects the Registry             (Q16)
FLOW-001-STEP-003  build registry.json and /<YYYY.MM.DD-sha>/<item>.json  (Q14)
                   each item: files with ~/ targets, meta.symlinks, meta.merge,
                   meta.workspaceDependencies, templates with inputs; per-item
                   sha256 and CLI compatibility range in the catalog     (Q4, Q17, Q18)
FLOW-001-STEP-004  upload to the Vercel deployment with the HI API; move `latest`
                   to the new version                                     (Q8, Q15)

Anchors: Q8, Q14 to Q18. Conclusion: a version is immutable once uploaded; the only mutable state is the latest pointer. No promotion step exists, so the authority failures of issues 49, 91, and 94 have no place to occur (S4).

FLOW-002 Update, including init

Context. Today hi update stages a full temporary copy of the repository, installs dependencies, runs a lint preview, then applies with a pending publication marker (S6 apps/cli/src/update/run.ts:6023-6456). Six of the 47 issues come from that candidate (S4). Accepted: plan, validate, apply in a fixed order, record last, no marker.

Anchors: Q22 (STEP-002), Q23 (order, STEP-004, STEP-012), Q24 (STEP-005), Q2 and Q9 (STEP-006), Q31 and Q34 (STEP-007), Q27 (STEP-009), Q13 and Q26 (STEP-010), Q17 (STEP-001), Q5 (STEP-013). Conclusion: every step before STEP-012 is idempotent by content compare, so a crash at any point is repaired by running again. The Installed Record is the only proof of completion and it is written after every other effect (S5 lens 4, lens 7).

hi init is FLOW-002 with two extra steps before STEP-001: detect the repository once to propose Packs and Software Scopes, and write Project settings from the confirmed selection (Q22, Q30). init needs network access and no credential (Q10, Q19).

Non-interactive rule: with --yes, STEP-005 overwrites a Copied Artifact that has both a local edit and an upstream change, and reports the path; git keeps the local version (Q24). Authored Artifacts are never overwritten (Q9, Q31).

FLOW-003 Diff and check

Context. Today hi check is the update pipeline in check mode, forces a stable refetch, and hashes 654 files on every session start (S6 apps/cli/src/features/repository-check/application.ts:592-597). Accepted: version compare for check, three-way compare for diff.

FLOW-003-STEP-001  fetch registry.json                                          (Q6)
FLOW-003-STEP-002  compare installed version with latest
                   hi check stops here: status current | update-available | unavailable
                   offline: status unavailable plus the cached installed version (Q6, S5 K2)
FLOW-003-STEP-003  hi diff: fetch installed and latest items, cache by sha256   (Q18)
FLOW-003-STEP-004  per managed path, classify:
                   Copied   local vs installed vs latest bytes, normalized line
                            endings and trailing whitespace                    (Q25)
                   Built    re-render at installed version with Recorded Shape;
                            re-render with current shape -> shape-drift        (Q2)
                   Authored never byte-compared; report template changed since
                            authoring                                          (Q9)
                   link     missing symlink -> link-failed                     (Q27)
                   classes: update-available, local-edit, conflict, shape-drift,
                            missing, stale, link-failed                        (S3)
FLOW-003-STEP-005  report one row per path; hi diff writes nothing

Anchors: Q2, Q6, Q18, Q25, Q27. Conclusion: because both the installed and the latest bytes come from the Registry, no hash is needed in the repository, and the four drift-fix waves in the issue history (S4) have no recurrence path.

FLOW-004 Agent session and edits

session start   hook runs hi check --json -> reads status field only
                current: one line; update-available: suggest hi update;
                unavailable: say so with the cached installed version         (Q6, S5 K2)
file edit       hook reads managed paths from the Installed Record;
                protected paths are not formatted;
                record missing -> nothing is managed, never block             (Q21)
manifest edit   .agents/subagents/manifest.mjs changed -> no hook action;
                hi diff reports harness agents stale; hi update re-renders    (Q12)

Anchors: Q6, Q12, Q21. Conclusion: the session hook never claims "no drift" after a failed fetch, and a fresh worktree never blocks edits (issue 231).

FLOW-005 Migration of a manifest-based repository

trigger  hi update finds .devpunks/scaffold-manifest.json and no installed.json  (Q33)
STEP-001 read old settings.json: Packs, Software Scopes, providers, required tools
STEP-002 detect once -> Recorded Shape
STEP-003 move skills from .devpunks/pre-existing-skills into .agents/skills as
         Project Skills; apply Q34 on id collision
STEP-004 delete scaffold-manifest.json, harness-projection-receipt.json,
         context-plan.json, specs/lint/assets.json, replaced-scaffold,
         replaced-skills, emptied pre-existing-skills
STEP-005 keep every Authored Artifact in place
STEP-006 continue as FLOW-002 from STEP-001; report each deletion

Anchors: Q31, Q33, Q34. Conclusion: migration is one branch of update, not a command, and it converges on re-run like the rest of FLOW-002.

Accepted Detail Coverage

Spec Traceability

• State: complete. Spec codes OUT-001 to OUT-015 and AC-001 to AC-037 from the sibling SPEC.md (section "Requirements Outcomes" and "Acceptance Criteria") map below. Completed by create-spec on 2026-09-28 without changing accepted design.

Retired or Superseded Selectors

Flow Failure Coverage

Parked Work and Non-material Unknowns

Validation

• Decision/source/glossary reconciliation: S1 shows confirmation confirmed, frontier empty, all branches 100%; S2 contains Q1 to Q35 and Q32a; Q11 is superseded by Q19; S3 matches the S1 glossary snapshot. Result: consistent.
• Exact-detail and cross-level coverage: every Q has a row in "Accepted Detail Coverage" with a selector; every selector appears in a table, flow, or diagram label. Result: complete.
• Relative links, selector targets, and visual source/order checks: all links are routed wiki paths that exist in the working tree; diagram order follows the accepted step order in Q23 and Q33. Result: pass.
• Spec-code -> architecture -> grill coverage: complete. OUT-001 to OUT-015 and AC-001 to AC-037 each map to at least one ARC or FLOW selector and to accepted Q entries; no code lacks a structural counterpart.
• Mermaid parsing/rendering: both diagrams parsed as flowchart-v2 with mermaid 11.15.0 (the wiki's pinned version) under Bun, using happy-dom as the DOM shim in an isolated temporary environment outside the repository, because the repository installs no DOM shim and mermaid.parse needs one for label sanitization. Rendering to an image was not run; the wiki renders Mermaid at build time. Labels use plain text without HTML line breaks.
• Existing spec agreement: absent; architecture precedes spec.
• Remaining limits: git blob ids are abbreviated to 12 characters; the sources are uncommitted at compile time and are retained in the same dedicated commit as this artifact.