Registry Baseline execution plan

Authority

Spec: SPEC.md at a89796e732cd1d787183af7dd6234b09d56b1663 (remote retention verified on origin/team/stefan/registry-baseline-architecture). Architecture: ARCHITECTURE.md at 3e63ec3c.
Full Delivery requested by the user on 2026-09-28 ("finish it and get that from 0 to 100 working").
task_identity_mode: planning-only. Sync-skip reason: the user declined Linear projection on 2026-09-28 ("Skip Linear"). Tn ids are the execution identities; depends_on names plan ids.
Workers share one working tree and own disjoint write scopes. A worker never edits outside its scope; it reports needed cross-scope changes to the parent.

Delivery decisions (planning detail the spec left open)

Id	Decision
D1	Registry mount: Vercel Blob store `harness-intelligence-registry` (public, fra1, linked to Vercel project `harness-intelligence-api`) behind an `apps/api/vercel.json` rewrite `/r/:path` -> `https://kxggix42sjnpqmtt.public.blob.vercel-storage.com/r/:path`. Registry base URL: `https://api.harness-intelligence.devpunks.com/r`. No API code serves it.
D2	Layout: `registry.json` (latest catalog + `latest`, cache max-age 60 s, overwritten on publish), `<version>/registry.json` and `<version>/<item>.json` (immutable, `allowOverwrite: false`, long cache). Catalog entries carry `meta.sha256` of the exact item bytes.
D3	Wire format and `meta.hi` field names: `apps/cli/src/registry/model.ts` (the contract). Items are `registry:item` with `registry:file` files targeting `~/...`.
D4	Built templates: `apps/cli/src/registry/template.ts` (logic-less `{{a.b}}`, `{{json a}}`, `{{#a}}`, `{{^a}}`). Builders add computed values under `build`. Template context excludes the Baseline version and time (AC-015).
D5	Harness Adapter envelopes keep today's formats (Claude/Cursor/OpenCode Markdown + YAML front matter, Codex TOML with `developer_instructions` and `[[skills.config]]`), with correct TOML string escaping and a new marker naming `hi update`.
D6	Migration copies the old manifest `finalPacks` into `settings.json` `packs` and drops CLI-managed `baselineVersion`/`cliVersion`: the one settings write outside `hi init`, performed once as the transition into the intent format (spec tension with AC-012 recorded in IMPLEMENTATION-NOTES). `scaffold-manifest.json` is deleted last, just before the Installed Record, so an interrupted migration re-enters.
D7	#232: the lint runner streams oxlint stdout to a temp file (no `maxBuffer`) and batches file arguments below the OS limit; the Commit Gate passes file lists through a temp file (`HI_STAGED_FILES_PATH`) or stdin, never argv/env strings; staged listing uses an explicit 256 MiB buffer. Full-owner expansion on config change is unchanged.
D8	`settings.json` gains `packs` and optional `registry`; the CLI stops writing `baselineVersion`/`cliVersion`.
D9	CLI major bump to `6.0.0` (commands removed). Baseline CLI range `>=6.0.0 <7.0.0`. Both changelogs get reviewed notes (mixed release).
D10	`hi update` STEP-013 runs `node .agents/scripts/managed-lint-runner.mjs` when Software Scopes exist and reports `lint: passed
D11	`pack-core` is always installed (shared prompt, prompts, handoff, subagents, harness, hooks, managed-lint, commit-gate, wiki, tools). Other Packs come only from settings `packs`.
D12	`.devpunks/specs/lint/selection.json`, `.devpunks/specs/lint/README.md`, `.devpunks/commit-gate-contracts.json` become Built Artifacts (no hashes). The Commit Gate lifecycle receipt is retired.
D13	Non-lifecycle commands kept: `upgrade`, `report`, `operator`, `skills` (alias), `commit-gate verify` (receipt-free), `tools ensure` (tool list from the installed Baseline). `ensure` and `scaffold` are retired; re-running `hi init` reconfigures settings.
D14	Everything the Registry distributes stays out of the npm package; `dist/` ships only the executable and non-Registry runtime data.
D15	No wiki starter is distributed (user decision 2026-09-28, follows CLI 5.2.2); amends OUT-004/OUT-006.
D16	Each Software Scope gets an Authored `oxlint.local.ts` (written once, seeded from an existing `oxlint.config.ts` on adoption) that the Built `oxlint.config.ts` extends last, so project lint tuning survives updates (user decision 2026-09-28).

Module map (apps/cli/src/registry)

File	Owner	Purpose
`model.ts`, `template.ts`, `errors.ts`, `build/source.ts`, `build/sources/index.ts`, `builders/index.ts`	parent	Shared contract. Change only through the parent.
`client.ts`, `version-range.ts`, `resolve.ts`, `shape.ts`, `settings.ts`, `materialize.ts`, `merge.ts`, `dependencies.ts`, `project-skills.ts`, `installed-record.ts`, `pipeline.ts`, `testing/**`	T2	Installer core (FLOW-002).
`build/build.ts`, `build/sources/{skills,packs,tools,source-guides,shared-prompt}.ts`, `builders/source-guides.ts`, `apps/cli/scripts/build-registry.mjs`	T3a	Publisher build and content items.
`build/sources/{prompts,wiki}.ts`, `builders/prompts.ts`, `apps/cli/src/data/registry/{prompts,handoff,wiki}/**`	T3b	Prompt specs, handoff, system prompt, wiki starter.
`harness-adapters.ts`, `build/sources/{subagents,harness}.ts`	T4	Harness Adapters and harness links.
`drift.ts`, `check.ts`	T5	Drift Check and `hi check`.
`build/sources/{lint,managed-lint,commit-gate}.ts`, `builders/{lint,commit-gate}.ts`, `apps/cli/src/data/scripts/`, `apps/cli/src/data/lint/`	T6	Managed lint, Commit Gate, #232.
`build/sources/hooks.ts`, `apps/cli/src/data/hooks/**`	T7	Session-start and edit hooks.
`migrate.ts`	T10	FLOW-005.

Each task: tests next to the code (*.test.ts, @effect/vitest or vitest), oxlint + oxfmt --check on owned files, bun run --cwd apps/cli check-types filtered to owned paths (other workers' in-flight files may fail; do not fix them). Evaluate activated rules from .agents/rules/index.md for owned paths.

Wave 1 (parallel)

T2 Installer core. OUT-005..OUT-007, OUT-012 (collision), AC-006, AC-007, AC-011, AC-012, AC-014..AC-021, AC-031..AC-033. pipeline.ts exports runInstall({ root, mode: "init" | "update", yes, cliVersion, client, intent? }) returning an UpdateReport (status, previous, applied, rows: PathRow<UpdateAction>[], lint, migration, failedLinks, refusal?). Order: STEP-001 catalog + range (refuse: write nothing) -> migration (migrateIfNeeded) -> STEP-002 resolve -> STEP-003 plan via materialize -> STEP-004 validate merge targets (any invalid: write nothing) -> STEP-005..011 -> finalizeMigration -> STEP-012 Installed Record -> STEP-013 lint -> STEP-014 report. Project Skills: any .agents/skills/<id> directory not recorded as Baseline-owned (Installed Record paths or migration previouslyManagedPaths) is a Project Skill; a real directory at .claude|.codex|.cursor|.opencode/skills/<id> is moved into .agents/skills/<id> when absent before harness links are created; on collision with a Registry skill id rename it to .agents/skills/[DEPRECATED] <id> and report. Deterministic JSON everywhere (sorted keys, 2-space, trailing newline). depends_on: none.
T3a Registry build + content items. OUT-002..OUT-004, AC-004 (builder refuses existing version dir), AC-008, AC-009. build/build.ts exports buildRegistry({ version, cliVersionRange, outDir }) writing registry.json, <v>/registry.json, <v>/<item>.json with canonical bytes and catalog sha256; validates every item against the shadcn registry-item JSON schema shape and RegistryItem; fails on duplicate names, dangling registryDependencies, or duplicate targets. Sources: skills (all catalogued skills; binary files base64; symlinks via meta.hi.symlinks; executable bits), packs (26 Packs + pack-core, deps by naming convention, pack detection data), tools, source guides (+ opensrc/README.md Built), shared prompt (.agents/AGENTS.md Copied). scripts/build-registry.mjs CLI: --version, --cli-range, --out (default dist/registry), version from YYYY.MM.DD-<git short sha> when omitted, range from BASELINE_CHANGELOG.md Unreleased Compatibility: line. depends_on: none.
T3b Prompts, handoff, wiki items. OUT-004, AC-010. Items prompts (prompt specs under .devpunks/specs/prompts/**, one per workspace + root/shared/docs, Built; root AGENTS.md starter Authored + CLAUDE.md symlink), handoff (.devpunks/AGENT-HANDOFF.md, .devpunks/AGENT-SYSTEM-PROMPT.md, Built, canonical terms, next steps for the agent), wiki (starter files Authored at the Recorded Shape wikiRoot). depends_on: none.
T4 Harness Adapters. OUT-010, AC-028, AC-029. buildHarnessAgentFiles, loadSubagentManifest, harnessAdapters (four). Items subagents (.agents/subagents/manifest.mjs Authored default, meta.hi.harnessAdapters: true) and harness (symlinks .claude/skills -> ../.agents/skills, .claude/CLAUDE.md, .codex/AGENTS.md, .opencode/AGENTS.md -> ../.agents/AGENTS.md). depends_on: none.
T5 Drift Check + check. OUT-008, OUT-009, AC-022..AC-027, AC-013. drift.ts exports runDiff({ root, client }) (reads Installed Record + settings; fetches installed + latest items; materializes at installed with Recorded Shape and with current shape; classes per path; writes nothing; offline works from cache at installed version). check.ts exports runCheck({ root, client, cliVersion }) -> { status, installed?, latest?, cliVersionRange?, cliCompatible?, missingTools, detail? }; fetches only the root catalog; reads only installed.json and settings. depends_on: none (codes against T2 stubs; integration verified in T11).
T6 Managed lint, Commit Gate, #232. OUT-004 (lint), OUT-014, AC-035, AC-036, AC-019 (deps declared per asset). Items lint-<asset> (anti-slop Copied per Software Scope, per-asset devDependencies), managed-lint (runner scripts Copied, selection.json/README.md Built, per-scope package.json scripts.lint merge, per-scope oxlint.config.ts Built), commit-gate (runner Copied, contracts Built, lefthook.yml YAML merge, root lefthook devDependency). Runner/gate fixes per D7 with regression tests (13.5 MB oxlint JSON; file list beyond ARG_MAX; large staged set). depends_on: none.
T7 Hooks. OUT-009, AC-026, AC-027. scaffold-update-check.mjs keys only on hi check --json status (never claims no drift; offline message names the cached installed version); runs when installed.json exists, else prints not-installed guidance. format-edited-file.mjs reads protected paths from installed.json (Copied + Built paths); missing record: nothing managed, never block. Item hooks: both hooks Copied; registration for all four harnesses (.claude/settings.json + .cursor/hooks.json JSON merges, .codex/config.toml Authored, .opencode/plugins/* symlinks incl. the session hook). depends_on: none.
T8 API/contract/db retirement. OUT-001, AC-001, AC-002. Remove the baseline HttpApi group, promotion store, release inventory, downloads, ledger cutover, their tests/snapshots; contract baseline.ts + export; DB drop migration for baseline_release/stable_baseline_promotion; apps/api/vercel.json rewrite per D1. Keep telemetry BaselineChannel values readable. depends_on: none.
T9 Release publication. OUT-001..OUT-003, AC-003..AC-005, AC-008. apps/cli/scripts/publish-registry.mjs (@vercel/blob put with allowOverwrite: false for versioned files, then overwrite registry.json; readback byte-compare through the public Registry URL). Replace the baseline product adapters in release-publication.mjs, classifier authority, recovery schema, build-dist.mjs (no bundled Baseline, no Registry data in dist), assert-package-surface.mjs, assert-dist-commands.mjs, release.yml secrets (BLOB_READ_WRITE_TOKEN), turbo tasks, root/CLI scripts; delete build-baseline, publish-baseline, promote-baseline-authority, rollback-baseline. depends_on: none (calls T3a's build-registry.mjs by its CLI contract).
T10 Migration. OUT-013, AC-034. migrateIfNeeded/finalizeMigration per stub docs and D6. Deletes harness-projection-receipt.json, context-plan.json, specs/lint/assets.json, replaced-scaffold/, replaced-skills/, emptied pre-existing-skills/ (skip .hi-*.backup), plus retired distributed files (.agents/scripts/sync-subagents.mjs, .agents/scripts/harness-projection/, .devpunks/commit-gate-lifecycle-receipt.json, .devpunks/required-tools.json, .devpunks/specs/subagents/manifest-spec.json, .devpunks-cache/). depends_on: none.

Wave 2

T11 Command wiring + retirement. OUT-011, AC-030, AC-001, AC-003. hi init (detect once, propose Packs and Software Scopes, confirm or --yes, write settings, run pipeline), hi update [--yes] [--json], hi diff [--json], hi check [--json]; presenters in canonical terms; delete retired modules (update/, scaffold/ pipeline, baseline/, features/{scaffold-update,scaffold-state,context-planning,repository-check,repository-scaffolding,baseline-resolution}, runtime/validation-candidate, update caches, ensure), packages/scaffold retired schemas, and their tests. End-to-end tests against a locally built Registry (file://) in temp repositories covering AC-010..AC-034. depends_on: T2, T3a, T3b, T4, T5, T6, T7, T10.
T12 Docs, rules, skills, changelogs. OUT-015, AC-037. docs/README.md, scaffolding runbook (both copies), CI publication runbook, rules HI-REPO-002/HI-CLI-002/HI-CLI-004 + index, apps/cli/AGENTS.md, root guidance lines, hi-cli operator skill in the skills repo main then bun run sync:skills, CHANGELOG.md 6.0.0 + BASELINE_CHANGELOG.md Unreleased, version bump. depends_on: T11 (behavior), T9.

Wave 3 (parent)

T13 Live proof. Build Registry, publish to the Blob store, deploy the API rewrite, run hi init/update/diff/check against the live Registry in a temp repository and migrate this repository; record evidence in VALIDATION.md. depends_on: T11, T8, T9, T12.

Validation gates

Per task: owned tests, lint, format, type check (owned paths).
T11: bun run --cwd apps/cli check-types, lint, format, test:source; bun run build for the CLI.
T13: live evidence per AC; bun run release:classify -- --base main --head HEAD.

Registry Baseline: execution plan