triad-plus 1.8.0 → 1.10.0

package/docs/assignment-packets.md

@@ -0,0 +1,35 @@
+# Assignment packets
+
+Before a delegated role starts, the Orchestrator creates one immutable
+Assignment Packet for that assignment:
+
+```bash
+node .triad-runtime/triad-assignment-packet.mjs \
+  --project /absolute/path/to/control-workspace \
+  --assignment .loop/runtime/assignments/<assignment-file>.json
+```
+
+The command binds `assignment_packet_path` and
+`assignment_packet_sha256` in the active assignment and returns a JSON dispatch
+context. The host launches the Developer with `dispatch.cwd` set to the
+declared product worktree. The Reviewer receives the same packet and uses that
+worktree when direct candidate inspection is needed. The control workspace
+remains the source for policy, cards, state, and evidence.
+
+Packets contain bounded assignment context: card outcome and acceptance
+criteria, relevant PRD/ADR excerpts supplied by the Orchestrator, verification
+mapping, expected paths, constraints, risks, mandatory skill paths/hashes, and
+prior evidence references. They are not a second PRD and do not copy skill
+contents. The Developer and Reviewer still read every real mandatory skill and
+the verifier remains authoritative for skill hashes and gate evidence.
+
+The packet and card are the normal startup contract. A full PRD or ADR is a
+fallback only when a detail is missing, contradictory, or explicitly required.
+Native `read`, `grep`, `glob`, and `list` operations should be preferred for
+simple discovery; shell commands remain appropriate for builds, tests, git,
+scripts, and system operations.
+
+Projects and assignments without packet fields keep the legacy behavior. A
+bound packet is validated before `triad-verify` runs skills, scope checks, or
+quality gates; a missing, changed, or mismatched packet fails closed as
+`assignment_packet_invalid` without consuming retry budget.

package/docs/bmad-integration.md

@@ -1,110 +1,215 @@
-# Optional BMAD Story integration
+# BMAD native intake
+
+Triad+ treats BMAD as the planning authority and takes over at the natural
+planning handoff: the read-only `_bmad-output/planning-artifacts/epics.md`
+artifact.
+
+```text
+BMAD planning
+  -> epics.md
+  -> deterministic Triad intake
+  -> normal Cards
+  -> Developer -> verifier -> Reviewer -> delivery
+```
 
-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.
+The owner does not need to split `epics.md` into Triad-shaped Story files or
+run one import command per Story. A normal host entry point such as
+`/triad /path/to/_bmad-output/planning-artifacts/epics.md` lets the Orchestrator
+detect the native artifact, ingest it, and continue with the initialized
+project-control workspace. Passing the BMAD output directory is also supported
+when it contains the conventional `planning-artifacts/epics.md` path.
 
-## Contract
+## Responsibilities
 
-The source is a read-only Markdown Story. It must contain:
+BMAD owns planning:
 
-- 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.
+- Epic and Story boundaries;
+- intent and user outcome;
+- acceptance criteria;
+- planning context, constraints, and references.
 
-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`.
+Triad owns execution:
 
-## CLI
+- project and repository resolution;
+- worktree and branch selection;
+- trusted quality gates and required-gate selection;
+- Card creation, assignment, Developer, verifier, Reviewer, retry, and delivery
+  semantics.
 
-```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
-```
+Triad never invokes `bmad-loop`, Build, Build Auto, or another BMAD workflow.
+It does not modify `epics.md` or add execution metadata to the BMAD source.
+
+## Bootstrap boundary
+
+When native BMAD planning has produced `epics.md`, that artifact is the sole
+authority for Epic/Story boundaries and acceptance criteria. Bootstrap consumes
+the canonical Stories and materializes one normal Triad Card per Story; it does
+not independently re-decompose the PRD, create a second semantic plan, or use
+an LLM to decide Story boundaries. This prevents parallel Cards A/B and keeps
+the handoff deterministic: BMAD plans, Triad executes.
+
+## Deterministic parser and API
+
+The integration is implemented in
+`integrations/bmad/epics-parser.mjs`. It recognizes native headings such as:
+
+```md
+### Epic 1: JsonForm integration
+
+### Story 1.1: Route the provider document
 
-`--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.
+**Intent / outcome:** ...
 
-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.
+**Acceptance Criteria:**
+**Given** ...
+**When** ...
+**Then** ...
+```
 
-The same operation is available to Node consumers:
+Story detection, Epic association, ID/title extraction, acceptance extraction,
+splitting, and provenance are deterministic code. No LLM is used for intake.
+The source is read twice and must remain byte-stable during the operation.
+
+Read-only ingestion returns canonical Stories without assigning a repository:
 
 ```js
-import { importBmadStory, writeImportedCard } from
-  'triad-plus/integrations/bmad/story-importer.mjs';
+import { ingestBmadEpics } from 'triad-plus/integrations/bmad/epics-parser.mjs';
 
-const result = await importBmadStory({
-  sourcePath: '/absolute/path/to/story.md',
-  targetRepository: 'webup',
-  requiredGates: ['cypress-jfr']
+const result = await ingestBmadEpics({
+  sourcePath: '/project/_bmad-output/planning-artifacts/epics.md'
 });
 
-await writeImportedCard({
-  sourcePath: '/absolute/path/to/story.md',
-  outputPath: '/absolute/path/to/control/features/JFR-001.md',
-  targetRepository: 'webup',
-  requiredGates: ['cypress-jfr']
-});
+// result.stories: canonical BMAD Stories
+// result.cards: [] — no execution assumptions were made
 ```
 
-## Example mapping
+The integration-side runtime primitive can materialize normal Cards when an
+initialized Triad project context is supplied:
 
-Input (abridged):
+```bash
+node .triad-runtime/triad-bmad-intake.mjs \
+  --source /project/_bmad-output/planning-artifacts/epics.md \
+  --project /project/triad-control \
+  --output /project/triad-control/features \
+  --repository webup \
+  --required-gate 1.4=cypress-jfr
+```
 
-```md
----
-id: JFR-001
-title: Route the provider document
-status: ready-for-dev
-target_repository: webup
----
+`--source` may also be the BMAD output directory; the conventional
+`_bmad-output/planning-artifacts/epics.md` file is selected deterministically.
+
+This is an automation/API primitive for the Orchestrator, not the primary user
+workflow. The primary workflow remains the host's `/triad` entry point with the
+BMAD artifact path.
+
+## Ingestion readiness versus execution readiness
 
-# Story JFR-001: Route the provider document
+An `epics.md` Story is ingestible when it has:
 
-## Intent
+- a unique Story ID;
+- a title;
+- an intent, outcome, or user story;
+- acceptance criteria;
+- an unambiguous Epic parent.
 
-Webup renders the provider-owned document at the existing boundary.
+`status: ready-for-dev` is not required for ingestion because native
+`epics.md` commonly does not contain that field. Ingestion does not dispatch a
+Developer and does not claim that a Card is executable.
 
-## Acceptance Criteria
+Before Card materialization, Triad resolves execution readiness:
 
-- Given a valid document, when the route is requested, then it renders.
+- project configuration is present;
+- the target repository is explicit, configured as the project default, or is
+  the only configured repository;
+- multiple repositories without a deterministic mapping fail closed;
+- the selected repository has a usable path/worktree;
+- the trusted gate catalog exists and contains no placeholders;
+- explicit per-Story required gates and dependencies validate as caller input.
 
-## Code Map
+An explicit non-ready BMAD status such as `draft`, `in-progress`, `done`, or
+`blocked` remains ingestible but is rejected at execution readiness. Triad never
+silently promotes it to `ready-for-dev` in the source.
 
-- `src/components/jfr/`
+## Repository and gate binding
+
+`target_repository` is optional in native BMAD. Resolution is deterministic:
+
+```text
+per-Story caller override / Story repository declaration
+  -> explicit caller default repository
+  -> project default repository
+  -> single configured repository
+  -> otherwise fail closed as ambiguous
 ```
 
-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.
+Conflicting explicit mappings fail closed rather than being silently chosen;
+unknown repositories fail closed. Quality gates are not inferred from
+acceptance prose or Story ordering. If a caller selects an additional gate, it
+is supplied explicitly and uses the existing additive `required_gates`
+semantics. Dependencies are preserved only when explicitly supplied; position
+in `epics.md` never becomes `depends_on` automatically.
+
+## Card and provenance output
+
+The parser reuses the existing Card builder. It does not create intermediate
+BMAD Story files. When Cards are materialized, each normal Card is accompanied
+by an integration-side provenance record containing at least:
+
+```json
+{
+  "source_kind": "bmad-epics",
+  "source_path": "_bmad-output/planning-artifacts/epics.md",
+  "source_sha256": "...",
+  "epic_id": "1",
+  "story_id": "1.1",
+  "source_heading": "Story 1.1: ...",
+  "source_range": { "start_line": 10, "end_line": 38 },
+  "card_sha256": "..."
+}
+```
+
+The source SHA, Story identity, source heading/range, and generated Card SHA
+form the audit binding. Line ranges are supporting evidence, not the sole
+identity. The BMAD source remains read-only.
+
+## Fail-closed conditions
+
+The native intake rejects malformed or unsafe input rather than inventing a
+planning decision. Examples include:
+
+- missing or malformed Epic/Story headings;
+- duplicate Epic or Story IDs;
+- a Story outside an Epic;
+- missing title, intent/outcome, or acceptance criteria;
+- source mutation during the read;
+- ambiguous or unknown repository resolution;
+- missing project/worktree/gate readiness;
+- an explicit non-ready Story status at execution time.
+
+No partial Card set is written when parsing or execution readiness fails.
+
+## Low-level single-Story compatibility path
+
+`import-bmad-story` remains available as a low-level API, debugging tool, test
+utility, and compatibility path for a standalone Story that already carries
+`status: ready-for-dev` and a repository (or an explicit caller override):
+
+```bash
+npx triad-plus import-bmad-story \
+  --source /absolute/path/to/story.md \
+  --output /absolute/path/to/control/features/STORY-001.md
+```
+
+It is no longer the primary BMAD workflow. It remains read-only and fail-closed,
+preserves explicit gates/dependencies, and uses the same Card contract.
+
+## Non-goals
+
+This integration does not add:
+
+- BMAD execution, Build Auto, or `bmad-loop`;
+- an Epic scheduler or batch execution engine;
+- dependency inference from `stories.yaml` or document order;
+- an LLM Story interpreter;
+- NotebookLM, SMEUP-specific policy, or Quality Baseline Core changes;
+- parallel writers, worktree orchestration, or a new plugin framework.

package/docs/configuration.md

@@ -31,6 +31,35 @@ 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.
 
+## Configure models through the agent
+
+The installed `triad-model-configuration` skill lets an owner ask the selected
+agent to show or change role models without editing host-specific files. The
+agent reads `.triad-runtime/adapter.json`, validates `.triad-plus/team.json`,
+changes only the explicitly requested `model` or `reasoning_effort` fields, and
+uses the existing managed binding path to materialize supported values. It
+reports whether each request was applied host-natively, recorded only in the
+team file, left at the host default, or unsupported. It never invents model IDs
+and never puts credentials in the configuration.
+
+The skill follows the adapter metadata: `global-profiles` writes native
+user-level profiles, `project-frontmatter` writes only the declared native
+fields (OpenCode supports model plus its native `variant`, Copilot supports
+model plus `reasoningEffort`, and Claude Code currently supports model only),
+and `team-record` records intent without fabricating a host binding. A null or
+blank value deliberately means host default. Reasoning levels are host-specific
+and are never translated between providers.
+
+For project-frontmatter adapters, `.triad-plus/team.json` remains the canonical
+source of truth. Managed installation and `upgrade --apply` re-materialize each
+configured role's supported fields after refreshing agent assets. OpenCode maps
+`model` to `model` and `reasoning_effort` to its native `variant` field; Copilot
+maps the same canonical fields to `model` and `reasoningEffort`; Claude Code
+currently maps `model` only. Null or blank values are omitted so the host uses
+its session default. Other adapters may expose different controls; Triad+ only
+materializes fields supported by the selected host. A host/session default is
+distinct from a role-agent binding.
+
 ## Retry and scope policy
 
 New control workspaces use separate finite budgets for environment recovery and

package/docs/npx-installation.md

@@ -10,6 +10,10 @@ npx triad-plus
 The interactive setup selects a host, optional user-level command, language,
 owner address, role display names/personas, models, and whether the optional
 Evaluator+ is enabled. It changes files only after `install` is typed.
+Before confirmation it prints a compact summary of the host, control workspace,
+interaction settings, Evaluator+, and each role's model/binding. Colors are
+used only for an interactive terminal and are disabled by `NO_COLOR` or when
+output is not a TTY.
 
 For repeatable setup:
 
@@ -46,6 +50,18 @@ personas, models, and supported effort/options. Existing schema-version-1 team
 files remain valid. Core roles are always enabled; Evaluator+ is enabled only
 when `roles.evaluator.enabled` is `true`.
 
+The shared `triad-model-configuration` skill is installed with the selected
+adapter. Ask the host agent to inspect or change a role model; it keeps
+`.triad-plus/team.json` as the source of truth and re-materializes only fields
+the adapter declares as host-native. Unsupported fields are reported rather
+than silently substituted.
+
+For OpenCode, the canonical `reasoning_effort` value is materialized as the
+native per-agent `variant` field. Copilot uses its own native
+`reasoningEffort` field; these host contracts are intentionally not inferred
+from one another. The active host/session default remains separate from a
+materialized role profile.
+
 | Role | Responsibility |
 | --- | --- |
 | Orchestrator | Maintains goal/context and decides the next step. |
@@ -58,3 +74,7 @@ PRD path. The Orchestrator presents feature cards before implementation, then
 delegates normal development and review. When `roles.evaluator.enabled` is true,
 the Orchestrator invokes Evaluator+ automatically after Triad is approved. Users never create
 evaluation packets, report paths, or evidence directories manually.
+
+During a run the Orchestrator creates any Assignment Packet internally and
+passes its explicit product-worktree dispatch context to the delegated roles;
+there is no user-facing packet path to configure.

package/docs/opencode-replication.md

@@ -7,3 +7,11 @@ command assets carry the configured role models where OpenCode supports them.
 Verification uses explicit Orchestrator dispatch. A configured Evaluator+ is
 automatically invoked only after a Reviewer-approved result; it cannot reopen
 that run.
+
+`.triad-plus/team.json` is the desired source of truth for OpenCode role
+configuration. Triad+ materializes each supported role's `model` and native
+`variant` (from `reasoning_effort`) in `.opencode/agents/*.md` during init and
+after `upgrade --apply`. A null value leaves that field absent so OpenCode uses
+its host/session default. The OpenCode session default is independent of these
+per-agent bindings; use `opencode models` to inspect available IDs and
+variants.

package/docs/operating-guide.it.md

@@ -18,6 +18,14 @@ Prima del lavoro l’Orchestrator congela il PRD, dichiara card misurabili,
 repository/worktree/branch e quality gate deterministici. Mostra il piano al
 proprietario, poi delega normalmente sviluppo e review.
 
+Per ogni assignment attivo può creare un Assignment Packet immutabile. Il
+packet contiene il contesto delimitato della card e gli estratti pertinenti; il
+host avvia il Developer con `cwd`/`workdir` uguale al product worktree
+dichiarato, mantenendo espliciti i path del control workspace. Il Reviewer
+riceve lo stesso packet più candidato/evidence. La rilettura completa di
+PRD/ADR è solo fallback e le skill obbligatorie continuano a essere lette e
+verificate tramite i loro path reali.
+
 Dopo il completamento del Developer avviene la verifica: tramite hook validato
 quando disponibile, altrimenti con dispatch esplicito dell’Orchestrator. Il
 verifier esegue solo comandi `control-plane` dichiarati. L’evidence atomica lega

package/docs/operating-guide.md

@@ -19,6 +19,13 @@ Before work, the Orchestrator snapshots the PRD, declares measurable feature
 cards, target repositories/worktrees/branches, and deterministic quality gates.
 It shows the plan to the owner, then delegates ordinary development and review.
 
+For each active assignment it may create an immutable Assignment Packet. The
+packet carries the bounded card context and relevant excerpts; the host launches
+the Developer with `cwd`/`workdir` equal to the declared product worktree, while
+control-workspace paths remain explicit. The Reviewer receives the same packet
+plus candidate/evidence. Full PRD/ADR reads are fallback-only, and mandatory
+repository skills are still read and hash-verified from their real paths.
+
 After Developer completion, verification happens through a validated host hook
 when available, or explicit Orchestrator dispatch. The verifier executes only
 declared `control-plane` commands. Atomic evidence binds assignment ID/hash, run,

package/docs/runtimes.md

@@ -49,6 +49,6 @@ validated independently as well.
 ## OpenCode
 
 Use the interactive OpenCode TUI for complete multi-step Triad runs. OpenCode
-1.18.0 validated the full Orchestrator → Developer → verifier → Reviewer →
+1.18.x validated the full Orchestrator → Developer → verifier → Reviewer →
 configured Evaluator+ lifecycle in the TUI. `opencode run` is useful for
 one-shot work but does not retain that multi-step parent/subagent lifecycle.

package/docs/verification.md

@@ -46,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.