triad-plus 1.10.0 → 1.12.0

package/docs/configuration.md

@@ -31,6 +31,37 @@ adapter writes those into host-native profiles only where the selected host
 supports that facility. A blank model means the host default. Never put tokens,
 API keys, or private deployment data in this file.
 
+## Installation ownership and version
+
+The package version and the installed workspace version are separate facts:
+
+```bash
+npx triad-plus --version
+npx triad-plus version --control /path/to/project-control
+```
+
+After successful materialization, `.triad-plus/installation.json` records the
+adapter, project/global scopes, exact managed files, SHA-256 hashes, timestamps,
+and a deterministic fingerprint. Project paths are control-workspace-relative;
+global paths identify the user-level managed asset. The manifest is generated
+from the same adapter registry and install plan used by `init` and `upgrade`.
+
+The manifest deliberately does not own `.triad-plus/team.json`, `.loop/`,
+`project.yaml`, feature cards, artifacts, evidence, or product source. A failed
+install never writes a success manifest. Legacy workspaces are migrated by
+`upgrade --apply` using the currently executing package version; the previous
+version is not guessed.
+
+When a team configuration is materialized, the managed role-run block in
+`AGENTS.md` is recorded as a bounded block asset. Uninstall removes that block
+only when its markers and hash still match, never the surrounding user file.
+Global assets are shared-capable and therefore preserved by default by
+`uninstall --global`.
+
+`doctor` reports CLI version, installed version, manifest state, adapter, and
+project/global scope. It reports version skew explicitly and never queries npm
+for `latest`.
+
 ## Configure models through the agent
 
 The installed `triad-model-configuration` skill lets an owner ask the selected

package/docs/human-readable-reports.md

@@ -0,0 +1,52 @@
+# 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, candidate
+fingerprint, passing verifier evidence, independent Reviewer approval, and the
+complete changed-path manifest. 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/npx-installation.md

@@ -22,11 +22,68 @@ npx triad-plus init --host codex --control /path/to/project-control --global
 npx triad-plus doctor --host codex --control /path/to/project-control
 ```
 
-## Upgrade an existing control workspace
+## Version visibility
 
-`upgrade` refreshes only Triad-managed runtime, skill, adapter, and optional
-host-entry assets. It never changes `team.json`, `.loop/`, PRD files, evidence,
-or product repositories. The default is a dry run:
+`--version` reports the package that is actually executing:
+
+```bash
+npx triad-plus --version
+```
+
+The workspace command reports the materialized installation recorded by the
+control workspace manifest:
+
+```bash
+npx triad-plus version --control /path/to/project-control
+```
+
+An older workspace without `.triad-plus/installation.json` is reported as a
+legacy installation. Triad+ does not infer a historical version from scattered
+agent files.
+
+## Installation manifest and safe uninstall
+
+After a successful `init`, Triad+ writes
+`.triad-plus/installation.json`. It records the selected adapter, CLI version,
+project/global scopes, normalized managed-file paths, SHA-256 hashes, and a
+manifest fingerprint. `upgrade --apply` refreshes this record after managed
+assets are materialized; a legacy workspace receives a new manifest without
+inventing its previous version.
+
+Uninstall is dry-run by default:
+
+```bash
+npx triad-plus uninstall --host opencode --control /path/to/project-control
+npx triad-plus uninstall --host opencode --control /path/to/project-control --apply
+npx triad-plus uninstall --host opencode --control /path/to/project-control --global --apply
+```
+
+Only files listed in the manifest, still unchanged from their recorded hash,
+are removed. Missing files are reported as `ABSENT`; modified assets are
+preserved. Host directories are never pruned because directory ownership is
+not claimed. The team configuration, `.loop/`, project manifest, feature
+cards, artifacts, evidence, and other user state are preserved. A managed
+`AGENTS.md` role-run block is tracked separately and removed only when its
+markers and hash are exact; surrounding user content remains. A manifest
+remains as an `uninstalled` or `partial` tombstone so a second uninstall is
+idempotent and the ownership history is auditable.
+
+`--global --apply` is deliberately preserve-by-default: global assets may be
+shared by several control workspaces, so the command reports them as shared
+and does not delete them without a cross-workspace ownership model.
+
+Read-only commands require an existing control workspace; a typo path is
+never created by `version` or `uninstall`.
+
+## Upgrade, repair, or restore an existing control workspace
+
+`init` is the first-install command and refuses to overwrite an existing
+workspace. `upgrade --apply` is the managed update, repair, and restore path
+for a workspace that is already registered by an installation manifest,
+including a workspace whose project scope is `uninstalled` or `partial` after a
+safe uninstall. It re-materializes project assets, reuses the preserved
+`team.json`, and refreshes the manifest without changing user state, `.loop/`,
+PRD files, evidence, or product repositories. The default is a dry run:
 
 ```bash
 npx triad-plus upgrade --host codex --control /path/to/project-control --global

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/docs/troubleshooting.md

@@ -6,6 +6,26 @@ Run doctor first:
 npx triad-plus doctor --host <runtime> --control /path/to/triad-control
 ```
 
+Compare the executing CLI with the materialized workspace installation:
+
+```bash
+npx triad-plus --version
+npx triad-plus version --control /path/to/triad-control
+```
+
+`legacy / manifest missing` means the workspace predates the installation
+manifest. Run `upgrade --apply` to materialize a current manifest; Triad+ does
+not infer the old version. The same `upgrade --apply` command is the managed
+restore path after a safe uninstall leaves an `uninstalled` or `partial`
+manifest: it re-materializes managed assets and reuses the preserved team
+configuration and user state. `init` is reserved for first installation and
+refuses existing paths. `manifest invalid` means the ownership record or its
+fingerprint is malformed and should be reviewed before any uninstall.
+
+Doctor also reports `CLI newer / upgrade available` and `CLI older than
+installed version` instead of silently claiming compatibility. It never checks
+the npm `latest` tag.
+
 `not installed` means the selected adapter assets are absent from that control
 workspace. `not installed or version unavailable` for a host means its binary is
 not on PATH or otherwise cannot answer `--version`. Re-run the appropriate host
@@ -20,3 +40,24 @@ baselines, worktree, branch, and candidate. Do not treat it as a passing test.
 
 If Evaluator+ is unavailable, check `roles.evaluator.enabled` in the team file.
 An Evaluator+ failure is post-run information, not an automatic repair request.
+
+## Safe uninstall
+
+Uninstall is a dry run unless `--apply` is supplied:
+
+```bash
+npx triad-plus uninstall --host <runtime> --control /path/to/triad-control
+npx triad-plus uninstall --host <runtime> --control /path/to/triad-control --apply
+```
+
+Only unchanged files listed in `.triad-plus/installation.json` are removed.
+`ABSENT` files are harmless. A `PRESERVE` line means the file was modified, no
+longer matches the trusted managed plan, or is not a regular file; no force
+option exists for this operation. Add `--global` only when user-level Triad
+assets should also be considered. Global assets are nevertheless preserved by
+default because another workspace may share them. Team config, loop state,
+cards, artifacts, evidence, generic host directories, and other user files are
+preserved. A managed `AGENTS.md` block is removed only when its exact markers
+and hash still match; a modified or ambiguous block leaves the uninstall
+partial. `version` and `uninstall` reject nonexistent control paths without
+creating them.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triad-plus",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "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/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",
     "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);
 }
@@ -84,6 +90,63 @@ 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 });
+  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 };
+}
+
 export async function worktreeBranch(worktree) {
   const root = await realpath(worktree);
   return (await gitLines(root, ["branch", "--show-current"]))[0] ?? "DETACHED";