triad-plus 1.6.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.8.0 — 2026-09-12
+
+- Add an optional Immutable Quality Contract with a deterministic Quality
+  Baseline fingerprint and fail-closed source-drift detection.
+- Add phase-scoped `product_quality` and `delivery_closure` criteria,
+  criterion-level Evaluator+ validation, and a deterministic aggregate
+  verdict.
+- Add deterministic Evaluator+/Delivery control-plane validation while
+  preserving legacy Triad+ 1.7 compatibility.
+
+## 1.7.0 — 2026-09-10
+
+- Add an optional deterministic importer for one BMAD `ready-for-dev` Story at
+  a time, preserving the normal Triad Card contract and source provenance.
+
 ## 1.6.0 — 2026-09-05
 
 - Add card-declared repository `required_gates` with additive per-card gate

package/README.md

@@ -107,6 +107,32 @@ The Orchestrator first shows the feature cards, then delegates the bounded work.
 If a tutorial step is unclear, see the [OpenCode guide](docs/runtimes.md#opencode)
 and [troubleshooting](docs/troubleshooting.md).
 
+## Optional immutable quality target
+
+An initialized project may bind an immutable JSON Quality Baseline through
+`project.quality_contract`. Triad fingerprints the canonical manifest, verifies
+all declared sources before running costly gates, and fails closed on malformed
+contracts or source drift. `product_quality` criteria are evaluated one by one
+by a fresh Evaluator+; `delivery_closure` criteria remain in the delivery gate.
+Projects without this opt-in continue to use the legacy PRD baseline path.
+
+## Optional BMAD Story import
+
+When BMAD planning has already produced a Story with `status: ready-for-dev`,
+you can convert one Story at a time into the normal Triad Card contract:
+
+```bash
+npx triad-plus import-bmad-story \
+  --source /absolute/path/to/story.md \
+  --output /absolute/path/to/control/features/STORY-001.md
+```
+
+The importer is read-only and fail-closed. It preserves the Story's executable
+intent, acceptance criteria, technical context, and references, while any
+required gates or dependencies remain explicit caller options. It does not run
+BMAD workflows or add BMAD semantics to the Core. See the [BMAD integration
+guide](docs/bmad-integration.md).
+
 ## Quick start for every runtime
 
 Requirements: Node.js 20+ and one supported coding-agent host.

package/adapters/antigravity/.agents/agents/triad-evaluator/agent.md

@@ -16,3 +16,8 @@ Return `candidate_wins`, `bar_wins`, or `indeterminate`; a `bar_wins` decision
 has exactly one evidence-based largest gap. Do not edit source, change loop
 state, commit, push, or review delivery, request repair, or reopen the Triad
 run.
+
+For an immutable Quality Contract, use the supplied baseline fingerprint and
+evaluate each `product_quality` criterion exactly once. `delivery_closure`
+criteria are excluded from this fresh packet and belong to delivery closure;
+the control plane validates the final aggregate.

package/adapters/claude-code/.claude/agents/triad-evaluator.md

@@ -23,3 +23,8 @@ Return `candidate_wins`, `bar_wins`, or `indeterminate`. A `bar_wins` result has
 exactly one evidence-based largest gap with one bounded repair scope. Do not edit
 product source, change state, commit, push, or approve delivery; do not request
 repair or reopen the Triad run.
+
+For an immutable Quality Contract, report the supplied baseline fingerprint and
+evaluate every supplied `product_quality` criterion once. `delivery_closure`
+criteria are not part of this packet and are checked by delivery closure. The
+control plane, not the model, determines the deterministic aggregate verdict.

package/adapters/copilot/.github/agents/triad-evaluator.agent.md

@@ -24,3 +24,8 @@ out-of-packet control record to justify a verdict. Return `PASS`, `FAIL`, or
 Do not edit source, change Triad queue/state, assign work, commit, push, publish,
 or start repair. Your verdict is post-run information. It never reopens Triad,
 requests repair, or changes an already closed result.
+
+When an immutable Quality Contract is present, report its fingerprint and one
+result for every supplied `product_quality` criterion. Do not receive or judge
+`delivery_closure` criteria; the control plane validates the deterministic
+aggregate rather than trusting a model-selected overall verdict.

package/adapters/hermes/skills/triad/SKILL.md

@@ -51,3 +51,8 @@ post-run report at the absolute `<control-workspace>/artifacts/evaluator-plus/`
 path supplied by the Orchestrator; never infer it relative to a product worktree.
 `FAIL` or `INDETERMINATE` is information for a new
 owner-requested run, never an automatic repair and never reopens Triad.
+
+If an immutable Quality Contract is configured, pass only its fingerprint and
+`product_quality` criteria to the fresh Evaluator+. Exclude `delivery_closure`
+criteria, which are recorded by delivery closure. Return one result per product
+criterion; the shared control plane validates coverage and aggregate verdict.

package/adapters/opencode/.opencode/agents/triad-evaluator.md

@@ -36,3 +36,9 @@ result being assessed.
 Return `PASS`, `FAIL`, or `INDETERMINATE` with concise evidence. Do not edit
 source, make delivery decisions, commit, push, or change workflow state; do not
 request repair. A verdict never reopens Triad or starts repair.
+
+If the packet includes an immutable Quality Contract, use its fingerprint and
+evaluate exactly the supplied `product_quality` criteria once each. Never
+evaluate `delivery_closure` criteria; delivery closure records those separately.
+The control plane validates the deterministic aggregate, so do not invent a
+different overall verdict.

package/bin/triad-plus.js

@@ -8,6 +8,7 @@ import { dirname, join, resolve } from 'node:path';
 import process from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { getAdapter, listAdapters, roleDefinitions, sharedSkillNames } from '../adapters/registry.mjs';
+import { writeImportedCard } from '../integrations/bmad/story-importer.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -20,6 +21,7 @@ Usage:
   npx triad-plus init --host <adapter-id> --control <path> [--global] [--team-config <path>] [--allow-product-repo]
   npx triad-plus doctor --host <adapter-id> --control <path> [--hook-config <path>]
   npx triad-plus upgrade --host <adapter-id> --control <path> [--global] [--apply]
+  npx triad-plus import-bmad-story --source <story.md> --output <card.md> [--target-repository <id>] [--provenance <record.json>] [--required-gate <id>] [--depends-on <card-id>]
 
 Adapters: ${listAdapters().map((adapter) => adapter.id).join(', ')}
 
@@ -31,13 +33,20 @@ Installation refuses every asset overwrite. Upgrade is a dry run unless --apply
 
 function parseArgs(args) {
   const [command, ...rest] = args;
-  const options = { command, global: false, allowProductRepo: false, apply: false };
+  const options = { command, global: false, allowProductRepo: false, apply: false, requiredGates: [], dependsOn: [] };
   for (let index = 0; index < rest.length; index += 1) {
     const argument = rest[index];
     if (argument === '--global') options.global = true;
     else if (argument === '--allow-product-repo') options.allowProductRepo = true;
     else if (argument === '--apply') options.apply = true;
-    else if (['--host', '--control', '--team-config', '--hook-config'].includes(argument)) {
+    else if (argument === '--required-gate' || argument === '--depends-on') {
+      const value = rest[index + 1];
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value.`);
+      const target = argument === '--required-gate' ? options.requiredGates : options.dependsOn;
+      target.push(value);
+      index += 1;
+    }
+    else if (['--host', '--control', '--team-config', '--hook-config', '--source', '--output', '--target-repository', '--provenance'].includes(argument)) {
       const value = rest[index + 1];
       if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value.`);
       options[argument.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase())] = value;
@@ -395,6 +404,21 @@ async function upgrade(options) {
   if (!options.apply) process.stdout.write('Dry run only. Re-run with --apply to update managed assets.\n');
 }
 
+async function importBmadStory(options) {
+  if (!options.source) throw new Error('Provide --source <bmad-story.md>.');
+  if (!options.output) throw new Error('Provide --output <triad-card.md>.');
+  const result = await writeImportedCard({
+    sourcePath: options.source,
+    outputPath: options.output,
+    targetRepository: options.targetRepository,
+    provenancePath: options.provenance,
+    requiredGates: options.requiredGates,
+    dependsOn: options.dependsOn
+  });
+  process.stdout.write(`Imported BMAD Story ${result.story.id} as Triad Card ${result.outputPath}\n`);
+  process.stdout.write(`Provenance ${result.provenancePath}\n`);
+}
+
 async function doctor(options) {
   if (!options.control) throw new Error('Provide --control <project-control-path>.');
   const controlRoot = resolve(options.control);
@@ -468,10 +492,11 @@ try {
   if (options.command === 'init') await init(options);
   else if (options.command === 'doctor') await doctor(options);
   else if (options.command === 'upgrade') await upgrade(options);
+  else if (options.command === 'import-bmad-story') await importBmadStory(options);
   else if (!options.command) await interactiveInit();
   else if (options.command === '--help' || options.command === '-h') usage(0);
   else throw new Error(`Unknown command: ${options.command}`);
 } catch (error) {
-  process.stderr.write(`${error.message}\n`);
+  process.stderr.write(`${error.code ? `${error.code}: ` : ''}${error.message}\n`);
   usage(2);
 }

package/docs/architecture.md

@@ -22,3 +22,10 @@ runtime-specific branches to Core installer or verification logic.
 
 Evaluator+ is outside the Core: it runs after a Reviewer-approved result, receives
 a deliberately limited fresh packet, and cannot reopen the completed run.
+
+An optional immutable Quality Contract extends this existing control-plane
+baseline without creating a second control plane. Its JSON manifest binds
+approved intent sources and phase-scoped criteria to one canonical fingerprint.
+`product_quality` criteria travel in the fresh Evaluator+ packet;
+`delivery_closure` criteria are checked only during delivery closure. Projects
+without the contract keep the legacy PRD baseline behavior.

package/docs/bmad-integration.md

@@ -0,0 +1,110 @@
+# Optional BMAD Story integration
+
+Triad+ can consume one already-produced BMAD Story and turn it into a normal
+Triad feature Card. This is an integration boundary, not a BMAD execution
+adapter: BMAD remains the planning authority and Triad remains responsible for
+implementation, verification, review, and delivery.
+
+## Contract
+
+The source is a read-only Markdown Story. It must contain:
+
+- a unique Story `id` and `title` (frontmatter, metadata labels, or a Story
+  heading);
+- `status: ready-for-dev` (frontmatter or a `Status` field);
+- a target repository (or an explicit `--target-repository` importer option);
+- an intent/outcome; and
+- acceptance criteria.
+
+The importer also carries through the Story's `Tasks & Acceptance`, Code Map,
+Design Notes/constraints, verification expectations, and source references
+when they are present. It does not interpret prose with an LLM, re-decompose a
+Story, or invoke BMAD Build, Build Auto, or `bmad-loop`.
+
+## CLI
+
+```bash
+npx triad-plus import-bmad-story \
+  --source /absolute/path/to/story.md \
+  --output /absolute/path/to/control/features/JFR-001.md \
+  --target-repository webup \
+  --required-gate cypress-jfr \
+  --depends-on JFR-000
+```
+
+`--required-gate` and `--depends-on` may be repeated. They are explicit caller
+options: gate IDs are additive to the repository's globally required gates,
+and dependencies are never inferred from `stories.yaml` order. Omit both when
+the Card should use the repository's normal/baseline behavior.
+
+The command writes the Card and a sidecar provenance record (by default
+`<card>.bmad-provenance.json`). The provenance records `source_kind:
+bmad-story`, the resolved source path, source SHA-256, BMAD Story ID, target
+repository, Card SHA-256, and the explicit options used for the import.
+
+The same operation is available to Node consumers:
+
+```js
+import { importBmadStory, writeImportedCard } from
+  'triad-plus/integrations/bmad/story-importer.mjs';
+
+const result = await importBmadStory({
+  sourcePath: '/absolute/path/to/story.md',
+  targetRepository: 'webup',
+  requiredGates: ['cypress-jfr']
+});
+
+await writeImportedCard({
+  sourcePath: '/absolute/path/to/story.md',
+  outputPath: '/absolute/path/to/control/features/JFR-001.md',
+  targetRepository: 'webup',
+  requiredGates: ['cypress-jfr']
+});
+```
+
+## Example mapping
+
+Input (abridged):
+
+```md
+---
+id: JFR-001
+title: Route the provider document
+status: ready-for-dev
+target_repository: webup
+---
+
+# Story JFR-001: Route the provider document
+
+## Intent
+
+Webup renders the provider-owned document at the existing boundary.
+
+## Acceptance Criteria
+
+- Given a valid document, when the route is requested, then it renders.
+
+## Code Map
+
+- `src/components/jfr/`
+```
+
+The generated Card keeps that intent, acceptance criterion, Code Map, and the
+target repository, then adds the normal Triad sections and the integration
+boundary note. The caller-supplied `cypress-jfr` (if any) is recorded as an
+additive required gate; it is not inferred from the word "render" or from a
+file extension.
+
+## Fail-closed behavior
+
+No executable Card is produced for a missing source, missing/non-`ready-for-dev`
+status, malformed or ambiguous ID/title, missing indispensable Card fields,
+conflicting target repository, invalid caller options, or a source that changes
+while it is being read. The API exposes integration-level error codes such as
+`bmad_story_not_ready`, `bmad_story_ambiguous`, `bmad_story_unmappable`, and
+`bmad_story_source_mutated` so a planning gap can return upstream rather than
+become a Developer decision.
+
+After import, the generated Card goes through the existing assignment and
+`triad-verify` path. No Core schema, lifecycle, Reviewer, retry, or gate
+execution semantics are changed by this integration.

package/docs/configuration.md

@@ -47,3 +47,22 @@ optional gate becomes required for that card, and an absent or empty list keeps
 the legacy gate behavior. Selected IDs are validated before Developer dispatch
 and are bound to the assignment; Triad does not attach visual or other
 domain-specific meaning to a gate ID.
+
+## Optional immutable Quality Contract
+
+New or upgraded control workspaces may set:
+
+```yaml
+project:
+  quality_contract:
+    baseline: artifacts/quality-baseline.json
+    fingerprint: <sha256 of the canonical manifest>
+```
+
+The JSON manifest must contain at least one hashed, project-relative source and
+may contain criteria scoped only to `product_quality` or `delivery_closure`.
+The fingerprint is deterministic and independent of JSON whitespace or object
+key order. A configured contract is validated before expensive verification
+gates; malformed manifests and source drift fail closed. Omitting the section
+preserves the 1.7 legacy PRD baseline behavior. A rebaseline is a new manifest
+revision and explicit owner event, never an in-place edit.

package/docs/evaluator-plus.md

@@ -12,3 +12,12 @@ attempt history unless the owner explicitly requires it. It reports `PASS`,
 
 An Evaluator+ `FAIL` does not reopen Triad, change the approved state, or start
 repair. An owner or a later Orchestrator may use it as input to a new run.
+
+When a project declares an immutable Quality Contract, the packet also carries
+the approved Quality Baseline fingerprint and exactly one result for each
+`product_quality` criterion. `delivery_closure` criteria are deliberately
+excluded and are evaluated by delivery closure. The control plane validates
+fingerprint, candidate binding, criterion coverage, and the deterministic
+aggregate (`FAIL` over `INDETERMINATE` over `PASS`) before recording the report.
+Formatting a manifest or changing a bound source invalidates the contract; it
+never starts a product retry.

package/docs/operating-guide.it.md

@@ -51,6 +51,16 @@ selezionati possono essere saltati. Lista assente o vuota mantiene il
 comportamento legacy. Triad collega e registra gli ID senza attribuire loro un
 significato visuale o di altro dominio.
 
+## Target di qualità immutabile
+
+Un progetto può optare per `project.quality_contract`, che collega al run un
+fingerprint canonico del Quality Baseline JSON e verifica le source hashate prima
+del dispatch e dei gate costosi. Drift o manifest invalido fermano il run come
+contesto invalido senza consumare il budget di retry del prodotto. I criteri
+`product_quality` vengono inviati al nuovo Evaluator+; quelli
+`delivery_closure` sono verificati separatamente prima di `delivered`. Senza
+questo opt-in i progetti legacy restano invariati.
+
 ## Retry e scope del candidato
 
 Gli attempt sono record storici di esecuzione. I nuovi workspace separano e

package/docs/operating-guide.md

@@ -51,6 +51,16 @@ become required for that card, and unselected optional gates may be skipped. An
 absent or empty list preserves the legacy behavior. Triad binds and records the
 IDs but does not attach visual or other domain-specific meaning to them.
 
+## Immutable quality target
+
+When a project opts in with `project.quality_contract`, the control plane binds a
+canonical JSON Quality Baseline fingerprint and verifies its hashed sources before
+dispatch or expensive gates. A source drift or invalid manifest stops the run as
+context invalid, without consuming product retry budget. Product-quality criteria
+are sent to the fresh Evaluator+ one at a time; delivery-closure criteria are
+checked separately before `delivered`. The contract is optional, and legacy
+projects without it are unchanged.
+
 ## Retry accounting and candidate scope
 
 Attempts are historical execution records. New workspaces separately bound

package/docs/quality-contract.md

@@ -0,0 +1,119 @@
+# Immutable Quality Contract
+
+Triad+ 1.8 optionally binds a run to an owner-approved, machine-readable
+Quality Baseline. It is an additional target record, not a second control
+plane and not a replacement for the PRD, card baseline, or candidate
+fingerprint.
+
+```text
+Quality Baseline fingerprint  = what the run was meant to satisfy
+Repository/card baseline     = where implementation started
+Candidate fingerprint        = what implementation produced
+```
+
+## Manifest
+
+The manifest is JSON and is normally stored at
+`artifacts/quality-baseline.json`:
+
+```json
+{
+  "schema_version": 1,
+  "id": "my-project-quality-baseline",
+  "revision": 1,
+  "sources": [
+    {
+      "id": "prd",
+      "role": "intent",
+      "path": "artifacts/prd.md",
+      "sha256": "<64-hex-digest>"
+    }
+  ],
+  "criteria": [
+    { "id": "QB-001", "scope": "product_quality", "requirement": "..." },
+    { "id": "QB-010", "scope": "delivery_closure", "requirement": "..." }
+  ],
+  "fingerprint": "<sha256-of-canonical-manifest-without-fingerprint>"
+}
+```
+
+The manifest requires a positive revision, at least one source, unique source
+and criterion IDs, project-relative source paths, SHA-256 for every source, and
+non-empty requirements. Version 1 has exactly two criterion scopes:
+`product_quality` and `delivery_closure`.
+
+The fingerprint is SHA-256 over canonical JSON with object keys sorted
+recursively, array order preserved, and the `fingerprint` field excluded from
+the payload. Whitespace and object formatting therefore do not change it.
+
+## Binding and drift
+
+When `project.quality_contract` is present, the Orchestrator binds both the
+manifest path and its fingerprint in every active Developer assignment:
+
+```json
+{
+  "quality_baseline_path": "artifacts/quality-baseline.json",
+  "expected_quality_baseline_fingerprint": "<sha256>"
+}
+```
+
+`triad-verify` validates the manifest and all source hashes before expensive
+gates. A malformed manifest or fingerprint mismatch is
+`quality_baseline_invalid`; a valid manifest whose declared sources or
+assignment fingerprint no longer match is `quality_baseline_drift`. Both are
+`invalid_context`: no Developer dispatch, expensive gates, or retry budget.
+
+Projects without `quality_contract` retain the legacy PRD-only path. A
+rebaseline is never an in-place edit: create a new revision/fingerprint and
+record an explicit lineage event. Historical evidence is not silently
+reinterpreted.
+
+## Phase ownership
+
+`product_quality` criteria are included in the fresh, blind Evaluator+ packet.
+The packet carries the baseline fingerprint, final candidate fingerprint,
+criteria, approved source material, and bounded verifier evidence. It never
+includes delivery criteria, queue state, handoff state, or attempt history.
+
+Evaluator+ returns one result per product criterion. The control plane validates
+coverage, uniqueness, scope, candidate/baseline fingerprints, and the overall
+verdict. Aggregation is deterministic:
+
+```text
+any FAIL               -> FAIL
+else any INDETERMINATE -> INDETERMINATE
+else                   -> PASS
+```
+
+`delivery_closure` criteria are evaluated separately during delivery closure
+and recorded with criterion ID, verdict, and evidence references. A run is not
+`delivered` when any configured delivery criterion is `FAIL` or
+`INDETERMINATE`. Quality Bar evaluation is not a required-gate replacement,
+and an Evaluator+ failure never repairs or reopens Triad automatically.
+
+## Explicit control-plane validation
+
+The installed runtime exposes deterministic commands for the two phase
+boundaries. Run the baseline preflight before dispatch, then run the phase
+validators from the control workspace so the baseline is reloaded from disk:
+
+```bash
+node .triad-runtime/triad-evaluator-validate.mjs --mode baseline \
+  --project /absolute/path/to/control \
+  --baseline artifacts/quality-baseline.json
+
+node .triad-runtime/triad-evaluator-validate.mjs --mode evaluator \
+  --project /absolute/path/to/control \
+  --baseline artifacts/quality-baseline.json \
+  --result artifacts/evaluator-plus/evaluation.json \
+  --expected-candidate-fingerprint <final-candidate-fingerprint>
+
+node .triad-runtime/triad-evaluator-validate.mjs --mode delivery \
+  --project /absolute/path/to/control \
+  --baseline artifacts/quality-baseline.json \
+  --result artifacts/delivery-closure.json
+```
+
+Each command emits one machine-readable JSON result and exits non-zero for an
+invalid contract, source drift, stale candidate binding, or invalid result.

package/docs/verification.md

@@ -17,6 +17,23 @@ An agent-reported claim is not the same as verification evidence. A Developer ca
 report the commands it ran; `triad-verify` independently observes declared
 required `control-plane` gates and writes atomic evidence.
 
+## Immutable Quality Contract
+
+Projects may opt into `project.quality_contract` with a project-relative JSON
+manifest and its expected SHA-256 fingerprint. The shared
+`runtime/lib/quality-baseline.mjs` loader canonicalizes the manifest (excluding
+its self-declared `fingerprint`), validates source paths, IDs, scopes, and hashes,
+then verifies every bound source before any expensive gate runs. A malformed,
+missing, or mismatched contract is `invalid_context`; a valid manifest whose
+bound source content has changed is `quality_baseline_drift`. Both fail closed:
+no Developer dispatch, gate execution, or retry budget consumption is allowed.
+
+The verifier records `baseline.quality_baseline_fingerprint` when configured and
+records `null` for legacy projects. The Quality Contract is distinct from the
+repository/card baseline and the candidate fingerprint: it says what the run is
+trying to satisfy, not which Git commit was checked out or what the candidate
+changed.
+
 Before gates run, the verifier validates the active assignment, PRD/card/gate
 hashes, worktree, expected branch, and candidate fingerprint. It records the
 assignment ID/hash and run ID, executes deterministic commands with a bounded

package/integrations/bmad/README.md

@@ -0,0 +1,12 @@
+# BMAD Story importer
+
+This optional integration converts one BMAD Markdown Story with
+`status: ready-for-dev` into a normal Triad feature Card. It is intentionally
+small and deterministic: the source is read-only, caller options are explicit,
+and BMAD workflows are never invoked.
+
+See [the public BMAD integration guide](../../docs/bmad-integration.md) for the
+mapping contract, CLI/API examples, provenance sidecar, and fail-closed rules.
+
+The implementation is in `story-importer.mjs`. It does not add BMAD-specific
+branches to the Triad Core or infer gates/dependencies from planning order.