triad-plus 1.9.0 → 1.10.0

package/runtime/lib/model-config.mjs

@@ -0,0 +1,165 @@
+import { roleDefinitions } from '../../adapters/registry.mjs';
+
+const roleIds = new Set(roleDefinitions.map((role) => role.id));
+const modelFields = new Set(['model', 'reasoning_effort']);
+
+function nullableString(value, field) {
+  if (value === undefined || value === null) return;
+  if (typeof value !== 'string') throw new Error(`${field} must be a string or null.`);
+}
+
+function adapterModelRoles(adapter) {
+  return new Set(adapter?.modelRoles ?? roleDefinitions.map((role) => role.id));
+}
+
+function defaultSourceForHostField(field) {
+  return field === 'reasoningEffort' ? 'reasoning_effort' : field;
+}
+
+function hostValue(value) {
+  return typeof value === 'string' && !value.trim() ? null : value ?? null;
+}
+
+/**
+ * Return whether the selected host can materialize a model for this role.
+ * A team-record adapter still records the requested value in team.json, but
+ * deliberately returns false because it has no native file to update.
+ */
+export function supportsNativeModel(adapter, roleId) {
+  if (adapter?.modelBinding === 'global-profiles') return roleIds.has(roleId);
+  if (adapter?.modelBinding === 'project-frontmatter') return adapterModelRoles(adapter).has(roleId);
+  return false;
+}
+
+/** Return whether the selected host exposes a native reasoning field. */
+export function supportsNativeReasoning(adapter, roleId) {
+  if (!supportsNativeModel(adapter, roleId)) return false;
+  if (adapter?.modelBinding === 'global-profiles') return true;
+  return modelFieldMappings(adapter, roleId).some(({ source }) => source === 'reasoning_effort');
+}
+
+/**
+ * Describe the one-way mapping from canonical team.json fields to the
+ * host-native fields managed in a role asset. The adapter registry is the
+ * only place that chooses host names; callers never infer them by analogy.
+ */
+export function modelFieldMappings(adapter, roleId) {
+  if (!supportsNativeModel(adapter, roleId) || adapter?.modelBinding !== 'project-frontmatter') return [];
+  const fields = Array.isArray(adapter?.modelFields) && adapter.modelFields.length ? adapter.modelFields : ['model'];
+  const sources = adapter?.modelFieldSources ?? {};
+  return fields.map((field) => ({ field, source: sources[field] ?? defaultSourceForHostField(field) }));
+}
+
+/** Return the host field used for a canonical semantic field, if any. */
+export function hostModelField(adapter, roleId, source) {
+  return modelFieldMappings(adapter, roleId).find((mapping) => mapping.source === source)?.field ?? null;
+}
+
+/**
+ * Describe how a role's requested configuration is handled by the adapter.
+ * This is presentation metadata; team.json remains authoritative in every
+ * mode.
+ */
+export function modelBindingSummary(adapter, roleId) {
+  if (adapter?.modelBinding === 'team-record') return 'recorded in team.json (host-native binding unavailable)';
+  if (!supportsNativeModel(adapter, roleId)) return 'recorded in team.json (role field unsupported by host)';
+  if (supportsNativeReasoning(adapter, roleId)) {
+    // Global profile adapters expose their native effort field through the
+    // profile writer rather than project frontmatter metadata.
+    return `host-native model + ${hostModelField(adapter, roleId, 'reasoning_effort') ?? 'reasoning'}`;
+  }
+  return 'host-native model; reasoning is host-managed';
+}
+
+/**
+ * Validate a complete schema-version-1 team configuration without changing or
+ * stripping fields. Unknown fields remain forward-compatible and are
+ * preserved; malformed model values fail closed before installation/upgrade.
+ */
+export function validateTeamConfiguration(team) {
+  if (!team || typeof team !== 'object' || Array.isArray(team)) throw new Error('team config must be an object.');
+  if (team.schema_version !== 1) throw new Error('team config must contain schema_version 1.');
+  if (!team.interaction || typeof team.interaction !== 'object' || Array.isArray(team.interaction)) {
+    throw new Error('team config must contain interaction.');
+  }
+  if (!team.roles || typeof team.roles !== 'object' || Array.isArray(team.roles)) {
+    throw new Error('team config must contain roles.');
+  }
+  for (const role of roleDefinitions) {
+    const configuration = team.roles[role.id];
+    if (!configuration || typeof configuration !== 'object' || Array.isArray(configuration)) {
+      throw new Error(`team config has an invalid ${role.id} role definition.`);
+    }
+    if (typeof configuration.displayName !== 'string' || !configuration.displayName.trim()) {
+      throw new Error(`team config has an invalid ${role.id} displayName.`);
+    }
+    nullableString(configuration.model, `${role.id}.model`);
+    nullableString(configuration.reasoning_effort, `${role.id}.reasoning_effort`);
+    if (configuration.enabled !== undefined && typeof configuration.enabled !== 'boolean') {
+      throw new Error(`team config has an invalid ${role.id}.enabled value.`);
+    }
+  }
+  return team;
+}
+
+/**
+ * Validate a user-requested native model patch. This intentionally rejects
+ * unknown fields and fields the selected host cannot materialize. Callers
+ * that only want to record intent should use team.json directly and report
+ * the adapter's modelBindingSummary instead of pretending native support.
+ */
+export function validateRequestedModelPatch(adapter, roleId, patch) {
+  if (!roleIds.has(roleId)) throw new Error(`Unknown Triad role: ${roleId}.`);
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('model patch must be an object.');
+  for (const field of Object.keys(patch)) {
+    if (!modelFields.has(field)) throw new Error(`Unsupported model configuration field: ${field}.`);
+    nullableString(patch[field], `${roleId}.${field}`);
+    if (field === 'model' && !supportsNativeModel(adapter, roleId)) {
+      throw new Error(`Model binding is not natively supported for ${adapter?.id ?? 'the selected host'} role ${roleId}.`);
+    }
+    if (field === 'reasoning_effort' && !supportsNativeReasoning(adapter, roleId)) {
+      throw new Error(`Reasoning effort is not natively supported for ${adapter?.id ?? 'the selected host'} role ${roleId}.`);
+    }
+  }
+  return patch;
+}
+
+/**
+ * Apply an explicitly requested model/reasoning patch to an in-memory team
+ * document while preserving every unrelated field. Callers still decide when
+ * to persist the returned document and must use the adapter binding afterwards.
+ */
+export function mergeTeamModelConfiguration(team, roleId, patch) {
+  validateTeamConfiguration(team);
+  if (!roleIds.has(roleId)) throw new Error(`Unknown Triad role: ${roleId}.`);
+  if (!patch || typeof patch !== 'object' || Array.isArray(patch)) throw new Error('model patch must be an object.');
+  for (const field of Object.keys(patch)) {
+    if (!modelFields.has(field)) throw new Error(`Unsupported model configuration field: ${field}.`);
+    nullableString(patch[field], `${roleId}.${field}`);
+  }
+  const updated = structuredClone(team);
+  Object.assign(updated.roles[roleId], patch);
+  return updated;
+}
+
+/** Return only fields that the adapter can materialize in host-managed assets. */
+export function materializedRoleConfiguration(adapter, roleId, configuration = {}) {
+  const result = {};
+  if (supportsNativeModel(adapter, roleId)) result.model = hostValue(configuration.model);
+  if (supportsNativeReasoning(adapter, roleId)) result.reasoning_effort = hostValue(configuration.reasoning_effort);
+  return result;
+}
+
+/**
+ * Translate canonical semantic values into the exact host fields declared by
+ * the adapter. Null values are retained so the managed writer can remove a
+ * stale host binding and restore the host default.
+ */
+export function materializedHostRoleConfiguration(adapter, roleId, configuration = {}) {
+  const semantic = materializedRoleConfiguration(adapter, roleId, configuration);
+  const result = {};
+  for (const { field, source } of modelFieldMappings(adapter, roleId)) {
+    result[field] = semantic[source] ?? null;
+  }
+  return result;
+}

package/runtime/lib/repository-context.mjs

@@ -0,0 +1,192 @@
+import { createHash } from "node:crypto";
+import { realpath, stat, readFile } from "node:fs/promises";
+import path from "node:path";
+import { runProcess } from "./process.mjs";
+
+const SHA256 = /^[a-f0-9]{64}$/i;
+
+function contextError(message, code = "repository_context_invalid") {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function inside(root, candidate) {
+  return candidate === root || candidate.startsWith(`${root}${path.sep}`);
+}
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+/**
+ * Required repository skills are deliberately worktree-relative. Reject
+ * absolute paths and parent traversal instead of allowing a caller to combine
+ * files from the control workspace or another repository root.
+ */
+export function repositoryRelativePath(value, label = "repository skill path") {
+  if (typeof value !== "string" || !value.trim()) throw contextError(`${label} must be a non-empty repository-relative path`);
+  const normalized = value.trim().replaceAll("\\", "/");
+  if (path.posix.isAbsolute(normalized) || path.win32.isAbsolute(normalized)) {
+    throw contextError(`${label} must be repository-relative`);
+  }
+  const segments = normalized.split("/");
+  if (segments.includes("..") || segments.includes("")) {
+    throw contextError(`${label} must not contain parent traversal or empty path segments`);
+  }
+  return normalized;
+}
+
+async function gitTopLevel(cwd) {
+  const result = await runProcess("git", ["rev-parse", "--show-toplevel"], { cwd, timeoutMs: 15_000 });
+  if (result.exitCode !== 0) return null;
+  const value = result.stdout.trim();
+  if (!value) return null;
+  return realpath(value).catch(() => path.resolve(value));
+}
+
+async function shellPwd(cwd) {
+  const result = await runProcess("pwd", [], { cwd, timeoutMs: 15_000 });
+  return result.exitCode === 0 ? result.stdout.trim() || null : null;
+}
+
+function issue(code, message, details = {}) {
+  return { code, message, ...details };
+}
+
+/**
+ * Inspect the repository context bound to an assignment. This is intentionally
+ * read-only and host-neutral: it proves the assigned worktree, its Git root,
+ * and every required skill's real path/hash. `checkActualCwd` is used by a
+ * role activation; verifier/packet creation leave it false because they run
+ * from the control workspace and must not mistake that process cwd for the
+ * delegated role cwd.
+ */
+export async function inspectRepositoryContext({
+  worktree,
+  requiredSkills = [],
+  actualCwd = null,
+  checkActualCwd = false
+} = {}) {
+  if (typeof worktree !== "string" || !worktree.trim()) throw contextError("assigned worktree is required");
+  if (!Array.isArray(requiredSkills)) throw contextError("required repository skills must be an array");
+  const assignedWorktree = await realpath(worktree).catch(() => {
+    throw contextError(`assigned worktree is missing: ${worktree}`);
+  });
+  const assignedGitTopLevel = await gitTopLevel(assignedWorktree);
+  const issues = [];
+  if (!assignedGitTopLevel) {
+    issues.push(issue("assigned_repository_not_git", "assigned worktree has no resolvable Git top-level", {
+      assigned_worktree: assignedWorktree
+    }));
+  } else if (assignedGitTopLevel !== assignedWorktree) {
+    issues.push(issue("assigned_worktree_not_repository_root", "assigned worktree is not the repository Git top-level", {
+      assigned_worktree: assignedWorktree,
+      assigned_git_top_level: assignedGitTopLevel
+    }));
+  }
+
+  const skills = [];
+  const seen = new Set();
+  for (const [index, item] of requiredSkills.entries()) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      issues.push(issue("invalid_repository_skill_binding", "repository skill binding must be an object", { index }));
+      continue;
+    }
+    let relative;
+    try { relative = repositoryRelativePath(item.path, `repository skill [${index}] path`); }
+    catch (error) {
+      issues.push(issue("invalid_repository_skill_path", error.message, { index, path: item.path ?? null }));
+      continue;
+    }
+    if (seen.has(relative)) {
+      issues.push(issue("duplicate_repository_skill", `repository skill is declared more than once: ${relative}`, { path: relative }));
+      continue;
+    }
+    seen.add(relative);
+    if (typeof item.sha256 !== "string" || !SHA256.test(item.sha256)) {
+      issues.push(issue("invalid_repository_skill_hash", `repository skill requires a SHA-256 hash: ${relative}`, { path: relative }));
+      continue;
+    }
+    const lexical = path.resolve(assignedWorktree, relative);
+    if (!inside(assignedWorktree, lexical)) {
+      issues.push(issue("repository_skill_outside_worktree", `repository skill escapes assigned worktree: ${relative}`, { path: relative }));
+      continue;
+    }
+    let resolved;
+    try { resolved = await realpath(lexical); }
+    catch {
+      issues.push(issue("repository_skill_missing", `repository skill missing: ${relative}`, { path: relative, resolved_path: lexical }));
+      continue;
+    }
+    if (!inside(assignedWorktree, resolved)) {
+      issues.push(issue("repository_skill_symlink_escape", `repository skill resolves outside assigned worktree: ${relative}`, { path: relative, resolved_path: resolved }));
+      continue;
+    }
+    try {
+      if (!(await stat(resolved)).isFile()) throw new Error("not a regular file");
+    } catch {
+      issues.push(issue("repository_skill_not_file", `repository skill is not a regular file: ${relative}`, { path: relative, resolved_path: resolved }));
+      continue;
+    }
+    const actual = digest(await readFile(resolved));
+    const skillGitTopLevel = await gitTopLevel(path.dirname(resolved));
+    const entry = {
+      path: relative,
+      resolved_path: resolved,
+      sha256: actual,
+      repository_root: skillGitTopLevel
+    };
+    skills.push(entry);
+    if (actual.toLowerCase() !== item.sha256.toLowerCase()) {
+      issues.push(issue("repository_skill_hash_mismatch", `repository skill hash mismatch: ${relative}`, {
+        path: relative,
+        expected_sha256: item.sha256,
+        actual_sha256: actual
+      }));
+    }
+    if (assignedGitTopLevel && skillGitTopLevel !== assignedGitTopLevel) {
+      issues.push(issue("repository_skill_root_mismatch", `repository skill belongs to a different Git root: ${relative}`, {
+        path: relative,
+        skill_repository_root: skillGitTopLevel,
+        assigned_git_top_level: assignedGitTopLevel
+      }));
+    }
+  }
+
+  let actual = null;
+  if (checkActualCwd) {
+    const requested = actualCwd || process.cwd();
+    const resolved = await realpath(requested).catch(() => path.resolve(requested));
+    const gitRoot = await gitTopLevel(resolved);
+    actual = {
+      process_cwd: process.cwd(),
+      shell_pwd: await shellPwd(process.cwd()),
+      resolved_cwd: resolved,
+      git_top_level: gitRoot
+    };
+    if (resolved !== assignedWorktree) {
+      issues.push(issue("runtime_cwd_mismatch", "role process cwd does not match assigned worktree", {
+        expected_worktree: assignedWorktree,
+        actual_cwd: resolved
+      }));
+    }
+    if (assignedGitTopLevel && gitRoot !== assignedGitTopLevel) {
+      issues.push(issue("runtime_git_root_mismatch", "role process Git top-level does not match assigned repository", {
+        expected_git_top_level: assignedGitTopLevel,
+        actual_git_top_level: gitRoot
+      }));
+    }
+  }
+
+  return {
+    status: issues.length ? "blocked" : "pass",
+    assigned_worktree: assignedWorktree,
+    assigned_git_top_level: assignedGitTopLevel,
+    actual,
+    skills,
+    issues
+  };
+}
+
+export { SHA256 };

package/runtime/lib/terminal.mjs

@@ -0,0 +1,86 @@
+import { roleDefinitions } from '../../adapters/registry.mjs';
+import { hostModelField, modelBindingSummary, supportsNativeReasoning } from './model-config.mjs';
+
+const ANSI = {
+  reset: '\u001b[0m',
+  bold: '\u001b[1m',
+  dim: '\u001b[2m',
+  cyan: '\u001b[36m',
+  blue: '\u001b[34m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  red: '\u001b[31m'
+};
+
+const toneCodes = {
+  title: `${ANSI.bold}${ANSI.cyan}`,
+  section: `${ANSI.bold}${ANSI.blue}`,
+  value: ANSI.bold,
+  success: ANSI.green,
+  warning: ANSI.yellow,
+  error: ANSI.red,
+  hint: ANSI.dim
+};
+
+export function colorEnabled(stream = process.stdout) {
+  return Boolean(stream?.isTTY) && process.env.NO_COLOR === undefined;
+}
+
+export function paint(value, tone, { stream = process.stdout } = {}) {
+  const text = String(value);
+  if (!colorEnabled(stream) || !toneCodes[tone]) return text;
+  return `${toneCodes[tone]}${text}${ANSI.reset}`;
+}
+
+export function statusText(status, { stream = process.stdout } = {}) {
+  const normalized = String(status).toLowerCase();
+  if (['ok', 'pass', 'passed', 'configured', 'installed', 'enabled'].includes(normalized) || /^ok\b/.test(normalized)) return paint(status, 'success', { stream });
+  if (['warning', 'warn', 'disabled', 'not configured', 'not installed', 'unavailable', 'host default'].includes(normalized) || normalized.startsWith('not installed') || normalized.startsWith('host rule detected')) return paint(status, 'warning', { stream });
+  if (['error', 'fail', 'failed', 'invalid', 'incomplete', 'missing'].includes(normalized) || normalized.startsWith('missing ') || normalized.startsWith('invalid ')) return paint(status, 'error', { stream });
+  return String(status);
+}
+
+function display(value, fallback = 'host default') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function roleModelLine(adapter, role, configuration, stream) {
+  const model = display(configuration?.model);
+  const parts = [`${role.label.padEnd(14)} ${display(configuration?.displayName, role.label)} — model: ${model}`];
+  if (supportsNativeReasoning(adapter, role.id)) {
+    const field = hostModelField(adapter, role.id, 'reasoning_effort');
+    parts.push(`${field === 'variant' ? 'variant' : 'reasoning'}: ${display(configuration?.reasoning_effort)}`);
+  }
+  parts.push(`binding: ${modelBindingSummary(adapter, role.id)}`);
+  return `  ${parts.join(' — ')}`;
+}
+
+/** Render the compact confirmation shown before the interactive install. */
+export function formatSetupSummary({ adapter, control, global = false, team, stream = process.stdout }) {
+  const interaction = team?.interaction ?? {};
+  const lines = [
+    paint('Triad+ setup summary', 'title', { stream }),
+    `${paint('Host', 'section', { stream })}: ${paint(`${adapter.label} (${adapter.id})`, 'value', { stream })}`,
+    `${paint('Control workspace', 'section', { stream })}: ${control}`,
+    `${paint('User-level assets', 'section', { stream })}: ${global ? 'yes' : 'no'}`,
+    `${paint('Interaction', 'section', { stream })}: ${display(interaction.language, 'English')} — owner ${display(interaction.owner_name, 'Owner')} — ${display(interaction.communication_style, 'professional and concise')}`,
+    `${paint('Evaluator+', 'section', { stream })}: ${team?.roles?.evaluator?.enabled === true ? statusText('enabled', { stream }) : statusText('disabled', { stream })}`,
+    paint('Roles', 'section', { stream }),
+    ...roleDefinitions.map((role) => roleModelLine(adapter, role, team?.roles?.[role.id], stream)),
+    paint('Confirm installation', 'section', { stream })
+  ];
+  return `${lines.join('\n')}\n`;
+}
+
+/** Render a doctor row while preserving scanner-friendly plain text. */
+export function formatDoctorLine(label, status, { stream = process.stdout } = {}) {
+  return `${label.padEnd(14)} ${statusText(status, { stream })}`;
+}
+
+export function formatDoctorSection(title, { stream = process.stdout } = {}) {
+  return paint(title, 'section', { stream });
+}
+
+export function formatModelValue(value) {
+  return display(value);
+}

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

@@ -9,6 +9,7 @@ import { executeGates, gateSelectionEvidence, loadTrustedGates, resolveGateSelec
 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) => {
@@ -35,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) {
@@ -71,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, assignmentPacket = 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,
@@ -90,6 +95,7 @@ async function buildInvalidEvidence({ runId, trigger, assignment, reason, output
     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",
@@ -159,6 +165,7 @@ async function main() {
   let gateSelection = null;
   let qualityBaseline = null;
   let assignmentPacket = null;
+  let repositorySkills = null;
   try {
     let assignmentHash;
     ({ assignmentPath, assignment, assignmentHash } = await resolveAssignment(projectRoot, trigger, option("--assignment")));
@@ -188,7 +195,7 @@ async function main() {
     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");
@@ -296,6 +303,7 @@ async function main() {
       gateSelection,
       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/skills/triad-loop-developer/SKILL.md

@@ -37,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

@@ -128,6 +128,19 @@ fail-closed escalation; do not dispatch a Developer or consume retry budget.
    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