@kontourai/flow-agents 3.6.0 → 3.8.0

package/kits/builder/skills/release-readiness/SKILL.md

@@ -1,133 +1,92 @@
 ---
 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."
+description: "Make a provider-neutral merge, release, deploy, or hold decision. Records Builder publish-learn CI merge-readiness in trust.bundle."
 ---
 
 # Release Readiness
 
-Turn a clean evidence result into an explicit release, deploy, or hold decision.
+## Role
 
-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.
+This is a Builder step skill.
 
-## Contract
+Release Readiness turns confidence and published-change evidence into an explicit
+`MERGE`, `RELEASE`, `DEPLOY`, `HOLD`, or `ROLLBACK_REQUIRED` decision. It does
+not fix code, publish a change, or deploy without explicit authorization.
 
-- 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.
+## Binding
 
-## 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 `.kontourai/flow-agents/<slug>/<slug>--release-readiness.md` with:
+| Context | Binding | Flow expectation |
+| --- | --- | --- |
+| Active Builder run | Parent `builder.build` projection at composed `builder.publish-learn` step `merge-ready-ci` | `ci-merge-readiness` |
+| Standalone invocation | No Flow binding | No workflow mutation. |
 
-- `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 `.kontourai/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:
+For an active run, confirm the binding before making the Flow claim:
 
 ```bash
-npm run workflow:sidecar -- record-release .kontourai/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 "..."
+flow-agents workflow status --session-dir <session-dir> --json
 ```
 
-Use additional `--gate-json` and `--post-deploy-json` values for release, deploy, docs, and post-deploy gates as needed.
+Public status reports the parent definition as `builder.build`. Only that parent
+run at `merge-ready-ci`, whose Flow Definition composes the step from
+`builder.publish-learn`, may publish `ci-merge-readiness`.
 
-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.
+## Inputs
 
-For an active Builder Flow run, record the CI merge-readiness claim only for a `MERGE`, `RELEASE`, or `DEPLOY` decision backed by current provider checks:
+- The evidence-gate confidence report and acceptance evidence.
+- Published-change state from `ChangeProvider` and repository scope from
+  `RepositoryAdapter`.
+- Check and review state from `CheckProvider`.
+- Release and deployment capabilities from `ReleaseProvider` and `DeployProvider`.
+- Risk, rollback, observability, ownership, and authorization information.
+
+No provider is assumed. A change record, check, release record, or deployment
+record may be unavailable because the repository or provider does not offer it.
+Record the capability and its impact rather than substituting provider-specific
+terms or treating absence as success.
+
+## Decision Work
+
+1. Confirm the confidence report remains applicable to the proposed scope.
+2. Reconcile current provider checks and review state with the revision covered
+   by acceptance evidence. Stale or mismatched evidence is `NOT_VERIFIED`.
+3. Evaluate change publication, release and deployment implications through the
+   available providers. Before `RELEASE` or `DEPLOY`, require an owner, an
+   executable rollback or recovery path, observable success and failure
+   signals, and a bounded post-release or post-deploy verification plan.
+4. Require explicit authorization for merge, release, deploy, or rollback.
+   Readiness evidence and an available provider capability are not authority to
+   perform the operation.
+5. Use `HOLD` for unresolved required evidence, ownership, rollback,
+   observability, post-operation verification, or authority. Use
+   `NOT_VERIFIED` for evidence that cannot be collected; it cannot be promoted
+   to a clean merge, release, or deploy decision without an explicit accepted gap.
+   Use `ROLLBACK_REQUIRED` when observed outcomes cross the recorded rollback
+   threshold.
+6. On a matching active run, publish the resulting evidence through the public
+   CLI:
 
 ```bash
-npm run workflow:sidecar -- record-gate-claim .kontourai/flow-agents/<slug> \
+flow-agents workflow evidence --session-dir <session-dir> \
   --expectation ci-merge-readiness \
-  --status pass \
-  --summary "Provider checks are current and passing; release-readiness decision and residual risks are recorded." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/<slug>/release.json","summary":"Release-readiness decision with provider checks, rollback, and observability evidence."}'
+  --status <pass|fail|not_verified> \
+  --summary "Release-readiness decision and residual risks are recorded." \
+  --evidence-ref-json '{"kind":"artifact","file":"<session-dir>/release.json","summary":"Release-readiness decision, authorization, rollback, and observability state."}'
 ```
 
-Use `fail` or `not_verified` for `HOLD` and unresolved provider evidence. Flow owns the transition to learning after it verifies this claim.
-
-## 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:
+## Output
 
-- 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 `.kontourai/flow-agents/<slug>/` plan/session artifact for implementation history.
+Record the decision as the `ci-merge-readiness` slice in `trust.bundle`. It
+includes assessed scope, confidence evidence, provider capability and check
+state, risks, rollback and observability plan, required authorization, and
+unresolved `NOT_VERIFIED` gaps. For release or deployment decisions, also record
+the owner, success/failure signals, rollback threshold, and post-operation
+verification commands or observations.
 
-## Gates
+When acceptance behavior is summarized, include a readable `Acceptance
+Evidence` table:
 
-- 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.
+| AC id | Status | Command/Test Evidence | Source Evidence | Gaps |
+| --- | --- | --- | --- | --- |
 
-After deployment evidence exists, hand off to `learning-review` to capture outcomes.
+The claim supports the next Builder step; it does not itself merge, release, or
+deploy anything.

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

@@ -1,195 +1,108 @@
 ---
 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."
+description: "Report-only critique before Builder verification. Records a critique slice through the public workflow interface without claiming Flow completion."
 ---
 
-# Review
+# Review Work
 
-Session file in, critique verdict out. Delegates to review agents and records findings separately from verification evidence.
+## Role
 
-## Why This Is Separate From Verify
+This is a Builder step skill.
 
-Verification is not critique.
+Review Work is the report-only critique step. It asks whether the changed work
+should change before verification: correctness risks, maintainability, security,
+dependencies, architecture, standards, and applicable policy.
 
-Review asks whether the implementation should change: maintainability, security, architecture, standards, edge cases, and risky assumptions.
+It does not prove accepted behavior and it does not fix source files.
 
-Verify asks whether the behavior is proven: build, lint/types, tests, browser/runtime evidence, acceptance criteria, and Goal Fit.
+## Binding
 
-Keeping them separate makes failures route cleanly:
+| Context | Binding | Flow expectation |
+| --- | --- | --- |
+| Active Builder run | `builder.build` at `verify` | `clean-critique`. Review Work owns the critique claim, not verification completion. |
+| Standalone invocation | No Flow binding | No workflow mutation. |
 
-- 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.
+For an active run, inspect the binding before work:
 
-## Agents
+```bash
+flow-agents workflow status --session-dir <session-dir> --json
+```
 
-| 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 |
+Run this skill only when the reported run is `builder.build` at `verify`.
+If there is no matching active run, operate standalone. Do not publish a gate
+expectation from this skill.
 
 ## Model Routing
 
-Review 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 review — a reviewer 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.
-
-## 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 `.kontourai/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`.
-
-For multi-repo or cross-product work, dependency review must preserve the full
-scope. Before delegating, enumerate every affected repo/package-manager root and
-record one status per root:
-
-- `pass`: dependency review ran and found no blocking issue
-- `fail`: dependency review ran and found a blocking advisory, version, or
-  lockfile issue
-- `skip_no_manifest`: the root has no supported dependency manifest
-- `not_verified`: review could not run or the result is unavailable
-
-Do not narrow the dependency lane to only roots that failed build/test. If the
-work changed shared conventions, generated artifact paths, install scripts, CI,
-or workspace-wide guidance, the dependency review summary must say which product
-roots were included and which were out of scope.
-
-External advisory/audit services can disclose private dependency metadata. Before
-running tools such as `npm audit`, registry lookups, or vendor advisory APIs,
-record whether the user explicitly approved that disclosure for the affected
-roots. If approval is absent, rejected, or too ambiguous for the local execution
-policy, keep local inventory evidence and mark the external-audit portion
-`not_verified` with the approval/privacy blocker. Do not convert that blocker
-into a clean pass.
-
-## 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
+Resolve `delegate-implementation` from `.datum/config.json` and follow
+`context/contracts/execution-contract.md`. The Goodhart guard applies: review
+must never resolve below the reasoning tier of the checked work. Record any
+fallback or escalation in the critique artifact.
+
+## Inputs
+
+- Changed-file scope from the session, plan, or `RepositoryAdapter`.
+- Acceptance criteria and implementation intent.
+- Repository standards and relevant decisions.
+- Available `CheckProvider` evidence and policy constraints.
+
+## Review Work
+
+1. Establish the changed-file scope. If it cannot be established, record the
+   scope review as `NOT_VERIFIED`.
+2. Select review lanes from the changed scope and risk, not from a fixed list
+   run unconditionally:
+   - `tool-code-reviewer` for code quality, correctness, architecture, and standards.
+   - `tool-security-reviewer` for authentication, authorization, secrets,
+     untrusted input, data handling, network boundaries, infrastructure, and
+     security-policy changes.
+   - `tool-dependencies-updater` for dependency-manifest, lockfile, or dependency-tooling changes.
+   - A configured domain or policy reviewer when the repository requires one.
+3. Use repository-provided scanners and checks when applicable. Do not install
+   a scanner, silently substitute a different one, or mark an unavailable
+   required lane clean; record the lane as `NOT_VERIFIED` with the missing
+   capability and consequence.
+4. Keep findings actionable: severity, affected scope, evidence, and the
+   required route back. Do not install scanners or change code to obtain a
+   cleaner result.
+5. Produce the critique artifact. Open blocking findings route to implementation;
+   unavailable required review remains `NOT_VERIFIED`.
 
 ## 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.
+For a matching active run, record the review through the public interface:
+
+```bash
+flow-agents workflow critique --session-dir <session-dir> \
+  --verdict <pass|fail|not_verified> \
+  --summary "Review scope, findings, and unresolved gaps are recorded." \
+  --artifact-ref ".kontourai/flow-agents/<slug>/<slug>--deliver.md" \
+  --artifact-ref "<reviewed-changed-file>" \
+  --lane-json '{"id":"code-review","status":"pass","summary":"Code quality, correctness, architecture, and standards were reviewed.","evidence_refs":[{"kind":"artifact","file":".kontourai/flow-agents/<slug>/<slug>--deliver.md","summary":"Reviewed delivery artifact and changed-scope context."}]}'
+```
+
+The delegated reviewer must invoke this operation under its own runtime actor
+identity. The public operation requires an active implementation assignment but
+rejects the assigned implementation actor as the reviewer; do not proxy the
+review through the implementation actor or supply a caller-selected reviewer
+label. The critique is stored as the review slice in `trust.bundle`: reviewer
+identity, covered scope, lane verdicts, severity-tagged findings, evidence, and
+unresolved `NOT_VERIFIED` gaps. A clean critique satisfies the declared
+`clean-critique` expectation, but it is not test evidence, does not satisfy
+`tests-evidence`, and does not independently advance a Flow run.
+
+Runtime actor separation is a coordination guarantee, not cryptographic
+attestation. When repository policy requires an externally attested reviewer
+credential and the runtime cannot provide one, record reviewer identity as
+`NOT_VERIFIED`; do not describe the review as independently authenticated.
+
+Every critique needs at least one substantive `--lane-json`. A passing critique
+also needs existing local `--artifact-ref` values for the delivery report and
+reviewed changed files. The writer hashes those files and captures the current
+workspace snapshot in `review_target`. Git repositories bind the review to
+`HEAD`, the tracked diff, and untracked file bytes; non-Git repositories bind it
+to the explicitly reviewed files. A later implementation change makes the
+critique stale rather than silently clean.
+
+For standalone use, return the same report to the caller without creating a
+workflow record.