triad-plus 1.8.0 → 1.10.0

package/runtime/triad-runtime-context.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { resolveAssignmentContext, validateAssignmentPacket } from "./lib/assignment-packet.mjs";
+import { inspectRepositoryContext } from "./lib/repository-context.mjs";
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  return index >= 0 ? argv[index + 1] : null;
+}
+
+function usage() {
+  process.stderr.write("Usage: node .triad-runtime/triad-runtime-context.mjs --project <control-workspace> --assignment <assignment.json>\n");
+}
+
+function issue(code, message) {
+  return { code, message };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  if (argv.includes("--help") || argv.includes("-h")) {
+    usage();
+    return;
+  }
+  const projectRoot = path.resolve(option(argv, "--project") ?? process.cwd());
+  const assignmentOption = option(argv, "--assignment");
+  if (!assignmentOption) throw Object.assign(new Error("--assignment is required"), { code: "runtime_context_invalid" });
+  const assignmentPath = path.resolve(projectRoot, assignmentOption);
+  const assignment = JSON.parse(await readFile(assignmentPath, "utf8"));
+  const output = {
+    status: "blocked",
+    assignment: {
+      id: assignment.assignment_id ?? null,
+      feature_id: assignment.feature_id ?? null,
+      attempt: assignment.attempt ?? null,
+      worktree: assignment.worktree ?? null,
+      packet_metadata_cwd: null
+    },
+    repository_mapping: null,
+    expected: null,
+    actual: null,
+    repository_skills: [],
+    issues: []
+  };
+  try {
+    const context = await resolveAssignmentContext(assignment, { projectRoot });
+    output.assignment.worktree = context.worktree;
+    output.repository_mapping = context.repositoryMapping;
+    output.expected = {
+      worktree: context.worktree,
+      git_top_level: context.repositoryContext.assigned_git_top_level,
+      repository: context.repository
+    };
+    if (assignment.assignment_packet_path || assignment.assignment_packet_sha256) {
+      const packet = await validateAssignmentPacket(assignment, projectRoot);
+      output.assignment.packet_metadata_cwd = packet.metadata.cwd ?? null;
+    }
+    const inspected = await inspectRepositoryContext({
+      worktree: context.worktree,
+      requiredSkills: context.requiredSkills,
+      actualCwd: process.cwd(),
+      checkActualCwd: true
+    });
+    output.actual = inspected.actual;
+    output.repository_skills = inspected.skills;
+    output.issues = inspected.issues;
+    output.status = inspected.status;
+  } catch (error) {
+    if (error.repositoryContext) {
+      output.actual = error.repositoryContext.actual ?? null;
+      output.repository_skills = error.repositoryContext.skills ?? [];
+      output.issues = error.repositoryContext.issues ?? [];
+    }
+    output.issues.push(issue(error.code ?? "runtime_context_invalid", error.message));
+  }
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+  if (output.status !== "pass") process.exitCode = 2;
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    process.stderr.write(`${error.code ? `${error.code}: ` : ""}${error.message}\n`);
+    process.exitCode = 2;
+  });
+}

package/runtime/triad-verify.mjs

@@ -8,6 +8,8 @@ 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";
+import { inspectRepositoryContext } from "./lib/repository-context.mjs";
 
 const argv = process.argv.slice(2);
 const option = (name) => {
@@ -34,23 +36,27 @@ async function sha256File(value) {
 }
 
 async function validateRepositorySkills(required, worktree) {
-  if (required === undefined) return { declared: false, skills: [] };
-  if (!Array.isArray(required) || required.length === 0) throw new Error("repository skill binding must declare at least one skill");
-  const root = await realpath(worktree);
-  const skills = [];
-  for (const item of required) {
-    if (!item || typeof item.path !== "string" || typeof item.sha256 !== "string") {
-      throw new Error("repository skill binding entries require path and sha256");
-    }
-    const candidate = path.resolve(root, item.path);
-    if (!candidate.startsWith(`${root}${path.sep}`)) throw new Error("repository skill path escapes worktree");
-    try { await access(candidate); }
-    catch { throw new Error(`repository skill missing: ${item.path}`); }
-    const actual = await sha256File(candidate);
-    if (actual !== item.sha256) throw new Error(`repository skill hash mismatch: ${item.path}`);
-    skills.push({ path: item.path, sha256: actual });
+  const declared = required !== undefined;
+  const requiredSkills = declared ? required : [];
+  const context = await inspectRepositoryContext({ worktree, requiredSkills });
+  if (!declared) return { declared: false, skills: [], context };
+  if (!Array.isArray(required) || required.length === 0) {
+    const error = new Error("repository skill binding must declare at least one skill");
+    error.code = "repository_context_invalid";
+    error.repositoryContext = context;
+    throw error;
+  }
+  if (context.status !== "pass") {
+    const error = new Error(context.issues.map((item) => item.message).join("; ") || "repository skill binding is invalid");
+    error.code = "repository_context_invalid";
+    error.repositoryContext = context;
+    throw error;
   }
-  return { declared: true, skills };
+  return {
+    declared: true,
+    skills: context.skills.map(({ path: relative, sha256 }) => ({ path: relative, sha256 })),
+    context
+  };
 }
 
 function triggerFrom(payload) {
@@ -70,7 +76,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, repositorySkills = null }) {
   const evidence = {
     schema_version: 1,
     run_id: runId,
@@ -86,6 +92,10 @@ 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),
+    ...(repositorySkills ? { repository_skills: repositorySkills } : {}),
     gates: [],
     required_gates_passed: false,
     status: "invalid_context",
@@ -154,6 +164,8 @@ async function main() {
   let outputPath;
   let gateSelection = null;
   let qualityBaseline = null;
+  let assignmentPacket = null;
+  let repositorySkills = null;
   try {
     let assignmentHash;
     ({ assignmentPath, assignment, assignmentHash } = await resolveAssignment(projectRoot, trigger, option("--assignment")));
@@ -167,19 +179,23 @@ 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).
     qualityBaseline = await resolveQualityContract(assignment, projectRoot);
     if ((await sha256File(prdPath)) !== assignment.expected_prd_sha256) throw new Error("PRD baseline hash mismatch");
     if ((await sha256File(cardPath)) !== assignment.expected_card_sha256) throw new Error("feature card hash mismatch");
-    const repositorySkills = await validateRepositorySkills(assignment.required_repository_skills, worktree);
+    repositorySkills = await validateRepositorySkills(assignment.required_repository_skills, worktree);
     const before = await calculateCandidateFingerprint(worktree);
     const branch = await worktreeBranch(worktree);
     if (assignment.expected_branch && assignment.expected_branch !== branch) throw new Error("worktree branch does not match assignment");
@@ -220,6 +236,7 @@ async function main() {
           candidate_fingerprint: before.value,
           branch,
         },
+        assignment_packet: assignmentPacket,
         repository_skills: repositorySkills,
         scope,
         gates: [],
@@ -257,6 +274,7 @@ async function main() {
         candidate_fingerprint: before.value,
         branch,
       },
+      assignment_packet: assignmentPacket,
       repository_skills: repositorySkills,
       scope,
       gate_selection: gateSelectionEvidence(gateSelection),
@@ -283,7 +301,9 @@ async function main() {
       outputPath,
       failureCode: error.code ?? "verification_context_invalid",
       gateSelection,
-      qualityBaselineFingerprint: qualityBaseline?.fingerprint ?? null
+      qualityBaselineFingerprint: qualityBaseline?.fingerprint ?? null,
+      assignmentPacket,
+      repositorySkills: repositorySkills ?? error.repositoryContext ?? null,
     });
     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
@@ -26,6 +37,20 @@ SHA-256 values in the report as a **repository-skill attestation**. If a bound
 skill is missing or its hash differs, stop and report the mismatch; do not
 replace it with external context or a similarly named skill.
 
+Before editing, prove the runtime context from the actual activation cwd with
+the installed control-plane diagnostic:
+
+```bash
+node /absolute/path/to/control-workspace/.triad-runtime/triad-runtime-context.mjs \
+  --project /absolute/path/to/control-workspace \
+  --assignment /absolute/path/to/control-workspace/.loop/runtime/assignments/<assignment-file>.json
+```
+
+Record its `process_cwd`, `shell_pwd`, `git_top_level`, assigned worktree, and
+resolved repository-skill paths/hashes. A non-zero result, a cwd/root mismatch,
+or a missing/mutated skill is an invalid runtime context; stop before editing
+and do not substitute a same-named control-workspace or global skill.
+
 Implement the smallest complete change and focused tests. Run useful local
 checks and measure declared criteria. Report changed files, tests, exact command
 results, metrics, worktree/branch, risks, and blockers to the Orchestrator.

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,48 @@ 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.
+   Require each delegated Developer and Reviewer to run the installed runtime
+   context diagnostic from its actual activation cwd before reading repository
+   skills:
+
+   ```bash
+   node /absolute/path/to/control-workspace/.triad-runtime/triad-runtime-context.mjs \
+     --project /absolute/path/to/control-workspace \
+     --assignment /absolute/path/to/control-workspace/.loop/runtime/assignments/<assignment-file>.json
+   ```
+
+   Collect its process `cwd`, shell `pwd`, Git top-level, repository mapping,
+   and resolved skill paths/hashes. A mismatch or missing skill blocks that role;
+   do not substitute control-workspace/global copies or continue to review.
+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 +175,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,26 @@ 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.
 
+Before inspecting the candidate, prove the actual Reviewer runtime context by
+running this command from the activation cwd:
+
+```bash
+node /absolute/path/to/control-workspace/.triad-runtime/triad-runtime-context.mjs \
+  --project /absolute/path/to/control-workspace \
+  --assignment /absolute/path/to/control-workspace/.loop/runtime/assignments/<assignment-file>.json
+```
+
+Record packet `cwd`, process `cwd`, `pwd`, `git rev-parse --show-toplevel`, and
+each repository-skill path, resolved path, and SHA-256. Compare the actual cwd
+and Git root with the assigned product worktree, and resolve every relative
+skill path under that worktree only. On `NotFound`, hash mismatch, mixed Git
+roots, or cwd inconsistency, return `blocked` / invalid runtime context; never
+fall back to a copy in the control workspace or a global skill.
+
+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