devrites 3.2.28 → 4.0.0

package/docs/adr/0014-native-host-hook-boundary.md

@@ -0,0 +1,64 @@
+# ADR-0014: Native host capability boundary
+
+- **Status:** Superseded by 0015
+- **Date:** 2026-07-29
+
+## Context
+
+DevRites accumulated Go hooks for agent permissions and lifecycle, session
+orientation, status presentation, compaction handoffs, test-output sentinels,
+web caching and content scanning, and background code-index refresh. Current
+Claude Code and Codex releases already own those static or host-specific
+surfaces. Keeping a second implementation increased latency, configuration,
+tests, and drift without strengthening the workflow.
+
+Some DevRites policies are different: they depend on live workspace state or
+one exact operation and cannot be represented by a static host permission
+profile.
+
+## Decision
+
+Use native host behavior first. The engine exposes only four hooks:
+
+- `git-guard` for exact, one-shot destructive Git authority;
+- `a1-guard` for dynamic root-versus-writer ownership;
+- `stop-gate` for canonical rest-point invariants; and
+- `wright-scope` for the slice-wright's per-run exact path allowlist, Forge
+  binding, and reconcile boundary.
+
+Claude read-only agents use native `permissionMode: plan`; Codex read-only
+agents use native `sandbox_mode = "read-only"`. Both hosts own named-agent
+lifecycle, transcript/session and compaction context, presentation, browsing
+and cache behavior, and connected index lifecycle.
+
+The slice-wright's first actionable `wright-scope` call captures its canonical
+reconcile boundary. Capture is idempotent, so later tool calls cannot move that
+boundary forward. No separate SubagentStart hook is required.
+
+Proof remains explicit in workspace evidence and real command output. The
+engine does not infer authority from a regex-based `.red` sentinel.
+
+This record supersedes ADR-0003's `.red` StopGate clause, narrows ADR-0005 to
+the four retained dynamic hooks, and replaces ADR-0013's wright-only start hook.
+The rest of those decisions remains in force.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep every hook for identical Claude/Codex behavior | It duplicates host features and makes DevRites responsible for unstable presentation and lifecycle APIs. |
+| Remove every engine hook | Static host permissions cannot express one-shot Git authority or a per-run `.wright-allowlist`. |
+| Keep a separate wright start hook | The existing PreToolUse scope hook can capture the same boundary safely when capture is idempotent. |
+| Keep `.red` as a test oracle | Output regexes create stale and false-positive state; explicit proof artifacts and actual command results are authoritative. |
+
+## Consequences
+
+- Project hook configuration shrinks to three hooks; only the writer profile
+  adds `wright-scope`.
+- Reviewer permissions have one owner per host.
+- The engine no longer owns lifecycle telemetry, UI/status output, web caches,
+  ingestion heuristics, or index workers.
+- Connected index providers may be refreshed explicitly when stale; absence of
+  one never blocks work.
+- Dynamic security checks remain engine-tested and fail closed where static
+  host policy is insufficient.

package/docs/adr/0015-read-only-root-native-orchestration.md

@@ -0,0 +1,96 @@
+# ADR-0015: Read-only root with native host orchestration
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+ADR-0014 retained four engine hooks after an initial native-host cleanup. Three
+of them still duplicated boundaries the hosts can enforce directly:
+
+- `a1-guard` inferred root-versus-writer ownership from hook payloads;
+- `git-guard` implemented a second destructive-action permission system; and
+- `stop-gate` rechecked lifecycle state when the host stopped.
+
+The engine also retained orchestration and convenience surfaces that Codex,
+Claude, native plugins, repository search, or CI already provide. This made
+DevRites implement the same work twice and coupled it to host event formats.
+
+Current hosts can load hierarchical instructions and exact named agent
+profiles, apply native permission modes per root/agent, schedule and await
+subagents, retain session history, and expose skills/plugins/search directly.
+
+## Decision
+
+DevRites uses this boundary:
+
+```text
+AGENTS.md / skills
+        ↓
+Codex or Claude interprets the workflow
+        ↓
+the host runs the exact native custom-agent profile
+        ↓
+the host waits and delivers results
+        ↓
+the root reconciles; the engine validates state/evidence/invariants
+```
+
+The root orchestration context is source-read-only. It may invoke the explicit
+DevRites commands that update `.devrites/**` and `.scratch/**`. Every specialist
+is read-only except `devrites-slice-wright`, which receives native source-write
+permission for one bounded task.
+
+- Claude uses project `permissions.defaultMode: plan`; the slice-wright profile
+  uses `permissionMode: acceptEdits`.
+- Codex uses a read-only project profile with state/artifact path overrides;
+  the slice-wright profile uses `sandbox_mode = "workspace-write"`.
+- User-authorized commit, push, tag, publish, deploy, and migration actions use
+  the host's normal explicit approval boundary. The engine does not implement a
+  second Git authority system.
+
+`wright-scope` is the only engine hook. It enforces the root-owned exact
+`.wright-allowlist`; `reconcile` separately validates the resulting source
+window. Both remain until universal per-agent worktree isolation can replace
+them.
+
+The engine owns deterministic workflow state, evidence freshness/integrity,
+artifact completeness, exact write reconciliation, and secret scanning. It
+does not own:
+
+- agent dispatch, waiting, result collection, or scheduling;
+- tool-call fields, file-backed agent envelopes, rollout parsing, or dispatch
+  receipts;
+- profile/context caches, archive/decision indexes, lane planners, or runbooks;
+- progress rendering, preambles, session telemetry, health/reviewer scores, or
+  fingerprints;
+- guessed repository commands, index refresh wrappers, learning/convention
+  scoring, or extension registries.
+
+Lifecycle rest points call explicit readiness/seal checks instead of relying on
+a Stop hook. Repository scripts and CI remain the authority for build, test,
+lint, and release commands.
+
+This ADR supersedes ADR-0014, the hook-runtime portions of ADR-0005, the custom
+packet/result portions of ADR-0010 and ADR-0013, and ADR-0003's historical
+StopGate clause. Their historical context remains unchanged.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep `git-guard`, `a1-guard`, and `stop-gate` as defense in depth | They duplicate native permission/lifecycle boundaries and preserve hook-format coupling. |
+| Keep agent packets and receipts without engine dispatch | They add a second identity/lifecycle protocol without an enforcing consumer. |
+| Remove `wright-scope` now | Native per-agent sandboxes do not yet express the dynamic per-slice exact file allowlist in every supported host/worktree mode. |
+| Let the root write source for small fixes | It collapses the single-writer boundary and makes A1-style inference necessary again. |
+
+## Consequences
+
+- Host configuration and agent profiles become the permission source of truth.
+- The engine hook surface shrinks to `wright-scope`.
+- Skills state semantic intent once and let the host construct native calls.
+- Engine and shell tests assert observable permissions/invariants rather than
+  host-internal event spelling.
+- Shipping and other irreversible actions require normal host/user approval.
+- Universal isolated agent worktrees are the deletion condition for
+  `wright-scope`.

package/docs/adr/0016-codex-writer-fail-closed.md

@@ -0,0 +1,53 @@
+# ADR-0016: Codex source writing fails closed
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+ADR-0013 and ADR-0015 assumed a Codex custom child could become the sole
+write-capable slice-wright under a source-read-only root and that a child
+`PreToolUse` hook could enforce the dynamic exact file allowlist.
+
+Live Codex 0.146.0 probes disproved both assumptions. A child inherits the
+parent turn's active sandbox and permission overrides; agent defaults such as
+`:workspace` or `workspace-write` cannot elevate it. Project and agent-local
+hooks also did not observe the tested child shell calls. Keeping the old profile
+would therefore either block all source work or claim an enforcement boundary
+that did not run.
+
+## Decision
+
+The root remains source-read-only on every host.
+
+- Claude may run the exact `devrites-slice-wright` with native edit permission
+  and the retained `wright-scope` exact-allowlist hook.
+- Every generated Codex specialist, including `devrites-slice-wright`, is
+  hook-free and `:read-only`. A Codex workflow that needs source changes stops
+  for HITL or an approved writing-host handoff.
+- DevRites never relaxes the Codex root, accepts a self-declared writer role,
+  substitutes a generic child, or restores an engine dispatch bridge.
+- Because Claude is the only shipped hook consumer, the command is simply
+  `devrites-engine hook wright-scope`; there is no runtime harness selector.
+
+This decision supersedes only the Codex writer-permission and writer-hook
+clauses of ADR-0013 and ADR-0015. Their native orchestration, read-only root,
+and engine-boundary decisions remain accepted.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Relax the Codex root to workspace-write | It removes the hard root boundary and lets orchestration write source inline. |
+| Keep the Codex writer hook as best effort | Live child calls bypassed it, so the claimed exact scope was false. |
+| Restore engine-owned dispatch | Codex already owns native role selection, waiting, and result delivery; a bridge duplicates the host protocol. |
+| Let the model follow an allowlist instruction without enforcement | A security boundary cannot depend on voluntary compliance. |
+
+## Consequences
+
+- Codex review/research orchestration remains native and fully read-only.
+- Codex build/correction phases pause instead of silently weakening isolation.
+- Claude keeps the only engine hook until a supported native isolated writer
+  can express the same dynamic exact-file boundary.
+- Generation and runtime tests assert observable permissions and fail-closed
+  behavior, not tool-call spelling or dispatch receipts.

package/docs/adr/0017-native-codex-writer-agent.md

@@ -0,0 +1,63 @@
+# ADR-0017: Native Codex writer-agent execution
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+ADR-0016 made every Codex role read-only after live Codex 0.146.0 probes showed
+that a child cannot elevate above its parent's active permission ceiling and
+that child-local hooks did not reliably observe writer tool calls. That choice
+preserved a hard read-only root, but it also prevented
+`devrites-slice-wright` from executing its defined implementation role.
+
+DevRites requires every catalog agent to remain installed and to execute when
+its workflow step names it. Restoring an engine-owned dispatch bridge would
+duplicate Codex's native spawn, wait, follow-up, and result-delivery lifecycle.
+
+## Decision
+
+Codex uses native custom-agent execution for every DevRites role:
+
+- the root `devrites-orchestrator` permission profile extends `:workspace` so a
+  write-capable child can run;
+- only `devrites-slice-wright` uses
+  `default_permissions = ":workspace"`;
+- every other generated specialist uses
+  `default_permissions = ":read-only"`;
+- all generated Codex agents remain hook-free;
+- the root never edits source or tests; it dispatches the exact wright in a
+  fresh context, waits, and reconciles the result;
+- the root writes the exact `.wright-allowlist`, runs
+  `devrites-engine reconcile snapshot` before dispatch, and runs
+  `reconcile check` and `reconcile close` afterward;
+- missing required roles, unauthorized drift, or an unavailable permission
+  profile stop the workflow. They never permit role substitution, inline root
+  implementation, allowlist widening, or an engine dispatch bridge.
+
+Claude's boundary is unchanged: its root remains in plan mode and the exact
+slice-wright retains `permissionMode: acceptEdits` plus the `wright-scope`
+pre-tool hook.
+
+This ADR supersedes ADR-0016 and the Codex read-only-root clauses of ADR-0015.
+Their live-probe findings and the native-host orchestration boundary remain
+valid.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep Codex source-writing disabled | It leaves `devrites-slice-wright` installed but unable to execute its required role. |
+| Let the Codex root implement directly | It bypasses the exact writer role and collapses workflow separation. |
+| Restore engine-owned dispatch | Codex already owns agent creation, scheduling, waiting, and result delivery. |
+| Re-enable the Codex child hook | Live probes showed that it was not a dependable enforcement surface. |
+
+## Consequences
+
+- Every DevRites role can execute natively on Codex.
+- The Codex root's no-source-writing boundary is instruction-enforced rather
+  than enforced by a narrower sandbox.
+- Codex exact-path enforcement is detect-and-stop through reconciliation, not
+  a pre-write hook. Claude retains pre-write exact-path enforcement.
+- The engine remains responsible for deterministic state, evidence, integrity,
+  and reconciliation, not agent dispatch.

package/docs/adr/0018-native-sandbox-instruction-writer-boundary.md

@@ -0,0 +1,66 @@
+# ADR-0018: Native sandbox and instruction writer boundary
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+DevRites kept a Claude `wright-scope` hook, a Git-backed `reconcile` window,
+and a snapshot-dependent `test-integrity` command to enforce one writer and an
+exact per-slice path list. Native Claude and Codex profiles now enforce the
+broader writer/read-only split directly. The remaining Go machinery duplicated
+host policy, coupled builds to hook payloads and private Git snapshots, and
+made ordinary corrections depend on an engine-owned source window.
+
+Neither host provides a universal dynamic exact-file sandbox for a child. The
+choice is therefore between retaining the second enforcement system or
+accepting native sandboxing plus explicit task and diff-review instructions.
+
+## Decision
+
+DevRites accepts native host sandboxing plus instructions:
+
+- the root never edits source or tests;
+- only `devrites-slice-wright` is writable: Claude grants it `acceptEdits` and
+  Codex grants it `:workspace`; the other 16 specialists remain read-only;
+- the dispatch task states the smallest exact project-relative source/test
+  paths, and the wright must not widen them;
+- the root waits, compares the returned file list and `git diff --name-only`
+  with the task contract, rejects any extra path, runs repository proof, reviews
+  the test diff, and records exact touched files;
+- test deletion, skipping, focusing, and weakened assertions remain prohibited
+  behavior and are checked through normal tests, diff review, and dedicated
+  test analysis;
+- the engine no longer exposes `hook`, `reconcile`, or `test-integrity`;
+- installation retains recognition and removal of legacy DevRites hooks so an
+  upgrade cleans stale host configuration, but installs no active writer hook.
+
+There is no compatibility command or replacement enforcement layer.
+
+This ADR supersedes only the active engine-hook clause of ADR-0005, the
+`wright-scope`/exact-allowlist/reconciliation clauses of ADR-0015, and the
+exact-path reconciliation clauses of ADR-0017. Their other decisions and
+historical context remain in force.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep `wright-scope` and `reconcile` as defense in depth | They preserve a second host-policy system, private Git snapshot state, and hook-format coupling. |
+| Rebuild test-integrity without reconciliation | It would recreate baseline machinery solely to inspect tests; normal proof, diff review, and the test analyst already own that behavior. |
+| Let the root write small changes | It collapses the sole-writer role and makes the native permission split misleading. |
+| Add another compatibility command | It retains the obsolete public surface without an operational owner. |
+
+## Consequences
+
+- Exact-path scope is honestly instruction-backed on both hosts, not hard
+  technical enforcement.
+- Native permissions still ensure only the wright is broadly writable and all
+  other specialists remain read-only.
+- Root diff inspection and test analysis are required acceptance steps rather
+  than optional commentary.
+- The engine becomes smaller and no longer owns source-window Git snapshots or
+  hook payload parsing.
+- `tests/phase-gate-routing-test.sh`,
+  `tests/codex-agent-generation-test.sh`, `tests/hooks-parity-test.sh`, and
+  focused installer tests guard the retained workflow and permission boundary.

package/docs/adr/0019-native-boundary-with-deterministic-gates.md

@@ -0,0 +1,48 @@
+# ADR-0019: Native boundary with deterministic gates
+
+- **Status:** Accepted
+- **Date:** 2026-07-30
+
+## Context
+
+ADR-0018 replaced engine hook and reconcile enforcement with native host
+permissions plus exact-path instructions. That simplification must not remove
+independent quality gates, lifecycle rest points, or action-time approval. Its
+statement that `test-integrity` was removed became obsolete when a
+reconcile-free, committed-HEAD comparison was restored.
+
+## Decision
+
+- Native permissions retain the writer boundary: the root and reviewers do not
+  edit source or tests; only `devrites-slice-wright` is writable, under an exact
+  path contract checked in the returned diff.
+- Deterministic gates remain independent of host hooks. Every successful
+  lifecycle advance runs `readiness <slug>` immediately before completion;
+  `/rite-seal` uses the final `seal <slug>` aggregate instead.
+- `test-integrity` compares the working tree with committed `HEAD` without
+  reconcile snapshots. The final seal retains acceptance, evidence freshness,
+  test integrity, review integrity, doubt coverage, and opted-in mutation gates.
+- Irreversible Git requires the exact commit/push/tag/PR plan and fresh literal
+  user approval for one attempt. Seal GO, AFK, and autocomplete flags are not
+  authority; changed or retried plans require fresh approval, and native host
+  permission/sandbox prompts remain authoritative.
+
+This supersedes only ADR-0018's statement that `test-integrity` is removed and
+its rejection of a reconcile-free test-integrity gate. ADR-0018's native
+permission, instruction-backed exact-path, hook-removal, and no-reconcile
+decisions remain in force.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Restore engine hooks or reconcile snapshots | Recreates host-policy duplication and snapshot machinery. |
+| Rely on instructions alone for quality and completion | Removes deterministic evidence independent of model behavior. |
+| Treat seal GO or `--ship` as Git authority | Conflates quality approval with fresh irreversible-action consent. |
+
+## Consequences
+
+The engine remains free of hook dispatch, writer-path classifiers, and
+reconcile state. Native profiles and exact instructions own execution scope;
+readiness, final seal, test integrity, and fresh action-time approval preserve
+the unrelated safety and quality guarantees.

package/docs/adr/0020-thin-engine-native-orchestration-boundary.md

@@ -0,0 +1,54 @@
+# ADR-0020: Thin engine and native host orchestration
+
+- **Status:** Accepted
+- **Date:** 2026-07-31
+
+## Context
+
+DevRites already installs exact Claude and Codex specialist definitions. Adding
+Go dispatch versions, tiers, receipts, polling, or fallbacks would mirror host
+internals, drift when a host changes, and turn workflow depth into a second
+protocol. The engine also accumulated repository-only and presentation commands
+that did not need a cross-host runtime primitive.
+
+## Decision
+
+- Skills name the exact generated `devrites-*` role and a bounded task. Claude
+  or Codex owns discovery, dispatch, scheduling, waiting, follow-up, result
+  delivery, and compatibility with its own agent protocol.
+- Quick, Standard, and Full select admission/evidence/review depth over one
+  lifecycle and artifact schema. They are not engine or agent API versions.
+- The Go engine is limited to deterministic cross-host runtime work: persisted
+  workspace state, readiness/acceptance/integrity gates, secret scanning,
+  bounded recovery, safe migration, and managed installation diagnostics.
+- Repository JSON/schema/generated parity/build/release validation stays in
+  repository scripts and CI. Installed skills use the engine and native host;
+  they never assume DevRites source-tree scripts exist in a consumer project.
+- `status`, `budget`, `mutation-gate`, standalone `review-integrity`, and
+  `validate-pack` are removed at the next major boundary with ordinary
+  unknown-command behavior and no tombstones. Snapshot replaces machine status;
+  reviewer accounts remain seal-internal; real mutation runners own mutation
+  proof; doctor owns installed-pack health.
+- Explicit versions remain only on persisted documents that need stable readers,
+  such as workspace snapshots and migration journals.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep a Go broker for Codex/Claude agents | Duplicates native APIs and creates V1/V2 compatibility work with no product value. |
+| Keep every legacy command as a wrapper | Preserves two authorities and makes help claim capabilities the engine does not own. |
+| Move deterministic state and safety into prompts | Loses machine-enforced, cross-host behavior and testable failure contracts. |
+
+## Consequences
+
+Host releases require native conformance tests rather than engine protocol
+changes. The engine surface is smaller and more stable. Repository maintainers
+and installed users have deliberately different validation surfaces, which must
+not be mixed in shipped skills.
+
+This narrows ADR-0001's broad control-plane scope and consolidates the native
+orchestration direction of ADR-0010, ADR-0013, and ADR-0019 without changing
+their retained deterministic safety gates. It supersedes ADR-0019's
+environment-driven opted-in mutation-gate clause; only evidence from a real
+repository mutation runner may support a mutation-testing claim.

package/docs/adr/0021-observable-workspace-compatibility.md

@@ -0,0 +1,49 @@
+# ADR-0021: Observable and reversible workspace compatibility
+
+- **Status:** Accepted
+- **Date:** 2026-07-31
+
+## Context
+
+Legacy workspace layouts, filenames, cursors, phase aliases, and older schemas
+must remain readable during the current support window. Silent compatibility
+cannot prove when removal is safe, while an automatic in-place rewrite can
+fabricate state, overwrite conflicting evidence, or leave a partial migration.
+
+## Decision
+
+- Runtime, validator, and migration share one active-workspace predicate:
+  `state.md` or a workspace map in active `work/` or compatible `features/`.
+  Archives, spec-only/empty directories, and operational remnants are ignored.
+- Normal successful legacy reads append a bounded mode-`0600` JSONL record with
+  only release, timestamp, category, slug, and canonical replacement. Pure
+  validation and migration reads emit no telemetry.
+- Compatibility is removed only by a later decision using records inside its
+  declared release/time window; this change does not guess a removal date or
+  build a future importer.
+- Bare `migrate` and `migrate preview` are read-only. The deterministic manifest
+  contains project-relative pre/post metadata and hashes, conflicts, ACTIVE
+  selection, and byte/path counts, never artifact bodies or absolute paths.
+- Apply requires an exact saved manifest, re-previews under one project lock,
+  and verifies a private journal plus backup/post recovery material before the
+  first target mutation. Rollback validates all material and touched path states
+  before restoration. Both operations are idempotent and resumable; recovery
+  material remains available.
+- Preview, apply, and rollback each have a separate fresh approval boundary.
+  Workflow mode, seal, AFK, or prior approval cannot imply mutation authority.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Rewrite every legacy directory automatically | Cannot distinguish remnants or conflicts and creates unreviewed destructive behavior. |
+| Keep compatibility forever without telemetry | Makes removal evidence impossible and retains permanent complexity. |
+| Record full legacy content for analysis | Leaks project data and is unnecessary for usage counts. |
+| Delete backups after success | Removes the verified recovery path before an operator accepts the result. |
+
+## Consequences
+
+Compatibility has a measurable cost and a deliberate later removal trigger.
+Migration is slower than an unchecked rename because it hashes, journals, and
+locks the whole transaction, but it preserves evidence and can recover from
+every recorded interruption boundary without guessing.

package/docs/adr/0022-native-orchestration-thin-engine.md

@@ -0,0 +1,90 @@
+# ADR-0022: Native orchestration with a thin deterministic engine
+
+- **Status:** Accepted
+- **Date:** 2026-07-31
+
+## Context
+
+Claude Code and Codex already load project skills and exact custom agents. They
+own agent discovery, dispatch, scheduling, waiting, follow-up, and result
+delivery. Re-implementing that protocol in Go adds a second authority and
+creates version, receipt, polling, and fallback machinery with no durable
+product state to protect.
+
+Semantic engine gates had the same problem. Heuristics that parsed readiness,
+traceability, acceptance, review prose, assertion counts, doubt accounts, or
+capability deltas duplicated judgments already made from fuller context by the
+active skill and exact reviewers. Repository test, build, lint, typecheck, and
+release validation likewise belong to the repository and CI.
+
+Release history also showed that the proposed compatibility surface was too
+broad. Released v1.0.0–v2.6.1 writers used
+`.devrites/work/<slug>/state.md` bullet cursors with `Phase`, `Next step`, and
+`qid`; v3 writers kept `work/<slug>/` and used the canonical map plus table
+cursor fields `phase`, `next_action`, and `question_id`. `.devrites/features`,
+alternate map/cursor/proof filenames, status-as-phase, and phase aliases were
+not official released writer outputs. Early v3 migration code could create
+extra copies, but it retained the canonical workspace and did not make those
+copies authoritative.
+
+Write-on-read local compatibility telemetry could not answer whether the global
+installed population still used a format. It also made an otherwise read-only
+operation mutate private project state. A journaled preview/apply/rollback
+migration system therefore preserved speculative formats while adding more
+risk and code than a small tolerant reader.
+
+## Decision
+
+- Claude Code and Codex own agent discovery, dispatch, scheduling, waiting,
+  follow-up, and result delivery. Installed skills and exact custom agents own
+  all semantic judgment: readiness, traceability, acceptance and evidence
+  quality, doubt, review reconciliation, test-quality assessment, capability
+  interpretation, semantic upgrade, and recovery routing.
+- The Go engine retains only deterministic cross-host primitives:
+  install/update/uninstall, `snapshot`, structural `check readiness`, structural
+  plus evidence-freshness `check seal`, grammar `check spec`, atomic
+  `state resolve|clarify|tick-afk|recovery|close`, `secret-scan`, `doctor`, and
+  `version`.
+- The engine has no agent bridge, semantic readiness V2 or digests, heuristic
+  prose parser, capability-ledger engine, compatibility telemetry, migration
+  command, or old command aliases/tombstones.
+- Runtime compatibility is a direct, non-mutating read of only the official
+  bullet and table `state.md` cursor forms described above. Semantic upgrades
+  are preservation-first native workflow edits, not structural engine
+  migrations.
+- Explicit schema versions remain where persisted readers need them. The
+  `devrites.workspace.v1` snapshot and current state schemas remain supported;
+  orchestration does not acquire a DevRites protocol version.
+- Native writer permissions and exact-path contracts remain in force.
+  Structural gates remain independent of the model. Seal GO, AFK, or an
+  autocomplete flag never authorizes an irreversible action: the exact current
+  commit/push/tag/PR plan still needs fresh user approval for that attempt.
+
+This ADR supersedes ADR-0019's semantic seal/test/reviewer/doubt gate clauses,
+ADR-0020's broader gate and safe-migration engine scope, and ADR-0021's
+telemetry plus preview/apply/rollback design. It retains their native
+orchestration, writer/permission, structural-gate, root-safety, and fresh
+irreversible-action approval rules.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep semantic Go gates as a second opinion | String and count heuristics see less context than the assigned native reviewers and create conflicting authorities. |
+| Keep the transaction migration platform for possible legacy layouts | Release evidence supports only two cursor encodings; a tolerant reader is smaller and non-mutating. |
+| Keep write-on-read telemetry until usage reaches zero | Local records cannot measure global usage and violate read-only expectations. |
+| Move deterministic state and secret safety into prompts | Atomicity, root containment, evidence freshness, and secret handling need testable cross-host enforcement. |
+| Retain old aliases for a transition | It preserves the oversized public surface and hides callers that must migrate. Unknown-command failure is explicit. |
+
+## Consequences
+
+The engine has one narrow, stable reason to exist: deterministic state and
+safety primitives shared by both hosts. Skills and exact agents can evolve
+semantic workflows without a Go protocol migration. Repository CI remains the
+source of observed engineering proof.
+
+Older official workspaces remain readable without a write, import step, or
+migration journal. Unsupported pre-release aliases fail visibly instead of
+silently becoming a permanent compatibility contract. Removing public commands
+is intentionally breaking; canonical skills and documentation must move in the
+same release.

package/docs/adr/0023-native-workspace-reads-line-output.md

@@ -0,0 +1,71 @@
+# ADR-0023: Native workspace reads and line-oriented engine output
+
+- **Status:** Accepted
+- **Date:** 2026-07-31
+
+## Context
+
+The installed skills and exact host agents already read the canonical workspace
+Markdown. The optional `snapshot` command rebuilt the same state into a
+`devrites.workspace.v1` document, added summary heuristics, and became a
+mandatory-looking preamble across workflows despite having no external consumer
+beyond repository smoke tests.
+
+The `devrites-command/v1` wrapper similarly converted ordinary check and doctor
+output into an agent-facing protocol. Its only repository consumer was the
+outcome harness. Stable gate reason IDs remain useful, but they do not require a
+versioned envelope. `doctor --verbose` produced exactly the normal doctor
+report, and recovery's ignored `--class` option preserved an obsolete command
+shape.
+
+Other remaining engine responsibilities have different properties. AFK slice
+and recovery-attempt limits are hard autonomy bounds, atomic state mutations
+protect multi-file consistency, and no established secret scanner is installed
+to replace the bounded scanner. The doctor is already a small deterministic
+root/install diagnostic. Moving those responsibilities into model judgment
+would weaken safety rather than simplify implementation.
+
+## Decision
+
+- Remove `snapshot`, its Go summary readers, `devrites.workspace.v1`, and its
+  JSON schema. Skills resolve an explicit slug or `.devrites/ACTIVE`, require
+  `.devrites/work/<slug>/state.md`, and read only the current phase artifacts.
+- Remove engine `--json` handling and the `devrites-command/v1` envelope.
+  Lifecycle checks emit line-oriented output with the existing stable
+  `reason: DRV-...` identifier; repository evals assert exit status and that
+  reason directly.
+- `doctor` accepts no inert `--verbose` alias. Recovery rejects the obsolete
+  `--class` option while continuing to tolerate unknown fields in already
+  persisted JSONL entries.
+- Retain `state tick-afk`, `state recovery`, the root/lock/atomic-write
+  boundary, structural checks, evidence freshness, secret scanning,
+  install/update/uninstall, doctor, and version.
+- Retain profile-selected and conditionally applicable native reviewers. No Go
+  broker, dispatch receipt, or agent protocol is introduced.
+- Removed commands and flags fail visibly; there are no compatibility aliases
+  or tombstones.
+
+This ADR supersedes ADR-0022's snapshot and JSON-output clauses. Its native
+orchestration, deterministic state/safety, released cursor compatibility, and
+fresh irreversible-action approval rules remain in force.
+
+## Alternatives considered
+
+| Option | Why not |
+|---|---|
+| Keep snapshot as an optional convenience | Workflow references made it functionally mandatory, while direct ledger reads are simpler and authoritative. |
+| Keep JSON for possible automation | No external consumer was established; a speculative protocol is not worth permanent compatibility cost. |
+| Move AFK/recovery limits into prose | That turns hard autonomy stops into best-effort model compliance. |
+| Remove the scanner and ask the model to inspect secrets | Secret handling is a trust-boundary control and no established deterministic replacement exists in the repository. |
+| Replace the retained Go helpers with skill scripts | It duplicates root containment, locking, and cross-platform install behavior without reducing concepts. |
+
+## Consequences
+
+The public CLI and installed allowlist are smaller. Skills and status reporting
+read the single authoritative ledger rather than a derived summary. Repository
+outcome tests no longer need an engine JSON decoder.
+
+Removing the two output schemas is intentionally breaking, but requires no data
+migration because neither schema is persisted workspace state. Released
+`state.md` cursor encodings remain readable. Deterministic autonomy and secret
+safety remain testable outside model judgment.