@kontourai/flow-agents 3.6.0 → 3.8.0

package/kits/builder/skills/tdd-workflow/SKILL.md

@@ -1,159 +1,65 @@
 ---
 name: "tdd-workflow"
-description: "Test-driven development — RED → GREEN → REFACTOR with git checkpoints. Wraps plan-work → execute-plan → review-work → verify-work with test-first constraints and coverage gates."
+description: "Test-first profile for builder.build. Requires observable RED, GREEN, and appropriate REFACTOR evidence through the standard build primitives."
 ---
 
 # TDD Workflow
 
-Test-driven development orchestrator. Wraps the standard plan → execute → verify chain with test-first constraints.
+## Role and Boundary
 
-## When to Activate
+**Role:** test-first `builder.build` profile.
 
-- User says "use TDD", "test-driven", "write tests first", "TDD"
-- User asks to build something and mentions test coverage requirements
+Select this profile only when the user requests test-driven development or when
+the selected Work Item explicitly requires a test-first approach. It constrains
+the standard build primitives; it is not a separate flow and does not replace
+`deliver` as the build entrypoint.
 
-## Agents
-
-Same as deliver (inherited from primitives):
-
-| Agent | Used by |
-|---|---|
-| tool-planner | plan-work (with TDD constraints) |
-| tool-worker (x4) | execute-plan (tests first, then implementation) |
-| tool-code-reviewer | review-work |
-| tool-security-reviewer | review-work (conditional) |
-| tool-verifier | verify-work (with coverage check) |
-| tool-playwright | verify-work (if UI) |
+The profile owns **no step-gate evidence**. The plan, execution, review, and
+verification primitives own the artifacts and evidence for their respective
+steps.
 
 ## Model Routing
 
-Delegates are spawned with an explicit model override resolved from
-`.datum/config.json` via `npx @kontourai/datum resolve <role> --json` — see
-`context/contracts/execution-contract.md` § Delegation: Model Routing:
-
-| Delegate | Role |
-|---|---|
-| tool-worker | `delegate-mechanical` for fully-specified mechanical slices, `delegate-implementation` for precisely-planned implementation (RED/GREEN/REFACTOR), `delegate-design` when a slice needs design latitude |
-| tool-planner | `delegate-design` |
-| tool-code-reviewer / tool-security-reviewer | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
-| tool-verifier / tool-playwright | `delegate-implementation` by default, raised to the worker's tier when higher — never below the tier of the checked work (Goodhart guard) |
-
-On a review/verify gate failure, re-dispatch the fix one tier higher and record
-the escalation (contract § Escalation on gate failure). Fallback: inherit the
-session model when datum/config is absent, noted in the artifact.
-
-## Orchestrator Rule
-
-Same as deliver: you never touch source files. You coordinate the primitives with TDD-specific context.
-
-## Workflow
-
-### 1. Create session file
-
-Filename: `<branch>--tdd-<slug>.md`
-Set `status: planning`, `type: tdd`, `iteration: 0`
-
-### 2. Plan (plan-work with TDD constraint)
-
-Invoke plan-work with additional constraint:
-```
-Constraint: TEST-FIRST DEVELOPMENT
-- Plan MUST include test files as separate tasks in Wave 1
-- Each feature task must have a corresponding test task that precedes it
-- Test tasks specify: test file path, test cases to write, expected failures
-- Implementation tasks specify: which tests they make pass
-- Include a final "coverage check" task
-```
-
-Present plan to user. Get approval.
-
-### 3. Execute RED phase
-
-Invoke execute-plan for Wave 1 only (test tasks):
-- tool-worker writes test files
-- After Wave 1 completes, run the tests — they MUST fail (RED)
-- If tests pass (no RED state), the tests are wrong — flag to user
-- Git checkpoint: `test: add failing tests for <feature>`
-
-### 4. Execute GREEN phase
-
-Invoke execute-plan for Wave 2 (implementation tasks):
-- tool-worker writes minimal code to make tests pass
-- After Wave 2 completes, run the tests — they MUST pass (GREEN)
-- If tests still fail, loop: re-invoke execute-plan with failure context
-- Git checkpoint: `feat: implement <feature> (tests passing)`
-
-### 5. Execute REFACTOR phase
-
-Invoke execute-plan for Wave 3 (refactor tasks, if any):
-- tool-worker improves code quality while keeping tests green
-- After Wave 3, run tests again — must still pass
-- Git checkpoint: `refactor: clean up <feature>`
-
-### 6. Review (review-work)
-
-Invoke `review-work` after GREEN/REFACTOR and before verification. Review findings must be fixed, accepted, deferred, or marked false positive before delivery.
-
-### 7. Verify (verify-work with coverage gate)
-
-Invoke verify-work with additional context:
-```
-Additional verification: Check test coverage.
-Run coverage command and verify >= 80% on changed files.
-Include coverage % in the verification report.
-If coverage < 80%, verdict is FAIL with coverage gap details.
-```
-
-### 8. Route on verdict
-
-Same as deliver:
-- **Clean review + all PASS + coverage >= 80%** → deliver
-- **Any FAIL or coverage < 80%** → loop (re-plan failing items)
-- **NOT_VERIFIED** → surface to user
-
-### 9. Deliver
-
-Same as deliver, plus:
-- Report TDD cycle summary: RED → GREEN → REFACTOR with checkpoint SHAs
-- Report final coverage %
-
-## Session File Format
-
-```markdown
-# TDD: <Goal one-liner>
-
-branch: <branch>
-created: <date>
-status: planning | red | green | refactor | verifying | delivered
-type: tdd
-iteration: 0
-coverage_target: 80
-
-## Plan
-(from plan-work)
-
-## RED Phase
-- Tests written: <list>
-- All failing: YES/NO
-- Checkpoint: <SHA>
-
-## GREEN Phase
-- Implementation: <list>
-- All passing: YES/NO
-- Checkpoint: <SHA>
-
-## REFACTOR Phase
-- Changes: <list>
-- Tests still passing: YES/NO
-- Checkpoint: <SHA>
-
-## Verification Report
-(from verify-work)
-
-## History
-- iteration 1: RED ✓, GREEN ✓, REFACTOR ✓, coverage 85%
-```
-
-`<branch>` is the branch recorded in `state.json`'s `branch` field (`ensure-session` derives `agent/<actor>/<slug>`; an explicit `--branch` flag overrides on a new session). `ensure-session` only records the name — creating and checking out the actual git branch/worktree remains this skill's responsibility.
-
-{context?}
+Use `delegate-mechanical` for test and check bookkeeping, `delegate-design` for
+acceptance and test design, and `delegate-implementation` for the red-green-
+refactor implementation and its review. Resolve roles from `.datum/config.json`
+under `context/contracts/execution-contract.md` and record fallbacks or
+escalations.
+
+## Inputs and Provider Adapters
+
+Use the selected Work Item's acceptance criteria, Repository adapter test
+conventions and commands, and Change-adapter risk context. A remote issue or
+pull request may supply these inputs, but no particular provider is required.
+
+## Profile Behavior
+
+1. Select `builder.build` through `deliver`, recording the `tdd-workflow`
+   profile in planning context.
+2. Have `plan-work` identify test scenarios before the implementation tasks,
+   including what behavior each test should demonstrate and why it should fail
+   against the pre-change behavior.
+3. Have `execute-plan` make the tests demonstrably fail for the intended
+   reason before implementation, then make them pass with the smallest adequate
+   change.
+4. Refactor only while the relevant tests remain passing. Use checkpoints when
+   the Repository adapter's practice calls for them; do not impose a commit
+   pattern.
+5. Have review and verification evaluate the test quality, changed behavior,
+   relevant regression coverage, and any project-defined coverage requirement.
+
+Do not require an arbitrary numeric coverage percentage. Coverage targets come
+from the Work Item, repository policy, or an explicit user decision.
+
+## Output Responsibility
+
+This profile creates no independent artifact or evidence. Its output is the
+test-first constraints and RED/GREEN/REFACTOR observations carried by the
+standard primitive artifacts and final delivery report.
+
+## Standalone and No-Active-Run Behavior
+
+`tdd-workflow` does not start or resume a run itself. With no active run,
+route to `deliver` to select and start `builder.build` with this profile. With
+an active run, apply it only when doing so is compatible with the current Work
+Item and canonical next action; otherwise surface the conflict.

package/kits/builder/skills/verify-work/SKILL.md

@@ -1,127 +1,115 @@
 ---
 name: "verify-work"
-description: "Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact."
+description: "Report-only acceptance verification. Records command-backed Builder verification evidence in trust.bundle when bound to an active run."
 ---
 
-# Verify
+# Verify Work
 
-Session file in, structured evidence verdict out. Delegates to tool-verifier and tool-playwright.
+## Role
 
-Verification is not critique. Run `review-work` first when the task needs maintainability, security, architecture, or standards review. Verification should start only after the required critique gate has been recorded or explicitly marked `not_verified`. `verify-work` records proof in `evidence.json`; `review-work` records critique through the critique artifact/sink, currently `critique.json` locally.
+This is a Builder step skill.
 
-## Agents
+Verify Work proves acceptance criteria with reproducible evidence. It is
+report-only: verifiers may inspect, test, and write evidence artifacts, but do
+not patch source files or apply autofixes.
 
-| Agent | Role |
-|---|---|
-| tool-verifier | Code verification, acceptance criteria checking, structured verdicts |
-| tool-playwright | Visual verification, screenshots, accessibility checks |
+Critique belongs to `review-work`; behavior proof belongs here.
+
+## Binding
+
+| Context | Binding | Flow expectations |
+| --- | --- | --- |
+| Active Builder run | `builder.build` at `verify` | `acceptance-criteria` and `tests-evidence`; `policy-compliance` only when applicable. `review-work` separately produces `clean-critique`. |
+| Standalone invocation | No Flow binding | No workflow mutation. |
+
+For an active run, verify the binding first:
+
+```bash
+flow-agents workflow status --session-dir <session-dir> --json
+```
+
+Only a matching active `builder.build` run at `verify` may receive workflow
+evidence. Otherwise, return the verification report and unresolved gaps without
+calling `workflow evidence`.
 
 ## Model Routing
 
-Verify roles never resolve **below** the tier of the work they check (Goodhart
-guard): default `delegate-implementation`, raised to match or exceed the tier
-that produced the work under verification — a verifier of `delegate-design` work
-resolves `delegate-design` or `orchestrator`, never a cheaper tier. Resolve the
-role from `.datum/config.json` (`npx @kontourai/datum resolve <role> --json`) and
-pass the model explicitly. See `context/contracts/execution-contract.md`
-§ Delegation: Model Routing and § Goodhart guard. Fallback: inherit the session
-model when datum/config is absent, noted in the artifact.
-
-## Orchestrator Rule
-
-You do not review source files. You delegate to tool-verifier and tool-playwright, then read the verdict artifact.
-
-## Shared Contracts
-
-Follow:
-- `context/contracts/artifact-contract.md`
-- `context/contracts/verification-contract.md`
-- `context/contracts/planning-contract.md` for acceptance criteria and Definition Of Done
-
-This skill owns orchestration and routing. The verification contract owns phases, report-only behavior, verdict rules, report shape, Goal Fit checks, and `NOT_VERIFIED` handling.
-
-## Read-Only Rule (STRICT)
-
-**Verifiers NEVER modify source code.** tool-verifier and tool-playwright are read-only reporters:
-- They may run commands (build, test, lint) but NEVER apply fixes
-- No format fixes, no lint auto-fixes, no "1 format fix applied"
-- No code patches, no "found and fixed" — report findings only
-- If a fix is needed, report it as a finding. The orchestrator routes it back to execute-plan.
-
-## Input
-
-- **Session file path**: the session file in `.kontourai/flow-agents/<slug>/` (preferred)
-- The session file references the plan artifact (which has acceptance criteria) and execution progress (which has modified files)
-- If NO session file exists, delegate to tool-verifier directly (see Standalone Verification below)
-
-## Standalone Verification (no session file)
-
-When invoked without a session file (e.g., user says "verify this project" or "run verification"):
-
-1. Delegate to tool-verifier with:
-   - The user's verification request
-   - The current working directory
-   - Modified files from `git diff --name-only` (if available)
-2. Delegate to tool-playwright in parallel if UI changes are mentioned
-3. Read the verdict and report to the user
-
-Skip session file lookup — go straight to delegation.
-
-## Workflow (with session file)
-
-1. Read the session file to find the plan artifact path and modified files
-2. Confirm the review-before-verify gate: the critique artifact/sink should show the required review pass, blocking findings, or an explicit `not_verified` gap. If the critique gate is missing for work that requires review, stop and route to `review-work` instead of treating verification as a substitute critique.
-3. Set session file `status: verifying` and update `state.json` phase/status. Use `npm run workflow:sidecar -- advance-state <artifact-dir> --status verifying --phase verification --summary ... --next-action ...` when the repository provides it.
-4. Delegate in parallel:
-   ```
-   tool-verifier:
-   - Acceptance criteria from plan artifact
-   - Acceptance criteria from acceptance.json when present
-   - Definition Of Done and stop-short risks from plan artifact
-   - Modified files from execution progress
-   - Requirement to preserve each AC id and map it to command/test evidence plus structured source evidence refs when implementation behavior is claimed
-   - Evidence ref schema: objects with `kind`, `url`, `file`, `line_start`, `line_end`, and `excerpt` where applicable; source refs require local file/line/excerpt and should use immutable GitHub blob permalinks pinned to a commit SHA when provider URLs are available
-   - Build/test commands from AGENTS.md or plan
-   - todo_file path for writing verdict artifact
-   - Workflow artifact root path; append verifier progress with record-agent-event
-
-   tool-playwright (if UI changes exist):
-   - Pages/components to check
-   - Expected visual state
-   - Workflow artifact root path; append browser evidence or blockers with record-agent-event
-   ```
-5. Read the verdict artifact: `<session-basename>-review.md`
-6. Update session file: paste verdict summary into `## Verification Report`
-7. Write or update `evidence.json` with verification checks, top-level verdict, and `not_verified_gaps`
-   - use `npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict ... --check-json ...` when the repository provides it
-   - `checks[].artifact_refs` must use structured evidence ref objects, not legacy strings
-   - for multi-repo or cross-product work, preserve a coverage matrix in the
-     evidence report or check summaries that lists each affected root and its
-     build/test, dependency/security, provider/CI, and accepted-gap status
-   - if external dependency audit or provider checks are blocked by approval,
-     privacy, credentials, network, or missing change-provider state, record the
-     affected roots as `not_verified` instead of collapsing the lane into a
-     generic pass/fail
-8. Update `acceptance.json` with criterion statuses and structured evidence refs
-   - `criteria[].evidence_refs` must use structured evidence refs and map each AC id to command/test proof plus source refs for behavior claims
-   - when source refs are missing for a behavior claim, mark the criterion `not_verified` or record an accepted gap instead of using broad prose-only evidence
-9. Route on verdicts:
-   - **All PASS** → set `status: verified`
-   - **Any FAIL** → set `status: failed`, list failures
-   - **Any NOT_VERIFIED** → set Markdown status `needs-decision`, set `state.json` status `needs_decision`, and surface to user
-
-## Verification Contract
-
-tool-verifier writes the verdict artifact using `context/contracts/verification-contract.md`.
-
-You do not override verdicts. FAIL is FAIL until re-verified. `NOT_VERIFIED` items are surfaced to the user so they can decide whether to accept, fix, or skip. A technically green build is not enough for PASS when the `Definition Of Done` says the user still cannot run, understand, inspect, or act on the result.
+Resolve `delegate-implementation` from `.datum/config.json` and follow
+`context/contracts/execution-contract.md`. The Goodhart guard applies:
+verification must never resolve below the reasoning tier of the checked work.
+Record any fallback or escalation in the verification report.
+
+## Inputs
+
+- Acceptance criteria, Definition Of Done, and stop-short risks.
+- Changed-file scope from the session, plan, or `RepositoryAdapter`.
+- Local checks and runtime evidence selected for the change.
+- Relevant `CheckProvider` and `ChangeProvider` evidence when it exists.
+- The `trust.bundle` critique slice when review is required; critique findings
+  remain separate from verification evidence.
+
+## Verification Work
+
+1. Re-check Goal Fit before testing: compare the delivered artifacts and actual
+   changed scope with the selected Work Item, Definition Of Done, acceptance
+   criteria, and stop-short risks. Missing requested behavior or unexplained
+   scope routes back even when the implementation plan was completed.
+2. Map each acceptance criterion to an observable check, source inspection, or
+   runtime observation. Delegate to `tool-verifier`; include `tool-playwright`
+   for browser-facing behavior.
+3. Run relevant build, type, lint, test, security, diff, browser, runtime, and
+   provider checks. `CheckProvider` evidence is provider-neutral; a provider
+   check is not assumed to exist for every repository.
+4. Record every criterion as `PASS`, `FAIL`, `NOT_VERIFIED`, or an explicitly
+   accepted gap. Missing, inaccessible, or inconclusive evidence is
+   `NOT_VERIFIED`, never `PASS`.
+   Reject prose-only claims and non-resolving references. Evidence references
+   must identify a command result, source location, provider record, runtime
+   observation, or artifact that a reviewer can inspect. A passing
+   `tests-evidence` claim needs every declared criterion exactly once, and every
+   passing criterion needs a `kind:"command"` reference whose command text
+   exactly matches one of the substantive `--command` values that ran
+   successfully. External-only attestations cannot satisfy it.
+5. Publish the relevant active-run expectation through the public CLI with one
+   or more exact commands that produced the test results. Repeat `--command`
+   when criteria require different checks, and include a matching top-level
+   `--evidence-ref-json` for every recorded command. A prose summary or an
+   artifact reference alone cannot satisfy `tests-evidence`:
+
+```bash
+flow-agents workflow evidence --session-dir <session-dir> \
+  --expectation tests-evidence \
+  --status <pass|fail|not_verified> \
+  --command "npm test" \
+  --summary "The recorded test command supports the accepted behavior." \
+  --evidence-ref-json '{"kind":"command","excerpt":"npm test","summary":"Exact substantive project test command recorded for this verification result."}' \
+  --criterion-json '{"id":"<criterion-id>","status":"pass","evidence_refs":[{"kind":"command","excerpt":"npm test","summary":"Exact substantive project test command run for this criterion."}]}' \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/<slug>--plan-work.md","summary":"Accepted criterion and planned verification mapping."}'
+```
+
+When a policy check applies, publish `policy-compliance` in the same way. Do
+not publish that optional expectation when no policy check applies.
 
 ## Output
 
-- Verdict artifact: `<session-basename>-review.md`
-- Session file updated with verification report and status
-- Structured sidecars updated: `state.json`, `acceptance.json`, and `evidence.json`
-- Acceptance evidence preserves AC ids and uses structured evidence refs; prose-only behavior claims are not clean verification evidence
-- Verdict follows `context/contracts/verification-contract.md`
-
-If `record-evidence` or artifact validation is unavailable or blocked, keep the verdict explicit and record the sidecar-write gap as `NOT_VERIFIED`. Do not convert verifier output into `PASS` without structured evidence when sidecars are required.
+Record completed criteria as the required `acceptance-criteria` slice and the
+verification result as the `tests-evidence` slice in `trust.bundle`.
+It must preserve criterion identifiers and include a readable `Acceptance
+Evidence` table in its summary or linked reviewable report:
+
+| AC id | Status | Command/Test Evidence | Source Evidence | Gaps |
+| --- | --- | --- | --- | --- |
+| `<id>` | `PASS`, `FAIL`, or `NOT_VERIFIED` | Command, result, or observation | File, test, provider, or runtime reference | Missing or accepted evidence |
+
+The result states the overall verification verdict and every unresolved gap.
+For an active matching run, publish one `--criterion-json` object for every
+accepted criterion, each with its own status and reviewable evidence refs, plus
+a substantive literal `--command` for every distinct check that was run. Every
+top-level and criterion command reference must exactly match one of those
+commands. The public evidence calls
+publish `acceptance-criteria`, `tests-evidence`, and applicable
+`policy-compliance`; no retired
+verification sidecar is a store. Never publish a placeholder, `true`,
+`bash -c true`, or `node --version` as behavior evidence. In a packed or
+temporary consumer repository, use a real project-local test/check/verify
+script rather than a command that exists only in the Flow Agents source repo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.6.0",
+  "version": "3.8.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -149,7 +149,7 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
-    "@kontourai/flow": "^3.1.0"
+    "@kontourai/flow": "^3.1.4"
   },
   "optionalDependencies": {
     "@kontourai/surface": "^2.0.0",

package/packaging/README.md

@@ -19,7 +19,7 @@ For the full source/generated/runtime inventory, see [Repository Structure](../d
 
 - `dist/kiro/` keeps native Kiro JSON agents and rewrites path-bound config through the install token.
 - `dist/claude-code/` exports `.claude/agents/*.md` and `.claude/skills/*/SKILL.md`.
-- `dist/codex/` exports `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and generated profile config for operating intents such as `builder` and `personal`.
+- `dist/codex/` exports Codex-only agents and profiles beneath `.codex/`, and portable, self-contained skills beneath the universal `.agents/skills/` catalog.
 
 All targets also receive shared canonical directories where supported: `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/`.
 

package/scripts/README.md

@@ -113,7 +113,7 @@ prompting. Add `--allow-network` to probe a non-local HTTPS Console endpoint.
 
 ## Install And Repo Utilities
 
-- `install-codex-home.sh`: installs the generated Codex bundle into `CODEX_HOME`, or `~/.codex` when `CODEX_HOME` is unset. A positional destination argument is the explicit override for isolated homes and tests.
+- `install-codex-home.sh`: installs Codex runtime assets into `CODEX_HOME` (or `~/.codex`) and portable skills into `$HOME/.agents/skills`. Use `--skills-dir PATH` or `FLOW_AGENTS_SKILLS_DIR` to select a hermetic or advanced-user skill catalog independently of the positional runtime destination. The installer reports both resolved roots, preserves user-owned files, migrates only unchanged Flow Agents-owned legacy skills, and refuses symlink destinations rather than creating a compatibility symlink.
 - `setup-repo-hooks.sh`: configures this clone's Git hook path.
 - `check-content-boundary.cjs`, `detect-tools.sh`, `discover-agents.sh`, `git-status.sh`: repo-local helper commands.
 - `context-budget/` and `statusline/`: specialized support tooling copied into bundles where needed.

package/scripts/hooks/lib/kit-catalog.js

@@ -137,7 +137,7 @@ function renderKitSteering(trigger) {
     else lines.push(`Activate \`${defaultSkill}\`.`);
   }
   if (targetFlowId) {
-    lines.push(`Keep the session on \`${targetFlowId}\` and use \`npm run workflow:sidecar -- ensure-session --flow-id ${targetFlowId} ...\` when the repo provides the sidecar writer.`);
+    lines.push(`Keep the session on \`${targetFlowId}\`. Use the public \`flow-agents workflow\` interface only when it supports that Flow and its Work Item binding; otherwise report an unsupported-runtime blocker. Never call the package-internal writer from skill guidance.`);
   }
   if (requiredSequence.length) {
     lines.push(`Do not bypass ${requiredSequence.join(' -> ')} for matching work.`);