triad-plus 1.7.0 → 1.9.0

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
@@ -29,6 +46,26 @@ it does not itself approve, rework, or transition a run.
 Evidence files and logs are diagnostics. Users normally need only the
 Orchestrator's summary and the Reviewer verdict.
 
+## Assignment packets and dispatch context
+
+The Orchestrator can create one immutable packet per active assignment with:
+
+```bash
+node .triad-runtime/triad-assignment-packet.mjs \
+  --project /absolute/path/to/control-workspace \
+  --assignment .loop/runtime/assignments/<assignment-file>.json
+```
+
+The command binds a packet path and SHA-256 to the assignment and returns the
+explicit product-worktree `dispatch.cwd`. The packet contains the bounded card
+contract, relevant excerpts, verification mapping, expected paths, risks,
+constraints, mandatory skill references, and prior evidence references. It is
+the primary Developer/Reviewer context; full PRD/ADR reads are fallback-only.
+It never replaces real skill reads or verifier hash checks. A bound packet is
+validated before `triad-verify` executes scope or gates, and a changed or
+missing packet fails closed as `assignment_packet_invalid`. Assignments without
+packet fields retain legacy behavior.
+
 ## Card-declared required gates
 
 The work queue may carry a machine-readable `required_gates` list for an

package/integrations/bmad/README.md

@@ -1,12 +1,20 @@
-# BMAD Story importer
+# BMAD integration
 
-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.
+The primary BMAD handoff is the native planning artifact
+`_bmad-output/planning-artifacts/epics.md`. Use the deterministic parser in
+`epics-parser.mjs` to detect Epic/Story boundaries, ingest canonical Stories,
+resolve Triad execution readiness, and materialize normal Cards with strong
+source provenance.
 
-See [the public BMAD integration guide](../../docs/bmad-integration.md) for the
-mapping contract, CLI/API examples, provenance sidecar, and fail-closed rules.
+The parser is read-only and does not invoke BMAD workflows or mutate
+`epics.md`. It reuses the Card builder from `story-importer.mjs`; no
+intermediate BMAD Story files are required.
 
-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.
+`story-importer.mjs` remains the low-level compatibility API for a standalone
+Story that already has `status: ready-for-dev`. It is retained for debugging,
+tests, automation, and existing callers, but it is not the primary BMAD user
+workflow.
+
+See [the native BMAD integration guide](../../docs/bmad-integration.md) for the
+handoff contract, repository resolution, execution readiness, provenance, and
+fail-closed behavior.