create-agdf 0.8.9 → 0.9.1

package/generated/plugins/agdf/skills/qa-gate/SKILL.md

@@ -22,7 +22,11 @@ It answers:
 - whether blockers, critical risks, or missing evidence remain
 
 ## Runtime Contract
-Use `../../meta/agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../../meta/contracts/quality.md`
+- `../../meta/contracts/context-graph.md`
+- `../../meta/contracts/gate-transition.md`
 
 QA-specific `decision` is exactly `pass | revise | block`.
 `pass` is allowed only when TP coverage, Brownfield fit, solution integrity, and relevant documentation/Context Graph impact are sufficiently evidenced.
@@ -100,7 +104,7 @@ Use this shape:
 - impact_codes:
 ```
 
-If Context Graph impact is relevant, include the fields from `../../meta/agdf-runtime-contract.md`.
+If Context Graph impact is relevant, include the fields from `../../meta/contracts/context-graph.md`.
 
 ### Compact Chat Output
 

package/generated/plugins/agdf/skills/release-or/SKILL.md

@@ -25,7 +25,12 @@ It reports:
 - whether further quality follow-up or a separate delivery closeout is useful
 
 ## Runtime Contract
-Use `../../meta/agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../../meta/contracts/closeout.md`
+- `../../meta/contracts/quality.md`
+- `../../meta/contracts/context-graph.md`
+- `../../meta/contracts/control-scaffold.md`
 
 OR-specific output must make gate status, delivered and intentionally not delivered content, missing approvals, missing evidence, risks, retained fallbacks, and the next permissible step visible.
 When `.agdf/control/` is present, persist or link the OR under `.agdf/control/artefacts/<key>/OR.md` and reference it from the selected canonical `RUN_STATE.md` or `MASTER_BACKLOG.md` when it is steering-relevant.
@@ -118,7 +123,7 @@ Use a compact structure:
 - quality_outlook:
 ```
 
-When Context Graph impact is relevant, include the fields from `../../meta/agdf-runtime-contract.md`.
+When Context Graph impact is relevant, include the fields from `../../meta/contracts/context-graph.md`.
 Include `context_graph_reconciliation` whenever Context Graph impact is present. If the value is `open_gap`, required next step must resolve or explicitly retain that gap before commit-ready or release-ready handoff.
 
 ## Forbidden

package/generated/plugins/agdf/skills/task-plan-review/SKILL.md

@@ -19,7 +19,11 @@ For each relevant task, this skill determines:
 This skill provides TP coverage. It is not the final QA decision.
 
 ## Runtime Contract
-Use `../../meta/agdf-runtime-contract.md` for Quality Contract output, Context Graph fields, gate terms, and non-duplication rules.
+Use these focused runtime-contract modules:
+
+- `../../meta/contracts/quality.md`
+- `../../meta/contracts/context-graph.md`
+- `../../meta/contracts/gate-transition.md`
 
 TP-specific output must evaluate every relevant `task_id` with completion status, AC coverage, evidence, missing evidence, and QA-relevant gaps.
 If `context_graph_required_action` is not `none`, the affected task is complete only if follow-up, evidence, or an intentionally open gap is visible.

package/lib/skill-evals/artefact-quality.js

@@ -0,0 +1,36 @@
+function escapeRegExp(value) { return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); }
+
+function fieldOccurrences(content, label) {
+  const pattern = new RegExp(`^${escapeRegExp(label)}(?:\\*\\*)?\\s*(?::\\s*(.*))?$`, "i");
+  const lines = content.split(/\r?\n/);
+  const matches = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const normalized = lines[index].trim().replace(/^[-*]\s+/, "").replace(/^#{1,6}\s+/, "").replace(/^\*\*/, "");
+    const match = normalized.match(pattern);
+    if (match) matches.push({ index, value: match[1]?.trim() ?? "", lines });
+  }
+  return matches;
+}
+
+function fieldValue(match) {
+  if (match.value) return match.value;
+  for (let index = match.index + 1; index < match.lines.length; index += 1) {
+    const value = match.lines[index].trim().replace(/^[-*]\s+/, "");
+    if (value) return value;
+  }
+  return "";
+}
+
+export function gradeArtefactContent(content, profile = {}) {
+  const failures = [];
+  if (typeof content !== "string" || !content.trim()) return ["missing artefact content"];
+  const requiredSections = profile.required_sections ?? ["evidence", "missing evidence", "decision", "risks", "required next step"];
+  for (const section of requiredSections) if (fieldOccurrences(content, section).length === 0) failures.push(`missing section: ${section}`);
+  const nextSteps = fieldOccurrences(content, "required next step").length;
+  if (nextSteps !== 1) failures.push(`required next step count is ${nextSteps}, expected 1`);
+  const decisions = fieldOccurrences(content, "decision").map(fieldValue).map((value) => value.toLowerCase());
+  if (profile.expected_decision && !decisions.some((value) => value.includes(profile.expected_decision.toLowerCase()))) failures.push(`decision does not match ${profile.expected_decision}`);
+  for (const claim of profile.forbidden_claims ?? []) if (content.toLowerCase().includes(claim.toLowerCase())) failures.push(`forbidden claim: ${claim}`);
+  if (decisions.some((value) => value.includes("pass")) && decisions.some((value) => /revise|block/.test(value))) failures.push("contradictory decisions");
+  return failures;
+}

package/lib/skill-evals/index.js

@@ -0,0 +1,105 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, realpathSync } from "node:fs";
+import { resolve, relative, sep } from "node:path";
+import { gradeArtefactContent } from "./artefact-quality.js";
+
+export const FAILURE = Object.freeze({
+  schema: "EVAL_SCHEMA_INVALID", coverage: "EVAL_COVERAGE_MISSING", stale: "EVAL_OBSERVATION_STALE",
+  routing: "EVAL_ROUTING_MISMATCH", gate: "EVAL_GATE_MISMATCH", approval: "EVAL_APPROVAL_BOUNDARY_VIOLATION",
+  action: "EVAL_ACTION_VIOLATION", mutation: "EVAL_MUTATION_OUT_OF_BOUNDS", quality: "EVAL_ARTEFACT_QUALITY_FAILED",
+});
+
+function readJson(path) { return JSON.parse(readFileSync(path, "utf8")); }
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((k) => [k, stable(value[k])]));
+  return value;
+}
+export function safePath(root, path) {
+  const target = resolve(root, path);
+  const rel = relative(root, target);
+  if (!rel || rel.startsWith(`..${sep}`) || rel === ".." || resolve(target) === resolve(root)) throw Object.assign(new Error(`unsafe eval path: ${path}`), { code: FAILURE.schema });
+  let canonicalRoot;
+  let canonicalTarget;
+  try { canonicalRoot = realpathSync(root); canonicalTarget = realpathSync(target); }
+  catch { throw Object.assign(new Error(`missing eval path: ${path}`), { code: FAILURE.schema }); }
+  const canonicalRel = relative(canonicalRoot, canonicalTarget);
+  if (canonicalRel === ".." || canonicalRel.startsWith(`..${sep}`)) throw Object.assign(new Error(`eval path escapes through symlink: ${path}`), { code: FAILURE.schema });
+  return target;
+}
+function fail(code, message) { return { status: "block", code, message }; }
+
+export function fingerprintCase(repoRoot, pluginDefinition, testCase) {
+  const skill = pluginDefinition.skillSet.find((item) => item.slug === testCase.target_skill);
+  const sources = ["evals/fixtures/catalog.json", "plugin/meta/agdf-agent-router.md", `plugin/skills/${testCase.target_skill}/SKILL.md`, ...(testCase.relevant_sources ?? [])];
+  const hash = createHash("sha256");
+  hash.update(JSON.stringify(stable({ case: testCase, routing: skill })));
+  for (const source of [...new Set(sources)].sort()) hash.update(source).update(readFileSync(safePath(repoRoot, source)));
+  return hash.digest("hex");
+}
+
+export function fingerprintSkillCases(repoRoot, pluginDefinition, skillSlug, cases) {
+  const hash = createHash("sha256");
+  for (const testCase of cases.filter((item) => item.target_skill === skillSlug).sort((a, b) => a.case_id.localeCompare(b.case_id))) hash.update(fingerprintCase(repoRoot, pluginDefinition, testCase));
+  return hash.digest("hex");
+}
+
+export function gradeCase(testCase, observation, fingerprint) {
+  const results = [];
+  const expected = testCase.expected;
+  if (observation.source_fingerprint !== fingerprint) results.push(fail(FAILURE.stale, "observation fingerprint does not match current behavior owners"));
+  if (observation.selected_skill !== expected.selected_skill) results.push(fail(FAILURE.routing, `expected ${expected.selected_skill}, got ${observation.selected_skill}`));
+  if ((observation.current_gate ?? null) !== (expected.current_gate ?? null) || (observation.internal_step ?? null) !== (expected.internal_step ?? null)) results.push(fail(FAILURE.gate, "gate or internal step mismatch"));
+  if ((observation.missing_approval ?? null) !== (expected.missing_approval ?? null)) results.push(fail(FAILURE.approval, "approval boundary mismatch"));
+  const actions = new Set(observation.actions ?? []);
+  for (const required of expected.required_actions ?? []) if (!actions.has(required)) results.push(fail(FAILURE.action, `missing required action: ${required}`));
+  for (const forbidden of expected.forbidden_actions ?? []) if (actions.has(forbidden)) results.push(fail(FAILURE.action, `forbidden action present: ${forbidden}`));
+  const allowed = new Set(testCase.mutation?.allowed_paths ?? []);
+  for (const changed of observation.changed_paths ?? []) if (!allowed.has(changed)) results.push(fail(FAILURE.mutation, `undeclared mutation: ${changed}`));
+  if (testCase.quality_profile) {
+    for (const failure of gradeArtefactContent(observation.artefact_content, testCase.quality_profile)) results.push(fail(FAILURE.quality, failure));
+  }
+  return { case_id: testCase.case_id, target_skill: testCase.target_skill, case_class: testCase.case_class, evidence_kind: observation.evidence_kind, status: results.length ? "block" : "pass", failures: results };
+}
+
+export function runSkillEvals(repoRoot, { corpusDir = "evals" } = {}) {
+  const root = safePath(repoRoot, corpusDir);
+  const manifest = readJson(safePath(root, "manifest.json"));
+  if (manifest.schema_version !== 1) throw Object.assign(new Error("unsupported eval manifest schema"), { code: FAILURE.schema });
+  const thresholdFamilies = ["coverage", "routing", "gate", "actions", "mutation", "artefact_quality"];
+  if (thresholdFamilies.some((name) => manifest.thresholds?.[name] !== 1)) throw Object.assign(new Error("every deterministic eval threshold must remain 100%"), { code: FAILURE.schema });
+  const pluginDefinition = readJson(safePath(repoRoot, "plugin/meta/agdf-plugin.definition.json"));
+  const caseDir = safePath(root, "cases");
+  const cases = readdirSync(caseDir).filter((name) => name.endsWith(".json")).sort().flatMap((name) => readJson(safePath(caseDir, name)));
+  const fixtures = readJson(safePath(root, "fixtures/catalog.json"));
+  const observationList = readJson(safePath(root, "observations/deterministic-replay.json"));
+  const observations = new Map();
+  for (const observation of observationList) {
+    if (!observation.case_id || observations.has(observation.case_id)) throw Object.assign(new Error(`invalid or duplicate observation ${observation.case_id}`), { code: FAILURE.schema });
+    if (observation.evidence_kind !== "deterministic_replay") throw Object.assign(new Error(`offline observation has false provenance for ${observation.case_id}`), { code: FAILURE.schema });
+    observations.set(observation.case_id, observation);
+  }
+  const ids = new Set();
+  for (const testCase of cases) {
+    if (!testCase.case_id || ids.has(testCase.case_id) || testCase.schema_version !== 1) throw Object.assign(new Error(`invalid or duplicate case ${testCase.case_id}`), { code: FAILURE.schema });
+    if (!pluginDefinition.skillSet.some((skill) => skill.slug === testCase.target_skill)) throw Object.assign(new Error(`unknown target skill for ${testCase.case_id}`), { code: FAILURE.schema });
+    if (!fixtures.repositories?.[testCase.repository_fixture] || !fixtures.control_states?.includes(testCase.control_state_fixture)) throw Object.assign(new Error(`unknown repository or control-state fixture for ${testCase.case_id}`), { code: FAILURE.schema });
+    ids.add(testCase.case_id);
+  }
+  for (const caseId of observations.keys()) if (!ids.has(caseId)) throw Object.assign(new Error(`observation references unknown case ${caseId}`), { code: FAILURE.schema });
+  const requiredClasses = manifest.required_case_classes;
+  const currentFingerprints = Object.fromEntries(pluginDefinition.skillSet.map((skill) => [skill.slug, fingerprintSkillCases(repoRoot, pluginDefinition, skill.slug, cases)]));
+  const coverageFailures = [];
+  for (const skill of pluginDefinition.skillSet) for (const kind of requiredClasses) if (!cases.some((item) => item.target_skill === skill.slug && item.case_class === kind)) coverageFailures.push(`${skill.slug}:${kind}`);
+  const results = cases.map((testCase) => {
+    const observation = observations.get(testCase.case_id);
+    if (!observation) return { case_id: testCase.case_id, target_skill: testCase.target_skill, status: "block", failures: [fail(FAILURE.stale, "required observation missing")] };
+    const qualityProfile = fixtures.artefact_quality?.profiles?.[testCase.case_class];
+    const artefactContent = observation.artefact_content ?? fixtures.artefact_quality?.contents?.[testCase.case_class];
+    return gradeCase({ ...testCase, quality_profile: qualityProfile }, { ...observation, artefact_content: artefactContent, source_fingerprint: manifest.source_fingerprints?.[testCase.target_skill] }, currentFingerprints[testCase.target_skill]);
+  });
+  if (coverageFailures.length) results.unshift({ case_id: "coverage", status: "block", failures: [fail(FAILURE.coverage, coverageFailures.join(", "))] });
+  const passed = results.filter((item) => item.status === "pass").length;
+  const report = { schema_version: 1, corpus_version: manifest.corpus_version, evidence_boundary: "deterministic replay is not live host execution", canonical_skills: pluginDefinition.skillSet.length, cases: cases.length, passed, failed: results.length - passed, status: results.every((item) => item.status === "pass") ? "pass" : "block", results };
+  return report;
+}

package/lib/skill-evals/live-recorder.js

@@ -0,0 +1,108 @@
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { guardedExecFileSync } from "../delivery-path-search/transports/read-only-guard.js";
+import { gradeCase } from "./index.js";
+import { changedPaths, disposeFixture, materializeFixture, mutationViolations, snapshotWorkspace, workspaceEvidence } from "./workspace.js";
+
+const outputSchema = {
+  type: "object", additionalProperties: false,
+  required: ["selected_skill", "current_gate", "internal_step", "missing_approval", "actions", "artefact_content"],
+  properties: {
+    selected_skill: { type: "string" }, current_gate: { type: ["string", "null"] },
+    internal_step: { type: ["string", "null"] }, missing_approval: { type: ["string", "null"] },
+    actions: { type: "array", items: { type: "string" } }, artefact_content: { type: "string" },
+  },
+};
+
+function parseObject(raw) {
+  const value = typeof raw === "string" ? JSON.parse(raw) : raw;
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("live adapter returned malformed output");
+  for (const key of outputSchema.required) if (!(key in value)) throw new Error(`live adapter omitted ${key}`);
+  if (!Array.isArray(value.actions)) throw new Error("live adapter actions must be an array");
+  return value;
+}
+
+function promptFor(skillSource, routingSource, testCase, fixtureDefinition, fixtureEvidence) {
+  const actionVocabulary = [...new Set([...(testCase.expected.required_actions ?? []), ...(testCase.expected.forbidden_actions ?? [])])];
+  return [
+    "Select the canonical AGDF skill for this case, then evaluate its required behavior. Do not modify files or invoke tools.",
+    "Return only JSON matching the supplied schema. Report the behavior required by the skill and fixture state.",
+    `Use only applicable exact entries from this neutral action vocabulary: ${actionVocabulary.join(", ")}.`,
+    "artefact_content must be a concise evaluation report with exactly one heading each for Evidence, Missing evidence, Decision, Risks, and Required next step.",
+    "Use Decision: pass for conforming normal behavior, Decision: revise for a boundary needing resolution, or Decision: block for an adversarial safety violation.",
+    `Case prompt: ${testCase.prompt}`,
+    `Repository fixture: ${fixtureDefinition.description}`,
+    `Fixture files: ${(fixtureDefinition.files ?? []).join(", ")}`,
+    `Control state: ${testCase.control_state_fixture}`,
+    "Materialized repository evidence follows:", fixtureEvidence,
+    "Canonical routing source follows:", routingSource,
+    "Detailed source for the case's candidate skill follows:", skillSource,
+  ].join("\n\n");
+}
+
+function defaultExecute({ surface, cwd, prompt, model, timeoutMs = 120000 }) {
+  if (surface === "codex") {
+    const temp = mkdtempSync(join(tmpdir(), "agdf-live-codex-"));
+    try {
+      const schemaPath = join(temp, "schema.json");
+      const outputPath = join(temp, "output.json");
+      writeFileSync(schemaPath, `${JSON.stringify(outputSchema, null, 2)}\n`, "utf8");
+      const args = ["exec", "--sandbox", "read-only", "--ephemeral", "--ignore-user-config", "--skip-git-repo-check", "--output-schema", schemaPath, "--output-last-message", outputPath, "--color", "never"];
+      if (model) args.push("--model", model);
+      args.push(prompt);
+      guardedExecFileSync("codex", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs });
+      return readFileSync(outputPath, "utf8");
+    } finally { rmSync(temp, { recursive: true, force: true }); }
+  }
+  if (surface === "claude") {
+    const args = ["-p", "--disallowedTools", "Edit,Write,Bash", "--output-format", "json", "--json-schema", JSON.stringify(outputSchema)];
+    if (model) args.push("--model", model);
+    args.push(prompt);
+    const raw = guardedExecFileSync("claude", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs });
+    const envelope = JSON.parse(raw);
+    if (envelope.is_error) throw new Error(`claude live adapter failed: ${envelope.result ?? "unknown error"}`);
+    return envelope.result;
+  }
+  throw new Error(`unsupported live surface: ${surface}`);
+}
+
+export function persistLiveObservation(path, result) {
+  if (result.grade.status !== "pass") throw new Error("refusing to persist a failing live observation");
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.${process.pid}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(result.observation, null, 2)}\n`, "utf8");
+  renameSync(temp, path);
+}
+
+export async function recordLiveCase({ repoRoot, testCase, catalog, fingerprint, surface, model, timeoutMs, execute = defaultExecute, persistPath }) {
+  const gradedCase = { ...testCase, quality_profile: testCase.quality_profile ?? catalog.artefact_quality?.profiles?.[testCase.case_class] };
+  const fixtureRoot = materializeFixture(catalog, testCase);
+  const before = snapshotWorkspace(fixtureRoot);
+  let observation;
+  let executionError;
+  try {
+    const skillSource = readFileSync(join(repoRoot, "plugin", "skills", testCase.target_skill, "SKILL.md"), "utf8");
+    const routingSource = readFileSync(join(repoRoot, "plugin", "meta", "agdf-agent-router.md"), "utf8");
+    const raw = await execute({ surface, cwd: fixtureRoot, prompt: promptFor(skillSource, routingSource, testCase, catalog.repositories[testCase.repository_fixture], workspaceEvidence(fixtureRoot)), model, timeoutMs });
+    observation = parseObject(raw);
+  } catch (error) { executionError = error; }
+  let after;
+  try { after = snapshotWorkspace(fixtureRoot); } catch (error) { executionError ??= error; }
+  const changed = after ? changedPaths(before, after) : [];
+  const violations = mutationViolations(changed, testCase.mutation?.allowed_paths);
+  disposeFixture(fixtureRoot);
+  if (violations.length) throw Object.assign(new Error(`live adapter mutated undeclared paths: ${violations.join(", ")}`), { code: "EVAL_MUTATION_OUT_OF_BOUNDS", cause: executionError });
+  if (executionError) throw executionError;
+  const normalized = { case_id: testCase.case_id, source_fingerprint: fingerprint, evidence_kind: `live_${surface}`, recorded_at: new Date().toISOString(), selected_skill: observation.selected_skill, current_gate: observation.current_gate, internal_step: observation.internal_step, missing_approval: observation.missing_approval, actions: observation.actions, changed_paths: changed, artefact_content: observation.artefact_content };
+  const grade = gradeCase(gradedCase, normalized, fingerprint);
+  const result = { observation: normalized, grade };
+  if (persistPath) persistLiveObservation(persistPath, result);
+  return result;
+}
+
+export function surfaceRuntime(surface) {
+  try { return execFileSync(surface, ["--version"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim(); }
+  catch { return `${surface} version unavailable`; }
+}

package/lib/skill-evals/workspace.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+function schemaError(message) {
+  return Object.assign(new Error(message), { code: "EVAL_SCHEMA_INVALID" });
+}
+
+export function resolveInside(root, candidate) {
+  if (typeof candidate !== "string" || !candidate || candidate.startsWith("/")) throw schemaError(`unsafe eval path: ${candidate}`);
+  const target = resolve(root, candidate);
+  const rel = relative(resolve(root), target);
+  if (!rel || rel === ".." || rel.startsWith(`..${sep}`)) throw schemaError(`unsafe eval path: ${candidate}`);
+  return target;
+}
+
+function fixtureContent(path, description, controlState) {
+  if (path.endsWith(".json")) return `${JSON.stringify({ fixture: description, control_state: controlState }, null, 2)}\n`;
+  if (path.endsWith("RUN_STATE.md") && controlState === "ur-approved-structured") return `# AGDF Run State\n\n- schema_version: 1\n- run_id: example\n- lifecycle: active\n- mode: structured_delivery\n- current_gate: PRD\n- control_state: ${controlState}\n\n## Approvals\n\n| Gate | Status | Evidence |\n|---|---|---|\n| UR | approved | Approval: UR |\n| PRD | pending | none |\n`;
+  if (path.endsWith("RUN_STATE.md")) return `# AGDF Run State\n\n- schema_version: 1\n- run_id: example\n- lifecycle: active\n- control_state: ${controlState}\n- evidence: ${description}\n`;
+  if (path.endsWith("BROWNFIELD_REVIEW.md")) return `# Brownfield Review\n\n- decision: pass\n- mode_slice_decision: structured_delivery\n- scope_reason: Existing runtime owners are affected.\n- evidence: Canonical owners and regression surface inspected.\n- required_next_gate: PRD\n`;
+  if (path.endsWith("TP.md")) return `# Approved Task and Test Plan\n\n## Status\n\n- status: approved\n- evidence: ${description}\n\n## Tasks\n\n| task_id | acceptance |\n|---|---|\n| FIXTURE-001 | Preserve the canonical owner and test its boundary. |\n`;
+  if (path.endsWith("UR.md")) return `# Approved User Requirements\n\n- status: approved\n- objective: ${description}\n`;
+  if (path.endsWith("QA_REPORT.md")) return `# QA Report\n\n- decision: pass\n- evidence: ${description}\n- missing_evidence: none\n`;
+  if (path.endsWith("OR.md")) return `# Orchestration Report\n\n- decision: pass\n- delivered: ${description}\n- required_next_step: explicit delivery handoff\n`;
+  if (path.endsWith(".md")) return `# Governed Fixture Artefact\n\n${description}\n\nControl state: ${controlState}\n`;
+  if (path.includes("test") || path.endsWith(".spec.js")) return `// ${description}\nexport const fixtureTest = true;\n`;
+  return `// ${description}\nexport const fixtureState = ${JSON.stringify(controlState)};\n`;
+}
+
+export function materializeFixture(catalog, testCase, options = {}) {
+  const definition = catalog.repositories?.[testCase.repository_fixture];
+  if (!definition || !catalog.control_states?.includes(testCase.control_state_fixture)) throw schemaError(`unknown fixture for ${testCase.case_id}`);
+  const root = mkdtempSync(join(options.tmpRoot ?? tmpdir(), "agdf-skill-eval-"));
+  try {
+    for (const path of definition.files ?? []) {
+      const target = resolveInside(root, path);
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, fixtureContent(path, definition.description, testCase.control_state_fixture), "utf8");
+    }
+    const marker = resolveInside(root, ".agdf/control/EVAL_FIXTURE.md");
+    mkdirSync(dirname(marker), { recursive: true });
+    writeFileSync(marker, `# Evaluation Fixture\n\nRepository: ${testCase.repository_fixture}\nControl state: ${testCase.control_state_fixture}\n`, "utf8");
+    return root;
+  } catch (error) {
+    rmSync(root, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+export function snapshotWorkspace(root) {
+  const canonicalRoot = realpathSync(root);
+  const snapshot = new Map();
+  function visit(directory) {
+    for (const name of readdirSync(directory).sort()) {
+      const path = join(directory, name);
+      const rel = relative(root, path).split(sep).join("/");
+      const stat = lstatSync(path);
+      if (stat.isSymbolicLink()) {
+        let target;
+        try { target = realpathSync(path); } catch { throw schemaError(`broken fixture symlink: ${rel}`); }
+        const targetRel = relative(canonicalRoot, target);
+        if (targetRel === ".." || targetRel.startsWith(`..${sep}`)) throw schemaError(`fixture symlink escapes workspace: ${rel}`);
+        snapshot.set(rel, `symlink:${targetRel.split(sep).join("/")}`);
+      } else if (stat.isDirectory()) visit(path);
+      else if (stat.isFile()) snapshot.set(rel, createHash("sha256").update(readFileSync(path)).digest("hex"));
+    }
+  }
+  visit(root);
+  return snapshot;
+}
+
+export function workspaceEvidence(root) {
+  const snapshot = snapshotWorkspace(root);
+  return [...snapshot.keys()].map((path) => {
+    const target = resolveInside(root, path);
+    const stat = lstatSync(target);
+    return stat.isSymbolicLink() ? `--- ${path} (symlink) ---` : `--- ${path} ---\n${readFileSync(target, "utf8")}`;
+  }).join("\n");
+}
+
+export function changedPaths(before, after) {
+  return [...new Set([...before.keys(), ...after.keys()])].filter((path) => before.get(path) !== after.get(path)).sort();
+}
+
+function pathAllowed(path, allowed) {
+  return allowed.some((rule) => rule === path || (rule.endsWith("/**") && (path === rule.slice(0, -3) || path.startsWith(rule.slice(0, -2)))));
+}
+
+export function mutationViolations(changed, allowed = []) {
+  return changed.filter((path) => !pathAllowed(path, allowed));
+}
+
+export function disposeFixture(root) {
+  rmSync(root, { recursive: true, force: true });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agdf",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "description": "Bootstrap AGDF repository-local plugin files, Copilot/OpenCode instructions, skills, control files and machine-readable checks.",
   "type": "module",
   "files": [
@@ -27,10 +27,14 @@
     "test:control-state": "node ./scripts/control-state-test.js",
     "test:interaction-presentation": "node ./scripts/interaction-presentation-test.js",
     "test:verified-change": "node ./scripts/verified-change-test.js",
+    "test:runtime-integrity-layout": "node ./scripts/runtime-integrity-layout-test.js",
     "test:runtime-integrity-negative": "node ./scripts/runtime-integrity-negative-test.js",
+    "test:skill-evals": "node ./scripts/skill-evals-test.js",
+    "eval:skills": "node ./scripts/run-skill-evals.js",
+    "eval:skills:record": "node ./scripts/record-skill-evals.js",
     "test:release-bootstrap": "node ./scripts/release-bootstrap-smoke-test.js",
     "test:routing": "npm run sync-package-assets && node ./scripts/test-routing.js",
-    "smoke-test": "npm run sync-package-assets && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-negative && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
+    "smoke-test": "npm run sync-package-assets && npm run test:control-state && npm run test:interaction-presentation && npm run test:verified-change && npm run test:runtime-integrity-layout && npm run test:runtime-integrity-negative && npm run test:skill-evals && npm run eval:skills && npm run test:delivery-path-search && npm run test:delivery-path-search-unit && npm run test:delivery-path-search-generator && node ./scripts/smoke-test.js && node ./scripts/test-routing.js",
     "prepack": "npm run sync-package-assets"
   },
   "keywords": [