devrites 3.2.28 → 4.0.0

package/docs/markdown-instruction-upgrade-2026-08-02.md

@@ -0,0 +1,302 @@
+# Fresh reference study: Markdown instruction architecture
+
+- Date: 2026-08-02
+- Scope: DevRites Markdown instructions only
+- Decision status: adopted and implemented in canonical Markdown; executable and
+  generated surfaces remain unchanged.
+
+## Research boundary
+
+This study used fresh clones in a temporary directory outside DevRites. Each
+clone was fetched with tags, updated with submodules where present, inspected at
+the exact revision below, and checked for object connectivity. The study read
+actual agents, skills, rules, workflow files, templates, docs, tests, release
+history, and selected implementation files needed to understand supported
+behavior. It did not treat a README or prior DevRites benchmark as sufficient
+evidence.
+
+All nine repositories use the MIT license at the inspected revision. DevRites
+adapts general ideas in original language; it copies no source, prompt,
+template, identity, or substantial prose.
+
+## Exact inventory
+
+| Repository | Default / checked branch | Audited commit | Commit date | Release/tag context | Markdown system shape |
+|---|---|---|---|---|---|
+| [gstack](https://github.com/garrytan/gstack) | main / main | a3259400a366593e0c909dd9ac3e59752efd2488 | 2026-07-14T18:33:46-07:00 | No reachable tag | Skills, generated workflow composites, specialist review checklists, templates, browser and context flows |
+| [skills](https://github.com/mattpocock/skills) | main / main | 2ab958093e83e0ec752e6c1c5932da465bf23e0c | 2026-07-28T10:18:17+01:00 | v1.1.0 | Promoted/draft/deprecated skill buckets, router, progressive references, human docs |
+| [OpenSpec](https://github.com/Fission-AI/OpenSpec) | main / main | 45cca5db6137ed209117cc70510eb3e057fb981b | 2026-07-31T02:04:10Z | v1.7.0 | Change/spec artifacts, command and skill templates, schemas, workflow docs, config-scoped instructions |
+| [Superpowers](https://github.com/obra/superpowers) | main / main | 44c9b2d6e889982ac18c27d05a19fefe335194e1 | 2026-07-28T12:25:36-07:00 | v6.2.0 | Focused discipline skills, planning/execution/review flows, host adapters, behavioral skill tests |
+| [Spec Kit](https://github.com/github/spec-kit) | main / main | d1e86f638277a99b82715c22c90558cd58d3cffd | 2026-07-31T12:45:15-05:00 | Latest release v0.15.1; its tag is not an ancestor of this head. Nearest reachable tag: v0.1.10 | Specification/planning/task templates, requirement checklists, presets, extensions, workflow docs |
+| [GSD Core](https://github.com/open-gsd/gsd-core) | next / next | 33985c11a9f0a27443f8b8fb114b2122d653cd78 | 2026-08-02T01:32:30-04:00 | v1.9.1 | Large skill/agent/workflow/reference graph, context budgets, state artifacts, verification and security contracts |
+| [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) | main / main | e510393b357ea71cbe8f7a273a1e10e14846acff | 2026-08-01T23:35:44-07:00 | v6.10.0; audited head is materially ahead | Step-loaded workflow skills, named agents, validators, spec companions, review lenses, migration shims |
+| [oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode) | main / main | 41a4c0f77144c5beb5f5f000a89cff379c680606 | 2026-07-23T04:44:59Z | v4.15.7 | Agent contracts, mode/skill catalog, hooks, state, keyword routing, compatibility and verification docs |
+| [ECC](https://github.com/affaan-m/ECC) | main / main | e4e4163101f162881e628f300a9ca4e6a940bcea | 2026-07-29T14:11:01-04:00 | v2.1.0 | Large cross-harness catalog of agents, skills, commands, layered rules, hooks, evals, translations, and docs |
+
+The Spec Kit release distinction matters: the release tag points to
+489a3d51d152fa160d88d86781a924e99c4af832, outside the ancestry of the audited
+main head. The table therefore does not present the release tag as the audited
+revision.
+
+## DevRites baseline
+
+The canonical instruction source is pack/.claude. Generated Claude and Codex
+trees are derived surfaces and were not edited. The current lifecycle remains:
+
+frame → spec → clarify → temper → define → plan → vet → build → converge →
+prove → polish → review → seal → ship → done
+
+The baseline already had strong exact-role boundaries, one source/test writer,
+immutable proof candidates, result admission, stable REQ/AC traceability,
+progressive references, workspace-owned state, compatibility-preserving public
+commands, positive discriminating proof, and fail-closed Seal/Ship separation.
+
+Fresh baseline inspection found these Markdown-level gaps:
+
+1. “Project conventions always win” appeared beside stricter safety/evidence
+   contracts, without separating prescriptive authority from descriptive code.
+2. Context guidance called all user-supplied content untrusted, which blurred the
+   controlling request with quoted or attached data supplied for inspection.
+3. Tooling repeated the same structural query across three indexes for
+   reassurance despite primary-index-first repository guidance.
+4. Slice orientation ended after an arbitrary lookup count rather than required
+   evidence.
+5. Brownfield specs had no first-class list of working outcomes to preserve.
+6. An Edge Coverage backstop had no qualifying-evidence or honest-abstention rule.
+7. Skill authoring lacked a normative old-to-new and load-path preservation gate.
+8. Skill routing had defining constraints but no complete explicit/active/implicit
+   activation order.
+9. The spec reviewer used stale AC notation.
+
+## Per-repository findings and decisions
+
+### gstack
+
+Strongest finding: specification starts from the current system and explicitly
+captures behavior that must not regress. Its code-grounded interrogation,
+sink-bound security, durable context handoff, and scope-selected review were
+also strong.
+
+Trade-offs: generated skills are very large; permissive “invoke when in doubt,”
+telemetry, browser daemons, quality arithmetic, and bundled issue/execution
+operations would increase context and runtime coupling.
+
+DevRites adaptation: the spec template now records observable existing outcomes,
+current evidence, and the REQ/AC that preserves each one. No gstack tool,
+terminology, or runtime mechanism was imported.
+
+### mattpocock/skills
+
+Strongest finding: steps should end on checkable completion criteria, and
+instruction context should be paid only by branches that consume it.
+
+Trade-offs: some small wrapper skills omit failure/output contracts; external
+ticket flows and host composition are not suitable as a second DevRites state
+system.
+
+DevRites adaptation: the sole writer’s ORIENT phase now ends when six named
+evidence categories are established, not after five lookups. Missing essential
+orientation causes the existing Escalation disposition.
+
+### OpenSpec
+
+Strongest finding: required context, scoped project rules, optional guidance,
+and runtime state are distinct layers. Treating them as one precedence bucket
+creates unsafe ambiguity.
+
+Trade-offs: adopting OpenSpec’s change directory, schemas, config, commands, or
+operation lifecycle would duplicate DevRites.
+
+DevRites adaptation: core now owns one authority/evidence/method/advice ladder.
+Context, security, contributor, rule-index, and public documentation align with
+that owner.
+
+### Superpowers
+
+Strongest finding: independent tasks are safe to parallelize only when their
+resources are independent. File ownership alone misses shared state, tools,
+ports, processes, locks, rate limits, and file descriptors.
+
+Trade-offs: universal TDD, worktrees, frequent commits, and fixed review rounds
+conflict with repository-specific evidence and user-owned dirty work.
+
+DevRites adaptation: native review dispatch now checks mutable and scarce
+resources, stops new spawning on exhaustion, collects running results, and
+continues in bounded batches or serially. This directly covers the observed
+too-many-open-files failure class without adding a scheduler.
+
+### Spec Kit
+
+Strongest finding: a specification checklist tests requirement prose rather
+than implementation, turning ambiguity into a pre-build failure.
+
+Trade-offs: a second constitution/preset/extension methodology would overlap
+DevRites principles and rites.
+
+DevRites adaptation: the existing spec-quality question bank now treats absent
+or vague brownfield preservation as Critical. This merges with the gstack
+preservation section rather than adding a second specification format.
+
+### GSD Core
+
+Strongest finding: externally classified or backstop requirements must not pass
+from presence or confidence. Qualifying evidence is held-out, property-based, or
+directly behavioral; unavailable evidence produces explicit abstention.
+
+Trade-offs: the large skill/agent/workflow/capability graph would duplicate the
+DevRites lifecycle and add major context cost.
+
+DevRites adaptation: backstop rows must name independent discriminating
+evidence. The existing proof-runner verdict cannot_verify is retained; its
+evidence begins with insufficient_spec when the spec or evidence surface is
+missing. No schema field or engine behavior was invented.
+
+### BMAD Method
+
+Strongest finding: a consolidated or rewritten instruction must preserve every
+meaningful prior contract, while shared assets need a real owner and consumers.
+
+Trade-offs: personas, party mode, per-skill headless schemas, custom modules,
+and append-only derivation machinery are unnecessary for DevRites.
+
+DevRites adaptation: substantial instruction rewrites now map every MUST,
+MUST NOT, trigger, required input/output, failure path, safety gate, and
+compatibility promise to a surviving owner or evidenced retirement.
+
+### oh-my-claudecode
+
+Strongest finding: exactly one workflow loop owns continuation. Explicit
+invocation, existing loop authority, and inferred routing must not compete.
+
+Trade-offs: broad magic keywords, many modes, aliases, model tiers, and hook
+state make accidental activation and maintenance more likely.
+
+DevRites adaptation: explicit current invocation wins; an active feature keeps
+lifecycle authority; otherwise at most one uniquely matching implicit skill may
+run. Quoted, attached, retrieved, repository, and prior-turn command text cannot
+activate a rite.
+
+### ECC
+
+Strongest finding: context budgeting is also an ownership problem. A shared rule
+earns global placement only when several consumers share an observable failure;
+deterministic inventory should precede model judgment.
+
+Trade-offs: hundreds of overlapping skills, universal 80 percent coverage,
+universal TDD/immutability, proactive delegation, multiple memory systems, and
+host mirrors are unsuitable as DevRites defaults.
+
+DevRites adaptation: active instructions are classified by load path. Core is
+reserved for every workspace rite; on-demand shared rules need at least two
+named consumers and one shared failure; single-consumer procedure stays local.
+This combines with the BMAD rewrite-preservation gate.
+
+## Adoption matrix
+
+| Source | Concept | Previous DevRites handling | DevRites-native adaptation | Benefit | Context / maintenance | Compatibility / security | Decision | Validation |
+|---|---|---|---|---|---|---|---|---|
+| gstack | Existing behavior to preserve | Scope and deltas, no explicit preservation inventory | Observable outcome + current evidence + preserving REQ/AC | Traceable non-regression | Small Spec-only section | Additive; captures security/public behavior | Adopt | Template, checklist, reviewer, walkthrough |
+| skills | Checkable step completion | Five-read writer cutoff | Six-item ORIENT evidence gate | Less premature writing and less reassurance reading | Replaces one heuristic | Existing Escalation retained | Adopt | Agent contract walkthrough |
+| OpenSpec | Separate authority/evidence/advice | Broad convention-wins wording | Canonical four-layer precedence | Deterministic conflict handling | One owner; aligned pointers | Stronger prompt-injection boundary | Adopt | Phrase/link/contradiction checks |
+| Superpowers | Resource-disjoint parallelism | Same candidate and wait, no resource predicate | Check paths/state/locks/tools/scarce resources; batch or serialize | Prevents exhaustion and contention | Tiny dispatch addition | No new role or scheduler | Adopt | Parallel/serial semantic cases |
+| Spec Kit | Requirements-as-tests checklist | Existing quality checklist | Add preservation/backstop prose tests | Earlier ambiguity failure | Reuses question bank | No new spec system | Merge | Checklist/readiness review |
+| GSD Core | Honest backstop abstention | Backstop undefined | Independent evidence or cannot_verify + insufficient_spec | No evidence-free pass | Conditional Prove text | Existing schema/verdict only | Adopt | Positive and missing evidence cases |
+| BMAD | Normative rewrite preservation | One-owner/source-intake guidance | Old-to-new obligation map | Prevents silent weakening | Contributor-only load | Protects safety/compatibility | Merge | Apply map to this diff |
+| OMC | One activation authority | Defining constraints only | Explicit → active lifecycle → one unique implicit route | Less over-triggering | Two short routing owners | Embedded content cannot activate | Adopt | Explicit/quoted/ambiguous cases |
+| ECC | Load-path placement gate | On-demand index, no promotion predicate | Core/every rite; shared/two consumers; local/one owner; human/research inactive | Lower context and drift | Prevents sprawl | Mandatory rules remain reachable | Merge | Consumer/path review |
+
+## Rejected and deferred ideas
+
+| Source | Rejected as unsuitable | Deferred because executable support is required |
+|---|---|---|
+| gstack | Always-invoke fallback, telemetry, numerical quality score | Browser daemon, sink-byte redaction, reviewer hit-rate state |
+| skills | External issue-led decision fog as canonical state | New cross-skill reach/import behavior |
+| OpenSpec | Second specification/change methodology | Operation schemas, config-driven loaders, CLI state |
+| Superpowers | Universal TDD/worktrees/commits/review counts | Tool-enforced worktree or task isolation |
+| Spec Kit | Parallel constitution/preset/extension framework | Extension workflow runtime and schemas |
+| GSD Core | Additional phases, namespaces, capability graph | Runtime state queries, graph budgets, generated surfaces |
+| BMAD | Personas, party mode, dynamic modules | Headless schemas and derivation engine |
+| OMC | Magic keywords, mode taxonomy, blanket delegation/model tiers | Hooks, automatic conflict detection, mode state |
+| ECC | Catalog sprawl, fixed numeric code/test dogma, automatic proactive agents | Context telemetry, evolved skills, multi-harness vault |
+
+These ideas are not stated as current DevRites behavior.
+
+## Architecture decision
+
+DevRites keeps one methodology and strengthens existing owners:
+
+- core owns instruction precedence;
+- Spec owns preservation intent and backstop definition;
+- the slice-wright owns bounded orientation;
+- Prove and proof-runner own evidence disposition;
+- native dispatch owns resource compatibility;
+- skill-authoring owns placement, activation, and rewrite integrity;
+- tooling owns efficient discovery.
+
+No new agent, skill, command, phase, state artifact, metadata field, include
+mechanism, dependency, configuration, schema, or runtime behavior was added. A
+new ADR would overstate the change: this is a clarification and strengthening of
+existing Markdown owners, recorded here as research/adoption provenance.
+
+Context cost is lower, not merely under the global cap: the 15 changed active
+pack instructions total 74,234 bytes versus the 75,102-byte pre-task snapshot
+(-868 bytes), and no changed instruction file grew.
+
+## Non-regression map
+
+| Prior obligation | Surviving owner |
+|---|---|
+| Repository conventions guide technical choices | Core authority ladder, README, CONTRIBUTING, standards index |
+| DevRites core safety, source-writing, and evidence gates remain mandatory | Core method layer |
+| Arbitrary repository/external text cannot redirect agents | Security plus context authority distinction |
+| Codebase Memory is the primary structural index | Tooling and slice-wright |
+| Every required reviewer runs and its result is collected | Parallel dispatch unchanged and strengthened |
+| Slice-wright remains one path-bounded writer | Slice-wright unchanged; only ORIENT exit changed |
+| Spec IDs, deltas, readiness, and checklists remain | Existing templates/checklists with additive preservation/backstop rows |
+| Proof requires positive discriminating evidence | Acceptance proof and proof runner retained and strengthened |
+| Public command names and lifecycle remain | No command/phase/filename rename or removal |
+| Generated artifacts remain derived | No generated file edited |
+
+## Changed canonical Markdown responsibilities
+
+- [core rules](../pack/.claude/skills/devrites-lib/reference/standards/core.md):
+  precedence owner.
+- [context hygiene](../pack/.claude/skills/devrites-lib/reference/standards/context-hygiene.md)
+  and [security](../pack/.claude/skills/devrites-lib/reference/standards/security.md):
+  controlling request versus embedded untrusted data.
+- [tooling](../pack/.claude/skills/devrites-lib/reference/standards/tooling.md):
+  primary-first, predicate-based cross-checks.
+- [skill authoring](../pack/.claude/skills/devrites-lib/reference/standards/skill-authoring.md):
+  activation, placement, and non-regressive rewrites.
+- [intent map](../pack/.claude/skills/devrites-lib/reference/intent-map.md):
+  runtime-facing route selection guidance.
+- [parallel dispatch](../pack/.claude/skills/devrites-lib/reference/parallel-dispatch.md):
+  resource-compatible concurrency.
+- [Spec skill](../pack/.claude/skills/rite-spec/SKILL.md),
+  [template](../pack/.claude/skills/rite-spec/reference/spec-template.md), and
+  [checklists](../pack/.claude/skills/rite-spec/reference/spec-checklists.md):
+  preservation and qualified backstops.
+- [spec reviewer](../pack/.claude/agents/devrites-spec-reviewer.md):
+  independent preservation coverage and current AC notation.
+- [slice-wright](../pack/.claude/agents/devrites-slice-wright.md):
+  evidence-based ORIENT completion.
+- [acceptance proof](../pack/.claude/skills/rite-prove/reference/acceptance-proof.md)
+  and [proof runner](../pack/.claude/agents/devrites-proof-runner.md):
+  honest backstop evidence.
+- [README](../README.md) and [contributor guide](../CONTRIBUTING.md):
+  user/contributor-facing precedence alignment.
+
+## Validation contract
+
+The patch is acceptable only if:
+
+1. the task-specific delta contains non-generated Markdown paths only;
+2. every pre-task non-Markdown hash is unchanged;
+3. Markdown whitespace, cross-reference, frontmatter, command, skill, agent, and
+   documented-path checks pass;
+4. no stale convention-wins or AC notation remains in canonical Markdown;
+5. a semantic Spec → Define → Build → Prove walkthrough reaches a clear
+   preservation contract, dependency-aware plan, bounded writer orientation, and
+   evidence-backed proof;
+6. missing backstop evidence cannot become a pass;
+7. no reference clone or temporary research artifact appears in DevRites.

package/docs/orchestration.md

@@ -1,149 +1,136 @@
-# Orchestration patterns
-
-DevRites delegates bounded work to agents while keeping authority in the root
-orchestrator. The governing contract is
-[`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md);
-this page summarizes that model.
-
-## Authority and topology
-
-- The active public `rite-*` skill is the root. It alone owns human questions,
-  decisions, routing, gates, reconciliation, canonical `.devrites/**` writes,
-  phase changes, and irreversible or external actions.
-- Orchestration is flat depth one: only the root dispatches. Leaves never
-  dispatch leaves.
-- Normally at most three read-only leaves run concurrently against one frozen
-  candidate. The root awaits every required return before mutation.
-- There are **18 named roles**: 17 read-only leaves and one source/test writer,
-  `devrites-slice-wright`.
-
-| Group | Roles |
-|---|---|
-| Bounded work leaves | `devrites-evidence-scout`, `devrites-plan-drafter`, `devrites-proof-runner`, `devrites-upgrade-planner` |
-| Strategic/claim challenge | `devrites-strategy-reviewer`, `devrites-plan-reviewer`, `devrites-doubt-reviewer` |
-| Review/audit | `devrites-spec-reviewer`, `devrites-code-reviewer`, `devrites-test-analyst`, `devrites-frontend-reviewer`, `devrites-security-auditor`, `devrites-performance-reviewer`, `devrites-devex-reviewer`, `devrites-simplifier-reviewer` |
-| Comparison/history | `devrites-forge-judge`, `devrites-retrospector` |
-| Sole writer | `devrites-slice-wright` |
-
-Every dispatch uses file-backed `agent-packet/v1` and `agent-result/v1`
-envelopes. They record exact inputs, scope, budgets, immutable baseline
-identity, side effects, and terminal status. The root rejects malformed, stale,
-or out-of-scope returns before adding anything to canonical state.
-
-## Dispatch and enforcement
-
-Use the first safe option available:
-
-1. the named project role; Codex V2 uses its exact `agent_type`, a unique
-   `task_name`, and a durable rollout proving native rules, wait, and result;
-2. a generic V1 `explorer`/`worker` only when the host still enforces read-only
-   or exact wright scope (or isolated staging);
-3. a HITL stop when neither safe fresh-context option is callable.
-
-Specialist work never runs in the root context. Declared leaf identity is
-fail-closed: a missing or crashed `devrites-engine` guard blocks the tool call.
-Every installed skill also carries `required-agent-roles` frontmatter. Codex
-arms those unconditional roles when the user invokes the skill and blocks Stop
-until each role has a confirmed start, wait, and non-empty result. `none`
-explicitly declares that the skill has no unconditional fresh-agent requirement;
-conditional fan-out still follows the phase's documented triggers.
-Leaves never ask the human, write `.devrites/**`, change phase, commit, push,
-install, deploy, migrate live data, or perform irreversible actions.
-
-## Single-writer build lifecycle
-
-The root derives normalized project-relative source/test paths and writes them,
-one per line, to `.devrites/work/<slug>/.wright-allowlist`. It is an exact
-authorization manifest and permits no directories, globs, traversal,
-duplicates, or `.devrites/**`. The wright's returned file list records what
-changed but cannot grant access.
-
-Each dispatch follows the retained-baseline sequence:
-
-1. `reconcile snapshot` captures the original dirty-tree baseline, private Git
-   objects, exact allowlist, and canonical-state fingerprint.
-2. The confirmed wright start captures a second canonical-state fingerprint.
-   This preserves the original source baseline while separating root-owned
-   recovery records that predate the writer from canonical mutations made while
-   the writer is active.
-3. The sole wright returns code/tests; the root validates its typed identity and
-   exact changed-file set.
-4. `reconcile check` rejects anything outside the root allowlist and any
-   canonical-state change after the wright start.
-5. `test-integrity` runs against the retained baseline.
-6. After proof and decision checks pass, `reconcile close` retires the private
-   window; only then does the root write canonical records.
-
-If the writer result is rejected before a clean check, the root runs the exact
-standalone `reconcile abort` operation. It restores source to the original
-pre-dispatch baseline while preserving pre-snapshot user work and canonical
-`.devrites` evidence, verifies a source-manifest digest, closes the retained
-window, and records a content-addressed `.reconcile-abort-<sha256>.json`
-receipt. The receipt binds the original tree, captured allowlist digest,
-restored path set, and closed-window result. Project-specific frozen hashes are
-verified separately against the restored worktree. `restore-check` remains the
-narrow rollback for source drift introduced after a clean check.
-
-An ordinary `reconcile check` may revalidate an existing retained window
-without a fresh current-turn wright receipt; it does not retire or widen that
-window. `reconcile close` still requires the confirmed, awaited wright result
-bound to the active snapshot. While the window is armed, the root guard permits
-inspectable writes only under `.devrites` or at an absolute scratch path outside
-the project; source-tree writes, relative escapes, and opaque execution remain
-blocked. The standalone A1 hook and wright-scope hook share this classification;
-Codex `cmd` and Claude `command` payloads may create a literal external packet
-with a patch, heredoc, or copy and may hash it without gaining source authority.
-
-The canonical-state fingerprint excludes root-owned operational records:
-`timeline.jsonl`, feature `events.jsonl`, a valid `recovery-attempts.jsonl`,
-the redwatch sentinel, automatic handoff snapshots, and hidden hook observation
-logs. Those records cannot grant source authority or invalidate a writer result
-merely because the engine or a hook wrote them. Unknown or canonical
-`.devrites` paths remain fail-closed, and recovery ledgers must still parse
-before reconciliation can pass. Gate-authoritative operational state such as
-recovery attempts and `.red` remains enforced by its owning gate. Checks also
-normalize these paths out of retained snapshots created by older engines.
-
-On retry, the root may add only an accepted still-in-slice path, then runs
-`reconcile snapshot` again. This refreshes the dispatch boundary while
-preserving the original slice baseline. The same objective root cause has a
-durable three-failure budget in `recovery-attempts.jsonl`; exhaustion records a
-technical blocker with reproduction and dead ends, not a retry-approval
-question.
-
-Build asks the human only for product/scope/policy choices, irreversible risk,
-or human-only access/actions. Tests, types, lint, runtime/browser failures,
-missing coverage, and workflow-tool defects stay agent-owned.
-
-## Isolation
-
-Parallel shared-tree writers are forbidden. A vetted `Forge: yes` slice may
-compare two or three complete strategies only through
-`devrites-engine forge`:
-
-1. `plan` validates the scorecard, pins the physical repository/base, writes
-   the sole `devrites-forge/v1` ownership manifest, and creates derived
-   worktrees outside `.devrites` **before** reconciliation snapshots.
-2. A real host adapter declares `manifest-env-v1`. Each candidate is bound
-   all-or-none to the manifest run, candidate, worktree cwd, branch, live
-   worker ID, PID, and the engine's `forge process-token` value.
-3. `record` and `extract` make every terminal full-tree delta immutable; the
-   read-only judge records one winner; `merge` preflights and lands exactly it.
-4. Normal reconcile, integrity, doubt, and proof gates record verification
-   before `cleanup`. The human `forge-report.md` is written afterward and owns
-   nothing.
-
-An ineligible layout returns a typed serial degradation before side effects.
-After planning, errors preserve manifest-owned state for recovery. Cleanup and
-reap enumerate only manifests, preserve live, dirty, mismatched, or ambiguous
-state, and never delete candidate branches. Ordinary features may also run in
-separate user worktrees so their `ACTIVE` cursors and source trees do not
-collide.
-
-## See also
-
-- [`architecture.md`](architecture.md): full layer model.
-- [`command-map.md`](command-map.md): every role and phase owner.
-- [`flow.md`](flow.md): lifecycle and state diagrams.
-- [`ADR-0010`](adr/0010-agent-first-fresh-context-orchestration.md): decision
-  record and rejected alternatives.
+# Orchestration
+
+DevRites defines workflow semantics; Codex and Claude provide native
+orchestration.
+
+```text
+AGENTS.md / CLAUDE.md / skills
+              ↓
+host interprets the requested workflow
+              ↓
+host runs .codex/agents/<role>.toml or .claude/agents/<role>.md
+              ↓
+host waits, follows up, and delivers results
+              ↓
+root reconciles semantics; engine checks deterministic structure/state/safety
+```
+
+## Authority
+
+- The public `rite-*` skill is the root orchestrator. It owns scope, human
+  questions, decisions, result reconciliation, `.devrites/**` artifacts, phase
+  transitions, and explicit irreversible-action approval.
+- Build maintains the strict candidate manifest. Prove, Review, and Seal bind
+  their artifacts to the engine-computed digest; Polish owns final durable
+  rollups and affected re-proof; Ship is candidate-read-only.
+- The root never writes source or tests. Claude enforces that with plan mode;
+  Codex enforces it as workflow policy because the parent must be
+  workspace-capable for its writer child to execute.
+- The role catalog has one source/test writer, `devrites-slice-wright`. Claude
+  and Codex make only that exact specialist writable.
+- Leaves never invoke leaves, ask the human, change phase, commit, push, deploy,
+  migrate live data, or write canonical workflow state.
+
+Skills name the exact role and bounded task in normal language. The host owns
+internal spawn fields, scheduling, waiting, follow-ups, and result delivery.
+DevRites does not parse rollout logs or maintain dispatch receipts.
+
+Quick, Standard, and Full select evidence/review depth only; they are not agent
+API versions or execution tiers. The shared contract lives in
+[`orchestration-profiles.md`](../pack/.claude/skills/devrites-lib/reference/orchestration-profiles.md).
+Persisted state schemas remain explicitly versioned because readers need
+stable data contracts; no compatibility protocol is
+inserted between a skill and the host's native agent call.
+
+## Native permission boundary
+
+Claude project settings use `permissions.defaultMode: plan`; its slice-wright
+profile uses `permissionMode: acceptEdits`. Codex uses a workspace-capable root
+because children cannot elevate above the parent permission ceiling. Its exact
+slice-wright uses `default_permissions = ":workspace"` and the other 16
+specialists use `default_permissions = ":read-only"`.
+
+If the exact role is unavailable, the root stops instead of substituting a
+generic agent or doing specialist/writer work inline.
+
+## Result closure
+
+Each leaf's final response is its complete admission packet. It repeats every
+finding, outcome, evidence citation, limitation, and gap that the root must
+reconcile; an earlier message followed by a bare `done` or a link is malformed.
+The root owns collection and accounts for every required or applicable role.
+Timeout, absence, failure, or malformed output remains a gap, and a successful
+sibling cannot erase it.
+
+An evidenced clean result is valid. Reviewers must account for their rubric and
+inspected scope, but they never manufacture a finding to fill a quota.
+
+## Slice-wright lifecycle
+
+For Claude or Codex, the root states the smallest exact project-relative source
+and test paths directly in the dispatch task. Directories, globs, traversal,
+symlink escapes, duplicates, and `.devrites/**` are invalid.
+
+1. The root records the pre-dispatch `git diff --name-only`.
+2. The host runs the exact `devrites-slice-wright` and waits for its result.
+3. The root compares the returned file list and `git diff --name-only` with the
+   task contract and rejects any extra path.
+4. The root inspects the test diff for deletion, skipping, focus markers, or
+   loosened assertions.
+5. Accepted changes receive repository/CI proof and applicable read-only review.
+6. The root records exact candidate rows and canonical evidence/state. Proof
+   must name a positive, discriminating assertion and decisive observed signal;
+   skipped/zero/assertion-free/tautological/unexecuted/exit-only results cannot
+   establish behavior.
+
+Exact-path scope is instruction-backed on both hosts; native sandboxes provide
+the broader writer/read-only split. An unauthorized delta is rejected and the
+same bounded writer must restore it before work continues. The root never
+widens the contract or rewrites source. Parallel source writers in one worktree
+are forbidden.
+
+## Engine boundary
+
+The engine owns deterministic:
+
+- local managed install, update, and uninstall against caller-supplied
+  candidates;
+- strict project-candidate validation/digesting, content-bound readiness, and final
+  structural plus exact-binding checks;
+- atomic answer/drop/batch resolve and transactional close mutations;
+- secret scanning and version reporting.
+
+Native hosts, skills, exact agents, repository tools, or CI own:
+
+- agent discovery, dispatch, scheduling, waiting, follow-up, and results;
+- semantic readiness, traceability, acceptance/evidence quality, doubt, review
+  reconciliation, test-quality assessment, capability interpretation, semantic
+  upgrade, and recovery routing;
+- normative spec grammar re-read, qid allocation, Clarify cursor edits, AFK
+  budget accounting, recovery attempt accounting, and read-only install/host
+  diagnosis;
+- exact-release bundle/binary acquisition before invoking local engine install
+  operations;
+- repository inspection, search, and test/build/lint/release execution;
+- repository JSON/schema/generated-artifact validation;
+- session history, compaction, status prose, progress, plugins, and memory.
+
+The engine has no agent bridge, semantic readiness protocol/digests, heuristic
+prose parser, capability-ledger interpreter, compatibility telemetry, migration
+command, or old aliases.
+
+Provider/consumer changes use the existing plan and traceability artifacts: one
+canonical contract plus provider- and consumer-side asserting tests that both
+consume it. Spec capability impact and lossless MODIFIED folding remain with
+Spec/Polish. These rules add no dispatch protocol, schema registry, or phase.
+
+Any harness adapter must expose the same read-only `check candidate` command,
+preserve exact binding lines and the Build/Prove/Polish/Review/Seal/Ship role
+boundaries, and stop rather than substitute another hash or inline specialist.
+
+See [ADR-0015](adr/0015-read-only-root-native-orchestration.md),
+[ADR-0017](adr/0017-native-codex-writer-agent.md),
+[ADR-0018](adr/0018-native-sandbox-instruction-writer-boundary.md),
+[ADR-0020](adr/0020-thin-engine-native-orchestration-boundary.md),
+[ADR-0022](adr/0022-native-orchestration-thin-engine.md), and
+[`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md).