triad-plus 1.10.0 → 1.12.0

package/runtime/lib/installation-manifest.mjs

@@ -0,0 +1,269 @@
+import { createHash } from 'node:crypto';
+import { access, lstat, mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export const INSTALLATION_MANIFEST_SCHEMA_VERSION = 1;
+export const INSTALLATION_MANIFEST_PATH = '.triad-plus/installation.json';
+
+const SHA256 = /^[a-f0-9]{64}$/i;
+const SCOPES = new Set(['project', 'global']);
+const SCOPE_STATES = new Set(['installed', 'partial', 'uninstalled', 'not_configured']);
+const TOP_LEVEL_KEYS = new Set([
+  'schema_version',
+  'triad_version',
+  'adapter',
+  'installed_at',
+  'updated_at',
+  'uninstalled_at',
+  'scopes',
+  'scope_status',
+  'managed_assets',
+  'status',
+  'fingerprint'
+]);
+const ASSET_KEYS = new Set(['scope', 'path', 'kind', 'sha256', 'start_marker', 'end_marker']);
+
+function invalid(message) {
+  const error = new Error(message);
+  error.code = 'installation_manifest_invalid';
+  return error;
+}
+
+function objectLike(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function digest(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+/**
+ * Return a stable JSON-compatible value with object keys ordered recursively.
+ * Array order is intentionally preserved because the manifest is an ordered
+ * record of the managed install plan.
+ */
+export function canonicalize(value) {
+  if (Array.isArray(value)) return value.map((item) => canonicalize(item));
+  if (!objectLike(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+
+export function installationManifestPayload(manifest) {
+  const { fingerprint: _fingerprint, ...payload } = manifest;
+  return payload;
+}
+
+export function installationManifestFingerprint(manifest) {
+  return digest(canonicalJson(installationManifestPayload(manifest)));
+}
+
+function normalizeRelative(value) {
+  if (typeof value !== 'string' || !value.trim()) throw invalid('installation manifest asset path must be non-empty');
+  if (value.includes('\0') || path.isAbsolute(value)) throw invalid(`installation manifest project path must be relative: ${value}`);
+  const normalized = value.split(path.sep).join('/');
+  const parts = normalized.split('/');
+  if (parts.some((part) => !part || part === '.' || part === '..')) {
+    throw invalid(`installation manifest path contains traversal or empty segments: ${value}`);
+  }
+  if (path.posix.normalize(normalized) !== normalized) throw invalid(`installation manifest path is not normalized: ${value}`);
+  return normalized;
+}
+
+function normalizeAbsolute(value) {
+  if (typeof value !== 'string' || !value.trim() || value.includes('\0') || !path.isAbsolute(value)) {
+    throw invalid(`installation manifest global path must be absolute: ${value}`);
+  }
+  const normalized = path.resolve(value);
+  if (normalized !== value) throw invalid(`installation manifest global path is not normalized: ${value}`);
+  return normalized;
+}
+
+function validateTimestamp(value, label) {
+  if (typeof value !== 'string' || !value.trim() || Number.isNaN(Date.parse(value))) {
+    throw invalid(`installation manifest ${label} must be an ISO timestamp`);
+  }
+}
+
+function rejectUnknown(value, allowed, label) {
+  for (const key of Object.keys(value)) if (!allowed.has(key)) throw invalid(`${label} has unknown property: ${key}`);
+}
+
+/** Validate a manifest, including its self-declared fingerprint. */
+export function validateInstallationManifest(manifest) {
+  if (!objectLike(manifest)) throw invalid('installation manifest must be a JSON object');
+  rejectUnknown(manifest, TOP_LEVEL_KEYS, 'installation manifest');
+  if (manifest.schema_version !== INSTALLATION_MANIFEST_SCHEMA_VERSION) {
+    throw invalid(`installation manifest schema_version must be ${INSTALLATION_MANIFEST_SCHEMA_VERSION}`);
+  }
+  if (typeof manifest.triad_version !== 'string' || !manifest.triad_version.trim()) throw invalid('installation manifest triad_version must be non-empty');
+  if (typeof manifest.adapter !== 'string' || !manifest.adapter.trim()) throw invalid('installation manifest adapter must be non-empty');
+  validateTimestamp(manifest.installed_at, 'installed_at');
+  validateTimestamp(manifest.updated_at, 'updated_at');
+  if (manifest.uninstalled_at !== undefined) validateTimestamp(manifest.uninstalled_at, 'uninstalled_at');
+
+  if (!objectLike(manifest.scopes)) throw invalid('installation manifest scopes must be an object');
+  rejectUnknown(manifest.scopes, SCOPES, 'installation manifest scopes');
+  if (typeof manifest.scopes.project !== 'boolean' || typeof manifest.scopes.global !== 'boolean') {
+    throw invalid('installation manifest scopes.project and scopes.global must be booleans');
+  }
+
+  if (manifest.scope_status !== undefined) {
+    if (!objectLike(manifest.scope_status)) throw invalid('installation manifest scope_status must be an object');
+    rejectUnknown(manifest.scope_status, SCOPES, 'installation manifest scope_status');
+    for (const scope of SCOPES) {
+      if (!SCOPE_STATES.has(manifest.scope_status[scope])) throw invalid(`installation manifest scope_status.${scope} is invalid`);
+    }
+  }
+
+  if (!Array.isArray(manifest.managed_assets)) throw invalid('installation manifest managed_assets must be an array');
+  const seen = new Set();
+  for (const asset of manifest.managed_assets) {
+    if (!objectLike(asset)) throw invalid('installation manifest managed asset must be an object');
+    rejectUnknown(asset, ASSET_KEYS, 'installation manifest managed asset');
+    if (!SCOPES.has(asset.scope)) throw invalid(`installation manifest managed asset scope is invalid: ${asset.scope}`);
+    const normalized = asset.scope === 'project' ? normalizeRelative(asset.path) : normalizeAbsolute(asset.path);
+    if (normalized !== asset.path) throw invalid(`installation manifest managed asset path is not normalized: ${asset.path}`);
+    if (asset.kind === 'file') {
+      if (asset.start_marker !== undefined || asset.end_marker !== undefined) {
+        throw invalid(`installation manifest file asset cannot contain managed block markers: ${asset.path}`);
+      }
+    } else if (asset.kind === 'managed_block') {
+      if (asset.scope !== 'project') throw invalid(`installation manifest managed block must be project-scoped: ${asset.path}`);
+      if (typeof asset.start_marker !== 'string' || !asset.start_marker || typeof asset.end_marker !== 'string' || !asset.end_marker || asset.start_marker === asset.end_marker) {
+        throw invalid(`installation manifest managed block markers are invalid: ${asset.path}`);
+      }
+    } else {
+      throw invalid(`installation manifest managed asset kind is unsupported: ${asset.kind}`);
+    }
+    if (typeof asset.sha256 !== 'string' || !SHA256.test(asset.sha256)) throw invalid(`installation manifest managed asset sha256 is invalid: ${asset.path}`);
+    const key = `${asset.scope}:${asset.path}`;
+    if (seen.has(key)) throw invalid(`installation manifest managed asset is duplicated: ${key}`);
+    seen.add(key);
+  }
+
+  if (manifest.status !== undefined && !SCOPE_STATES.has(manifest.status)) throw invalid(`installation manifest status is invalid: ${manifest.status}`);
+  if (typeof manifest.fingerprint !== 'string' || !SHA256.test(manifest.fingerprint)) throw invalid('installation manifest fingerprint is invalid');
+  const calculated = installationManifestFingerprint(manifest);
+  if (manifest.fingerprint.toLowerCase() !== calculated) throw invalid('installation manifest fingerprint does not match its contents');
+  return manifest;
+}
+
+export function installationManifestPath(controlRoot) {
+  return path.join(controlRoot, INSTALLATION_MANIFEST_PATH);
+}
+
+export async function loadInstallationManifest(controlRoot) {
+  const manifestPath = installationManifestPath(controlRoot);
+  try {
+    await access(manifestPath);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+  } catch (error) {
+    throw invalid(`installation manifest is not valid JSON: ${error.message}`);
+  }
+  validateInstallationManifest(manifest);
+  return { path: manifestPath, manifest };
+}
+
+export async function writeInstallationManifest(controlRoot, manifest) {
+  validateInstallationManifest(manifest);
+  const target = installationManifestPath(controlRoot);
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = `${target}.tmp`;
+  await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+  await rename(temporary, target);
+  return target;
+}
+
+function within(root, target) {
+  const base = path.resolve(root);
+  const resolved = path.resolve(target);
+  return resolved === base || resolved.startsWith(`${base}${path.sep}`);
+}
+
+async function walkFiles(target, files) {
+  let info;
+  try { info = await lstat(target); } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  if (info.isDirectory()) {
+    for (const name of (await readdir(target)).sort()) await walkFiles(path.join(target, name), files);
+    return;
+  }
+  if (!info.isFile()) throw invalid(`managed installation asset is not a regular file: ${target}`);
+  files.push(target);
+}
+
+export async function sha256File(filePath) {
+  return digest(await readFile(filePath));
+}
+
+export function sha256Text(value) {
+  return digest(value);
+}
+
+/** Collect the exact regular files materialized below one or more asset roots. */
+export async function collectManagedAssetRecords(roots, { scope, baseRoot = null } = {}) {
+  if (!SCOPES.has(scope)) throw new Error(`unknown installation asset scope: ${scope}`);
+  const files = [];
+  for (const root of [...new Set(roots.map((item) => path.resolve(item)))]) await walkFiles(root, files);
+  const unique = [...new Set(files.map((item) => path.resolve(item)))].sort();
+  return Promise.all(unique.map(async (filePath) => {
+    const assetPath = scope === 'project'
+      ? path.relative(path.resolve(baseRoot), filePath).split(path.sep).join('/')
+      : filePath;
+    if (scope === 'project' && (!assetPath || assetPath.startsWith('..') || !within(baseRoot, filePath))) {
+      throw invalid(`managed project asset escaped control root: ${filePath}`);
+    }
+    return { scope, path: assetPath, kind: 'file', sha256: await sha256File(filePath) };
+  }));
+}
+
+export function buildInstallationManifest({
+  triadVersion,
+  adapter,
+  installedAt = new Date().toISOString(),
+  updatedAt = installedAt,
+  uninstalledAt,
+  scopes = { project: true, global: false },
+  scopeStatus = { project: 'installed', global: scopes.global ? 'installed' : 'not_configured' },
+  managedAssets = [],
+  status = 'installed'
+}) {
+  const manifest = {
+    schema_version: INSTALLATION_MANIFEST_SCHEMA_VERSION,
+    triad_version: triadVersion,
+    adapter,
+    installed_at: installedAt,
+    updated_at: updatedAt,
+    scopes: { project: Boolean(scopes.project), global: Boolean(scopes.global) },
+    scope_status: { project: scopeStatus.project, global: scopeStatus.global },
+    managed_assets: [...managedAssets].sort((left, right) => `${left.scope}:${left.path}`.localeCompare(`${right.scope}:${right.path}`)),
+    status
+  };
+  if (uninstalledAt) manifest.uninstalled_at = uninstalledAt;
+  manifest.fingerprint = installationManifestFingerprint(manifest);
+  validateInstallationManifest(manifest);
+  return manifest;
+}
+
+export function manifestScopeStatus(manifest, scope) {
+  if (manifest.scope_status?.[scope]) return manifest.scope_status[scope];
+  return manifest.scopes?.[scope] ? 'installed' : 'not_configured';
+}
+
+export function manifestIsUninstalled(manifest) {
+  return manifest.status === 'uninstalled' || (
+    ['project', 'global'].every((scope) => ['not_configured', 'uninstalled'].includes(manifestScopeStatus(manifest, scope)))
+  );
+}

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/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,28 @@
+{
+  "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",
+    "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,54 @@ 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. 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