devrites 3.2.2 → 3.2.3

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to DevRites are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and DevRites adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). Releases are generated automatically by [semantic-release](https://semantic-release.gitbook.io/) from Conventional Commits on `main`.
 
+## [3.2.3](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.2...v3.2.3) (2026-07-25)
+
+### Fixed
+
+* **agents:** enforce native specialist dispatch ([4ac3eb1](https://github.com/ViktorsBaikers/DevRites/commit/4ac3eb1a407ed8df4d3097984fbc0e369a5918b4))
+* **agents:** satisfy staticcheck error style ([cc21c46](https://github.com/ViktorsBaikers/DevRites/commit/cc21c4600171111dc30065327a9cd0ffff2420bc))
+* **skills:** avoid false invocation reference ([45f25bb](https://github.com/ViktorsBaikers/DevRites/commit/45f25bb70516460d753bccaa5ba78cce73e2a1d0))
+
 ## [3.2.2](https://github.com/ViktorsBaikers/DevRites/compare/v3.2.1...v3.2.2) (2026-07-25)
 
 ### Fixed

package/README.md

@@ -25,7 +25,7 @@ final commit, push, and tag, and it requires a typed `GO` confirmation.
 Unattended runs may create local WIP checkpoint commits along the way, but only
 Ship collapses and pushes them.
 
-**Status:** [`v3.2.2`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.2): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
+**Status:** [`v3.2.3`](https://github.com/ViktorsBaikers/DevRites/releases/tag/v3.2.3): see [`CHANGELOG.md`](CHANGELOG.md) for release notes.
 
 ## Quick start
 

package/docs/architecture.md

@@ -318,7 +318,8 @@ contract.
 - **Drift**: an explicit **Spec Drift Guard** in build/prove/polish/review/seal.
 - **Design**: `devrites-frontend-craft` + a four-phase `/rite-polish` orchestrator (code + backend always; UI normalize + polish when UI is in scope).
 - **Agents**: 18 fresh-context roles at flat depth one: 17 read-only leaves and
-  one wright. Fallback order is named, generic, then labelled inline.
+  one wright. Dispatch order is named, then guarded generic; if neither can
+  spawn, the workflow stops for HITL.
 - **Review**: **feature-scoped** multi-axis review with severity labels and
   fresh-context agents at the seal.
 - **Scope**: clarify → seal (decide) → ship (commit → push → tag or PR,
@@ -332,7 +333,10 @@ contract.
 1. **Invocation semantics are explicit in frontmatter.** `user-invocable`
    controls whether a skill is a public command; `disable-model-invocation`
    independently marks explicit-only public utilities and the internal
-   `devrites-lib` library. Model-invocable phases can still hand off and route;
+   `devrites-lib` library. `required-agent-roles` is the canonical list of
+   unconditional fresh-agent roles for one invocation (`none` is explicit);
+   Codex derives its fail-closed dispatch receipt from the installed mirror.
+   Model-invocable phases can still hand off and route;
    per-phase side-effect discipline (for example, "stop after one slice") is
    enforced in the skill **body**, because invocation flags cannot express it.
 2. **`context: fork` used selectively.** Verified it is a real field (isolated

package/docs/command-map.md

@@ -144,9 +144,9 @@ the shared reference library.
 Only the root dispatches; leaves never dispatch other leaves. The first
 fallback is a generic `explorer` or `worker` that reads the same role contract,
 but only when the host preserves the required read-only or exact-write
-boundary. If no safe fresh-context option is available, the root runs the work
-inline and labels the result `independence: fallback`. Declared leaf identity
-and scope guards fail closed. A missing or crashed engine blocks the tool call
+boundary. If no safe fresh-context option is available, the workflow stops for
+HITL. The root never executes a specialist role. Declared leaf identity and
+scope guards fail closed. A missing or crashed engine blocks the tool call
 instead of granting permission to continue.
 
 ## Engineering rules (`pack/.claude/skills/devrites-lib/reference/standards/`)

package/docs/engine/agent-contract.md

@@ -132,7 +132,8 @@ timeline rows remain readable beside v1 rows.
 
 The v1 validator accepts only:
 
-- `execution_mode`: `named` · `generic` · `inline` · `none`;
+- `execution_mode`: `named` · `generic` · `inline` · `none` (`inline` remains
+  readable for historical telemetry; current specialist dispatch never emits it);
 - `guard_strength`: `enforced` · `observed` · `unavailable` · `bypassed` · `n/a`;
 - `host`: `engine` · `claude` · `codex`;
 - registered `DRV-*` reason and rule IDs;
@@ -166,6 +167,6 @@ reasons are:
 | `DRV-GIT-AMBIGUOUS-*` / `DRV-GIT-INPUT-TOO-LARGE` | direct-literal Git parser boundary |
 | `DRV-GIT-DESTRUCTIVE-*` | destructive-operation classifier |
 | `DRV-GIT-AUTHORITY-*` / `DRV-GIT-WORKSPACE-UNAVAILABLE` | exact one-shot authority and replay gate |
-| `DRV-AGENT-*` | named/generic/inline execution and result reconciliation |
+| `DRV-AGENT-*` | named/generic execution, historical inline telemetry, and result reconciliation |
 
 Add a reason to that registry before an emitting rule or eval depends on it.

package/docs/harness-compliance.md

@@ -40,7 +40,7 @@ the table and the code can never silently drift apart.
 | Stop gate | Conditional | Conditional | all rest points | observe-only finding + manual host-specific rite-status | yes | high | Both deliver Stop; stop-gate blocks with DEVRITES_STOP_GATE=enforce or DEVRITES_HOOK_PROFILE=strict. |
 | SubagentStart discipline injection | Native | Native | review/build fan-out | agent file preamble | yes | high | subagent-orient wired on both. |
 | Skill invocation | Native | Adapter-backed | all public rites | explicit file read | yes | high | Claude: native /rite. Codex: $rite over the mirrored .agents/skills tree. |
-| Reviewer subagent dispatch | Native | Instruction-backed | review/seal confidence | labelled inline pass | partial | medium | Codex under-fires embedded spawns (openai/codex#23496); falls back to .codex/agents + a labelled inline pass. |
+| Reviewer subagent dispatch | Native | Adapter-backed | review/seal confidence | HITL stop; no root inline review | yes | high | Codex V2 requires the exact named role and verifies its durable parent/child rollout because V2 collaboration lifecycle calls bypass hooks; V1 keeps the guarded explorer fallback. |
 | Standards step-0 load | Native | Instruction-backed | all phases | explicit standards read | partial | medium | Claude: skill Reads core.md. Codex: an AGENTS.md directive to read it. |
 | Project activation | Native | Conditional | Codex-only startup | inspect hooks/config, decide trust, then rerun doctor | yes | medium | Codex silently skips every .codex/ layer in an untrusted project; trust remains an operator decision after inspection. |
 
@@ -52,7 +52,7 @@ Tiers: **Native** (the harness exposes and delivers the surface directly; policy
 
 The matrix above records what each host can support. The agent-contract eval
 checks whether the complete dispatch path behaves as claimed. Its 12 scenarios
-cover named reviewer and wright runs, generic and inline fallbacks, denial
+cover named reviewer and wright runs, generic fallback and dispatch unavailability, denial
 paths, stale or malformed results, session orientation, interruption, and
 post-compaction recovery. Every scenario runs once on Claude and once on
 Codex, for 24 isolated cells.

package/docs/orchestration.md

@@ -34,18 +34,21 @@ or out-of-scope returns before adding anything to canonical state.
 
 Use the first safe option available:
 
-1. the named project role;
-2. a generic `explorer` or `worker` reading the same generated role contract
-   only when the host still enforces read-only or exact wright scope (or
-   isolated staging);
-3. inline execution, labelled `independence: fallback`, when neither safe
-   fresh-context option is callable.
-
-Inline self-review never silently satisfies an independence gate. Declared
-leaf identity is fail-closed: a missing or crashed `devrites-engine` guard
-blocks the tool call. Leaves never ask the human, write `.devrites/**`, change
-phase, commit, push, install, deploy, migrate live data, or perform irreversible
-actions.
+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
 

package/docs/porting-to-a-new-harness.md

@@ -21,7 +21,8 @@ The harness must invoke DevRites and route to `/rite-spec` (or the host's explic
 - Skill discovery path is project-local and installed by `npx devrites`.
 - Session/project orientation runs automatically at startup/compact/resume, or the missing surface is recorded in `docs/harness-compliance.md`.
 - `devrites-engine` hooks/gates are wired, or each degraded gate has an honest fallback and confidence label.
-- Subagent support is mapped; if unavailable, reviewers/wrights use the documented inline fallback and label it.
+- Subagent support is mapped; if unavailable, required reviewer/wright work
+  stops for HITL rather than running in the root context.
 - Skills, agents, standards, hooks, and harness guidance stay project-local;
   the optional shared `devrites-engine` executable is the sole sanctioned
   global artifact and must remain skippable with `--no-binary`.

package/docs/skills.md

@@ -18,6 +18,11 @@ only when needed; small utilities keep their narrower contract local. The npm
 `devrites` shim bootstraps or proxies the engine directly (see
 [`cli.md`](cli.md)).
 
+Every canonical skill declares `required-agent-roles`. A comma-separated list
+means those fresh agents are mandatory for a Codex invocation; `none` means no
+agent is unconditionally required. Host generation preserves the field and
+validation rejects missing or unresolved role contracts.
+
 ## Naming convention
 
 `rite-*` is the namespace for lifecycle and utility commands. Its utilities are
@@ -248,8 +253,8 @@ context with only the slice contract; all other agents are read-only.
 | [`devrites-slice-wright`](../pack/.claude/agents/devrites-slice-wright.md) | Turn ONE exact allowlisted slice into the smallest complete, idiomatic, proven implementation. Writes code + tests only; returns a typed artifact for the root to reconcile, gate, and record. Writes no `.devrites/` bookkeeping; single-threaded per tree. |
 
 Dispatch contract + return shape + fallback: [`rite-build/reference/wright-dispatch.md`](../pack/.claude/skills/rite-build/reference/wright-dispatch.md).
-The shared topology, named → generic → labelled-inline fallback, and fail-closed
-identity rules live in [`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md).
+The shared topology, named → guarded generic → HITL stop, and fail-closed identity
+rules live in [`standards/agents.md`](../pack/.claude/skills/devrites-lib/reference/standards/agents.md).
 
 ---
 

package/engine/hooks.go

@@ -467,7 +467,7 @@ func hookReviewerReadonly(h harness.Harness, stdin io.Reader, stdout, stderr io.
 		return exitOK
 	}
 	in := h.ParseGuardInput(bytes.NewReader(data))
-	kind := devritesAgent(in.AgentType)
+	kind := devritesAgentForGuard(h, in)
 	if kind == devritesAgentNone &&
 		os.Getenv("DEVRITES_CODEX_GENERIC_AGENT_COMPAT") == "1" &&
 		in.AgentType == "" {
@@ -540,11 +540,46 @@ var subagentOrientContext string
 // Spawned agents have fresh context and do not load the rite-* framework the
 // same way as the main thread. The output matches devrites-subagent-orient.sh.
 func hookSubagentOrient(h harness.Harness, stdin io.Reader, stdout, stderr io.Writer) int {
-	agentType := h.SubagentAgentType(stdin)
-	if !strings.HasPrefix(agentType, "devrites-") {
+	data, err := io.ReadAll(stdin)
+	if err != nil {
+		return exitOK
+	}
+	agentType := h.SubagentAgentType(bytes.NewReader(data))
+	context := strings.ReplaceAll(subagentOrientContext, "\r\n", "\n")
+	if h == harness.Codex {
+		in, parseErr := parseAgentDispatchHookInput(bytes.NewReader(data))
+		root, ok := agentDispatchRoot()
+		if parseErr != nil || !ok || in.SessionID == "" || in.TurnID == "" || in.AgentID == "" {
+			if !strings.HasPrefix(agentType, "devrites-") {
+				return exitOK
+			}
+			context += "\n\n- **Dispatch binding unavailable.** Return blocked without doing specialist work; the parent must retry a confirmed spawn."
+		} else {
+			role, bound, bindErr := bindAgentDispatchStart(root, in)
+			if bindErr != nil {
+				context += "\n\n- **Dispatch binding failed.** Return blocked without doing specialist work; the parent must repair the agent-start receipt."
+			} else if bound {
+				if in.AgentType == role {
+					context += fmt.Sprintf(
+						"\n\n- **Confirmed role.** Your named Codex profile is `%s`; follow its loaded `developer_instructions` and execute only the unchanged packet from the parent.",
+						role,
+					)
+				} else {
+					context += fmt.Sprintf(
+						"\n\n- **Confirmed role.** Your generic `%s` identity is bound to `%s`; the spawn hook injected `.codex/agents/%s.toml` `developer_instructions` into your message. Follow them and execute only the unchanged packet from the parent.",
+						in.AgentType, role, role,
+					)
+				}
+			} else if !strings.HasPrefix(agentType, "devrites-") {
+				return exitOK
+			} else {
+				context += "\n\n- **Unbound named start.** Return blocked without doing specialist work; no matching root spawn receipt exists."
+			}
+		}
+	} else if !strings.HasPrefix(agentType, "devrites-") {
 		return exitOK // Stay silent without a DevRites agent identity.
 	}
-	out, err := h.SubagentStartContext(strings.ReplaceAll(subagentOrientContext, "\r\n", "\n"))
+	out, err := h.SubagentStartContext(context)
 	if err != nil {
 		debugf(stderr, "subagent-orient: %v", err)
 		return exitOK