triad-plus 1.11.0 → 1.12.1

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## Unreleased
+
+## 1.12.1 — 2026-09-26
+
+- Bind approved human-readable Card reports to the independently verified
+  candidate manifest, preserving the pre-commit verifier fingerprint while
+  recording the committed fingerprint separately.
+- Preserve raw candidate bytes for commit-derived hashes, fail closed on
+  post-verification path/content changes, and retain legacy no-manifest
+  behavior without silently widening the verified candidate.
+
+## 1.12.0 — 2026-09-23
+
+- Add deterministic human-readable Markdown views for terminal Cards and the
+  final delivery handoff, derived from canonical evidence with baseline-based
+  changed-path attribution and truthful blocked/not-delivered reporting.
+
 ## 1.11.0 — 2026-09-17
 
 - Add an installation manifest that records Triad-owned assets, materialized

package/README.md

@@ -167,6 +167,15 @@ planning; Triad owns execution, verification, review, and delivery.
 ready-for-dev Stories, debugging, and automation. It is no longer the primary
 BMAD workflow. See the [BMAD integration guide](docs/bmad-integration.md).
 
+## Human-readable delivery reports
+
+Triad+ can materialize deterministic Markdown views from canonical control-plane
+records: one report for each terminal Card and a human-first final handoff. The
+views include baseline-attributed changed paths, attempts, verifier gates,
+independent review, provenance, residual risks, and practical-test links. They
+never replace the JSON/YAML evidence or add an LLM reporting call. See the
+[human-readable reports guide](docs/human-readable-reports.md).
+
 ## Quick start for every runtime
 
 Requirements: Node.js 20+ and one supported coding-agent host.

package/docs/human-readable-reports.md

@@ -0,0 +1,55 @@
+# Human-readable reports
+
+Triad+ keeps JSON/YAML control records, verification evidence, review reports,
+candidate fingerprints, and delivery records as the source of truth. From those
+records the Orchestrator can materialize two portable Markdown views:
+
+- one `card-reports/<card-id>.md` for every terminal Card;
+- one final delivery handoff with a human-first summary and links to the Card
+  reports.
+
+The report renderer is deterministic and does not make an additional LLM call.
+It attributes changed paths to the complete Card baseline, so a rework attempt
+does not hide files changed by an earlier attempt. Reports contain relative
+evidence references and redact unrelated absolute paths.
+
+## Materialize a Card report
+
+The Orchestrator first writes a small derived JSON context from the canonical
+Card, attempt, verifier, Reviewer, and delivery records. The source Card and
+those records remain read-only. Then run:
+
+```bash
+node .triad-runtime/triad-human-report.mjs \
+  --mode card \
+  --project /absolute/path/to/control-workspace \
+  --input .loop/runtime/report-context/CARD-001.json \
+  --output card-reports/CARD-001.md \
+  --worktree /absolute/path/to/product-worktree \
+  --base-commit <card-baseline-commit>
+```
+
+For an approved Card the renderer requires a final commit, the candidate
+fingerprint recorded by passing verifier evidence, independent Reviewer
+approval, and the complete changed-path manifest. Current verifier evidence
+also carries a `candidate_manifest` with the verified paths and content hashes.
+The renderer binds that manifest to the final commit delta (allowing the
+expected `git_head` change caused by the commit) and records the resulting
+committed fingerprint separately. A blocked or not-delivered terminal Card must
+include a truthful reason and never claims delivery. Writes are atomic and
+re-running the command with the same context is idempotent.
+
+## Materialize the final handoff
+
+```bash
+node .triad-runtime/triad-human-report.mjs \
+  --mode handoff \
+  --project /absolute/path/to/control-workspace \
+  --input .loop/runtime/report-context/delivery.json \
+  --output handoff.md
+```
+
+The handoff opens with the executive summary and Card results, then preserves
+links to the technical evidence, branch/commit map, quality-contract closure,
+Evaluator+ result, delivery gates, demo details, risks, and practical test.
+It is a view for people, not an alternative delivery state machine.

package/docs/operating-guide.it.md

@@ -96,6 +96,15 @@ inserire token o segreti. Gli hook sono un’ottimizzazione, non autorità: il
 dispatch esplicito della verification resta sempre disponibile. Vedi la
 [matrice di compatibilità](compatibility.md).
 
+Per ogni Card terminale l’Orchestrator può generare una vista deterministica
+`card-reports/<card-id>.md` dai record canonici di Card, attempt, verifier e
+Reviewer. Il renderer attribuisce al baseline completo della Card il delta dei
+path modificati, inclusi rework, rinomina e cancellazione. L’handoff finale si
+apre con un riepilogo leggibile e collega questi report, mantenendo anche le
+evidence tecniche di delivery. I report sono scritti atomicamente, sono
+ripetibili e usano riferimenti relativi: non sono una nuova source of truth né
+una chiamata aggiuntiva a un agente. Vedi la [guida ai report leggibili](human-readable-reports.md).
+
 Per ogni demo configurata, registra nel progetto e nell’handoff comando, URL
 locale, modalità di accesso remoto e URL remoto. `localhost` è solo locale: non
 va indicato a chi prova da remoto. Avvia il servizio soltanto su richiesta del

package/docs/operating-guide.md

@@ -95,6 +95,15 @@ reports, and handoff in a separate project-control workspace. Never place tokens
 or secrets there. Hooks are an optimization, not authority; explicit verification
 is always the fallback. See the [compatibility matrix](compatibility.md).
 
+For every terminal Card, the Orchestrator may render a deterministic
+`card-reports/<card-id>.md` view from the canonical Card, attempt, verifier, and
+Reviewer records. The renderer attributes the complete changed-path delta to the
+Card baseline, including rework, renames, and deletions. The final handoff opens
+with a human-readable summary and links to those reports while retaining the
+technical delivery evidence. Reports are atomic, repeatable, relative-path
+views; they are not a new source of truth or an additional agent call. See the
+[human-readable reports guide](human-readable-reports.md).
+
 For a configured demo service, record its command, local URL, remote-access mode,
 and remote URL in the project and handoff. `localhost` is local-only; do not give
 it to a remote tester as a reachable endpoint. Start the service only on the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "A lightweight, evidence-backed engineering loop for coding agents.",
   "license": "Apache-2.0",
   "type": "module",
@@ -28,7 +28,7 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node tests/runtime-forward-test.mjs && node tests/retry-scope-contracts-test.mjs && node tests/cli-install-test.mjs && node tests/installation-manifest-test.mjs && node tests/codex-liveness-test.mjs && node tests/bmad-story-importer-test.mjs && node tests/bmad-epics-intake-test.mjs && node tests/immutable-quality-contract-test.mjs && node tests/assignment-packet-test.mjs && node tests/repository-context-test.mjs && node tests/tui-model-configuration-test.mjs",
+    "test": "node tests/runtime-forward-test.mjs && node tests/retry-scope-contracts-test.mjs && node tests/cli-install-test.mjs && node tests/installation-manifest-test.mjs && node tests/codex-liveness-test.mjs && node tests/bmad-story-importer-test.mjs && node tests/bmad-epics-intake-test.mjs && node tests/immutable-quality-contract-test.mjs && node tests/assignment-packet-test.mjs && node tests/repository-context-test.mjs && node tests/tui-model-configuration-test.mjs && node tests/human-reports-test.mjs && node tests/human-report-fingerprint-binding-test.mjs",
     "pack:check": "npm pack --dry-run"
   },
   "repository": {

package/runtime/lib/evidence.mjs

@@ -29,3 +29,14 @@ export async function writeAtomicJson(targetPath, value) {
   await writeFile(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
   await rename(temporaryPath, targetPath);
 }
+
+/**
+ * Persist a derived human-readable artifact without exposing a partially
+ * written report to the owner or to a resumed Orchestrator.
+ */
+export async function writeAtomicText(targetPath, value) {
+  await mkdir(path.dirname(targetPath), { recursive: true });
+  const temporaryPath = `${targetPath}.tmp`;
+  await writeFile(temporaryPath, String(value), "utf8");
+  await rename(temporaryPath, targetPath);
+}

package/runtime/lib/fingerprint.mjs

@@ -26,6 +26,12 @@ async function gitOutput(worktree, args) {
   return result.stdout;
 }
 
+async function verifiedCommit(root, commit, label) {
+  const resolved = (await gitLines(root, ["rev-parse", "--verify", `${commit}^{commit}`]))[0];
+  if (!resolved) throw new Error(`${label} does not resolve to a commit`);
+  return resolved;
+}
+
 function ignored(relativePath) {
   return SENSITIVE_PATH.test(relativePath) || IGNORED_PATH.test(relativePath);
 }
@@ -57,6 +63,67 @@ function pathsFor(entry) {
   return entry.status === "renamed" ? [entry.source, entry.destination] : [entry.path];
 }
 
+function candidateManifest(candidate, files) {
+  return {
+    base_commit: candidate.base_commit,
+    git_head: candidate.git_head,
+    changes: candidate.changes,
+    ignored_paths: candidate.ignored_paths,
+    files,
+  };
+}
+
+/**
+ * Return the content/path binding captured for a candidate independently of
+ * the Git commit identity used to produce it. The fingerprint value below
+ * intentionally retains its historical git_head binding; reports use this
+ * manifest to bind that verified candidate to the later commit tree.
+ */
+export function candidateManifestFor(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  if (!Array.isArray(value.files) || !Array.isArray(value.changes)) return null;
+  return {
+    base_commit: value.base_commit ?? null,
+    git_head: value.git_head ?? null,
+    changes: value.changes,
+    ignored_paths: Array.isArray(value.ignored_paths) ? value.ignored_paths : [],
+    files: value.files,
+  };
+}
+
+function changePaths(manifest) {
+  return (manifest?.changes ?? []).flatMap((change) => change?.status === "renamed"
+    ? [change.source, change.destination]
+    : [change.path]).filter((value) => typeof value === "string").sort();
+}
+
+function fileEntries(manifest) {
+  return (manifest?.files ?? [])
+    .map((file) => ({ path: file?.path, sha256: file?.sha256 }))
+    .sort((left, right) => String(left.path).localeCompare(String(right.path)));
+}
+
+function ignoredPaths(manifest) {
+  return [...new Set(manifest?.ignored_paths ?? [])].filter((value) => typeof value === "string").sort();
+}
+
+/**
+ * Compare a verifier's pre-commit manifest with a commit-derived manifest.
+ * git_head is deliberately excluded: committing an unchanged candidate is
+ * expected to change that identity. Paths and content hashes are not ignored,
+ * so a file added or modified after verification fails closed.
+ */
+export function candidateManifestsBind(verified, committed, { expectedBaseCommit = null } = {}) {
+  const left = candidateManifestFor(verified);
+  const right = candidateManifestFor(committed);
+  if (!left || !right) return false;
+  if (expectedBaseCommit && (left.base_commit !== expectedBaseCommit || right.base_commit !== expectedBaseCommit)) return false;
+  if (left.base_commit !== right.base_commit) return false;
+  if (JSON.stringify(ignoredPaths(left)) !== JSON.stringify(ignoredPaths(right))) return false;
+  if (JSON.stringify(fileEntries(left)) !== JSON.stringify(fileEntries(right))) return false;
+  return JSON.stringify(changePaths(left)) === JSON.stringify(changePaths(right));
+}
+
 export async function collectCandidateChanges(worktree, { baseCommit = null } = {}) {
   const root = await realpath(worktree);
   const head = (await gitLines(root, ["rev-parse", "HEAD"]))[0] ?? "NO_HEAD";
@@ -84,6 +151,69 @@ export async function collectCandidateChanges(worktree, { baseCommit = null } =
   return { git_head: head, base_commit: base, changes, ignored_paths: [...new Set(ignored_paths)].sort() };
 }
 
+/**
+ * Collect a complete candidate delta from an immutable Git commit rather than
+ * from whatever happens to be in the current worktree. This is used by derived
+ * reports so a later Card on the same branch cannot contaminate an earlier one.
+ */
+export async function collectCandidateChangesAtCommit(worktree, { baseCommit, commit }) {
+  const root = await realpath(worktree);
+  const base = await verifiedCommit(root, baseCommit, "base commit");
+  const head = await verifiedCommit(root, commit, "final commit");
+  const ancestry = await runProcess("git", ["merge-base", "--is-ancestor", base, head], { cwd: root, timeoutMs: 15_000 });
+  if (ancestry.exitCode !== 0) throw new Error("card baseline is not an ancestor of the final commit");
+  const tracked = parseNameStatus(await gitOutput(root, ["diff", "--name-status", "--find-renames", base, head]));
+  const changes = [];
+  const ignored_paths = [];
+  for (const entry of tracked) {
+    const entryPaths = pathsFor(entry);
+    if (entryPaths.some(ignored)) {
+      ignored_paths.push(...entryPaths.filter(ignored));
+      continue;
+    }
+    for (const relativePath of entryPaths) {
+      const absolutePath = path.resolve(root, relativePath);
+      if (!absolutePath.startsWith(`${root}${path.sep}`)) throw new Error(`unsafe changed path: ${relativePath}`);
+    }
+    changes.push(entry);
+  }
+  return { git_head: head, base_commit: base, changes, ignored_paths: [...new Set(ignored_paths)].sort() };
+}
+
+async function commitFileHash(root, commit, relativePath) {
+  const result = await runProcess("git", ["show", `${commit}:${relativePath}`], { cwd: root, timeoutMs: 15_000, encoding: null });
+  if (result.exitCode !== 0) throw new Error(`git show failed for ${commit}:${relativePath}`);
+  return digest(result.stdout);
+}
+
+/** Calculate the same candidate fingerprint algorithm at a specific commit. */
+export async function calculateCandidateFingerprintAtCommit(worktree, { baseCommit, commit }) {
+  const root = await realpath(worktree);
+  const candidate = await collectCandidateChangesAtCommit(root, { baseCommit, commit });
+  const files = [];
+  const changed = new Map();
+  for (const entry of candidate.changes) {
+    if (entry.status === "renamed") {
+      changed.set(entry.source, "DELETED");
+      changed.set(entry.destination, null);
+    } else {
+      changed.set(entry.path, entry.status === "deleted" ? "DELETED" : null);
+    }
+  }
+  for (const [relativePath, knownHash] of [...changed.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    const contentHash = knownHash === null ? await commitFileHash(root, candidate.git_head, relativePath) : knownHash;
+    files.push({ path: relativePath, sha256: contentHash });
+  }
+  const canonical = JSON.stringify({ git_head: candidate.git_head, files });
+  return {
+    algorithm: "sha256",
+    value: digest(canonical),
+    git_head: candidate.git_head,
+    files,
+    manifest: candidateManifest(candidate, files),
+  };
+}
+
 export async function worktreeBranch(worktree) {
   const root = await realpath(worktree);
   return (await gitLines(root, ["branch", "--show-current"]))[0] ?? "DETACHED";
@@ -118,5 +248,11 @@ export async function calculateCandidateFingerprint(worktree) {
     files.push({ path: relativePath, sha256: contentHash });
   }
   const canonical = JSON.stringify({ git_head: candidate.git_head, files });
-  return { algorithm: "sha256", value: digest(canonical), git_head: candidate.git_head, files };
+  return {
+    algorithm: "sha256",
+    value: digest(canonical),
+    git_head: candidate.git_head,
+    files,
+    manifest: candidateManifest(candidate, files),
+  };
 }

package/runtime/lib/human-reports.mjs

@@ -0,0 +1,530 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { calculateCandidateFingerprintAtCommit, candidateManifestsBind, collectCandidateChangesAtCommit } from "./fingerprint.mjs";
+import { writeAtomicText } from "./evidence.mjs";
+
+export const HUMAN_REPORT_SCHEMA_VERSION = 1;
+
+function reportError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function requiredString(value, label) {
+  if (typeof value !== "string" || !value.trim()) throw reportError("human_report_invalid", `${label} must be a non-empty string`);
+  return value.trim();
+}
+
+function optionalString(value, label) {
+  if (value === null || value === undefined) return null;
+  return requiredString(value, label);
+}
+
+function statusLabel(value) {
+  return {
+    approved: "APPROVED",
+    blocked: "BLOCKED",
+    not_delivered: "NOT DELIVERED",
+    delivery_blocked: "DELIVERY BLOCKED",
+    rework: "REWORK",
+  }[value] ?? String(value ?? "UNKNOWN").toUpperCase();
+}
+
+function text(value, fallback = "Not recorded.") {
+  if (value === null || value === undefined || value === "") return fallback;
+  return String(value).trim() || fallback;
+}
+
+function list(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function tableCell(value) {
+  return text(value, "—").replaceAll("|", "\\|").replaceAll("\n", "<br>");
+}
+
+function markdownBullet(value) {
+  return `- ${text(value)}`;
+}
+
+function within(root, target) {
+  const base = path.resolve(root);
+  const resolved = path.resolve(target);
+  return resolved === base || resolved.startsWith(`${base}${path.sep}`);
+}
+
+/**
+ * Reports are views. Absolute machine paths are never emitted in them. A path
+ * inside a declared project/worktree is converted to a portable relative ref;
+ * an unrelated path is deliberately redacted rather than leaked.
+ */
+export function reportPath(value, { projectRoot = null, worktree = null } = {}) {
+  if (value === null || value === undefined || value === "") return "—";
+  const raw = String(value);
+  if (!path.isAbsolute(raw)) return raw.replaceAll(path.sep, "/");
+  const roots = [projectRoot, worktree].filter(Boolean).map((root) => path.resolve(root));
+  for (const root of roots) {
+    if (within(root, raw)) {
+      const relative = path.relative(root, path.resolve(raw));
+      return (relative || ".").split(path.sep).join("/");
+    }
+  }
+  return "<external path>";
+}
+
+function changedPathLabel(change, context) {
+  if (change?.status === "renamed") {
+    return `${reportPath(change.source, context)} → ${reportPath(change.destination, context)}`;
+  }
+  return reportPath(change?.path, context);
+}
+
+function normalizeChangedPaths(changes, context) {
+  return list(changes).map((change) => ({
+    status: text(change?.status, "modified"),
+    path: change?.path,
+    source: change?.source,
+    destination: change?.destination,
+    repository: change?.repository ?? null,
+    label: changedPathLabel(change, context),
+  }));
+}
+
+function validateAttempt(attempt, index, context = {}) {
+  if (!objectLike(attempt)) throw reportError("human_report_invalid", `attempt ${index + 1} must be an object`);
+  return {
+    number: attempt.number ?? attempt.attempt ?? index + 1,
+    outcome: text(attempt.outcome ?? attempt.status, "not recorded"),
+    resolution: text(attempt.resolution ?? attempt.resolution_kind, "none"),
+    candidate_fingerprint: optionalString(attempt.candidate_fingerprint, `attempt ${index + 1} candidate_fingerprint`),
+    evidence_refs: list(attempt.evidence_refs).map((ref) => reportPath(ref, context)),
+    notes: text(attempt.notes, "—"),
+  };
+}
+
+function validateVerification(run, index, context = {}) {
+  if (!objectLike(run)) throw reportError("human_report_invalid", `verification ${index + 1} must be an object`);
+  return {
+    run_id: text(run.run_id ?? run.id, `verification-${index + 1}`),
+    status: text(run.status, "not recorded"),
+    gates: list(run.gates).map((gate) => ({
+      id: text(gate?.id, "unknown"),
+      status: text(gate?.status, "not recorded"),
+      evidence_refs: list(gate?.evidence_refs).map((ref) => reportPath(ref, context)),
+      exit_code: gate?.exit_code ?? "—",
+      duration_ms: gate?.duration_ms ?? "—",
+    })),
+    evidence_path: reportPath(run.evidence_path ?? run.path, context),
+    candidate_fingerprint: optionalString(run.candidate_fingerprint, `verification ${index + 1} candidate_fingerprint`),
+    candidate_manifest: run.candidate_manifest ?? run.baseline?.candidate_manifest ?? null,
+    notes: text(run.notes, "—"),
+  };
+}
+
+function validateReview(review, context = {}) {
+  if (review === null || review === undefined) return null;
+  if (!objectLike(review)) throw reportError("human_report_invalid", "review must be an object");
+  return {
+    decision: text(review.decision, "not recorded"),
+    reviewer: text(review.reviewer, "independent Reviewer"),
+    evidence_path: reportPath(review.evidence_path ?? review.path, context),
+    candidate_fingerprint: optionalString(review.candidate_fingerprint, "review candidate_fingerprint"),
+    findings: list(review.findings).map((finding) => ({
+      severity: text(finding?.severity, "unspecified"),
+      finding: text(finding?.finding, "not recorded"),
+      resolution: text(finding?.resolution, "none"),
+      evidence: text(finding?.evidence, "not recorded"),
+    })),
+    risks: list(review.risks),
+  };
+}
+
+function validateFinal(final, status) {
+  if (!objectLike(final)) throw reportError("human_report_invalid", "final must be an object");
+  const normalized = {
+    branch: optionalString(final.branch, "final branch"),
+    commit: optionalString(final.commit ?? final.final_commit, "final commit"),
+    base_commit: optionalString(final.base_commit, "final base_commit"),
+    candidate_fingerprint: optionalString(final.candidate_fingerprint, "final candidate_fingerprint"),
+    committed_candidate_fingerprint: optionalString(final.committed_candidate_fingerprint, "final committed_candidate_fingerprint"),
+    worktree: optionalString(final.worktree, "final worktree"),
+    repository: optionalString(final.repository, "final repository"),
+  };
+  if (status === "approved") {
+    for (const [key, value] of Object.entries(normalized)) {
+      if (["branch", "commit", "candidate_fingerprint", "repository"].includes(key) && !value) {
+        throw reportError("human_report_invalid", `approved report requires final.${key}`);
+      }
+    }
+  }
+  return normalized;
+}
+
+/** Validate and normalize the derived context supplied by the Orchestrator. */
+export function normalizeCardReportInput(input, { projectRoot = null, worktree = null } = {}) {
+  if (!objectLike(input)) throw reportError("human_report_invalid", "card report input must be an object");
+  const card = objectLike(input.card) ? input.card : input;
+  const cardId = requiredString(card.id ?? input.card_id, "card id");
+  const status = requiredString(input.status ?? input.terminal_status, "terminal status").toLowerCase();
+  if (!new Set(["approved", "blocked", "not_delivered", "delivery_blocked"]).has(status)) {
+    throw reportError("human_report_invalid", `unsupported terminal status: ${status}`);
+  }
+  const context = { projectRoot, worktree };
+  const final = validateFinal(input.final ?? {}, status);
+  const attempts = list(input.attempts).map((attempt, index) => validateAttempt(attempt, index, context));
+  const verification = list(input.verification ?? input.verification_runs).map((run, index) => validateVerification(run, index, context));
+  const review = validateReview(input.review, context);
+  if (status === "approved") {
+    const passingRuns = verification.filter((run) => run.status === "pass" || run.status === "PASS");
+    if (!passingRuns.length) {
+      throw reportError("human_report_invalid", "approved report requires a passing verification run");
+    }
+    if (!review || !["approved", "APPROVED"].includes(review.decision)) {
+      throw reportError("human_report_invalid", "approved report requires an independent Reviewer approval");
+    }
+    if (!passingRuns.some((run) => run.candidate_fingerprint === final.candidate_fingerprint)) {
+      throw reportError("human_report_invalid", "approved report requires passing verifier evidence bound to the final candidate fingerprint");
+    }
+    if (review.candidate_fingerprint && review.candidate_fingerprint !== final.candidate_fingerprint) {
+      throw reportError("human_report_invalid", "Reviewer evidence is bound to a different candidate fingerprint");
+    }
+  }
+  if (status !== "approved" && !text(input.block_reason ?? input.reason, "").trim()) {
+    throw reportError("human_report_invalid", "non-approved terminal report requires a truthful reason");
+  }
+  return {
+    schema_version: HUMAN_REPORT_SCHEMA_VERSION,
+    project_id: text(input.project_id, "unnamed-project"),
+    card: {
+      id: cardId,
+      title: text(card.title, cardId),
+      goal: text(card.goal ?? card.observable_goal ?? card.outcome, "Not recorded."),
+      outcome: text(card.outcome ?? input.outcome, "Not recorded."),
+      repository: text(card.target_repository ?? card.repository ?? final.repository, "Not recorded."),
+      card_path: reportPath(card.card_path, context),
+      context: text(card.context, "Not recorded."),
+    },
+    status,
+    block_reason: text(input.block_reason ?? input.reason, "None recorded."),
+    implementation: {
+      summary: text(input.implementation?.summary ?? input.implemented, status === "approved" ? "Implementation completed." : "No delivered implementation claimed."),
+      paths: normalizeChangedPaths(input.implementation?.paths ?? [], context),
+    },
+    attempts,
+    verification,
+    review,
+    final,
+    provenance: {
+      assignment_path: reportPath(input.provenance?.assignment_path, context),
+      assignment_sha256: text(input.provenance?.assignment_sha256, "not recorded"),
+      packet_path: reportPath(input.provenance?.packet_path, context),
+      packet_sha256: text(input.provenance?.packet_sha256, "not recorded"),
+      verification_paths: list(input.provenance?.verification_paths).map((ref) => reportPath(ref, context)),
+      review_path: reportPath(input.provenance?.review_path, context),
+    },
+    risks: list(input.risks),
+    deferred: list(input.deferred),
+    evidence_refs: list(input.evidence_refs).map((ref) => reportPath(ref, context)),
+    generated_from: text(input.generated_from, "canonical control-plane evidence"),
+    changed_paths: input.changed_paths === undefined ? null : normalizeChangedPaths(input.changed_paths, context),
+    changed_paths_base: input.changed_paths_base ?? final.base_commit ?? null,
+    context,
+  };
+}
+
+function changedPathsForReport(report) {
+  if (report.changed_paths !== null) return report.changed_paths;
+  return [];
+}
+
+export function renderCardReport(input, options = {}) {
+  const report = input.schema_version === HUMAN_REPORT_SCHEMA_VERSION && input.card?.id
+    ? input
+    : normalizeCardReportInput(input, options);
+  const changed = changedPathsForReport(report);
+  const status = statusLabel(report.status);
+  const verificationRows = report.verification.flatMap((run) => run.gates.length
+    ? run.gates.map((gate) => `| ${tableCell(run.run_id)} | ${tableCell(gate.id)} | ${tableCell(gate.status)} | ${tableCell(gate.exit_code)} | ${tableCell(gate.duration_ms)} | ${tableCell([run.evidence_path, ...gate.evidence_refs].filter((ref) => ref && ref !== "—").join(", "))} |`)
+    : [`| ${tableCell(run.run_id)} | — | ${tableCell(run.status)} | — | — | ${tableCell(run.evidence_path)} |`]);
+  const attemptRows = report.attempts.length
+    ? report.attempts.map((attempt) => `| ${tableCell(attempt.number)} | ${tableCell(attempt.outcome)} | ${tableCell(attempt.resolution)} | ${tableCell(attempt.candidate_fingerprint)} | ${tableCell(attempt.notes)} | ${tableCell(attempt.evidence_refs.join(", "))} |`)
+    : ["| — | No attempts recorded | — | — | — | — |"];
+  const changedRows = changed.length
+    ? changed.map((entry) => `| ${tableCell(entry.status)} | ${tableCell(entry.label)} | ${tableCell(entry.repository ?? report.card.repository)} |`)
+    : ["| — | No changed paths recorded from the card baseline | — |"];
+  const review = report.review;
+  const findings = review?.findings?.length
+    ? review.findings.map((finding) => `| ${tableCell(finding.severity)} | ${tableCell(finding.finding)} | ${tableCell(finding.evidence)} | ${tableCell(finding.resolution)} |`)
+    : ["| — | No findings recorded | — | None |"];
+  const finalEvidence = report.status === "approved"
+    ? `- Final commit: \`${tableCell(report.final.commit)}\`\n- Verified candidate fingerprint: \`${tableCell(report.final.candidate_fingerprint)}\`\n- Committed candidate fingerprint: \`${tableCell(report.final.committed_candidate_fingerprint ?? "not recorded")}\`\n- Reviewer decision: \`${tableCell(review?.decision)}\``
+    : `- Terminal state: \`${status}\`\n- Reason: ${text(report.block_reason)}`;
+  return `# Card report — ${report.card.id}: ${report.card.title}
+
+> Derived human-readable view of canonical Triad+ evidence. This report is not a new source of truth.
+
+## Result
+
+**${status}**
+
+- Project: ${tableCell(report.project_id)}
+- Repository: ${tableCell(report.card.repository)}
+- Goal: ${tableCell(report.card.goal)}
+- Outcome: ${tableCell(report.card.outcome)}
+- Card path: \`${tableCell(report.card.card_path)}\`
+
+## What was implemented
+
+${text(report.implementation.summary)}
+
+## Card-attributable changed paths
+
+Baseline: \`${tableCell(report.changed_paths_base)}\`
+
+| Status | Path | Repository |
+| --- | --- | --- |
+${changedRows.join("\n")}
+
+## Verification and gates
+
+| Verification run | Gate | Status | Exit code | Duration (ms) | Evidence |
+| --- | --- | --- | --- | --- | --- |
+${verificationRows.join("\n")}
+
+## Attempts and rework
+
+| Attempt | Outcome | Resolution | Candidate fingerprint | Notes | Evidence |
+| --- | --- | --- | --- | --- | --- |
+${attemptRows.join("\n")}
+
+## Independent Reviewer
+
+- Reviewer: ${tableCell(review?.reviewer ?? "Not dispatched")}
+- Decision: **${tableCell(review?.decision ?? "not recorded")}**
+- Evidence: \`${tableCell(review?.evidence_path ?? "not recorded")}\`
+
+| Severity | Finding | Evidence | Resolution |
+| --- | --- | --- | --- |
+${findings.join("\n")}
+
+${review?.risks?.length ? `Reviewer risks:\n${review.risks.map(markdownBullet).join("\n")}` : "Reviewer risks: none recorded."}
+
+## Final evidence and provenance
+
+${finalEvidence}
+
+- Branch: \`${tableCell(report.final.branch)}\`
+- Repository baseline: \`${tableCell(report.final.base_commit)}\`
+- Source: ${tableCell(report.generated_from)}
+- Evidence references: ${report.evidence_refs.length ? report.evidence_refs.map((ref) => `\`${tableCell(ref)}\``).join(", ") : "none recorded"}
+- Assignment: \`${tableCell(report.provenance.assignment_path)}\` (${tableCell(report.provenance.assignment_sha256)})
+- Assignment Packet: \`${tableCell(report.provenance.packet_path)}\` (${tableCell(report.provenance.packet_sha256)})
+- Verification references: ${report.provenance.verification_paths.length ? report.provenance.verification_paths.map((ref) => `\`${tableCell(ref)}\``).join(", ") : "none recorded"}
+
+## Risks, deferred work, and terminal notes
+
+${report.risks.length ? report.risks.map(markdownBullet).join("\n") : "- No residual risks recorded."}
+${report.deferred.length ? report.deferred.map((item) => `- Deferred: ${text(item)}`).join("\n") : "- No deferred items recorded."}
+${report.status !== "approved" ? `- Terminal reason: ${text(report.block_reason)}` : "- The card reached approved status after current verification and independent review."}
+`;
+}
+
+function normalizeHandoffInput(input, options = {}) {
+  if (!objectLike(input)) throw reportError("human_report_invalid", "handoff input must be an object");
+  const cards = list(input.cards).map((card) => ({
+    id: requiredString(card.id, "handoff card id"),
+    title: text(card.title, card.id),
+    status: text(card.status, "not recorded"),
+    summary: text(card.summary ?? card.outcome, "Not recorded."),
+    report_path: reportPath(card.report_path, options),
+    commit: optionalString(card.commit, `handoff card ${card.id} commit`),
+    candidate_fingerprint: optionalString(card.candidate_fingerprint, `handoff card ${card.id} candidate_fingerprint`),
+    verification: text(card.verification, "Not recorded."),
+    review: text(card.review, "Not recorded."),
+    evaluator_report: reportPath(card.evaluator_report, options),
+    evidence_refs: list(card.evidence_refs).map((ref) => reportPath(ref, options)),
+  }));
+  if (!cards.length) throw reportError("human_report_invalid", "handoff requires at least one card result");
+  return {
+    project_id: text(input.project_id, "unnamed-project"),
+    decision: requiredString(input.decision, "handoff decision"),
+    executive_summary: text(input.executive_summary ?? input.summary, "Not recorded."),
+    cards,
+    code_areas: list(input.code_areas),
+    residual: list(input.residual ?? input.deferred),
+    verification: text(input.verification, "Not recorded."),
+    review: text(input.review, "Not recorded."),
+    branch_commits: list(input.branch_commits),
+    practical_test: list(input.practical_test),
+    evaluator: text(input.evaluator, "Not configured."),
+    delivery: text(input.delivery, "Not recorded."),
+    quality_contract: text(input.quality_contract, "Not configured."),
+    delivery_criteria: list(input.delivery_criteria).map((criterion) => ({
+      ...criterion,
+      evidence_refs: list(criterion?.evidence_refs).map((ref) => reportPath(ref, options)),
+    })),
+    demo: text(input.demo, "Not configured."),
+    evidence_refs: list(input.evidence_refs).map((ref) => reportPath(ref, options)),
+    exceptions: list(input.exceptions),
+    prd_baseline: text(input.prd_baseline, "Not recorded."),
+    approved_cards: list(input.approved_cards),
+    push_evidence: list(input.push_evidence),
+    gate_metrics: list(input.gate_metrics),
+    local_worktree_integration: list(input.local_worktree_integration),
+    delivery_closure_record: text(input.delivery_closure_record, "Not recorded."),
+    final_message: text(input.final_message, "Not recorded."),
+    risks: list(input.risks),
+    generated_from: text(input.generated_from, "canonical control-plane evidence"),
+  };
+}
+
+export function renderHandoffReport(input, options = {}) {
+  const handoff = input.project_id && Array.isArray(input.cards) && input.cards[0]?.report_path !== undefined
+    ? input
+    : normalizeHandoffInput(input, options);
+  const cardRows = handoff.cards.map((card) => `| ${tableCell(card.id)} | ${tableCell(card.title)} | **${tableCell(statusLabel(card.status))}** | ${tableCell(card.summary)} | ${tableCell(card.commit)} | ${tableCell(card.candidate_fingerprint)} | ${tableCell(card.evaluator_report)} | [Card report](${tableCell(card.report_path)}) |`);
+  const links = handoff.cards.map((card) => `- [${card.id} card report](${card.report_path})`).join("\n");
+  return `# Delivery handoff — ${handoff.project_id}
+
+## Executive summary
+
+**${tableCell(statusLabel(handoff.decision))}**
+
+${handoff.executive_summary}
+
+## Card-by-card results
+
+| Card | Title | Result | Outcome | Commit | Candidate fingerprint | Evaluator+ | Human-readable report |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+${cardRows.join("\n")}
+
+${links}
+
+## Main code areas, problem, and resolution
+
+${handoff.code_areas.length ? handoff.code_areas.map((item) => `- ${text(item)}`).join("\n") : "- Not recorded."}
+
+## Residual, deferred, and blocked items
+
+${handoff.residual.length ? handoff.residual.map((item) => `- ${text(item)}`).join("\n") : "- None recorded."}
+
+## Verification and review status
+
+- Verification: ${handoff.verification}
+- Independent review: ${handoff.review}
+- Evaluator+: ${handoff.evaluator}
+- Delivery closure: ${handoff.delivery}
+
+- PRD baseline: ${handoff.prd_baseline}
+- Approved cards: ${handoff.approved_cards.length ? handoff.approved_cards.map((item) => text(item)).join(", ") : "Not recorded."}
+- Push evidence: ${handoff.push_evidence.length ? handoff.push_evidence.map((item) => text(item)).join("; ") : "Not recorded."}
+- Gates and metrics: ${handoff.gate_metrics.length ? handoff.gate_metrics.map((item) => text(item)).join("; ") : "Not recorded."}
+
+## Quality and delivery closure
+
+- Quality Contract: ${handoff.quality_contract}
+- Demo: ${handoff.demo}
+
+${handoff.delivery_criteria.length ? `| Criterion | Verdict | Evidence |\n| --- | --- | --- |\n${handoff.delivery_criteria.map((criterion) => `| ${tableCell(criterion?.id)} | ${tableCell(criterion?.verdict)} | ${tableCell(criterion?.evidence_refs?.join(", "))} |`).join("\n")}` : "No delivery criteria recorded."}
+
+- Delivery closure record: ${handoff.delivery_closure_record}
+- Final delivery message: ${handoff.final_message}
+
+## Branch, commit, and evidence map
+
+${handoff.branch_commits.length ? handoff.branch_commits.map((item) => `- ${text(item)}`).join("\n") : "- Not recorded."}
+
+${handoff.local_worktree_integration.length ? `### Local-worktree integration\n${handoff.local_worktree_integration.map((item) => `- ${text(item)}`).join("\n")}` : "### Local-worktree integration\n- Not recorded."}
+
+## Practical test / follow-up
+
+${handoff.practical_test.length ? handoff.practical_test.map((item) => `- ${text(item)}`).join("\n") : "- No practical test recorded."}
+
+## Exceptions and evidence references
+
+${handoff.exceptions.length ? handoff.exceptions.map((item) => `- ${text(item)}`).join("\n") : "- No exceptions recorded."}
+${handoff.evidence_refs.length ? handoff.evidence_refs.map((item) => `- \`${tableCell(item)}\``).join("\n") : "- No additional evidence references recorded."}
+
+## Risks
+
+${handoff.risks.length ? handoff.risks.map((item) => `- ${text(item)}`).join("\n") : "- None recorded."}
+
+## Canonical record boundary
+
+This Markdown handoff is a derived view generated from ${handoff.generated_from}. Technical delivery gates, evaluator results, evidence paths, branch/commit data, demo details, and quality-contract closure remain authoritative in the control records referenced above.
+`;
+}
+
+/**
+ * Generate a card report while attributing paths to the complete card baseline.
+ * The changed-path manifest is collected from Git, never from Developer prose.
+ */
+export async function writeCardReport(input, { outputPath, projectRoot = null, worktree = null, baseCommit = null } = {}) {
+  const preliminary = normalizeCardReportInput(input, { projectRoot, worktree });
+  let changedPaths = preliminary.changed_paths;
+  let changedPathsBase = preliminary.changed_paths_base ?? baseCommit;
+  let committedCandidateFingerprint = preliminary.final.committed_candidate_fingerprint;
+  if (preliminary.status === "approved") {
+    if (!worktree || !(baseCommit ?? preliminary.final.base_commit) || !preliminary.final.commit) {
+      throw reportError("human_report_invalid", "approved card report requires a worktree, card baseline, and final commit for canonical evidence");
+    }
+    const candidate = await collectCandidateChangesAtCommit(worktree, {
+      baseCommit: baseCommit ?? preliminary.final.base_commit,
+      commit: preliminary.final.commit,
+    });
+    changedPaths = normalizeChangedPaths(candidate.changes, { projectRoot, worktree });
+    changedPathsBase = candidate.base_commit;
+    const actualFingerprint = await calculateCandidateFingerprintAtCommit(worktree, {
+      baseCommit: candidate.base_commit,
+      commit: candidate.git_head,
+    });
+    const passingRuns = preliminary.verification.filter((run) =>
+      (run.status === "pass" || run.status === "PASS")
+      && run.candidate_fingerprint === preliminary.final.candidate_fingerprint);
+    const passingRun = passingRuns.find((run) => run.candidate_manifest) ?? passingRuns[0];
+    if (passingRun?.candidate_manifest) {
+      if (!candidateManifestsBind(passingRun.candidate_manifest, actualFingerprint.manifest, { expectedBaseCommit: candidate.base_commit })) {
+        throw reportError("human_report_invalid", "committed candidate does not match the independently verified candidate manifest");
+      }
+    } else if (actualFingerprint.value !== preliminary.final.candidate_fingerprint) {
+      throw reportError("human_report_invalid", "final candidate fingerprint does not match the final commit delta");
+    }
+    committedCandidateFingerprint = actualFingerprint.value;
+  }
+  const report = {
+    ...preliminary,
+    final: { ...preliminary.final, committed_candidate_fingerprint: committedCandidateFingerprint ?? null },
+    changed_paths: changedPaths ?? [],
+    changed_paths_base: changedPathsBase
+  };
+  const markdown = renderCardReport(report, { projectRoot, worktree });
+  if (outputPath) {
+    try {
+      const previous = await readFile(outputPath, "utf8");
+      const previousApproved = /\n\*\*APPROVED\*\*\n/.test(previous);
+      if (previousApproved && report.status !== "approved") {
+        throw reportError("human_report_immutable", "an approved Card report cannot be overwritten by a non-approved terminal view");
+      }
+      if (previousApproved && previous !== markdown) {
+        throw reportError("human_report_immutable", "an approved Card report cannot be changed after publication");
+      }
+      if (previous === markdown) return { report, markdown, outputPath };
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+    await writeAtomicText(outputPath, markdown);
+  }
+  return { report, markdown, outputPath: outputPath ?? null };
+}
+
+export async function writeHandoffReport(input, { outputPath, projectRoot = null } = {}) {
+  const handoff = normalizeHandoffInput(input, { projectRoot });
+  const markdown = renderHandoffReport(handoff, { projectRoot });
+  if (outputPath) await writeAtomicText(outputPath, markdown);
+  return { handoff, markdown, outputPath: outputPath ?? null };
+}

package/runtime/lib/process.mjs

@@ -2,11 +2,11 @@ import { spawn } from "node:child_process";
 import process from "node:process";
 
 export function runProcess(command, args = [], options = {}) {
-  const { cwd, timeoutMs = 600_000, shell = false, killGraceMs = 2_000 } = options;
+  const { cwd, timeoutMs = 600_000, shell = false, killGraceMs = 2_000, encoding = "utf8" } = options;
   return new Promise((resolve) => {
     const detached = process.platform !== "win32";
     const child = spawn(command, args, { cwd, shell, detached, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
+    let stdout = encoding === null ? [] : "";
     let stderr = "";
     let timedOut = false;
     let forceTimer;
@@ -15,13 +15,16 @@ export function runProcess(command, args = [], options = {}) {
       signalProcess(child, "SIGTERM", detached);
       forceTimer = setTimeout(() => signalProcess(child, "SIGKILL", detached), killGraceMs);
     }, timeoutMs);
-    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stdout.on("data", (chunk) => {
+      if (encoding === null) stdout.push(Buffer.from(chunk));
+      else stdout += chunk;
+    });
     child.stderr.on("data", (chunk) => { stderr += chunk; });
     child.on("error", (error) => { stderr += `${error.message}\n`; });
     child.on("close", (exitCode, signal) => {
       clearTimeout(timer);
       clearTimeout(forceTimer);
-      resolve({ exitCode: exitCode ?? 1, signal, timedOut, stdout, stderr });
+      resolve({ exitCode: exitCode ?? 1, signal, timedOut, stdout: encoding === null ? Buffer.concat(stdout) : stdout, stderr });
     });
   });
 }

package/runtime/triad-human-report.mjs

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { readFile, realpath } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { writeCardReport, writeHandoffReport } from "./lib/human-reports.mjs";
+
+function parseArgs(argv) {
+  const args = { mode: null, input: null, output: null, project: process.cwd(), worktree: null, baseCommit: null };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === "--help" || flag === "-h") {
+      process.stdout.write("Usage: node .triad-runtime/triad-human-report.mjs --mode <card|handoff> --input <derived-report-context.json> --output <report.md> [--project <control-workspace>] [--worktree <product-worktree>] [--base-commit <card-baseline> ]\n");
+      return null;
+    }
+    const key = { "--mode": "mode", "--input": "input", "--output": "output", "--project": "project", "--worktree": "worktree", "--base-commit": "baseCommit" }[flag];
+    if (!key) throw Object.assign(new Error(`unknown option: ${flag}`), { code: "human_report_cli_invalid" });
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw Object.assign(new Error(`${flag} requires a value`), { code: "human_report_cli_invalid" });
+    args[key] = value;
+    index += 1;
+  }
+  if (!args.mode || !["card", "handoff"].includes(args.mode)) throw Object.assign(new Error("--mode must be card or handoff"), { code: "human_report_cli_invalid" });
+  if (!args.input || !args.output) throw Object.assign(new Error("--input and --output are required"), { code: "human_report_cli_invalid" });
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args) return;
+  const projectRoot = await realpath(args.project);
+  const inputPath = path.resolve(projectRoot, args.input);
+  const outputPath = path.resolve(projectRoot, args.output);
+  const input = JSON.parse(await readFile(inputPath, "utf8"));
+  const result = args.mode === "card"
+    ? await writeCardReport(input, {
+      outputPath,
+      projectRoot,
+      worktree: args.worktree ? await realpath(path.resolve(projectRoot, args.worktree)) : input?.final?.worktree ?? null,
+      baseCommit: args.baseCommit ?? input?.final?.base_commit ?? null,
+    })
+    : await writeHandoffReport(input, { outputPath, projectRoot });
+  process.stdout.write(`${JSON.stringify({ valid: true, mode: args.mode, output: path.relative(projectRoot, result.outputPath) })}\n`);
+}
+
+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

@@ -236,6 +236,7 @@ async function main() {
           candidate_fingerprint: before.value,
           branch,
         },
+        candidate_manifest: before.manifest,
         assignment_packet: assignmentPacket,
         repository_skills: repositorySkills,
         scope,
@@ -266,14 +267,15 @@ async function main() {
       trigger,
       assignment_ref: path.relative(projectRoot, assignmentPath),
       baseline: {
-          prd_sha256: assignment.expected_prd_sha256,
-          card_sha256: assignment.expected_card_sha256,
-          quality_baseline_fingerprint: qualityBaseline?.fingerprint ?? null,
-          gates_sha256: trusted.actualHash,
+        prd_sha256: assignment.expected_prd_sha256,
+        card_sha256: assignment.expected_card_sha256,
+        quality_baseline_fingerprint: qualityBaseline?.fingerprint ?? null,
+        gates_sha256: trusted.actualHash,
         git_head: before.git_head,
         candidate_fingerprint: before.value,
         branch,
       },
+      candidate_manifest: before.manifest,
       assignment_packet: assignmentPacket,
       repository_skills: repositorySkills,
       scope,

package/schemas/verification-evidence.schema.json

@@ -13,6 +13,39 @@
     "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"] } } },
+    "candidate_manifest": {
+      "type": ["object", "null"],
+      "required": ["base_commit", "git_head", "changes", "ignored_paths", "files"],
+      "properties": {
+        "base_commit": { "type": ["string", "null"] },
+        "git_head": { "type": ["string", "null"] },
+        "changes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["status"],
+            "properties": {
+              "status": { "type": "string" },
+              "path": { "type": ["string", "null"] },
+              "source": { "type": ["string", "null"] },
+              "destination": { "type": ["string", "null"] }
+            }
+          }
+        },
+        "ignored_paths": { "type": "array", "items": { "type": "string" } },
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["path", "sha256"],
+            "properties": {
+              "path": { "type": "string" },
+              "sha256": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
     "assignment_packet": {
       "type": ["object", "null"],
       "required": ["path", "sha256"],

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

@@ -30,7 +30,10 @@ authority after the planning handoff.
    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/`. For ordinary PRD-only input,
+4. Copy `assets/loop-template/` to `.loop/`. This includes derived report
+   templates under `runtime/report-context/`; keep report contexts and
+   `card-reports/` in the control workspace, never in product source. 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

package/skills/triad-loop-bootstrap/assets/loop-template/card-report.template.md

@@ -0,0 +1,32 @@
+# Card report — <feature ID>: <title>
+
+> Derived human-readable view of canonical Triad+ evidence. This report is not a new source of truth.
+
+## Result
+
+`APPROVED | BLOCKED | NOT DELIVERED`
+
+## What was implemented
+
+`<bounded outcome and actual result>`
+
+## Card-attributable changed paths
+
+`<complete delta from the immutable card baseline, including additions, modifications, renames, and deletions>`
+
+## Verification and gates
+
+`<verification runs, gate results, evidence references, and attempt/rework history>`
+
+## Independent Reviewer
+
+`<decision, findings, resolutions, risks, and review evidence>`
+
+## Final evidence and provenance
+
+`<repository, branch, commit/range, card baseline, candidate fingerprint, packet, review, and evidence references>`
+
+## Risks, deferred work, and terminal notes
+
+`<truthful residual information; never claim success for a blocked card>`
+

package/skills/triad-loop-bootstrap/assets/loop-template/handoff-report.template.md

@@ -1,5 +1,19 @@
 # Delivery handoff — <project ID>
 
+## Executive summary
+
+`<human-first summary of the delivery decision, product outcome, and any blocked or deferred work>`
+
+## Card-by-card results
+
+| Card | Result | Outcome | Commit | Candidate fingerprint | Evaluator+ | Human-readable report |
+| --- | --- | --- | --- | --- | --- | --- |
+| `<ID>` | `<approved|blocked|not delivered>` | `<summary>` | `<commit>` | `<fingerprint>` | `<report or not configured>` | `<relative card-reports/<ID>.md path>` |
+
+The Markdown reports are derived views. The control-workspace run state,
+verification evidence, review records, delivery gates, and optional Evaluator+
+report remain authoritative.
+
 ## Decision
 
 `delivered | delivery_blocked | delivered_without_demo`

package/skills/triad-loop-bootstrap/assets/loop-template/runtime/report-context/card.template.json

@@ -0,0 +1,29 @@
+{
+  "schema_version": 1,
+  "project_id": "REPLACE_ME",
+  "card": {
+    "id": "REPLACE_ME",
+    "title": "REPLACE_ME",
+    "goal": "REPLACE_ME",
+    "outcome": "REPLACE_ME",
+    "target_repository": "REPLACE_ME",
+    "card_path": "features/REPLACE_ME.md"
+  },
+  "status": "approved",
+  "implementation": { "summary": "REPLACE_ME" },
+  "attempts": [],
+  "verification": [],
+  "review": null,
+  "final": {
+    "repository": "REPLACE_ME",
+    "branch": "REPLACE_ME",
+    "commit": "REPLACE_ME",
+    "base_commit": "REPLACE_ME",
+    "candidate_fingerprint": "REPLACE_ME",
+    "committed_candidate_fingerprint": null,
+    "worktree": "REPLACE_ME_ABSOLUTE_PRODUCT_WORKTREE"
+  },
+  "evidence_refs": [],
+  "risks": [],
+  "deferred": []
+}

package/skills/triad-loop-bootstrap/assets/loop-template/runtime/report-context/delivery.template.json

@@ -0,0 +1,16 @@
+{
+  "schema_version": 1,
+  "project_id": "REPLACE_ME",
+  "decision": "delivered",
+  "executive_summary": "REPLACE_ME",
+  "cards": [],
+  "code_areas": [],
+  "residual": [],
+  "verification": "REPLACE_ME",
+  "review": "REPLACE_ME",
+  "branch_commits": [],
+  "practical_test": [],
+  "evaluator": "not configured",
+  "delivery": "REPLACE_ME",
+  "risks": []
+}

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

@@ -204,6 +204,63 @@ fail-closed escalation; do not dispatch a Developer or consume retry budget.
    while a dependency-satisfied card remains `ready`; stop only for a declared
    escalation, a blocked card, or when every required card is terminal.
 
+## Human-readable terminal reports
+
+Human-readable reports are derived views, not a second control plane and not a
+new LLM task. For every terminal Card, assemble a small JSON context from the
+canonical card, attempts, verifier evidence, Reviewer record, final commit, and
+candidate fingerprint. Do not copy Developer prose as changed-path evidence.
+
+For an approved Card, the context must include the final commit and fingerprint,
+at least one current passing verifier record, an independent Reviewer approval,
+and the complete Card-baseline commit. The final candidate fingerprint in this
+context is the identity recorded by the passing verifier (the pre-commit
+candidate), not a newly recalculated commit fingerprint. Preserve the verifier's
+`candidate_manifest` alongside that record. The report runtime binds that
+independently verified path/content manifest to the final commit delta and
+records both the verified fingerprint and the committed fingerprint. It ignores
+only the expected `git_head` identity change caused by committing; added,
+removed, renamed, or modified paths and their content hashes must still match.
+If a legacy verifier record has no manifest, the historical fingerprint equality
+check remains fail-closed. Materialize the report with the installed runtime
+command, which collects the complete baseline delta from Git:
+
+```bash
+node .triad-runtime/triad-human-report.mjs \
+  --mode card \
+  --project /absolute/path/to/control-workspace \
+  --input .loop/runtime/report-context/<card-id>.json \
+  --output card-reports/<card-id>.md \
+  --worktree /absolute/path/to/product-worktree \
+  --base-commit <card-baseline-commit>
+```
+
+Generate this only after the Card reaches its terminal state. A blocked or
+not-delivered Card must include a truthful reason and must never be rendered as
+approved. The renderer is atomic and idempotent; a resumed run may repeat the
+same command without creating duplicate reports. It records additions,
+modifications, deletions, and renames from the Card baseline, including paths
+left by earlier rework attempts. Keep report paths relative to the control
+workspace and never emit machine-specific absolute paths.
+
+After all required Cards and delivery criteria are closed, assemble a derived
+handoff context and run:
+
+```bash
+node .triad-runtime/triad-human-report.mjs \
+  --mode handoff \
+  --project /absolute/path/to/control-workspace \
+  --input .loop/runtime/report-context/delivery.json \
+  --output handoff.md
+```
+
+The handoff must open with an executive summary and Card-by-Card report links,
+then preserve the technical branch/commit map, verifier/review/evaluator
+evidence, delivery criteria, demos, risks, and practical-test instructions.
+Missing or invalid final evidence is a report-generation error, not a success
+claim. Do not add a second report agent or overwrite an approved report with a
+later non-terminal candidate.
+
 ## Unattended continuation rule
 
 The normal chain is unattended: Developer completion → verification → Reviewer