triad-plus 1.8.0 → 1.9.0

package/runtime/triad-bmad-intake.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { access } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const runtimeDirectory = path.dirname(fileURLToPath(import.meta.url));
+
+async function loadIntegration() {
+  const candidates = [
+    path.join(runtimeDirectory, 'integrations', 'bmad', 'epics-parser.mjs'),
+    path.resolve(runtimeDirectory, '..', 'integrations', 'bmad', 'epics-parser.mjs')
+  ];
+  for (const candidate of candidates) {
+    try {
+      await access(candidate);
+      return import(pathToFileURL(candidate).href);
+    } catch {}
+  }
+  throw new Error('BMAD native intake assets are not installed');
+}
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function repeated(argv, name) {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] !== name) continue;
+    const value = argv[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${name} requires a value`);
+    values.push(value);
+    index += 1;
+  }
+  return values;
+}
+
+function usage() {
+  process.stderr.write(`Native BMAD epics.md intake (integration/automation API)
+
+Usage:
+  node .triad-runtime/triad-bmad-intake.mjs --source <epics.md>
+  node .triad-runtime/triad-bmad-intake.mjs --source <epics.md> --project <control> --output <features-dir> [--repository <id>] [--required-gate <story-id>=<gate-id>] [--depends-on <story-id>=<card-id>]
+
+Without --output the command performs read-only ingestion and prints canonical
+Stories. With --output it resolves Triad execution readiness and writes normal
+Cards plus integration-side provenance. This command is an internal
+deterministic primitive; the normal user entry point is the host's /triad
+workflow with the epics.md path.
+`);
+}
+
+function keyed(values, label) {
+  const result = {};
+  for (const value of values) {
+    const separator = value.indexOf('=');
+    if (separator <= 0 || separator === value.length - 1) throw new Error(`${label} must use STORY-ID=VALUE`);
+    const storyId = value.slice(0, separator).trim();
+    const item = value.slice(separator + 1).trim();
+    if (!storyId || !item) throw new Error(`${label} must use STORY-ID=VALUE`);
+    (result[storyId] ??= []).push(item);
+  }
+  return result;
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes('--help') || argv.includes('-h')) {
+    usage();
+    return;
+  }
+  const source = option(argv, '--source');
+  if (!source) throw new Error('--source is required');
+  const output = option(argv, '--output');
+  const project = option(argv, '--project');
+  const repository = option(argv, '--repository');
+  const requiredGatesByStory = keyed(repeated(argv, '--required-gate'), '--required-gate');
+  const dependsOnByStory = keyed(repeated(argv, '--depends-on'), '--depends-on');
+  const { ingestBmadEpics, writeImportedEpics } = await loadIntegration();
+  if (output && !project) throw new Error('--project is required when --output is supplied');
+  const options = {
+    sourcePath: source,
+    projectRoot: project,
+    targetRepository: repository,
+    requiredGatesByStory,
+    dependsOnByStory
+  };
+  if (output) {
+    const result = await writeImportedEpics({ ...options, outputDirectory: output });
+    process.stdout.write(`${JSON.stringify({
+      status: 'ready',
+      source_kind: result.source_kind,
+      source_path: result.source_path,
+      source_sha256: result.source_sha256,
+      epic_count: result.epics.length,
+      story_count: result.stories.length,
+      card_count: result.outputs.length,
+      cards: result.outputs.map(({ story, cardPath, provenancePath, provenance }) => ({
+        story_id: story.id,
+        epic_id: story.epicId,
+        card_path: cardPath,
+        provenance_path: provenancePath,
+        card_sha256: provenance.card_sha256
+      }))
+    })}\n`);
+    return;
+  }
+  const result = await ingestBmadEpics(options);
+  process.stdout.write(`${JSON.stringify({
+    status: 'ingested',
+    source_kind: result.source_kind,
+    source_path: result.source_path,
+    source_sha256: result.source_sha256,
+    epic_count: result.epics.length,
+    story_count: result.stories.length,
+    stories: result.stories.map((story) => ({
+      epic_id: story.epicId,
+      epic_title: story.epicTitle,
+      story_id: story.id,
+      title: story.title,
+      status: story.status,
+      ingestion_ready: story.ingestionReady,
+      execution_ready: story.executionReady,
+      source_heading: story.sourceHeading,
+      source_range: story.sourceRange
+    }))
+  })}\n`);
+}
+
+// `mktemp`/system temporary roots on macOS are commonly reached through the
+// `/var` -> `/private/var` symlink.  Compare canonical paths so the installed
+// runtime CLI still runs when invoked from such a control workspace.
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+}
+
+if (isMainModule()) {
+  main().catch((error) => {
+    process.stderr.write(`${error.code ? `${error.code}: ` : ''}${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/runtime/triad-verify.mjs

@@ -8,6 +8,7 @@ import { calculateCandidateFingerprint, collectCandidateChanges, worktreeBranch
 import { executeGates, gateSelectionEvidence, loadTrustedGates, resolveGateSelection } from "./lib/gates.mjs";
 import { resolveQualityContract } from "./lib/quality-baseline.mjs";
 import { evaluateScopeContract, parseScopeContract } from "./lib/scope-contract.mjs";
+import { resolveAssignmentContext, validateAssignmentPacket } from "./lib/assignment-packet.mjs";
 
 const argv = process.argv.slice(2);
 const option = (name) => {
@@ -70,7 +71,7 @@ async function resolveAssignment(projectRoot, trigger, explicitAssignment) {
   return { assignmentPath, assignment: JSON.parse(source), assignmentHash: sha256(source) };
 }
 
-async function buildInvalidEvidence({ runId, trigger, assignment, reason, outputPath, failureCode = "verification_context_invalid", gateSelection = null, qualityBaselineFingerprint = null }) {
+async function buildInvalidEvidence({ runId, trigger, assignment, reason, outputPath, failureCode = "verification_context_invalid", gateSelection = null, qualityBaselineFingerprint = null, assignmentPacket = null }) {
   const evidence = {
     schema_version: 1,
     run_id: runId,
@@ -86,6 +87,9 @@ async function buildInvalidEvidence({ runId, trigger, assignment, reason, output
       git_head: null,
       candidate_fingerprint: null,
     },
+    assignment_packet: assignmentPacket ?? (assignment?.assignment_packet_path || assignment?.assignment_packet_sha256
+      ? { path: assignment.assignment_packet_path ?? null, sha256: assignment.assignment_packet_sha256 ?? null }
+      : null),
     gates: [],
     required_gates_passed: false,
     status: "invalid_context",
@@ -154,6 +158,7 @@ async function main() {
   let outputPath;
   let gateSelection = null;
   let qualityBaseline = null;
+  let assignmentPacket = null;
   try {
     let assignmentHash;
     ({ assignmentPath, assignment, assignmentHash } = await resolveAssignment(projectRoot, trigger, option("--assignment")));
@@ -167,12 +172,16 @@ async function main() {
     if (!assignment.assignment_id) throw new Error("assignment ID is required");
     if (assignment.agent_id !== trigger.agent_id || assignment.agent_type !== "triad_developer") throw new Error("developer assignment does not match trigger");
     if ((await realpath(path.resolve(assignment.project_root ?? projectRoot))) !== projectRoot) throw new Error("assignment project root mismatch");
-    const worktree = await realpath(path.resolve(projectRoot, assignment.worktree));
-    if (!worktree.startsWith(`${projectRoot}${path.sep}`) && !assignment.allow_external_worktree) throw new Error("undeclared external worktree");
+    const assignmentContext = await resolveAssignmentContext(assignment, { projectRoot });
+    const worktree = assignmentContext.worktree;
     const prdPath = path.resolve(projectRoot, assignment.prd_path ?? "artifacts/prd.md");
     const cardPath = path.resolve(projectRoot, assignment.card_path);
     await access(prdPath);
     await access(cardPath);
+    // The packet is an immutable, shared assignment contract. Validate its
+    // binding before skills, scope, or expensive gates so a stale packet is
+    // reported as invalid context and consumes no retry budget.
+    assignmentPacket = await validateAssignmentPacket(assignment, projectRoot);
     // Resolve the optional immutable Quality Contract before any baseline or
     // expensive-gate check so a bound source drift keeps its precise failure
     // classification (including when the source is the PRD itself).
@@ -220,6 +229,7 @@ async function main() {
           candidate_fingerprint: before.value,
           branch,
         },
+        assignment_packet: assignmentPacket,
         repository_skills: repositorySkills,
         scope,
         gates: [],
@@ -257,6 +267,7 @@ async function main() {
         candidate_fingerprint: before.value,
         branch,
       },
+      assignment_packet: assignmentPacket,
       repository_skills: repositorySkills,
       scope,
       gate_selection: gateSelectionEvidence(gateSelection),
@@ -283,7 +294,8 @@ async function main() {
       outputPath,
       failureCode: error.code ?? "verification_context_invalid",
       gateSelection,
-      qualityBaselineFingerprint: qualityBaseline?.fingerprint ?? null
+      qualityBaselineFingerprint: qualityBaseline?.fingerprint ?? null,
+      assignmentPacket,
     });
     process.stdout.write(`${JSON.stringify({ run_id: runId, status: evidence.status, evidence: outputPath ?? null })}\n`);
     process.exitCode = 3;

package/schemas/verification-evidence.schema.json

@@ -13,6 +13,14 @@
     "assignment_sha256": { "type": ["string", "null"] },
     "trigger": { "type": "object", "required": ["event", "agent_id", "agent_type"], "properties": { "event": { "type": "string" }, "agent_id": { "type": ["string", "null"] }, "agent_type": { "type": ["string", "null"] } } },
     "baseline": { "type": "object", "required": ["prd_sha256", "card_sha256", "git_head", "candidate_fingerprint"], "properties": { "prd_sha256": { "type": ["string", "null"] }, "card_sha256": { "type": ["string", "null"] }, "quality_baseline_fingerprint": { "type": ["string", "null"], "pattern": "^[a-fA-F0-9]{64}$" }, "git_head": { "type": ["string", "null"] }, "candidate_fingerprint": { "type": ["string", "null"] }, "branch": { "type": ["string", "null"] } } },
+    "assignment_packet": {
+      "type": ["object", "null"],
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": { "type": ["string", "null"] },
+        "sha256": { "type": ["string", "null"], "pattern": "^[a-fA-F0-9]{64}$" }
+      }
+    },
     "scope": {
       "type": "object",
       "properties": {

package/skills/triad-loop-bootstrap/SKILL.md

@@ -13,13 +13,28 @@ Collect only missing essentials: project ID/title, readable PRD source, target
 repositories with base/project branches and worktrees, measurable success
 conditions, runnable quality gates, practical-test need, and integration need.
 
+## Native BMAD planning boundary
+
+When the owner input is a native BMAD `epics.md` artifact, BMAD is the
+planning authority for Epic/Story boundaries and acceptance criteria. The
+canonical Stories in that read-only artifact are the sole planning boundaries:
+one canonical Story maps to one normal Triad Card. Bootstrap must not independently
+re-decompose the PRD into another feature-card plan, create a second Story set,
+or invoke an LLM to decide native Story boundaries. The native flow is
+BMAD `epics.md` → canonical Stories → Triad Cards; the generic PRD-only
+feature-plan step below does not apply to that input. Triad remains execution
+authority after the planning handoff.
+
 1. Create `<control-repository>/projects/<project-id>/`.
 2. Copy `assets/project.yaml` to `project.yaml`; register only declared product
    repositories, branches, and worktrees.
 3. Copy the approved PRD to `artifacts/prd.md`; record source, collection time,
    snapshot, revision when available, and SHA-256.
-4. Copy `assets/loop-template/` to `.loop/`, then create bounded feature cards
-   under `features/` and a complete `feature-plan.md`.
+4. Copy `assets/loop-template/` to `.loop/`. For ordinary PRD-only input,
+   create bounded feature cards under `features/` and a complete
+   `feature-plan.md`. For native BMAD input, ingest the canonical Stories and
+   materialize one normal Card per Story instead; do not perform a second
+   semantic decomposition.
    When an owner-approved Quality Bar or additional intent/architecture source
    exists, copy `assets/loop-template/quality-baseline.json`, fill only the
    declared source hashes and criteria, compute its canonical fingerprint, and
@@ -47,10 +62,30 @@ conditions, runnable quality gates, practical-test need, and integration need.
 The normal state route is `draft → ready → in_progress → verifying → in_review
 → approved|rework|blocked`. The Orchestrator owns those records. Before each
 Developer dispatch, write an active assignment with a unique assignment ID,
-feature, attempt, expected branch, worktree, PRD/card/gate hashes, and verifier
-run ID. The verifier produces environment-derived evidence; it never changes
+   feature, repository ID, attempt, expected branch, worktree, PRD/card/gate
+   hashes, and verifier run ID. Populate only the packet's bounded `context`
+   fields (relevant excerpts, acceptance, verification mapping, touch points,
+   constraints, risks, and prior evidence). Then create its immutable Assignment Packet and bind the returned path
+and SHA-256 in that assignment:
+
+```bash
+node .triad-runtime/triad-assignment-packet.mjs \
+  --project /absolute/path/to/control-workspace \
+  --assignment .loop/runtime/assignments/<assignment-file>.json
+```
+
+The command returns JSON containing the packet path and the dispatch context;
+launch the delegated role with `dispatch.cwd` set to the declared product
+worktree. The verifier produces environment-derived evidence; it never changes
 card state.
 
+The control workspace and product worktree may be separate directories. An
+external worktree is authorized by an exact repository mapping in
+`project.yaml` (`repositories[].worktree`, falling back to `path`), not by an
+assignment escape hatch. A mapped external worktree is valid even when the
+legacy `allow_external_worktree` field is absent or false; an unmapped external
+path fails closed before dispatch or gate execution.
+
 Use local worktrees for enabled multi-repository integration and declare a final
 integration card. Do not publish packages, alter registry versions, or create a
 release as a bootstrap/integration step. Re-baseline only after an explicit owner

package/skills/triad-loop-bootstrap/assets/loop-template/runtime/assignments/assignment.template.json

@@ -7,6 +7,7 @@
   "feature_id": "REPLACE_ME_FEATURE_ID",
   "attempt": 1,
   "project_root": "REPLACE_ME_ABSOLUTE_CONTROL_WORKSPACE",
+  "repository_id": "REPLACE_ME_REPOSITORY_ID",
   "worktree": "REPLACE_ME_DECLARED_WORKTREE_OR_ABSOLUTE_PATH",
   "expected_branch": "REPLACE_ME_PROJECT_BRANCH",
   "allow_external_worktree": false,
@@ -31,5 +32,17 @@
     }
   ],
   "verification_run_id": "REPLACE_ME_UUID",
-  "evidence_directory": ".loop/evidence/REPLACE_ME_FEATURE_ID/attempt-001"
+  "evidence_directory": ".loop/evidence/REPLACE_ME_FEATURE_ID/attempt-001",
+  "assignment_packet_path": null,
+  "assignment_packet_sha256": null,
+  "context": {
+    "relevant_prd_excerpts": [],
+    "relevant_adr_excerpts": [],
+    "acceptance_criteria": [],
+    "verification_mapping": [],
+    "expected_paths": [],
+    "constraints": [],
+    "risks": [],
+    "previous_evidence": []
+  }
 }

package/skills/triad-loop-developer/SKILL.md

@@ -5,14 +5,25 @@ description: Implement one bounded Triad feature card, add focused tests, and re
 
 # Triad Developer
 
-Change the artifact to satisfy the assigned goal. Read the card, PRD excerpt,
-project manifest, repository instructions, allowed surface, prior findings, and
-gates. When the assignment contains a scope contract, read it as a deterministic
-path boundary in addition to the human card scope: keep every cumulative change
-from the card baseline within its allowed paths, and use the recorded offending
-paths for `scope_cleanup`. Verify the declared worktree and branch before
-editing. Do not change scope, policy, assignments, queue, state, or evidence
-records.
+Change the artifact to satisfy the assigned goal. The host MUST launch this
+activation with `cwd`/`workdir` equal to the assignment's declared product
+worktree, not the control workspace. Verify that operational directory and
+branch before editing. Read the immutable Assignment Packet first, then the
+card, the mandatory repository skills, project instructions, and prior evidence
+references named by the assignment. The packet is the primary contract and
+eliminates broad startup discovery; read only the needed PRD/ADR section when a
+packet detail is missing or contradictory, never the full documents by default.
+When the assignment contains a scope contract, read it as a deterministic path
+boundary in addition to the human card scope: keep every cumulative change from
+the card baseline within its allowed paths, and use the recorded offending paths
+for `scope_cleanup`. Do not change scope, policy, assignments, queue, state, or
+evidence records.
+
+The Orchestrator supplies explicit control-workspace, repository, worktree,
+branch, card, packet, and mandatory-skill paths. Use native `read`, `grep`,
+`glob`, and `list` primitives for simple reads/discovery when the host provides
+them. Use shell/Bash for builds, tests, git, scripts, and system commands; do
+not use shell as the default filesystem API.
 
 At the beginning of every activation, read `.triad-plus/team.json` when it
 exists. Your first report to the Orchestrator must identify you as its configured

package/skills/triad-loop-orchestrator/SKILL.md

@@ -8,6 +8,10 @@ description: Coordinate a Triad engineering run from declared feature cards thro
 Maintain the goal and operational context. Decide the next step; do not perform
 ordinary implementation or review. Read `project.yaml`, the frozen PRD, queue,
 decision policy, current records, and `.triad-plus/team.json` when present.
+The control workspace is the policy/state/evidence source; a delegated
+Developer or Reviewer operates from the assigned product worktree. Prepare one
+immutable Assignment Packet per assignment so role contexts do not reconstruct
+the entire PRD/ADR from scratch.
 
 Before the first owner-facing reply, read `.triad-plus/team.json` when it exists.
 User-facing identity is permanent: adopt its non-empty
@@ -26,6 +30,50 @@ localized to the configured interaction language; then state whether the run is
 new or resumed and what input was received. If the entry point already made that
 presentation for this invocation, do not repeat it.
 
+## Native BMAD intake
+
+When the owner input is an `epics.md` file, or a directory that deterministically
+contains `_bmad-output/planning-artifacts/epics.md`, use the native BMAD intake
+before selecting a card. Do not ask the owner to split the file into Story
+files or to run `import-bmad-story` once per Story. The BMAD source is read-only
+and planning-owned.
+
+For native BMAD input, the canonical Stories from `epics.md` are the sole
+planning boundaries and the source of Triad Cards: one canonical Story maps to
+one normal Triad Card. Do not run the generic PRD bootstrap decomposition a
+second time, create parallel Cards, or use an LLM to reinterpret the Epic/Story
+boundaries. BMAD decides what the executable Story is; Triad decides how it is
+implemented, verified, and reviewed.
+
+First ingest the source without execution assumptions so the Orchestrator can
+inspect the canonical Epic/Story set:
+
+```bash
+node .triad-runtime/triad-bmad-intake.mjs \
+  --source /absolute/path/to/_bmad-output/planning-artifacts/epics.md
+```
+
+After the control workspace is initialized and its project/repository/gate
+readiness is valid, materialize normal Cards with the same deterministic
+primitive and an explicit output directory:
+
+```bash
+node .triad-runtime/triad-bmad-intake.mjs \
+  --source /absolute/path/to/_bmad-output/planning-artifacts/epics.md \
+  --project /absolute/path/to/control-workspace \
+  --output /absolute/path/to/control-workspace/features
+```
+
+Supply `--repository` only when the Story or project configuration does not
+resolve one deterministically. Supply per-Story `--required-gate STORY-ID=ID`
+and `--depends-on STORY-ID=CARD-ID` only from explicit planning/owner input;
+never infer them from prose or document order. Ingestion readiness (ID, title,
+intent, acceptance criteria, Epic parent) is distinct from execution readiness
+(repository, worktree, trusted gates, and Card contract). A native Story may be
+ingested without `status: ready-for-dev`, but an explicit non-ready status stays
+blocked from execution. Ambiguous or unavailable execution context is a
+fail-closed escalation; do not dispatch a Developer or consume retry budget.
+
 ## Run one card
 
 1. Verify the PRD hash, declared worktree/branch, repository instructions,
@@ -61,15 +109,35 @@ presentation for this invocation, do not repeat it.
    gates, or consume retry/remediation budget. Legacy projects without the
    quality contract retain PRD-only behavior.
 2. Choose one dependency-approved `ready` card, mark it `in_progress`, append an
-   attempt, and create an active assignment before delegating. Before each
-   delegation, publish an owner-facing activation notice that attributes the
-   configured display name, technical role, and card/attempt to that role.
-3. Give the Developer the card, relevant PRD excerpt, allowed surface, the
-   effective gate IDs (all trusted `required: true` gates plus the card's
-   selected IDs), risks, and prior findings. Globally required gates are never
-   suppressed. In selected mode, a selected optional gate is required for that card and unselected optional gates may be
-   skipped; dedupe the effective set. Treat its command results and report as
-   **agent-reported claims**, never as control-plane gate truth.
+   attempt, and create an active assignment before delegating. Bind the selected
+   repository ID as well as its declared branch/worktree. Populate the optional
+   `context` object with only bounded, assignment-relevant fields such as
+   `relevant_prd_excerpts`, `relevant_adr_excerpts`, `acceptance_criteria`,
+   `verification_mapping`, `expected_paths`, `constraints`, `risks`, and
+   `previous_evidence` (short text or references, never whole source files).
+   Before each delegation, publish an owner-facing
+   activation notice that attributes the configured display name, technical role,
+   and card/attempt to that role. Then run the exact packet command:
+
+   ```bash
+   node .triad-runtime/triad-assignment-packet.mjs \
+     --project /absolute/path/to/control-workspace \
+     --assignment .loop/runtime/assignments/<assignment-file>.json
+   ```
+
+   It atomically creates (or verifies) the immutable packet, binds its path and
+   SHA-256 to the assignment, and returns explicit `dispatch.cwd`, control
+   workspace, repository, branch, card, packet, and mandatory-skill paths.
+3. Dispatch the Developer with `cwd`/`workdir` exactly equal to the returned
+   assigned product worktree. Pass the card and Assignment Packet as the
+   primary contract, followed by the mandatory skill paths and any prior
+   evidence. Include the effective gate IDs (all trusted `required: true` gates
+   plus the card's selected IDs), risks, and findings. Globally required gates
+   are never suppressed. In selected mode, a selected optional gate is required
+   for that card and unselected optional gates may be skipped; dedupe the
+   effective set. Treat command results and role reports as **agent-reported
+   claims**, never as control-plane gate truth. The full PRD/ADR is a fallback
+   for a missing detail or contradiction, not systematic startup context.
 4. After completion, move to `verifying`. Follow the recorded dispatch route:
    wait for a valid hook-produced file when one is configured, otherwise invoke
    the verifier explicitly. Accept only current evidence whose assignment ID,
@@ -94,8 +162,12 @@ presentation for this invocation, do not repeat it.
 5. A passing verifier result is **environment-derived evidence**. Move only then
    to `in_review`. Missing, stale, failed, timed-out, invalid-context, or
    invalidated evidence never advances the card.
-6. Give the Reviewer the card, diff, developer report, verifier evidence, prior
-   attempts, and risks. Record its recommendation:
+6. Dispatch the Reviewer with the same immutable Assignment Packet and
+   `cwd`/`workdir` equal to the candidate worktree when the review needs direct
+   candidate inspection. Add the diff, Developer report, verifier evidence,
+   prior attempts, and risks. The Reviewer may consult only a necessary PRD/ADR
+   section when the packet is insufficient; it must not reconstruct the whole
+   requirement by default. Record its recommendation:
    - `approved`: verify scope/evidence, commit the card locally, promote every
      dependency-satisfied draft card to `ready`, then immediately select and
      assign the next ready card;

package/skills/triad-loop-reviewer/SKILL.md

@@ -5,11 +5,17 @@ description: Independently review one verified Triad implementation attempt agai
 
 # Triad Reviewer
 
-Look for defects and request correction until the result is acceptable. Read the
-card, PRD excerpt, project policy, prior attempts, Developer report, repository
-instructions, actual diff/worktree, and verifier evidence. You may know prior
-attempts and correction history; independence means assess the artifact and
-evidence yourself, not blindness.
+Look for defects and request correction until the result is acceptable. The host
+should launch the Reviewer with `cwd`/`workdir` equal to the candidate worktree
+when direct candidate inspection is required, while control-workspace paths are
+passed explicitly. Read the same immutable Assignment Packet used by the
+Developer, then the card, Developer report, actual diff/worktree, verifier
+evidence, project policy, repository instructions, and prior attempts. The
+packet is the shared assignment contract; consult only the necessary PRD/ADR
+section when it is insufficient or contradictory rather than reconstructing
+the whole requirement on every review. You may know prior attempts and
+correction history; independence means assess the artifact and evidence
+yourself, not blindness.
 
 At the beginning of every activation, read `.triad-plus/team.json` when it
 exists. Your first report to the Orchestrator must identify you as its configured
@@ -24,6 +30,10 @@ mismatched, or unreported required repository skill is a `blocked` result until
 the Orchestrator creates a valid assignment; external context never substitutes
 for the repository skill policy.
 
+Use native `read`, `grep`, `glob`, and `list` primitives for simple reads when
+the host provides them. Use shell/Bash for builds, tests, git, scripts, and
+system commands, not as the default filesystem API.
+
 Confirm scope, dependencies, candidate fingerprint, assignment ID, feature,
 attempt, expected branch, and PRD/card/gate hashes. Reject stale, missing,
 invalidated, or failed verifier evidence. Independently rerun enough required