@kontourai/flow-agents 0.1.1

package/skills/release-readiness/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: "release-readiness"
+description: "Decide whether evidence-backed work is ready to merge, release, deploy, or hold. Use after evidence-gate PASS, before merge/release/deploy, and for post-deploy verification planning."
+---
+
+# Release Readiness
+
+Turn a clean evidence result into an explicit release, deploy, or hold decision.
+
+Release Readiness is not Evidence Gate. Evidence Gate decides whether completed work is trustworthy enough to publish or continue fixing. Release Readiness assumes evidence is clean and then checks the real publish/release surface: committed diff, pushed branch, provider change record or explicit no-provider-change reason, provider checks, ownership, rollout timing, rollback, observability, docs, and post-deploy verification.
+
+## Contract
+
+- Use only after `evidence-gate` has produced `PASS`, or explicitly record why release review is blocked.
+- Use only after the verified changes have been committed, pushed, and represented by a provider change record or an explicit no-provider-change decision.
+- Do not fix code or weaken release criteria.
+- Do not deploy unless the user explicitly asks and the environment is clear.
+- Treat merge, release, deploy, and post-deploy verification as separate gates.
+- Record rollback, observability, and ownership before approving release.
+- Treat final acceptance documentation as part of release readiness: CI/merge should leave durable docs or an explicit reason they are not needed.
+
+## Inputs
+
+- Evidence gate artifact and verdict.
+- Issue/brief, commit SHA, pushed branch, provider change link or no-provider-change reason, provider check run links, and changed-file summary.
+- Release notes, migration notes, feature flags, deploy target, and rollback plan.
+- Known incidents, freezes, dependency risk, and owner availability.
+
+## Artifact Contract
+
+Create or update `.flow-agents/<slug>/<slug>--release-readiness.md` with:
+
+- `release_scope`: work included, excluded, issue/provider-change links
+- `evidence_reference`: evidence artifact, verdict, residual risks
+- `risk_review`: migrations, data, security, dependencies, flags, compatibility
+- `operational_plan`: deploy target, order, owner, timing, comms
+- `rollback_plan`: trigger, steps, owner, expected recovery signal
+- `observability_plan`: metrics, logs, traces, alerts, dashboards
+- `post_deploy_checks`: checks, commands, URLs, timing, expected signals
+- `final_acceptance_docs`: long-lived docs updated, archived `.flow-agents/<slug>/` links, and deferred docs follow-ups
+- `decision`: MERGE, RELEASE, DEPLOY, HOLD, or ROLLBACK_REQUIRED
+
+When the repository provides `npm run workflow:sidecar --`, also write `release.json` with:
+
+```bash
+npm run workflow:sidecar -- record-release .flow-agents/<slug> \
+  --decision merge \
+  --scope "..." \
+  --evidence-ref evidence.json \
+  --gate-json '{"name":"merge","status":"pass","summary":"..."}' \
+  --rollback-json '{"status":"not_required","summary":"...","owner":"..."}' \
+  --observability-json '{"status":"not_required","summary":"..."}' \
+  --docs-json '{"status":"updated","summary":"..."}' \
+  --summary "..."
+```
+
+Use additional `--gate-json` and `--post-deploy-json` values for release, deploy, docs, and post-deploy gates as needed.
+
+After writing `release.json`, run artifact validation when available. If `record-release` is unavailable or blocked, keep the release decision as `HOLD` in the Markdown artifact and record the sidecar-write or validation blocker as a `NOT_VERIFIED` evidence gap until the structured release record can be written or the gap is explicitly accepted.
+
+## Workflow
+
+### 1. Confirm Evidence
+
+Verify the evidence verdict is `PASS`, current, and tied to the release scope. If scope changed, return to `evidence-gate`.
+
+Then verify the publish-change gate:
+
+- verified diff is committed
+- branch is pushed
+- provider change record is open or updated, or a no-provider-change reason is explicitly recorded
+- provider checks / CI are linked and their status is known
+- GitHub PRs remain the first `ChangeProvider` adapter example: for GitHub, the provider change record is the PR and provider checks include PR checks
+
+If these are missing, return `HOLD` and route back to `publish-change` or `evidence-gate`; do not make a merge/release/deploy decision from local verification alone. Missing provider checks also return `HOLD` unless the risk class supports accepting the gap and the no-check reason is recorded.
+
+For Flow Agents source changes, the default provider check is the GitHub Actions `Flow Agents CI / Builder Kit Baseline` job. Its summary should list command results, artifact names, and skipped live lanes. A passing baseline supports merge readiness for deterministic workflow, docs, hook, package, and bundle checks, but it does not prove live GitHub mutation, LLM acceptance, or Veritas/governance provider evidence unless those lanes are explicitly run and linked.
+
+### 2. Review Release Risk
+
+Check migrations, feature flags, config, dependency changes, compatibility, security-sensitive paths, customer impact, and deploy timing.
+
+### 3. Plan Operation
+
+Record who owns merge/release/deploy, where it happens, when it happens, what communication is required, and what must not be included.
+
+### 4. Plan Rollback
+
+Define rollback trigger, rollback steps, owner, data recovery limits, and the signal that confirms recovery.
+
+### 5. Plan Post-Deploy Verification
+
+Map expected behavior to production-like checks, telemetry, dashboards, logs, smoke tests, or manual verification. High-risk work must have direct runtime evidence planned.
+
+### 6. Decide
+
+Produce one verdict:
+
+- `MERGE`: safe to merge, release/deploy not yet authorized.
+- `RELEASE`: safe to cut or publish a release artifact.
+- `DEPLOY`: safe to deploy with recorded owner and checks.
+- `HOLD`: blocked by risk, timing, missing evidence, or ownership.
+- `ROLLBACK_REQUIRED`: deployed state is unsafe and rollback should be considered.
+
+### 7. Promote Delivery Knowledge
+
+When CI has passed and merge/release acceptance is clear, require a docs decision:
+
+- update long-lived docs with what changed, how to use it, and important why/how decisions; or
+- record why no durable docs are needed; and
+- link back to the archived `.flow-agents/<slug>/` plan/session artifact for implementation history.
+
+## Gates
+
+- Merge Gate: evidence is current, scope matches, CI is acceptable, and review ownership is clear.
+- Release Gate: versioning, notes, compatibility, and artifact risk are clear.
+- Deploy Gate: deploy owner, target, rollback, and observability are ready.
+- Post-Deploy Gate: checks are scheduled or completed and signals are recorded.
+- Docs Gate: durable docs are updated, intentionally skipped, or routed to an owned follow-up.
+
+After deployment evidence exists, hand off to `learning-review` to capture outcomes.

package/skills/review-work/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: "review-work"
+description: "Review primitive - run report-only code, security, dependency, architecture/standards, and IaC/policy critique before verification; records findings through the critique artifact/sink, currently critique.json locally."
+---
+
+# Review
+
+Session file in, critique verdict out. Delegates to review agents and records findings separately from verification evidence.
+
+## Why This Is Separate From Verify
+
+Verification is not critique.
+
+Review asks whether the implementation should change: maintainability, security, architecture, standards, edge cases, and risky assumptions.
+
+Verify asks whether the behavior is proven: build, lint/types, tests, browser/runtime evidence, acceptance criteria, and Goal Fit.
+
+Keeping them separate makes failures route cleanly:
+
+- The critique artifact/sink says what a reviewer thinks should be fixed or accepted; the current local sidecar materialization is `critique.json`.
+- `evidence.json` says what was proven, failed, or could not be verified.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| tool-code-reviewer | Quality, maintainability, correctness, architecture fit, and project standards |
+| tool-security-reviewer | Security review when risk triggers are present |
+| tool-dependencies-updater | Dependency review when package manifests, dependency manifests, package manager config, or lockfiles change |
+| configured architecture/domain/IaC/policy reviewer | Optional reviewer when the project or user configures one |
+
+## Shared Contracts
+
+Follow:
+- `context/contracts/artifact-contract.md`
+- `context/contracts/review-contract.md`
+- `context/contracts/planning-contract.md` for acceptance criteria and Definition Of Done context
+
+## Read-Only Rule (STRICT)
+
+Reviewers NEVER modify source code:
+- No code patches
+- No format fixes
+- No lint autofixes
+- No "found and fixed"
+
+If a fix is needed, report it as a finding. The orchestrator routes it back to execution.
+
+## Input
+
+- Session file path in `.flow-agents/<slug>/` when available
+- Plan artifact or implementation summary
+- Modified files from execution progress or `git diff --name-only`
+- Project standards, especially `context/code-review-standards.md` when present
+- Security trigger context when present
+- Dependency trigger context when package manifests, dependency manifests, package manager config, or lockfiles change
+- IaC/policy trigger context when infrastructure, deployment, or policy files change
+
+## Security Review Triggers
+
+Run `tool-security-reviewer` when modified files or the task touch:
+
+- authentication or authorization
+- user input handling, forms, query params, headers, templates, or serialization
+- database queries, migrations, schemas, or persistence
+- filesystem paths, uploads, downloads, archives, or generated files
+- API endpoints, webhooks, external API calls, or network operations
+- cryptography, token handling, secrets, payments, billing, CI, deployment, or feature flags
+
+If trigger detection is uncertain for a substantial change, run the security reviewer or record the security review as `not_verified`.
+
+## Dependency Review Triggers
+
+Delegate to `tool-dependencies-updater` when modified files include package
+manifests, dependency manifests, package manager configuration, or lockfiles.
+Common triggers include `package.json`, `package-lock.json`, `pnpm-lock.yaml`,
+`yarn.lock`, `requirements.txt`, `pyproject.toml`, `poetry.lock`,
+`Pipfile.lock`, `Cargo.toml`, `Cargo.lock`, `go.mod`, `go.sum`, `pom.xml`,
+`build.gradle`, `Gemfile.lock`, `composer.lock`, NuGet lock files, Docker base
+image dependency declarations, and dependency update policy files.
+
+The dependency lane is report-only. It may inspect version, advisory, and
+lockfile risk using configured read-only tooling, but review-work must not add
+package-registry behavior, update dependencies, or install scanners. If the
+required dependency review cannot run, record the dependency lane as
+`not_verified`.
+
+## IaC/Policy Review Triggers
+
+Run security and configured IaC/policy review when modified files touch
+infrastructure as code, policy as code, cloud/deployment config, Terraform,
+OpenTofu, CloudFormation, Kubernetes manifests, Helm charts, Dockerfiles,
+Compose files, GitHub Actions, CI/CD permissions, IAM, OPA/Rego, Sentinel, or
+environment provisioning.
+
+IaC/policy scanner guidance is vendor-neutral. Acceptable scanner classes
+include Checkov, tfsec, Trivy, Semgrep, and project-configured policy scanners;
+do not hard-require one vendor. Treat scanner output as report-only critique
+input. If repo-local scanner tooling is unavailable, record the IaC/policy lane
+as `not_verified` instead of installing tools or silently passing it.
+
+## Workflow
+
+1. Read the session file to find the plan artifact path and modified files.
+2. Mark review as in progress. Markdown session files may use human-readable progress labels such as `reviewing`, but machine-readable workflow sidecars must use canonical `state.status` and `state.phase` values. For review-work, keep the lifecycle phase in execution and record critique results through the critique artifact/sink, currently `critique.json` locally:
+
+   ```bash
+   npm run workflow:sidecar -- advance-state <artifact-dir> \
+     --status in_progress \
+     --phase execution \
+     --summary "Review in progress." \
+     --next-action "Resolve review findings, then run verify-work."
+   ```
+
+3. Delegate in parallel:
+
+   ```text
+   tool-code-reviewer:
+   - Modified files
+   - Plan/acceptance criteria and user outcome
+   - context/code-review-standards.md when present
+   - Architecture, standards, maintainability, and correctness focus
+   - todo_file path or artifact root for writing a review artifact
+
+   tool-security-reviewer (when triggered):
+   - Modified files
+   - Security-sensitive areas to inspect
+   - Dependency/security commands available to run read-only
+
+   tool-dependencies-updater (when dependency triggers are present):
+   - Modified package manifests, dependency manifests, package manager config, and lockfiles
+   - Plan/acceptance criteria and dependency-risk context
+   - Read-only dependency review focus; no dependency updates or registry behavior changes from review-work
+
+   configured IaC/policy reviewer or repo-local scanner output (when IaC/policy triggers are present):
+   - Modified Terraform, Kubernetes, Docker, Helm, GitHub Actions, policy-as-code, cloud, or deployment files
+   - Read-only scanner classes such as Checkov, tfsec, Trivy, and Semgrep when already configured
+   - Missing scanner or reviewer recorded as not_verified
+   ```
+
+4. Import or record reviewer results into the critique artifact/sink, currently `critique.json` locally:
+
+   ```bash
+   npm run workflow:sidecar -- import-critique <artifact-dir> <review-artifact> \
+     --reviewer tool-code-reviewer
+   ```
+
+   Use `record-critique` directly when the reviewer returns structured findings instead of a Markdown artifact.
+
+5. Route on critique status:
+   - **pass/comment with no blocking findings** -> proceed to `verify-work`
+   - **fail** -> route findings back to `execute-plan` or `plan-work`
+   - **not_verified** -> surface the gap for user decision or run the missing reviewer
+
+## Output
+
+- Review artifacts written by reviewers when available
+- Critique artifact/sink updated with reviewer verdicts and findings; locally this is currently `critique.json`
+- Session or sidecar state updated so the next step is clear
+
+Do not treat a clean review as proof that the feature works. It only clears the critique gate; `verify-work` still has to collect evidence.

package/skills/search-first/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: search-first
+description: "Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code."
+---
+
+# Search-First
+
+Research before building. Every implementation task starts here.
+
+## Workflow
+
+### 1. Need Analysis
+Define clearly before searching:
+- What functionality is needed (inputs, outputs, behavior)
+- Language and framework constraints
+- Performance, size, or license requirements
+
+### 2. Parallel Search
+Search all sources simultaneously:
+- **Codebase** — grep/code search for existing implementations or utilities
+- **Package registries** — npm (`npmjs.com`), PyPI (`pypi.org`), crates.io, Go modules
+- **GitHub** — code search for patterns, reference implementations
+- **Web** — blog posts, Stack Overflow, official docs for recommended approaches
+
+### 3. Evaluate Candidates
+
+Score each candidate (1-5) on:
+
+| Criterion | Weight | What to check |
+|-----------|--------|---------------|
+| Functionality | High | Does it solve the actual need? |
+| Maintenance | High | Last release, open issues, bus factor |
+| Community | Medium | Downloads, stars, dependents |
+| Documentation | Medium | API docs, examples, migration guides |
+| License | High | Compatible with project? (MIT/Apache preferred) |
+| Dependencies | Medium | Transitive dep count, known vulnerabilities |
+
+### 4. Decide
+
+- **Adopt** — exact match, well-maintained, good community → install and use directly
+- **Extend** — partial match, solid core → wrap with thin adapter layer
+- **Build** — nothing suitable, unique requirements → write minimal custom code
+
+### 5. Implement
+- Adopt: install package, write integration code
+- Extend: install package, write wrapper/adapter
+- Build: write minimal custom implementation, document why existing solutions were rejected
+
+## Search Shortcuts
+
+| Category | First check |
+|----------|-------------|
+| HTTP client | axios (JS), httpx (Python), net/http (Go) |
+| Validation | Zod (TS), Pydantic (Python), validator (Go) |
+| CLI parsing | commander/yargs (JS), click/typer (Python), cobra (Go) |
+| Testing | Jest/Vitest (TS), pytest (Python), testing (Go) |
+| Date/time | date-fns (JS), pendulum (Python), time (Go) |
+| Logging | pino/winston (JS), structlog (Python), slog (Go) |
+
+## Anti-Patterns
+
+- **Jumping to code** — writing custom implementations without searching first
+- **Ignoring existing solutions** — the codebase already has a utility for this
+- **Over-customizing** — wrapping a library so heavily it's harder than building from scratch
+- **Dependency bloat** — adding a 50KB package for one function (just copy the function)
+- **Stale picks** — choosing unmaintained packages because they were popular 3 years ago

package/skills/tdd-workflow/SKILL.md

@@ -0,0 +1,140 @@
+---
+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."
+---
+
+# TDD Workflow
+
+Test-driven development orchestrator. Wraps the standard plan → execute → verify chain with test-first constraints.
+
+## When to Activate
+
+- User says "use TDD", "test-driven", "write tests first", "TDD"
+- User asks to build something and mentions test coverage requirements
+
+## 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) |
+
+## 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%
+```
+
+{context?}

package/skills/verify-work/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: "verify-work"
+description: "Verification primitive — session file path to structured evidence verdict via tool-verifier + tool-playwright. Reads acceptance criteria from plan artifact."
+---
+
+# Verify
+
+Session file in, structured evidence verdict out. Delegates to tool-verifier and tool-playwright.
+
+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.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| tool-verifier | Code verification, acceptance criteria checking, structured verdicts |
+| tool-playwright | Visual verification, screenshots, accessibility checks |
+
+## 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 `.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
+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.
+
+## 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.