CLI Context Architecture Grill Log

Source: user request to investigate and redesign the semantic architecture behind Harness Intelligence context engineering, move the Effect implementation toward v4 deep modules, and revisit the CLI presentation model using the Devpunks Secrets CLI as design evidence.

This log preserves early evidence and candidates as provisional history. Q1-Q58 are the current authority, and later accepted answers supersede earlier provisional wording where they conflict.

Initial Situation

Harness Intelligence grew its context-engineering primitives incrementally. Skill packs now influence scoped prompts, subagent templates, additional tools, hooks, lint overlays, harness-specific files, manifests, and later update behavior. The resulting implementation works, but the same domain decisions are recomputed across command orchestration, scaffold writing, update reconciliation, and generated compatibility scripts.

The main concern is semantic scattering rather than a proven TypeScript import cycle. Large orchestration modules currently combine policy, planning, filesystem effects, harness projection, package mutation, prompts, terminal presentation, and telemetry. That makes the true dependency direction difficult to see and creates opportunities for setup, check, and update behavior to drift.

Current Evidence

apps/cli/src/scaffold/run.ts combines repository detection, pack resolution, interactive selection, tool installation, scaffold writes, handoff output, and telemetry.
apps/cli/src/scaffold/output.ts materializes skills, prompts, subagents, hooks, tools, lint configuration, harness mirrors, manifests, and hashes.
apps/cli/src/update/run.ts independently resolves packs, renders expected output, computes drift, reconciles files and settings, prompts, and emits telemetry.
apps/cli/src/content/prompts.ts and apps/cli/src/content/subagents.ts derive prompt and subagent behavior from pack and repository facts outside a single explicit context model.
apps/cli/src/ui/brand.ts, apps/cli/src/core/format-summary.ts, and prompt widgets split ownership of visible CLI semantics and interaction behavior.
The CLI still uses Effect v3 and @effect/cli; the requested target was checked against Effect-TS/effect-smol at 4.0.0-beta.93.
Existing project decisions keep the CLI as local scanner, executor, cache, and filesystem writer; the API remains the authority/control plane; versioned baselines remain the practical distribution artifact.

Effect v4 Source Research — 2026-07-13

This is source evidence, not an accepted Harness Intelligence design. The verified opensrc checkouts are:

effect-smol beta.93: /Users/stefan/.opensrc/repos/github.com/Effect-TS/effect-smol/main
OpenCode beta.83: /Users/stefan/.opensrc/repos/github.com/sst/opencode/dev
T3 Code beta.78: /Users/stefan/.opensrc/repos/github.com/pingdotgg/t3code/main

Proven Patterns

Services use Context.Service, with explicit open and live Layers.
Layer.provide hides provided dependencies from the resulting Layer, while Layer.provideMerge keeps them exposed.
Applications use one shared runtime and composition root. Commands parse input, call an application operation, and render its result; they do not construct runtimes.
Deep feature modules own their contracts and Schema.TaggedErrorClass errors.
Configuration is represented by explicit services with replaceable test overrides.
T3 Code uses a neutral provider adapter with explicit capabilities.
Effect tests use @effect/vitest it.layer and focused Layer.mock substitutions.
The exact Effect v4 beta must be pinned because the three verified source snapshots use different betas.

Meaningful Design Comparison

OpenCode co-locates a feature contract and implementation in a deep feature module and composes an explicit dependency graph.
T3 Code sometimes splits Services from Layers and demonstrates more repetitive wiring at the composition root.
Neither style is accepted for Harness Intelligence yet.

Configuration Readonly Research — 2026-07-13

This is current evidence and source guidance, not an accepted ownership design:

Harness Intelligence has no single reusable typed Effect configuration Layer. packages/env exposes T3/Zod singleton environment objects with narrow consumption; packages/db has a database-only Effect config service, but createDb can bypass it through ambient process.env.
CLI, API, and backoffice code contain many direct process.env reads and module-load configuration decisions. packages/contract and packages/scaffold are configuration-free and should remain so.
effect-smol beta.93 provides Config.schema, ConfigProvider, and Context.Service, with typed ConfigError and strict failure for present-but-invalid values.
OpenCode provides a reusable small config-service factory with live and parsed-value test Layers. T3 Code resolves CLI flag, then environment value, then default or bootstrap once at the root and provides typed configuration.
Do not copy OpenCode's Layer.orDie or silent invalid-config behavior, and do not copy T3 Code's config-resolution side effects. Keep ConfigError typed to the application root.

CLI Terminal UI Readonly Research — 2026-07-13

This is evidence and candidate vocabulary, not an accepted renderer design:

The reusable Secrets architecture is one production semantic renderer shared by commands and the developer preview, not its exact palette or skin. Harness Intelligence should preserve its own gradient, title, and theme identity.
Current HI brand rendering guesses semantics from finished strings and prefix glyphs. Format-summary and selectors duplicate rails, bullets, glyphs, ANSI, and wrapping, while NO_COLOR and theme selection do not govern every component.
Prompts use safe Effect.ensuring cleanup, but rendering and input ownership remain split.
JSON behavior is inconsistent: some commands can emit decorative text or the full human UI before JSON. The title also repeats inside scaffold flows instead of remaining a deliberate root-level element.

Candidate primitives:

semantic states: success, warning, error, info, empty, create, update, delete, active, and muted
section, rail, key-value, table, step, state, and prompt-frame presentation primitives
a separate prompt interaction service for keyboard input and raw-terminal cleanup
a developer-only catalog that exercises the production renderer
no generic widget framework beyond actual current needs

`packages/contract` Readonly Research — 2026-07-13

This is current ownership evidence, not an accepted redesign:

packages/contract owns cross-process schemas, public errors, and endpoint definitions for baseline and artifacts, telemetry, harness reports, and backoffice access and usage.
API handlers and business behavior remain in apps/api; CLI scaffold, fallback, and report policy remain in apps/cli; backoffice UI and session behavior remain in apps/backoffice.
The package contains no persistence or scaffold execution.
One boundary leaks: packages/contract/src/client.ts makeHarnessClient directly provides FetchHttpClient.layer, so the contract package chooses the concrete request runtime.
The root barrel currently exposes every protocol area together. Domain submodules are a candidate, not an accepted design.

Operator Skill Scope Readonly Research — 2026-07-13

This is current behavior evidence, not an accepted lifecycle design:

Detection lists project and global installations separately, but treats a list failure as absence.
Presence is name-only and discards path, source, revision, version, hash, and agent bindings. No effective copy or precedence is resolved.
Install adds a global copy only when neither scope exists, so a project copy suppresses the global default.
Update changes detected project and global copies sequentially, with no post-mutation verification.
Migrate can remove the legacy copy after an update failure.
Partial success has no reload guidance.

Observed Semantic Flow

repo evidence
  -> pack selection
  -> context plan
  -> scaffold desired state
  -> harness materialization
  -> managed manifest
  -> update reconciliation

The flow is directional: downstream stages should consume explicit upstream meaning instead of rediscovering it. The investigation has not yet decided whether each stage deserves its own module, whether some stages collapse into one aggregate, or which data crosses module boundaries.

Upstream Main Enrichment — 2026-07-13

The branch was rebased onto the settings-reconfiguration, runtime-product-validation, and operator-skill command releases. Those changes preserve the original pack-to-managed-state flow and expose additional parallel semantic axes.

project settings
  -> provider and backlog-destination authority
  -> repository-manager tool requirements
  -> CLI and baseline version pins
  -> check/update behavior and scaffolded skill runtime

operator skill source
  -> external Skills CLI
  -> global/project installation state
  -> hi-cli runtime instructions
  -> command and post-command behavior

Project Settings Are a Separate Authority Aggregate

apps/cli/src/scaffold/settings-selection.ts now shares provider and backlog-URL selection between hi init and hi ensure.
apps/cli/src/cli/ensure-command.ts reads, selects, reconciles, and rewrites settings without running hi init.
apps/cli/src/core/tools.ts still co-owns settings types, normalization, persistence, repository-manager tool derivation, command execution, and tool bootstrap.
writeRepoSettings(..., { stampVersions: false }) distinguishes operator reconfiguration from scaffold/update version stamping through a behavioral flag.
One settings document therefore contains at least three ownership classes: operator-selected provider/destination authority, derived required-tool state, and system-managed CLI/baseline pins.

This state should not be absorbed into the pack graph or treated as ordinary managed scaffold output. Context/scaffold operations may consume a project-settings boundary, while the settings module owns schema evolution, authority, derivation, and persistence policy.

Skill Contributions Carry Workflow Contracts

The runtime-product-validation release changed create-plan, implement-spec, their references, implementation-note evidence, generated skill copies, content alignment tests, baseline changelog, release artifact, and the repository baseline pin.

That propagation demonstrates that a pack-selected skill is not merely a file contribution. It can participate in a versioned cross-skill protocol: planning emits runtime_validation, runtime_target, runtime_evidence, and runtime_cleanup; execution consumes them and refuses completion without correlated runtime proof.

The pack/context model must preserve skill identity, version/provenance, reference closure, and compatibility across collaborating skills. It should not duplicate the internal workflow policy of each skill. Current substring-based content tests are useful distribution locks, but a deep boundary should validate the authored skill graph and its required reference closure before materialization.

Operator Skill Has an Independent Acquisition Lifecycle

hi operator status|install|update|migrate manages hi-cli separately from project scaffold output; the documented post-command branch explicitly avoids .devpunks artifacts, setup, update reconciliation, prompt generation, and project inspection.
The lifecycle distinguishes global and project installations, updates every detected hi-cli copy, and removes legacy dp-cli copies only during migration.
hi operator update uses a targeted skills add against the shared skill source because the current Skills CLI update operation is update-all. Source selection, installation scope, and legacy removal are therefore external-adapter concerns.
hi upgrade remains executable-only. The CLI package, the operator skill, and the project baseline can change independently and need an explicit compatibility story.
Operator-skill actions currently live in core/self-update.ts beside npm package-manager detection and executable upgrade. This module now combines two different update domains and their process adapters.
The action result records presence and mutation booleans but not resolved skill version, source revision, provenance, or executable compatibility. The installed source currently follows the shared repository's main branch.

The operator skill is not a selected project pack and should not enter the project context plan or scaffold manifest. It is an independently acquired instruction/runtime dependency for the agent operating hi. Its acquisition, scope precedence, compatibility, and reload boundary require explicit ownership outside candidate 1.

New CLI Evidence Reinforces the Presentation Seam

Adding hi ensure required separate registration in the Effect command tree and the handwritten command atlas in apps/cli/src/ui/brand.ts.
Adding hi operator updated the Effect command tree but left the handwritten root atlas on hi skills rename, directly demonstrating command-metadata drift.
runEnsure returns void; prompts provide the only human interaction and there is no typed operation result for human, JSON, or non-TTY presentation.
Operator actions have a structured internal result, but the command wrapper immediately formats strings, writes to stdout/stderr, and sets process.exitCode; machine-readable and non-TTY contracts remain undefined.
Shared selector extraction removed duplicated prompts from scaffold/stage.ts, but the reusable module remains under scaffold/ even though a top-level command consumes it.

This strengthens the case for command metadata with one presentation policy and for application actions that return typed outcomes before terminal rendering.

Revised Boundary Implications

Pack graph: selects and validates contributed artifacts/capabilities, including skill reference closure and provenance; it does not own operator settings or reinterpret skill-internal workflow policy.
Project settings: owns provider/destination authority, schema migration, derived manager tools, and managed version pins with explicit field-level ownership.
Scaffold reconciliation: owns baseline-managed desired state and consumes project settings through a narrow boundary; it must not overwrite operator-owned settings fields.
Operator skill lifecycle: owns hi-cli presence, install/update/migration policy, source/provenance, scope precedence, and executable compatibility through a Skills CLI adapter; it remains isolated from project scaffold reconciliation.
CLI operations: orchestrate domain actions and return typed outcomes; Effect CLI and terminal rendering remain outer adapters.
Baseline distribution: ships a coherent versioned project capability graph, not an unstructured directory snapshot; it does not implicitly version an independently installed operator skill.

Historical Pre-Decision Contradictions and Risks

Overloaded vocabulary: "pack" names the scaffold selection primitive and also appears in generated subagent capability grouping. Those meanings may not share one lifecycle or owner.
Effect version mismatch: apps/cli/AGENTS.md currently requires stable Effect v3, while this refactor requests Effect v4. effect-smol replaces v3 service and CLI APIs, so this is a coordinated migration decision rather than a local import cleanup.
Duplicated semantic derivation: selected skills, expected files, prompt scopes, and harness mirrors are derived in more than one lifecycle path.
Behavior boundary uncertainty: "preserve behavior" could mean byte-compatible generated files and prose, or equivalent domain outcomes with intentional output changes.
Harness contract uncertainty: supported harnesses expose different prompt, skill, subagent, hook, and configuration surfaces, but the current contract is mostly encoded in filesystem branches and a generated synchronization script.
Cross-surface migration risk: CLI architecture, shared scaffold/contract packages, API registry behavior, and baseline compatibility may need coordinated movement. A CLI-only refactor could preserve existing duplication at package boundaries.
Presentation coupling: command handlers emit presentation strings directly, while JSON, non-TTY, interactive, and human-readable modes need different guarantees.
Update vocabulary and ownership: executable upgrade, operator-skill refresh, and project scaffold reconciliation are separate lifecycles, but operator-skill management currently shares core/self-update.ts with executable updates.
Operator compatibility gap: independently changing the CLI package, operator skill source, and project baseline can create instruction/runtime skew; no version or compatibility evidence appears in operator action results.
UI evidence is directional, not a specification: the Secrets CLI suggests a semantic renderer, command atlas, rails, glyphs, theme handling, and a development styleguide. HI still needs explicit decisions about help density, logo use, output compatibility, and machine-clean modes.

Test Suite Signal and Feedback Latency Research — 2026-07-13

This is completed readonly research. It informs a new requirements branch but does not accept a target budget, command split, worker policy, or implementation design.

Current Scale and Latency

The repository has 309 passing tests across 39 files and 12,639 lines of test code.
apps/cli is the dominant critical path with 216 tests across 25 files and 8,949 lines of test code.
Forced full-suite measurements varied from 23.06s to 30.59s wall time. A warm Turbo cache completed in about 0.27s to 0.29s with 7/7 tasks cached.
The CLI task took 21.9s in a normal forced run and up to 30.36s under contention while other real test workspaces ran concurrently.
The slowest CLI files were update/run.test.ts at about 17–18s, scaffold/run.test.ts at about 6–8s, scaffold/stage.test.ts at about 5–7s, and baseline/resolve.test.ts at about 3.4s.
CLI tests contain at least 116 temporary-directory creation sites and 24 explicit child-process calls. Repeated full baseline, scaffold, and update materialization dominates the critical path.

Signal to Preserve

High-signal coverage should continue to prove durable behavior at the nearest public seam:

generated and updated CLI filesystem outcomes
baseline traversal safety
API app.fetch route behavior
typed-client transport and header behavior
preservation and recreation of project-owned wiki state

Potential consolidation targets are lower-level or repeated assertions rather than these outcomes:

incidental Markdown or prose substring tombstones
exact internal registry and object shapes
cache-tag literals and prototype mechanics
repeated wiki-root, scaffold, and update decision matrices

Only seven CLI files use Effect-specific test methods, although 32 of the 39 test files import @effect/vitest. Narrowing that dependency is a directional optimization candidate, not an accepted migration.

Coverage and Environment Risks

Only 7 of 12 workspaces run real test tasks. apps/web, apps/wiki, packages/config, packages/env, and packages/ui have no test script, so reducing current-suite latency must not conceal repository coverage gaps.
CI=1 currently fails a CLI telemetry expectation because the observed environment label changes from test to ci. Environment and task-hash sensitivity must be part of the test-gate design.
The phrase "full suite" is ambiguous between the seven workspaces that currently run tests and an actually comprehensive repository gate.

Experimental Hypothesis, Not Accepted Policy

One experimental forced run with VITEST_MAX_FORKS=4 improved wall time from 29.29s to 21.66s. This is only a hypothesis. It needs repeated median measurements under a defined protocol before any worker cap or test policy is accepted.

Deepening Candidates

These are investigation candidates, not accepted module boundaries or final interfaces.

1. Pack Graph and Context-Plan Compiler (Recommended)

Cluster: repository evidence, pack catalog and resolution, skills, scoped prompts, subagent templates, hooks, tools, lint overlays, and context metadata.
Why coupled: pack selection is the upstream semantic decision that determines every context-engineering contribution. Today downstream writers repeatedly interpret the same selected packs.
Dependency category: in-process domain policy with local deterministic substitutes.
Test impact: add boundary tests from repository evidence and selected packs to one coherent semantic plan; replace redundant helper tests that only prove fragments of the same derivation.

2. Scaffold Desired State and Reconciliation

Cluster: setup, init, check, update, staged adoption, expected files, manifest hashes, system-managed settings pins, package edits, drift, and apply behavior.
Why coupled: these operations are views of the same desired-state lifecycle, but currently construct and compare that state through separate orchestration paths.
Dependency category: local filesystem and process boundary behind a deterministic reconciliation core.
Test impact: center tests on plan, diff, apply, idempotence, and managed-versus-user-owned preservation; prove that operator-owned project settings survive reconciliation; retire shallow tests duplicated across command wrappers where boundary coverage supersedes them.

3. Harness Capability and Projection Adapters

Cluster: Codex, Claude, Cursor, OpenCode, neutral .agents sources, skill homes, prompt files, subagent configuration, hooks, symlinks, and compatibility mirrors.
Why coupled: each harness consumes the same context intent through a different filesystem and configuration API. Current branches mix capability policy with file emission.
Dependency category: in-process adapter policy plus local filesystem materialization.
Test impact: define contract tests that project one neutral desired state into every supported harness and prove capability gaps, preservation rules, and fallback behavior.

4. CLI Operations and Semantic Terminal UI

Cluster: command outcomes, summaries, root/help presentation, prompts, approval, terminal theme, glyphs, panels/rails, JSON, non-TTY behavior, and the developer-only styleguide concept from Secrets.
Why coupled: terminal output should render typed command states, but command handlers and UI helpers currently co-own prose and interaction details.
Dependency category: local terminal boundary with substitutable renderer and interaction ports.
Test impact: add semantic renderer and mode contract tests for TTY, NO_COLOR, JSON, non-interactive, success, warning, failure, and empty states; reduce snapshot coverage of incidental layout strings.

5. Baseline Acquisition and Control-Plane Boundary

Cluster: bundled baselines, release artifacts, channels, caches, registry metadata, provenance, compatibility, API lookup, GitHub assets, and offline fallback.
Why coupled: the backend is authoritative while the CLI applies versioned artifacts locally, so acquisition precedence and trust metadata form one cross-process contract.
Dependency category: remote owned service plus true external GitHub/network dependencies, each behind an explicit port.
Test impact: add contract tests for channel resolution, provenance, cache freshness, authenticated asset fetches, explicit stable behavior, and fallback precedence.

6. API Domain Layers and Shared-Contract Migration

Cluster: baseline registry, reports, telemetry, access/backoffice actions, persistence, provider integrations, shared schemas, and CLI-facing contracts.
Why coupled: the API is currently flat and some scaffold/baseline concepts are duplicated across CLI, packages/scaffold, and packages/contract. Effect v4 changes service construction and layer composition across all of them.
Dependency category: cross-process owned API with external database, GitHub, and provider adapters.
Test impact: introduce feature-level use-case tests and adapter contract tests; migrate shared schema tests with the owning contract and preserve transport-level integration proof.

7. Project Settings and Provider Authority

Cluster: core/tools.ts settings schema/read/write/normalization, scaffold/settings-selection.ts, cli/ensure-command.ts, init, tool reconciliation, check/update pins, and scaffolded skills that consume provider authority.
Why coupled: these callers share one persistent aggregate but currently divide field ownership and lifecycle policy across scaffold, command, and tool modules. The stampVersions switch is evidence that different writers own different fields.
Dependency category: in-process schema and derivation with a local-substitutable filesystem boundary; provider APIs remain downstream external adapters.
Test impact: replace scattered normalization, selection, write, and manager-tool helper coverage with boundary tests for read/migrate/select/reconcile/write behavior and field-level ownership; retain command and lifecycle integration tests for non-mutation guarantees.

8. Operator Skill Acquisition and Compatibility

Cluster: hi operator, core/self-update.ts skill operations, the external Skills CLI, global/project installation detection, shared-skill source selection, legacy dp-cli migration, reload/reactivation, and compatibility with the installed CLI executable.
Why coupled: the operator skill is independently acquired and can change separately from the executable and project baseline, yet it defines how agents interpret command results and follow through. Its source, version, scope, and compatibility form one lifecycle that must remain isolated from project scaffold state.
Dependency category: in-process lifecycle policy with a true external process/source adapter and local installation-state discovery.
Test impact: add state-transition tests across absent/project/global/both/legacy installations, adapter contract tests for targeted add/remove commands and partial failure, and compatibility/provenance tests once the version contract is chosen; retain CLI integration proof for exit status and reload guidance.

Investigation Sequence

The selected candidate determines the first deepening sequence, not the final refactor scope. After selection, the next step is to trace its concrete callers, outputs, invariants, and change reasons, then design multiple competing boundaries before choosing an interface.

Accepted Decisions — 2026-07-13

Q1

Question: Which deepening candidate goes first?

Accepted answer:

Deepen candidate 1, Pack Graph + Context-Plan Compiler, first.
This sets investigation order, not total refactor scope.

Q2

Question: Which Effect generation is the target for this refactor?

Accepted answer:

Effect v4 supersedes the local stable-v3 instruction for this refactor.
Exact version remained open; Q32 supersedes this entry's open migration-wave and sequencing status.

Q3

Question: Should candidate 1 centralize the existing pack-to-workspace placement policy in the context-plan compiler without introducing a new applicability metadata model yet?

Accepted answer:

Yes. Candidate 1 centralizes the existing pack-to-workspace placement policy in the context-plan compiler and preserves current behavior behind one typed, testable boundary.
Do not introduce a new applicability metadata model now. Reconsider pack-authored selectors only if repeated cases justify them.
The independently acquired operator skill lifecycle remains outside candidate 1.

Q4

Question: Should candidate 1 know which skill identity, version, source, and reference files a pack contributes while leaving workflow instructions inside SKILL.md instead of modeling them as pack rules?

Accepted answer:

Yes. The context plan/compiler tracks and validates contributed skill identity, version, source and provenance, reference closure, and compatibility.
SKILL.md owns workflow semantics. Pack rules and the compiler must not duplicate or interpret skill-internal workflow policy.
The independently acquired operator skill lifecycle remains outside candidate 1.

Glossary Q5

Question: Should “pack” refer only to the project-level context unit selected or detected by the CLI, while generated subagent template groupings use the distinct term “capability group”?

Accepted answer:

Yes.
Canonical term: Pack — the project-level context selection unit selected or detected by the CLI; it drives the context-plan and scaffold lifecycle.
Canonical term: Capability group — a reusable grouping of skills used to compose a subagent template.
Relationship: a subagent template composes one or more Capability groups and does not directly consume project Packs.
Avoid: capability pack and unqualified pack for subagent-template groupings.

Q6

Question: Should the context plan stop at a neutral per-repository-scope semantic result and exclude target files, symlinks, hashes, package mutations, and write actions?

Accepted answer:

Yes.
The context plan ends at a neutral per-repository-scope semantic result. It may contain repository scope identifiers and resolved contribution intent.
It excludes target files, symlinks, hashes, package mutations, and write actions.
The scaffold plan and harness adapters own filesystem and harness materialization.

Q7

Question: Should Candidate 1 preserve behavior through semantic equality of context plans, while byte-for-byte generated-file and prose compatibility remains a downstream scaffold/harness test concern?

Accepted answer:

Yes.
Candidate 1 preserves behavior through semantic equality of context plans: same repository scopes, packs, resolved contributions, provenance, and meaningful ordering.
Byte-for-byte generated-file and prose compatibility belongs to downstream scaffold/harness tests.
Downstream tests may byte-lock managed outputs during migration; the compiler does not emit those bytes.

Q8

Question: Should the suite define separate fast and comprehensive test contracts?

Accepted answer:

No. This supersedes and rejects the previous recommendation to add a separate test:fast lane or split the suite.
Use one comprehensive repository test suite only, and make that single suite as fast as possible without weakening high-signal coverage.
Use Effect test Layers as the primary mechanism for meaningful deterministic substitutions at dependency seams where they reduce integration cost.
The exact Layer and substitution boundary remains open.

Q9

Question: Should tests keep domain logic real by default and replace only external/system adapters through Effect test Layers, while retaining a deliberately small real filesystem/process/HTTP/database contract spine?

Accepted answer:

Yes.
Keep domain logic real by default. Do not mock internal domain modules or collaborators.
Replace external and system adapters through typed Effect test Layers for deterministic, fast tests.
Retain a deliberately small real filesystem, process, HTTP, and database adapter contract spine.
The exact structure and size of the real adapter spine remains open.

Q10

Question: Should expensive real-adapter coverage be limited to one focused contract suite per adapter family, while broader behavior and decision matrices run against deterministic Layer implementations of the same ports?

Accepted answer:

Yes.
Limit expensive real-adapter coverage to one focused contract suite per adapter family.
Run broader behavior and decision matrices against deterministic Effect Layer implementations of the same ports.
The real adapter and deterministic Layer implementations must honor the same boundary contract.

Q11

Question: Should the suite adopt a forced-uncached acceptance budget of at most 10 seconds median on the reference developer machine, measured over five runs after one warm-up, with warm Turbo-cache time reported separately but never used as the speed gate?

Accepted answer:

No. This supersedes and rejects the recommendation to adopt a rigid suite runtime target.
Do not set a suite time budget or deadline. Make the single comprehensive suite as fast as possible without weakening high-signal coverage.
Treat runtime measurements as optimization evidence, not a release or pass threshold.
The proposed 10-second target, five-run protocol, and one warm-up are not accepted policy.

Q12

Question: Should every test-optimization slice include repeatable before-and-after forced-uncached measurements, with regressions investigated, but no fixed runtime threshold blocking completion?

Accepted answer:

Yes.
Every test-optimization slice includes repeatable, comparable before-and-after forced-uncached measurements.
Investigate regressions.
Measurements remain evidence; no fixed runtime threshold blocks completion.

Q13

Question: Should shared Effect test Layers be immutable or read-only by default, with mutable adapter state created fresh per test scope so fixture reuse cannot introduce order dependence?

Accepted answer:

Yes.
Shared Effect test Layers are immutable or read-only by default, and expensive immutable construction may be shared.
Create mutable filesystem, repository, clock, process, and request state fresh per test scope.
Fixture reuse must not introduce order dependence or hidden coupling.

Q14

Question: Should test concurrency remain a benchmark-tuned implementation setting rather than a permanently fixed worker count, with isolation guarantees holding at every supported concurrency level?

Accepted answer:

Yes.
Test concurrency is benchmark-tuned, not a permanently fixed worker count.
The four-worker experiment remains evidence, not architecture or policy.
Determinism and state isolation must hold at every supported concurrency level.

Q15

Question: Should local and CI runs execute the same suite contract, with caching used only as an acceleration layer and behavior-affecting environment inputs modeled explicitly in tests and task hashes rather than through implicit CI branches?

Accepted answer:

Yes.
Local and CI runs execute the same suite behavior contract.
Caching is an acceleration layer only and cannot change coverage or results.
Model behavior-affecting environment inputs explicitly in tests and task hashes, not through implicit CI branches.

Q16

Question: Should every behavior-owning workspace participate in the comprehensive suite, while workspaces with no testable behavior may carry an explicit reason_not_testable instead of empty or low-signal placeholder tests?

Accepted answer:

Yes.
Every behavior-owning workspace participates in the comprehensive suite with high-signal public-seam proof.
A workspace with no testable behavior may carry an explicit reason_not_testable instead of empty or low-signal placeholder tests.
Such surfaces still use their appropriate typecheck, lint, or build validation.
Determining which current workspaces qualify is an implementation audit, not an open design decision.

Q17

Question: Should scaffold init, check, and update consume one shared desired-state compiler, with observation, diffing, and application kept as separate stages instead of each command re-deriving expected state?

Accepted answer:

Yes.
Scaffold init, check, and update consume one shared desired-state compiler.
Observation, diffing, and application are separate stages: init applies the plan, check compares it, and update reconciles it.
Filesystem effects and conflict handling stay outside domain planning.

Q18

Question: Should the desired-state compiler be pure and deterministic over explicit inputs—a context plan, project-settings snapshot, baseline/catalog data, and harness capabilities—with repository discovery, filesystem reads, environment access, and process execution kept outside it?

Accepted answer:

Yes.
The desired-state compiler is pure and deterministic over explicit context plan, project-settings snapshot, baseline/catalog data, and harness-capability inputs.
Repository discovery, filesystem reads, environment access, and process execution stay outside the compiler.
The same inputs yield the same scaffold plan across init, check, and update.

Q19

Question: Should the managed manifest be an application receipt describing the last successfully applied managed state and provenance, never a source of desired state, with reconciliation comparing desired plan, observed repository state, and prior receipt?

Accepted answer:

Yes.
The managed manifest is an application receipt for the last successfully applied managed state and provenance, never a source of desired state.
Reconciliation compares the desired plan, observed repository state, and prior receipt.
This distinguishes unchanged managed output, user modification, stale ownership, and safe removal.

Q20

Question: Should package and structured-config changes be represented as semantic field-level mutations in the scaffold plan rather than whole-file replacement, with ownership tracked per managed dependency/key so unrelated user edits survive?

Accepted answer:

Yes.
Package and structured-config changes are semantic field-level mutations, not whole-file replacements.
Ownership is tracked per managed dependency or key.
Reconciliation updates managed entries deterministically and preserves unrelated user fields and dependencies.

Q21

Question: Should reconciliation be non-destructive by default: automatically apply changes only when managed state is unchanged since the prior receipt, but preserve and report any user-modified managed file/key that would otherwise be overwritten or removed until the operator explicitly resolves it?

Accepted answer:

Yes.
Reconciliation is non-destructive by default and automatically applies changes only when managed state is unchanged since the prior receipt.
Preserve and report any user-modified managed file or key that would otherwise be overwritten or removed.
Divergent managed state requires explicit operator resolution.
Conflicts do not inherently block unrelated safe changes.

Q22

Question: When a reconciliation contains both safe actions and conflicts, should application complete the independent safe actions, emit a typed outcome for every action, and advance the managed receipt only for changes that actually succeeded while leaving conflicts unresolved?

Accepted answer:

Yes.
Complete independent safe actions during mixed safe/conflict reconciliation and emit a typed outcome for every action.
Advance the managed receipt only for changes that actually succeeded.
Leave skipped, failed, and conflicting actions unresolved and unrecorded as applied.
Retries remain deterministic and truthful.

Q23

Question: Should every harness adapter expose an explicit capability contract and return typed unsupported-capability diagnostics when a context contribution cannot be represented, rather than silently omitting it or applying an undocumented fallback?

Accepted answer:

Yes; this is a pinned axiom.
Every harness adapter exposes an explicit capability contract.
A contribution that cannot be represented returns a typed unsupported-capability diagnostic; silent omission and undocumented fallback are forbidden.
Capability gaps are visible and testable for prompts, hooks, subagents, tools, and skills.

Q24

Question: Should an unsupported contribution be a hard planning error by default, with a fallback allowed only when the harness adapter declares an explicit semantically equivalent projection rather than a warning-and-skip path?

Accepted answer:

No. This supersedes and rejects the prior hard-error recommendation; that recommendation was not an accepted Q23 decision.
Known unsupported harness capabilities produce non-blocking typed warnings scoped to the affected harness and contribution, while supported projections for that and other harnesses continue.
The CLI returns an explicit degraded or partial outcome, and the agent reports exactly what was omitted and for which harness.
The managed receipt records the omission or degradation so nothing disappears silently.
Genuine adapter bugs, invalid projections, and application or write failures remain errors for affected actions.
Silent omission and undocumented fallback remain forbidden under Q23.

Q25

Question: Should harness capability contracts describe neutral semantic capabilities—skill installation, scoped prompts, subagent templates, lifecycle hooks, and tool configuration—while harness-specific paths, filenames, schemas, and link strategies remain projection details inside each adapter?

Accepted answer:

Yes.
Harness capability contracts describe neutral semantic behaviors: skill installation, scoped prompts, subagent templates, lifecycle hooks, and tool configuration.
Harness-specific paths, filenames, schemas, and link strategies are adapter projection details.
The context model does not encode the current filesystem layout.

Q26

Question: Should neutral authored contributions remain the canonical source, while every harness-specific file, symlink, mirror, or config entry is a managed, fully reproducible projection that never becomes an independent source of truth?

Accepted answer:

Yes.
Neutral authored contributions remain the canonical source.
Every harness-specific file, symlink, mirror, or config entry is a managed, fully reproducible projection and never an independent source of truth.
Adapters may choose the harness-native mechanism, but each projection stays traceable to canonical contribution identity and safe to recreate, reconcile, or remove.

Q27

Question: Should each harness adapter publish a versioned capability matrix and run the same projection contract tests across supported, degraded, and unsupported cases, with any capability change treated as an explicit compatibility change rather than an incidental adapter edit?

Accepted answer:

Yes.
Each harness adapter publishes a versioned capability matrix.
The same projection contract tests cover supported, degraded, and unsupported cases across adapters.
A capability change is an explicit compatibility change, not an incidental adapter edit.
Matrices and compatibility history let the baseline and CLI explain newly supported or degraded projections.

Q28

Question: Should every field in .devpunks/settings.json have one clear owner, with each command changing only the fields it owns?

Accepted answer:

Yes.
.devpunks/settings.json contains three classes: user choices such as provider and backlog destination; CLI-calculated required tools; and CLI-managed CLI and baseline versions.
User-facing settings commands may change user choices. CLI recalculation may change derived required tools. Scaffold and update may change managed version values.
Every operation preserves fields it does not own. For example, hi update must not replace the user's GitHub or Linear choice.

Q29

Question: What should happen when the CLI reads an older .devpunks/settings.json that is missing new fields or uses an older field shape?

Accepted answer:

Preserve the user's choices and convert old or missing values to the current shape only when the conversion is safe and unambiguous.
hi check reports that an upgrade is needed but never rewrites the file.
Setup, ensure, and update may save the upgraded shape together with their intended changes.
An unsafe or ambiguous conversion produces a clear error; the CLI must not guess or discard values.

Q30

Question: Should every command use one shared settings component instead of reading or writing .devpunks/settings.json directly?

Accepted answer:

Yes.
Every command uses one shared settings component to read, validate, upgrade, and save .devpunks/settings.json; command modules do not read or write the JSON file directly.
Commands receive current valid settings and request only the changes they are allowed to make.
The component applies field ownership and old-file rules consistently for setup, ensure, check, and update.

Q31

Question: Do the corrected command names and responsibilities match the intended behavior?

Accepted answer:

Yes. This supersedes the earlier command naming in Q17, Q29, and Q30.
hi init replaces and renames the old scaffold init. It creates missing settings, asks for the user's provider and backlog destination, calculates required tools, and records the CLI and baseline versions used for the initial scaffold.
hi scaffold replaces and renames the old scaffold setup; it keeps that command's existing role without adding new behavior.
hi ensure changes only the user's provider and backlog choices and recalculates required tools. It does not run scaffold reconciliation or change recorded CLI or baseline versions.
hi check is read-only.
hi update preserves provider and backlog choices, recalculates required tools, updates CLI and baseline version records, and reconciles the managed scaffold.

Q32

Question: How should the Effect v4 upgrade and architecture refactor be sequenced across the repository?

Accepted answer:

Upgrade every Effect-dependent workspace to Effect v4 and refactor it to the intended v4 architecture in one coordinated migration that is green as one repository-wide change.
This supersedes the previously proposed compile-first, refactor-later sequencing. Do not maintain v3/v4 translation layers or defer architecture cleanup to a later migration.
Use effect-smol and the OpenCode and T3 Code repositories as required source references for v4 patterns, resolving them through opensrc.
Source research remains an input rather than an accepted design conclusion. Exact module, service, error, layer, and runtime design remains open.

Q33

Question: Should each hi command invocation have one application runtime created and run only by the top-level executable entrypoint?

Accepted answer:

Yes. For each invocation, the top-level executable entrypoint is the only composition point that combines production dependencies and runs the Effect application.
Feature modules may define and export their production setup, but commands and domain modules may not create runtimes or independently select real filesystem, network, terminal, or config implementations.
Commands read inputs, call an application operation, and render the result.
This does not create a daemon, shared mutable global state, or one giant wiring file. Feature-owned production setup remains distributed behind one top-level composition boundary.
Exact internal type and file names remain open.

Q34

Question: Should applicable Effect and backend roots adopt the domain-first rules from backend-domain-structure and effect-backend-structure?

Accepted answer:

Yes. Applicable roots are domain-first with platform/, integrations/, and features/<domain>/. A shared package that already owns one coherent domain may itself be the domain root instead of mechanically nesting another features/ directory.
Each feature owns its actions and use cases, models and schemas, errors, ports and contracts, justified repositories and services, Layer setup, colocated tests and support, private helpers, and a deliberate root or public module.
Cross-feature consumers import only deliberate public roots, never feature internals.
Actions own workflows and policy. Services exist only for reusable mechanics. Persistence stays behind repositories and adapters.
Transport parses input, calls application behavior, maps failures, and renders results; it remains thin. Root platform composition combines feature and integration Layers.
Avoid generic root buckets and compatibility aliases.
These architecture rules are accepted, but v3 API spellings in the named skills, such as Effect.Service, do not override the Effect v4 source and version selected by this grill. The exact v4 service API remains tied to the exact pinned v4 release and current source research.
Exact domain inventory, shared-package ownership, internal type names, and file names remain open.

Q35

Question: Should packages/contract own only the protocol exchanged across processes and stop choosing request runtime or product behavior?

Accepted answer:

Yes. packages/contract owns only cross-process shared data schemas, public typed errors, and HTTP endpoint definitions.
It does not choose the concrete HTTP client or runtime and does not own auth-header injection, retries, handlers, persistence, scaffold behavior, harness policy, CLI decisions, or backoffice UI and session behavior.
The CLI and backoffice own request runtime, auth headers, and retries. The API owns handlers. Product behavior remains with its owning domains.
packages/contract/src/client.ts makeHarnessClient providing FetchHttpClient.layer is a boundary leak to remove during the refactor.
The domain submodule and export shape remained open until Q36.

Q36

Question: Should packages/contract expose separate public protocol submodules instead of one broad root barrel?

Accepted answer:

Yes. Expose separate public protocol submodules for baseline, telemetry, reports, and backoffice; consumers import only the protocol area they use.
A small explicit common submodule is allowed only for primitives genuinely shared by multiple protocol areas.
The broad root barrel must not expose every protocol domain together.
This is a coordinated migration. Do not retain stale compatibility aliases or re-exports unless the user later explicitly requires external compatibility.
Exact file and symbol names remain implementation tuning.

Q37

Question: Should this grill pin today's numeric Effect v4 beta, or define when and how implementation selects it?

Accepted answer:

The requirements do not pin today's numeric beta.
At the start of implementation, select the latest published Effect v4 beta and matching compatible @effect/* versions, then pin that exact coordinated set in the shared catalog and lockfile across every Effect-dependent workspace.
Do not use caret or range versions.
Do not automatically chase betas released during implementation. Any subsequent upgrade is a deliberate repository-wide decision.
The exact numeric version and corresponding API are resolved at implementation time under this rule.

Q38

Question: How must expected domain and operational failures flow through Effect code?

Accepted answer:

Every possible expected domain or operational failure is modeled with an accepted schema-backed domain error in Effect's typed error channel, Effect<A, E, R>.
Callers explicitly handle each expected failure or intentionally propagate it.
Expected failures may not be swallowed, converted to defects, hidden as unknown, reduced to untyped strings, or handled through printing, process exit codes, or HTTP responses inside domain code.
CLI, API, and other transport code translate expected errors only at their boundaries.
Unexpected programmer defects remain defects outside the expected-error channel.

Q39

Question: How should integration and system adapters expose expected operational failures to feature code?

Accepted answer:

Every integration and system adapter, including filesystem, subprocess, network, database, GitHub, and Skills CLI adapters, catches raw library or system failures that are expected operational cases.
At the adapter boundary, convert those cases into a small, stable typed Effect error set before feature code sees them.
Errors carry useful context such as path, provider and status, command and timeout, or operation, and preserve the original cause for diagnostics.
Unexpected defects remain defects.
Do not invent one universal catch-all error.

Q40

Question: Where should environment, process, and runtime configuration be read, validated, and provided?

Accepted answer:

Read and schema-validate environment, process, and runtime configuration only during platform/config setup.
Features, commands, and integrations never read process.env directly. Application roots provide typed configuration services and Layers.
Tests provide explicit configuration services or providers.
Missing configuration and present-but-invalid configuration are typed startup or config failures. Secrets are redacted.
Keep packages/contract and packages/scaffold configuration-free, with explicit client options where needed.
Exact focused config-service ownership remained open until Q41.

Q41

Question: Should packages/env own only reusable Effect v4 configuration building blocks while applications and domains own focused config services?

Accepted answer:

Strong yes. packages/env provides only reusable Effect v4 Config decoding and schema fragments plus ConfigProvider and provider-building primitives. It is not a global config object.
Each application or domain owns small focused typed config services and Layers, such as ControlPlaneConfig, BaselineConfig, DatabaseConfig, and ReportsGitHubConfig. Application-only config stays app-local.
A decoder moves into packages/env only after genuine cross-root reuse.
Each application composition root combines its focused config services.
Tests inject parsed services or focused providers.
Exact class, symbol, and file names remain implementation tuning.

Q42

Question: Should every command or application operation produce one structured result before any output is rendered?

Accepted answer:

Yes. Every command or application operation first produces a structured, presentation-neutral operation result.
As applicable, it contains overall status, changes made or planned, warnings and degradations, handled per-action conflicts and failures, and suggested next actions.
Interactive human, plain non-TTY, and JSON renderers consume the same result.
Prompts are input concerns, not result fields or presentation.
Command-stopping expected failures remain typed Effect errors until the presentation or transport boundary maps them.
Domain and application code contains no formatted terminal prose, glyphs, ANSI, spinners, or exit-code decisions.

Q43

Question: Should output mode be selected once at the CLI root with explicit interactive, plain, and JSON contracts?

Accepted answer:

Strong yes. Select output mode once at the CLI root.
An interactive human terminal may use rich styling, prompts, and progress.
Piped or redirected non-JSON output is deterministic plain text with no ANSI or color, animation, or prompts.
--json is always non-interactive. Stdout contains exactly one valid JSON document with no logo, prose, or progress; expected failures produce a structured JSON error document plus a nonzero exit status.
Unexpected diagnostics may use stderr but never corrupt JSON stdout.
Missing required input in non-interactive modes yields a typed, actionable error.
Renderers do not make domain decisions.

Q44

Question: Should every command own one metadata declaration that drives every discovery and reference surface?

Accepted answer:

Yes. Every command owns one metadata declaration beside its Effect command definition containing its name, group, summary, options, examples, interaction requirements, and supported output modes.
Root help, the command atlas or listing, examples, and generated CLI reference or styleguide views derive from that metadata.
Remove handwritten duplicate command lists. Adding, renaming, or removing a command updates every discovery surface through the same source.
Metadata is presentation and discovery input; it does not own domain behavior.

Q45

Question: Should commands send semantic facts to one shared human renderer instead of constructing terminal presentation themselves?

Accepted answer:

Yes. Commands emit structured semantic facts to one shared human terminal renderer and never construct panels, bullets, colors, glyphs, spacing, wrapping, or terminal prose themselves.
The renderer maps semantic states and layout primitives to Harness Intelligence's visual identity and honors the root-selected interactive or plain policy. JSON bypasses the human renderer completely.
Prompts use the same semantic theme and glyph rules, while a separate prompt interaction service owns keyboard input, raw-terminal lifecycle, and cleanup.
Preserve the HI gradient, title, and theme identity. Reuse the Secrets renderer architecture, not its skin.
Do not create a generic widget framework. Add only primitives used by real current flows.

Q46

Question: Where should the large gradient HI title appear?

Accepted answer:

Show the large gradient HI title only on the root hi screen or root help, and optionally on an explicit welcome or onboarding screen.
Normal subcommands such as init, scaffold, update, and check use a compact command heading or no heading instead of repeating the title.
Plain non-TTY and JSON output never show the title.
This is hierarchy policy, not removal of the Harness Intelligence identity.

Q47

Question: Should the repository include a developer-only catalog that exercises the real terminal renderer without running commands?

Accepted answer:

Yes. Include a developer-only terminal UI catalog using deterministic fake structured results to exercise every production renderer semantic state, layout, and prompt frame across light, dark, NO_COLOR, and narrow-width modes.
The catalog imports production renderer primitives in one direction. Production never imports it, and it is not shipped as a normal user command.
It enables focused snapshot or golden testing and visual review without real command side effects.
It must not become a second renderer.
Exact primitive names, palette values, and spacing are implementation tuning within the accepted HI identity and renderer rules.

Q48

Question: How should the independently installed hi-cli operator skill be sourced, versioned, and matched to the CLI?

Accepted answer:

The shared Devpunks skills repository remains the source of truth for hi-cli.
Installs and updates resolve an immutable released version or commit selected by explicit CLI compatibility metadata instead of following moving main.
The CLI reports the installed skill version, source, revision, and compatibility with the current CLI.
Update installs the compatible immutable target, and resolving the same target is reproducible.
Exact release mechanism and compatibility-range representation remain open; do not invent either yet.

Q49

Question: How should global and project-local hi-cli installations interact?

Accepted answer:

hi operator install ensures the global default.
A project-local hi-cli is an explicit override and wins only inside that project; the global installation is the fallback elsewhere.
Status determines the effective copy for both the current directory and active agent and reports shadowed copies.
Default update targets every detected hi-cli scope. Future explicit scope flags are implementation tuning.
Detection or list failure must not be treated as absence under this effective-copy contract.

Q50

Question: How should operator update and migration verify and report mutations across scopes?

Accepted answer:

After every successful-looking Skills CLI mutation, re-list or re-inspect and count success only when the expected version, source, revision, and active-agent binding are verified.
Independent successful scopes remain changed and are reported; do not roll them back because another scope failed.
Failed or unverified scopes are typed failures with exact retry actions.
Migration removes legacy dp-cli only after a compatible hi-cli replacement is verified for every scope whose fallback is removed.
Any successful write emits reload or reactivate guidance even when another scope failed.

Q51

Question: What boundary should own operator-skill lifecycle policy versus external Skills CLI mechanics?

Accepted answer:

Operator lifecycle depends on a typed, feature-owned boundary for inspecting state, installing an immutable target, removing legacy copies, and verifying the effective copy.
External Skills CLI command syntax, JSON parsing, timeouts, agent-binding mechanics, and subprocess failures live only in one integration adapter.
A missing or broken Skills CLI is a typed unavailable or adapter failure, never false absence.
There is no silent filesystem fallback.
Tests replace the adapter with a deterministic Layer.
Exact boundary names, release mechanism, compatibility encoding, and scope-flag syntax are implementation tuning under the accepted immutable compatibility rules.

Q52

Question: What contract should baseline resolution return across API, release, cache, and bundled sources?

Accepted answer:

Return one neutral, verified artifact record for every source.
The record contains the requested channel or version, exact immutable resolved version, digest, source and provenance, compatibility, and retrieval, cache, or fallback status.
A baseline-resolution feature owns authority, version selection, and fallback policy.
API, published-release, cache, and bundled adapters only fetch and verify bytes and metadata. They cannot silently choose a different version.

Q53

Question: What is the online authority and invariant for the moving stable baseline channel?

Accepted answer:

The control-plane API is the sole online authority for moving baseline resolution.
stable always maps to the newest published baseline, and the newest baseline is always stable; no newer non-stable baseline exists ahead of it.
The API always returns that newest stable version, digest, and compatibility.
Release, cache, and bundled retrieval must match the API resolution and cannot override it.
If API metadata is behind or disagrees with the newest published baseline, that is a typed control-plane authority or integrity defect. It does not permit the CLI to silently choose GitHub.
Explicit immutable version requests remain exact.

Q54

Question: What should HI do when the control-plane API is unavailable?

Accepted answer:

API unavailability is a rare edge case; a simple typed, actionable failure is the sufficient default. This supersedes the stronger offline-fallback recommendation after Q53.
Do not require a new cache or bundled fallback implementation.
If a verified cache or bundled path already works and is cheap to preserve during refactoring, it may remain as an implementation detail under Q52 provenance, digest, and compatibility checks; otherwise omit it.
Never silently downgrade and never let GitHub redefine stable.
An explicit bundled request may remain when it is already supported safely.

Q55

Question: What compatibility evidence and phase boundary must exist before the architecture refactor starts?

Accepted answer:

Before implementation, classify every externally visible output as byte-for-byte locked, semantically equivalent, or intentionally changed by an accepted requirement.
Give each output a characterization fixture or test at its public seam before refactoring it.
Managed scaffold assets and public JSON are byte-locked by default unless explicitly changed; context plans use the accepted semantic-equality contract; terminal UI and renamed commands are intentional changes.
Do not start implementation, prototyping, planning or delivery transition, or code refactoring until the grill is fully finished and the user explicitly routes onward.
During the grill, edit requirements artifacts only.

Q56

Question: Should the final migration ship old and new architectures together, or only the new Effect v4 architecture?

Accepted answer:

The final migration ships only the new Effect v4 architecture.
Remove the old architecture and compatibility shims in the same final change.
Do not ship a production v3/v4 feature flag or dual implementation.
Temporary scaffolding used while working must not ship.
Rollback means reverting or redeploying the prior known-good commit or release, not maintaining two production architectures.

Q57

Question: What gates must pass together before the coordinated migration can merge or release?

Accepted answer:

Block merge and release until the comprehensive repository suite passes.
Typecheck, lint, and build every participating workspace; pass all output-classification fixtures; prove zero Effect v3 dependencies, imports, or compatibility shims.
Pass packaged CLI command, help, and JSON checks; API contract and handler checks; renderer-catalog tests; and operator-lifecycle contract tests.
Pass isolated representative consumer proof for fresh hi init and hi scaffold, plus existing-repository hi check and hi update preserving user changes.
Any unavailable required gate is an explicit blocker and is never silently waived.

Q58

Question: Should migration proceed by fully completing one domain at a time, or breadth-first through the architecture hierarchy?

Accepted answer:

Use breadth-first migration through the architecture hierarchy. This supersedes the vertical one-domain-at-a-time proposal after Q57.
First define deliberate public or root modules for every major domain and their dependency direction. Then establish the next level across the system—actions, services, repositories, and adapters where applicable—and continue level by level toward leaf implementations.
Do not fully finish packs before beginning context or the other peer domains.
Work happens on one unmerged, undeployed branch or pull request. Intermediate branch states may be broken, need not be deployable, and need not preserve old runtime paths.
There is no safe live migration, dual path, compatibility shim, feature flag, or staged deployment. Old paths may be deleted or replaced directly as work proceeds, and temporary scaffolding must not ship.
Merge only after every accepted gate passes. After merge, rollback remains reverting or redeploying the prior known-good commit or release.
Q55 public-output characterization and Q57 final gates protect final correctness; they do not require intermediate branch states to be deployable.

CLI Context Architecture Grill Log

On this page