CLI Context Architecture Grill Status

Source: architecture and CLI UI investigation requested on 2026-07-10.

Current grill artifacts:

• Log: apps/wiki/content/docs/project/grilling/cli-context-architecture-grill-log.md
• Status: apps/wiki/content/docs/project/grilling/cli-context-architecture-grill-status.md

Branch Dashboard

Percentages describe investigation depth, not implementation progress.

Locked User Brief

• Every Effect-dependent workspace upgrades to Effect v4 and adopts the intended v4 architecture in one coordinated migration that is green as one repository-wide change; this supersedes compile-first, refactor-later sequencing, forbids v3/v4 translation layers, and does not defer architecture cleanup.
• effect-smol and the OpenCode and T3 Code repositories are required v4 pattern references resolved through opensrc; source research does not lock exact module, service, error, layer, config, adapter, or runtime design.
• The requirements do not pin today's numeric Effect beta. At implementation start, select the latest published v4 beta and matching compatible @effect/* versions, then pin that exact coordinated set in the shared catalog and lockfile across every Effect-dependent workspace. Use no caret/range versions, do not automatically chase later betas during implementation, and treat every subsequent upgrade as a deliberate repository-wide decision.
• Every possible expected domain or operational failure uses an accepted schema-backed error in Effect<A, E, R>, and callers explicitly handle or intentionally propagate it. Expected failures are never swallowed, defect-converted, hidden as unknown, reduced to untyped strings, printed, mapped to exit codes, or turned into HTTP responses inside domain code; CLI, API, and transport translate only at their boundaries. Unexpected programmer defects remain defects.
• Every integration and system adapter converts expected raw filesystem, subprocess, network, database, GitHub, Skills CLI, and similar failures into a small stable typed Effect error set before feature code sees them. Errors carry useful path, provider/status, command/timeout, or operation context and preserve the original cause; unexpected defects remain defects, and no universal catch-all error is allowed.
• Environment, process, and runtime configuration is read and schema-validated only during platform/config setup. Application roots provide typed config services and Layers; features, commands, and integrations never read process.env; tests provide explicit services or providers; missing or present-but-invalid configuration remains a typed startup/config failure, and secrets are redacted. packages/contract and packages/scaffold stay config-free with explicit client options.
• packages/env provides only genuinely reusable Effect v4 Config decoding/schema fragments and ConfigProvider or provider-building primitives; it is not a global config object. Applications and domains own focused typed config services and Layers, application-only config stays local, decoders move to packages/env only after cross-root reuse, roots compose the focused services, and tests inject parsed services or focused providers.
• For each hi invocation, only the top-level executable entrypoint combines production dependencies and runs the Effect application. Feature modules may export production setup; commands and domain modules never create runtimes or select real filesystem, network, terminal, or config implementations. Commands read inputs, call an application operation, and render the result.
• One runtime per invocation is not a daemon, shared mutable global state, or one giant wiring file; feature-owned production setup remains distributed behind the single top-level composition boundary.
• Applicable Effect and backend 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 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 public root. Cross-feature consumers import only that public root, never internals.
• Actions own workflows and policy; services are reusable mechanics only; persistence stays behind repositories and adapters; transport only parses, calls, maps, and renders; root platform composition combines feature and integration Layers. Generic root buckets and compatibility aliases are rejected.
• The named structure skills' architecture rules are accepted, but their v3 API spellings such as Effect.Service do not override this grill's Effect v4 source/version. Exact service APIs follow the exact pinned v4 release and current source research.
• packages/contract owns only cross-process shared data schemas, public typed errors, and HTTP endpoint definitions. It owns no request runtime, auth headers, retries, handlers, persistence, scaffold behavior, harness policy, CLI decisions, or backoffice UI/session behavior.
• CLI and backoffice own their request runtime, auth, and retries; API owns handlers; product behavior stays with owning domains. makeHarnessClient providing FetchHttpClient.layer is a boundary leak to remove.
• packages/contract exposes separate public baseline, telemetry, reports, and backoffice protocol submodules; consumers import only what they use. A small explicit common submodule is allowed only for primitives genuinely shared across protocol areas, and the root barrel does not expose every domain together.
• The contract-submodule change is coordinated across the repository. Stale compatibility aliases and re-exports are forbidden unless the user later explicitly requires external compatibility.
• Baseline resolution returns one neutral verified artifact record across API, published release, cache, and bundled sources, containing requested channel/version, exact immutable resolved version, digest, provenance, compatibility, and retrieval/cache/fallback status. The feature owns authority, version selection, and fallback policy; adapters only fetch and verify and never silently choose another version.
• The control-plane API is the sole online authority for moving baseline channels. stable always resolves to the newest published baseline, and the newest baseline is always stable; the API returns its exact version/digest/compatibility, retrieval sources must match it, disagreement or stale API metadata is a typed authority/integrity defect rather than permission to choose GitHub, and immutable version requests stay exact.
• API unavailability defaults to a simple typed actionable failure; no new cache or bundled fallback is required. An already-working verified path may remain only when cheap to preserve under provenance/digest/compatibility checks, and an already-safe explicit bundled request may remain; silent downgrade and GitHub redefining stable are forbidden.
• The architecture should use deep modules with explicit primitives and dependency direction.
• Skill packs are a central primitive because scoped prompt and subagent generation depend on them.
• Hooks, tools, harness inputs, and other context-engineering contributions must be investigated as part of the same semantic system.
• Candidate 1 centralizes the existing pack-to-workspace placement policy in the context-plan compiler, preserves current behavior through semantic equality, and adds no new applicability metadata model now.
• Candidate 1 tracks and validates contributed skill identity, version, provenance, reference closure, and compatibility while leaving workflow semantics inside SKILL.md.
• The context plan ends at repository scope identifiers and resolved contribution intent; target files, symlinks, hashes, package mutations, and write actions belong to scaffold plans and harness adapters.
• Pack names the project-level context selection unit; capability group names a reusable skill grouping used to compose subagent templates.
• The Devpunks Secrets CLI renderer, command atlas, semantic states, and interaction patterns are accepted architecture evidence; HI preserves its own identity under Q45-Q47.
• Every command or application operation produces one presentation-neutral structured result before output, containing applicable status, changes, warnings/degradations, handled per-action conflicts/failures, and next actions. Interactive human, plain non-TTY, and JSON renderers consume it; prompts remain input concerns; stopping expected failures remain typed until boundary translation; domain/application code contains no terminal prose, glyphs, ANSI, spinners, or exit-code decisions.
• Output mode is selected once at the CLI root. Interactive terminals may use rich styling, prompts, and progress; piped/redirected non-JSON output is deterministic plain text without ANSI/color, animation, or prompts; --json is non-interactive and writes exactly one JSON document to stdout with no logo, prose, or progress, including structured expected-error output plus nonzero status. Unexpected diagnostics may use stderr without corrupting stdout; missing non-interactive input is a typed actionable error; renderers make no domain decisions.
• Every command owns one metadata declaration beside its Effect command definition with name, group, summary, options, examples, interaction requirements, and supported output modes. Root help, command listings, examples, and generated reference/styleguide views derive from it; handwritten duplicate command lists are removed, command lifecycle changes update every discovery surface from the same source, and metadata owns no domain behavior.
• Commands send structured semantic facts to one shared human terminal renderer and never build panels, bullets, colors, glyphs, spacing, wrapping, or terminal prose. The renderer applies HI's gradient/title/theme identity and root-selected interactive/plain policy; JSON bypasses it. Prompts share semantic theme/glyph rules while a separate interaction service owns keyboard/raw-terminal lifecycle and cleanup. Reuse Secrets architecture, not its skin, and add only primitives required by real flows rather than a generic widget framework.
• The large gradient HI title appears only on the root hi screen or root help and optionally an explicit welcome/onboarding screen. Normal subcommands use a compact heading or none; plain non-TTY and JSON never show the title. This preserves HI identity while keeping repeated workflows concise.
• A developer-only terminal UI catalog uses deterministic fake structured results to exercise every production semantic state, layout, and prompt frame in light, dark, NO_COLOR, and narrow-width modes. It imports production renderer primitives one-way, is never imported by production or shipped as a user command, and supports snapshot/golden plus visual testing without side effects or a second renderer.
• The independently installed hi-cli operator skill remains outside project pack/scaffold state; Q48-Q51 lock its source, compatibility, precedence, verification, and typed adapter ownership.
• The shared Devpunks skills repository remains authoritative for independently installed hi-cli, while explicit CLI compatibility metadata resolves an immutable released version or commit rather than moving main. Status reports installed version, source, revision, and compatibility; update installs the compatible immutable target reproducibly. Exact release mechanism and range representation are downstream implementation tuning.
• hi operator install ensures a global default; a project-local hi-cli is an explicit override only inside that project, with global fallback elsewhere. Status resolves the effective copy for current directory and active agent and reports shadowed copies; default update targets every detected scope; detection/list failure is never absence. Explicit scope flags may be implementation tuning.
• Every successful-looking Skills CLI mutation is re-inspected and counts as success only after version, source, revision, and active-agent binding match. Independent successful scopes remain changed and reported; failed/unverified scopes are typed failures with exact retries; migration removes legacy dp-cli only after every affected fallback has a verified compatible hi-cli; any successful write emits reload/reactivate guidance despite other failures.
• Operator lifecycle uses a typed feature-owned boundary for inspect, immutable install, legacy removal, and effective-copy verification. One integration adapter alone owns Skills CLI syntax, JSON, timeouts, agent binding, and subprocess failures; missing/broken CLI is typed unavailable/adapter failure, never absence; no filesystem fallback exists; tests provide a deterministic Layer.
• There is one comprehensive repository test suite, with no separate fast lane; make it as fast as possible without weakening high-signal coverage, but impose no rigid runtime target, budget, deadline, release threshold, or pass threshold.
• Domain logic stays real, broad behavior runs through deterministic Effect Layers, and expensive real-adapter coverage is limited to one focused contract suite per adapter family, with both implementations honoring the same boundary contract.
• Every test-optimization slice includes repeatable, comparable before-and-after forced-uncached measurements, and regressions are investigated; measurements remain evidence rather than a blocking threshold.
• Shared Effect test Layers are immutable or read-only by default; expensive immutable construction may be shared, but mutable filesystem, repository, clock, process, and request state is fresh per test scope so reuse cannot create order dependence or hidden coupling.
• Test concurrency is benchmark-tuned rather than fixed permanently; the four-worker experiment remains evidence, and determinism and state isolation hold at every supported concurrency level.
• Local and CI execute the same suite behavior contract; caching accelerates unchanged work without changing coverage or results, and behavior-affecting environment inputs are explicit in tests and task hashes rather than implicit CI branches.
• Every behavior-owning workspace participates in the comprehensive suite with high-signal public-seam proof; a workspace with no testable behavior may declare reason_not_testable instead of adding placeholder tests, while still running appropriate typecheck, lint, or build validation.
• hi init, hi check, and hi update consume one shared desired-state compiler; hi init applies the plan, hi check compares it, and hi update reconciles it through separate observation, diffing, and application stages, with filesystem effects and conflict handling outside domain planning.
• The desired-state compiler is pure and deterministic over explicit context plan, project-settings snapshot, baseline/catalog data, and harness-capability inputs; discovery, filesystem reads, environment access, and process execution stay outside, and identical inputs yield the same plan across hi init, hi check, and hi update.
• The managed manifest is an application receipt for the last successfully applied managed state and provenance, never desired-state authority; reconciliation compares desired plan, observed repository state, and prior receipt to distinguish unchanged output, user modification, stale ownership, and safe removal.
• Package and structured-config changes are semantic field-level mutations rather than whole-file replacements; ownership is tracked per managed dependency or key so reconciliation updates managed entries deterministically while preserving unrelated user fields and dependencies.
• Reconciliation is non-destructive by default: automatically update only managed state unchanged since the prior receipt, preserve and report divergent user-modified files or keys for explicit operator resolution, and continue unrelated safe changes.
• Mixed safe/conflict reconciliation completes independent safe actions, emits a typed outcome for every action, advances the receipt only for successful changes, and leaves skipped, failed, or conflicting actions unresolved and unrecorded as applied so retries remain deterministic and truthful.
• Every harness adapter exposes an explicit capability contract; unrepresentable contributions return typed unsupported-capability diagnostics, with no silent omission or undocumented fallback, making prompt, hook, subagent, tool, and skill gaps visible and testable.
• Known unsupported harness capabilities are non-blocking typed warnings scoped to the affected harness and contribution; supported projections continue, the CLI and agent report explicit degraded/partial outcomes and exact omissions, and the receipt records degradation. Genuine adapter bugs, invalid projections, and application/write failures remain errors.
• Harness capability contracts describe neutral skill-installation, scoped-prompt, subagent-template, lifecycle-hook, and tool-configuration behaviors; harness-specific paths, filenames, schemas, and link strategies stay inside adapters, and the context model does not encode current filesystem layout.
• Neutral authored contributions remain canonical; every harness-specific file, symlink, mirror, or config entry is a managed, fully reproducible projection that never becomes independent authority, remains traceable to canonical contribution identity, and is safe to recreate, reconcile, or remove.
• Each harness adapter publishes a versioned capability matrix and runs the same projection contract tests across supported, degraded, and unsupported cases; capability changes are explicit compatibility changes so baselines and the CLI can explain new support or degradation.
• .devpunks/settings.json separates user choices, CLI-calculated required tools, and CLI-managed CLI/baseline versions; each field has one writer, every operation preserves fields it does not own, and hi update cannot replace the user's GitHub or Linear choice.
• Older settings preserve user choices and convert old or missing values only when safe and unambiguous; hi check reports a needed upgrade without rewriting, while hi init, hi scaffold, hi ensure, and hi update may save it with intended changes, and unsafe conversions fail clearly without guessing or discarding values.
• Every command uses one shared settings component to read, validate, upgrade, and save .devpunks/settings.json; command modules never read or write it directly, receive current valid settings, and request only allowed changes under the accepted ownership and old-file rules.
• hi init replaces the old scaffold init; hi scaffold replaces the old scaffold setup without changing that role. hi init creates initial settings and version records, hi ensure changes user choices and recalculates tools only, hi check never writes, and hi update preserves choices while recalculating tools, updating version records, and reconciling the managed scaffold.
• Before refactoring, classify every externally visible output as byte-for-byte locked, semantically equivalent, or intentionally changed by an accepted requirement and add a characterization fixture/test at its public seam. Managed scaffold assets and public JSON default to byte-locked, context plans use semantic equality, and terminal UI/renamed commands are intentional changes.
• The grill is requirements-only. No implementation, prototype, planning/delivery transition, or code refactor begins until the grill is fully finished and the user explicitly routes onward.
• The final migration ships only the new Effect v4 architecture and removes the old architecture and compatibility shims in the same change. No production dual path or feature flag and no temporary scaffolding may ship; rollback reverts or redeploys the prior known-good commit/release.
• Merge/release is blocked until the comprehensive suite; participating workspace typecheck/lint/build; output fixtures; zero v3 dependencies/imports/shims; packaged CLI command/help/JSON; API contract/handler; renderer catalog; operator lifecycle; and isolated fresh hi init/hi scaffold plus existing-repository hi check/hi update preservation proofs pass together. An unavailable gate is an explicit blocker, never a waiver.
• Migration is breadth-first through the architecture hierarchy: define deliberate public/root modules and dependency direction for every major domain, then establish each next level across peer domains toward leaf implementations. Do not complete packs before starting context and peers. One unmerged, undeployed branch may be broken; old paths may be replaced directly with no live dual path, shim, flag, or staged deployment. Q55/Q57 protect final correctness, and only the fully gated branch may merge.
• Exact v4 APIs are resolved under the implementation-start pinning rule; exact class, symbol, file, and per-domain error-catalog names are implementation tuning under the accepted domain rules. Concrete domain inventory and shared-package ownership are downstream implementation inventory and ownership mapping under Q34/Q58.

Pinned Axioms

These accepted architecture decisions remain inputs unless this grill explicitly reopens them:

• The CLI owns local repository scanning, interactive setup, filesystem writes, local cache/client behavior, diff/update UX, and operator ergonomics.
• Every command or application operation returns one structured presentation-neutral result before rendering. Interactive, plain non-TTY, and JSON modes consume that same result; prompts are inputs, stopping failures remain typed until the boundary, and domain/application code owns no formatted terminal output or exit-code policy.
• CLI output mode is chosen once at the root. Interactive mode may be rich; plain non-TTY mode is deterministic and free of styling, animation, and prompts; JSON mode is always non-interactive and emits exactly one clean document, including structured expected failures with nonzero status. Stderr diagnostics never corrupt JSON stdout, missing input becomes a typed error, and renderers make no domain decisions.
• Each command has one presentation/discovery metadata declaration beside its Effect definition. Root help, listings, examples, and generated CLI reference/styleguide views derive from it; duplicate handwritten command lists are forbidden, and metadata does not own domain behavior.
• One shared human renderer maps structured semantic facts to HI-native presentation under the selected interactive/plain policy. Commands own no terminal layout or prose, JSON bypasses the renderer, and a separate prompt interaction service owns keyboard/raw-terminal lifecycle while sharing semantic theme/glyph rules. Renderer primitives are introduced only for real flows, not as a generic widget framework.
• The large gradient HI title is root/help-only, with an optional explicit welcome/onboarding use. Ordinary subcommands use compact or no headings, and plain non-TTY/JSON never render the title; hierarchy policy preserves rather than removes HI identity.
• A developer-only catalog exercises the production renderer with deterministic fake results across semantic states, layouts, prompt frames, themes, NO_COLOR, and narrow widths. Its dependency direction is one-way into production primitives; production never imports or ships it, and it never becomes a second renderer.
• The API is the authority/control plane for registry, versions, channels, compatibility, provenance, and shared service behavior.
• Versioned baselines remain the practical distribution artifact. Q54 requires no offline fallback; only an already-working verified cache or bundled path may remain when cheap and safe.
• Baseline resolution produces one source-neutral verified record with requested and exact resolved identity, digest, provenance, compatibility, and retrieval status. Authority/version/fallback policy belongs to the baseline feature; source adapters only fetch and verify bytes/metadata and never substitute versions.
• The control-plane API alone authoritatively resolves moving channels. stable is always the newest published baseline and no newer non-stable baseline exists; retrieval sources must match the returned version/digest/compatibility, disagreement is a typed control-plane defect, and explicit immutable requests remain exact.
• API unavailability requires only a typed actionable failure by default. No new offline fallback must be built; existing verified cache/bundled behavior may survive as implementation detail when cheap and safe, but never silently downgrades or changes stable authority.
• Operator-skill commands inspect and mutate operator installation state only; they do not trigger project scaffold follow-through. Executable upgrade remains a separate lifecycle.
• The shared Devpunks skills repository is the hi-cli source of truth, but installs and updates use an immutable released version or commit selected through explicit CLI compatibility metadata. Status exposes version/source/revision/compatibility, update installs the compatible target, and the same target resolves reproducibly.
• Operator install ensures the global default, while a project-local hi-cli explicitly overrides it only in that project. Status resolves effective and shadowed copies for current directory and active agent; update targets every detected scope; detection/list failures remain failures rather than absence.
• Operator mutations are verified by re-inspection of expected version, source, revision, and active-agent binding. Independent scope successes are preserved, failures are typed with exact retries, legacy removal waits for verified compatible replacements, and every successful write produces reload/reactivate guidance even under partial failure.
• A typed feature-owned operator boundary owns lifecycle policy, while one Skills CLI integration adapter owns command/JSON/timeout/agent/subprocess mechanics. Missing or broken tooling is a typed failure, silent filesystem fallback is forbidden, and tests substitute a deterministic Layer.
• The context plan/compiler owns skill contribution metadata, closure, and compatibility; SKILL.md owns workflow semantics, which pack rules and the compiler do not duplicate or interpret.
• The context plan is a neutral per-repository-scope semantic result; scaffold plans and harness adapters own filesystem and harness materialization.
• Context-plan behavior is preserved when repository scopes, packs, resolved contributions, provenance, and meaningful ordering are semantically equal; generated bytes and prose remain downstream concerns.
• Tests run as one comprehensive repository suite. Domain logic stays real by default; broader behavior and decision matrices use deterministic Effect Layer implementations, and each adapter family has one focused real-adapter contract suite proving both implementations honor the same boundary contract.
• Every test-optimization slice includes repeatable, comparable before-and-after forced-uncached measurements, and regressions are investigated. Measurements remain evidence, not a release or pass threshold; the suite has no fixed performance target, time budget, or deadline.
• Shared Effect test Layers are immutable or read-only by default. Expensive immutable construction may be shared; mutable filesystem, repository, clock, process, and request state is created fresh per test scope, preventing order dependence and hidden coupling.
• Test concurrency is a benchmark-tuned implementation setting, not a permanently fixed worker count. Determinism and state isolation hold at every supported concurrency level.
• Local and CI execute the same suite behavior contract. Caching is acceleration only and cannot change coverage or results; behavior-affecting environment inputs are modeled explicitly in tests and task hashes, not implicit CI branches.
• Every behavior-owning workspace participates in the comprehensive repository gate with high-signal public-seam proof. A workspace with no testable behavior may carry reason_not_testable instead of placeholder tests and remains subject to appropriate typecheck, lint, or build validation.
• hi init, hi check, and hi update consume one shared desired-state compiler. Observation, diffing, and application are separate stages; filesystem effects and conflict handling stay outside domain planning.
• The desired-state compiler is pure and deterministic over explicit context plan, project-settings snapshot, baseline/catalog data, and harness-capability inputs. Repository discovery and I/O stay outside; identical inputs yield the same scaffold plan across hi init, hi check, and hi update.
• The managed manifest is an application receipt for the last successfully applied managed state and provenance, never a source of desired state. Reconciliation compares desired plan, observed repository state, and prior receipt to classify unchanged managed output, user modification, stale ownership, and safe removal.
• 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.
• Reconciliation is non-destructive by default. Only managed state unchanged since the prior receipt is applied automatically; divergent user-modified files or keys are preserved and reported for explicit operator resolution without inherently blocking unrelated safe changes.
• Mixed safe/conflict reconciliation completes independent safe actions and emits typed per-action outcomes. The managed receipt advances only for successful changes; skipped, failed, and conflicting actions remain unresolved and unrecorded as applied, keeping retries deterministic and truthful.
• Every harness adapter exposes an explicit capability contract. Contributions that cannot be represented return typed unsupported-capability diagnostics; silent omission and undocumented fallback are forbidden, and capability gaps for prompts, hooks, subagents, tools, and skills remain visible and testable.
• Known unsupported harness capabilities produce non-blocking typed warnings scoped to the affected harness and contribution. Supported projections continue; explicit degraded/partial outcomes and receipts identify every omission. Genuine adapter bugs, invalid projections, and application or write failures remain errors for affected actions.
• Harness capability contracts describe neutral semantic behaviors for skill installation, scoped prompts, subagent templates, lifecycle hooks, and tool configuration. Harness-specific paths, filenames, schemas, and link strategies remain adapter projection details; the context model does not encode current filesystem layout.
• Neutral authored contributions are the canonical source. Every harness-specific file, symlink, mirror, or config entry is a managed, fully reproducible projection that remains traceable to canonical contribution identity and safe to recreate, reconcile, or remove; projections never become independent sources of truth.
• Each harness adapter publishes a versioned capability matrix. Shared projection contract tests cover supported, degraded, and unsupported cases across adapters; capability changes are explicit compatibility changes that baselines and the CLI can explain.
• .devpunks/settings.json has three ownership classes: user choices for provider/backlog destination, CLI-calculated required tools, and CLI-managed CLI/baseline versions. Each field has one writer, and every operation preserves fields it does not own.
• Older settings preserve user choices and upgrade only through safe, unambiguous conversion. hi check reports but never rewrites; hi init, hi scaffold, hi ensure, and hi update may save the upgraded shape with intended changes, while unsafe or ambiguous conversions fail clearly without guessing or discarding values.
• Every command uses one shared component to read, validate, upgrade, and save .devpunks/settings.json. Command modules do not access the JSON file directly; they receive current valid settings and request only allowed changes, with ownership and old-file rules applied consistently.
• hi init replaces the old scaffold init, and hi scaffold replaces the old scaffold setup without changing that role. hi ensure changes user choices and recalculates tools only; hi check is read-only; hi update preserves user choices while recalculating tools, updating version records, and reconciling managed scaffold state.
• Every public output is classified before refactor as byte-locked, semantically equivalent, or intentionally changed, then characterized at its public seam. Scaffold assets and public JSON default to byte-locking; context plans use semantic equality; accepted terminal/command changes are intentional.
• Requirements artifacts are the only edits during the grill. Implementation, prototype, planning/delivery transition, and code refactor require a finished grill plus explicit user routing.
• The final change contains only the v4 architecture; old architecture, compatibility shims, production dual paths/flags, and temporary migration scaffolding are absent. Rollback uses the prior known-good commit or release.
• The coordinated merge/release gate combines repository tests, participating workspace validation, output fixtures, zero-v3 proof, packaged CLI/API/renderer/operator checks, and isolated fresh/existing consumer proof. Every required gate must run and pass; unavailable gates block explicitly.
• Migration works breadth-first across architecture levels on one unmerged and undeployed branch. Intermediate states need not run or preserve the old architecture; there is no staged deployment, compatibility shim, dual runtime, or feature flag. Q55 characterization and Q57 gates constrain the final merge, not intermediate deployability; rollback remains the prior known-good release.
• All Effect-dependent workspaces upgrade to Effect v4 and refactor to the intended v4 architecture in one coordinated, repository-green change. Compile-first, refactor-later sequencing, v3/v4 translation layers, and deferred architecture cleanup are rejected.
• effect-smol and the OpenCode and T3 Code repositories are required v4 pattern references resolved through opensrc; exact module, service, error, layer, config, adapter, and runtime names are downstream implementation tuning under the accepted architecture.
• The numeric Effect v4 beta is selected at implementation start as the latest published beta with matching compatible @effect/* packages, then pinned exactly in the shared catalog and lockfile across all Effect-dependent workspaces. Caret/range versions and automatic beta chasing are forbidden; later upgrades require a deliberate repository-wide decision.
• Every expected domain or operational failure is a schema-backed typed error in Effect<A, E, R>. Callers handle it explicitly or intentionally propagate it; domain code never swallows it, converts it to a defect, hides it as unknown, reduces it to an untyped string, or handles it through printing, exit codes, or HTTP. Boundaries translate expected errors, while unexpected programmer defects remain outside the expected-error channel.
• Integration and system adapters normalize expected raw library or system failures at their boundary into small stable typed Effect error sets. Those errors preserve the original cause and useful operation-specific context; unexpected defects remain defects, and a universal catch-all error is forbidden.
• Runtime configuration is read and schema-validated only at platform/config setup and provided by application roots as typed services or Layers. Features, commands, and integrations never access process.env; tests supply explicit configuration; config failures remain typed and secrets redacted. Contract and scaffold packages remain config-free and accept explicit options.
• packages/env contains only reusable Effect v4 config decoders, schema fragments, and provider-building primitives, never global application config. Focused typed config services and Layers belong to their application or domain, app-local config remains local, and only genuinely cross-root decoders move into the package; roots compose them and tests inject parsed services or focused providers.
• Each hi invocation composes production dependencies and runs the Effect application only at the top-level executable entrypoint. Feature modules may export production setup; commands and domain modules do not create runtimes or choose real implementations, and commands only read, call, and render. This boundary implies neither a daemon nor shared mutable global state nor one giant wiring file.
• Applicable Effect and backend roots use domain-first platform/, integrations/, and features/<domain>/ boundaries. A coherent shared-domain package may itself be the domain root. Features own behavior, ports, models, errors, Layers, tests, private helpers, and deliberate public roots; other features never import their internals.
• Actions own workflows and policy; services are reusable mechanics only; repositories and adapters hide persistence; transport stays thin; root platform composition combines feature and integration Layers. Generic root buckets and compatibility aliases are forbidden.
• Architecture guidance from the named skills is accepted, but v3 spellings such as Effect.Service do not override the selected Effect v4 source/version; exact service APIs follow the pinned v4 release and current source research.
• packages/contract owns cross-process shared data schemas, public typed errors, and HTTP endpoint definitions only. Request runtimes, auth, retries, handlers, persistence, scaffold/harness policy, CLI decisions, and backoffice behavior stay with their owning applications and domains; makeHarnessClient must stop providing FetchHttpClient.layer.
• packages/contract exposes separate baseline, telemetry, reports, and backoffice public protocol submodules. Consumers import only their protocol area; genuinely cross-protocol primitives may use one small explicit common submodule. No broad cross-domain root barrel or stale compatibility re-exports survive the coordinated migration unless external compatibility is later required explicitly.

Grill State

• Every dashboard branch is 100%, all branches are closed, and the final readonly consistency review has passed.
• There is no further grill question.
• This is not authorization to implement, prototype, plan, or enter delivery. Q55 still requires explicit user routing onward.
• Concrete module/domain inventories, characterization fixtures, and work breakdown are downstream artifacts under the accepted rules, not unresolved requirements in this grill.

Glossary

Terms

• Pack: the project-level context selection unit selected or detected by the CLI; it drives the context-plan and scaffold lifecycle.
• Capability group: a reusable grouping of skills used to compose a subagent template. Avoid: capability pack and unqualified pack for subagent-template groupings.
• Context plan: a neutral per-repository-scope semantic result containing repository scope identifiers and resolved contribution intent, but no target files, symlinks, hashes, package mutations, or write actions.
• Scaffold plan: a desired-state description of files, links, package/config mutations, managed ownership, and metadata used to materialize a context plan locally.
• Harness adapter: a boundary that maps neutral contribution intent into one supported harness's configuration and filesystem surfaces.
• Managed reconciliation: comparison and application of expected managed state against recorded manifests and current repository state while preserving explicitly user-owned state.
• Project settings: .devpunks/settings.json, containing user-owned provider/backlog choices, CLI-calculated required tools, and CLI-managed CLI/baseline versions, with one writer per field.
• Operator skill: the independently installed hi-cli instruction set used by an agent operating the executable; it is outside project pack and scaffold state.

Relationships

• A subagent template composes one or more Capability groups and does not directly consume project Packs.
• Scaffold plans and Harness adapters materialize a Context plan into filesystem and harness-specific state.