@kontourai/flow-agents 4.0.0 → 4.2.0

package/dist/base/kits/builder/skills/pull-work/SKILL.md

@@ -32,6 +32,18 @@ Select ready backlog work and prepare a bounded handoff without implementing it.
 
 An optional GitHub adapter may implement these interfaces. Do not require GitHub issue numbers, labels, Projects, pull requests, `gh`, or provider-native dependency APIs.
 
+### Readiness Source Integrity
+
+A configured `BoardProvider` is the canonical Backlog Readiness Source
+(`docs/decisions/backlog-readiness-source.md`). When the configured board
+yields zero ready items or cannot be read, record the provider warning
+(`zero_ready_items`, or the read failure) in the pull-work artifact and route
+to triage/intake for an explicit readiness decision. Never silently
+substitute `WorkItemProvider` issue-level listing for board-driven selection:
+a deliberate issue-listing pass must carry the `board_provider_bypassed`
+warning it received into the artifact, with the reason the board was
+bypassed.
+
 ## Model Routing
 
 For board scans, WIP assessment, dependency joins, and selection bookkeeping, resolve `delegate-mechanical` from `.datum/config.json`. If unavailable, inherit the session model and record the fallback.

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

@@ -58,6 +58,17 @@ fallback or escalation in the critique artifact.
      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.
+
+   When review fans out to delegated reviewer lanes, declare the fan-out in the
+   session's wave manifest (`waves.json`, schema
+   `schemas/workflow-waves.schema.json`, step `review`) with one
+   `expected_workers` entry per reviewer lane before dispatch. Reconcile against
+   that manifest at collection — "N of M reported" — instead of collecting from
+   memory: every declared reviewer lands exactly one terminal status record;
+   record a reviewer that never reports as `not_reported` in the manifest —
+   never silently absorb it — and carry that lane into the critique as
+   `not_verified` with the missing report named. A missing reviewer is never a
+   clean lane.
 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

package/dist/base/kits/veritas-governance/adapter/readiness-to-trust-bundle.mjs

@@ -19,22 +19,21 @@
 // external-tool `fail`/`missing` (mirrors veritas/src/surface/readiness.mjs's own PRIVATE
 // `readinessHasBlockingFailure` helper, and matches Surface's `buildTrustReport` weakest-link
 // derivation, which downgrades a readiness claim to `rejected` on any rejected Require —
-// tests/surface/readiness-derived-claim.test.mjs:256-278). It intentionally does NOT apply
-// Veritas's EXPORTED `promotion_allowed` short-circuit (readinessSurfaceStatus/readinessVerdict
-// treat promotion_allowed===true as verified/ready regardless of blocking Require failures):
-// promotion_allowed is a workstream-routing hint from src/repo/routing.mjs `resolveWorkstream()`
-// (file-pattern lane resolution), not a safety signal — it never reads policy_results, evidence
-// checks, uncovered paths, or external tools, so it cannot account for blocking failures. This is
-// a filed Veritas bug, not a legitimate alternate reading: kontourai/veritas#106
-// (https://github.com/kontourai/veritas/issues/106) — "promotion_allowed short-circuit bypasses
-// blocking Require failures" — recommends veritas fix readiness.mjs to check
-// readinessHasBlockingFailure() before the promotion_allowed short-circuit. Conclusion: the
-// adapter's stricter derivation is correct today and will agree with veritas's own exported
-// functions once #106 lands; it is not a fork of Veritas's intended semantics, and the
-// Governance Kit's blocking-failure semantics are the successor the wider system is moving
-// toward (this adapter's independent CLI wrap was for reversibility while that landed). Ready
-// (no blocking failure) -> Surface derives `verified` -> gate passes. Not-ready -> Surface
-// derives a non-`verified` status -> gate blocks.
+// tests/surface/readiness-derived-claim.test.mjs:256-278). It does NOT treat Veritas's
+// `promotion_allowed` flag as a safety signal: promotion_allowed is a workstream-routing hint
+// from src/repo/routing.mjs `resolveWorkstream()` (file-pattern lane resolution) — it never
+// reads policy_results, evidence checks, uncovered paths, or external tools, so it cannot
+// account for blocking failures. The divergence this originally guarded against —
+// kontourai/veritas#106 (https://github.com/kontourai/veritas/issues/106), Veritas's exported
+// readinessVerdict/readinessSurfaceStatus honoring promotion_allowed before checking blocking
+// failures — is FIXED: veritas src/surface/readiness.mjs now checks
+// readinessHasBlockingFailure() before the promotion_allowed short-circuit (regression-tested
+// in veritas tests/surface/readiness-verdict.test.mjs), so this adapter and Veritas's exported
+// functions now agree. The adapter keeps its own derivation because kit code consumes the
+// recorded artifact, not Veritas library exports; the record fields and blocking-failure
+// semantics it reads are frozen in veritas docs/architecture/engine-surface-seam.md
+// (flow-agents#646 Slice 1). Ready (no blocking failure) -> Surface derives `verified` -> gate
+// passes. Not-ready -> Surface derives a non-`verified` status -> gate blocks.
 //
 // Usage: node readiness-to-trust-bundle.mjs --report <veritas-evidence-report.json> \
 //          --out <bundle.json> [--subject-id <id>]
@@ -54,10 +53,10 @@ function parseArgs(argv) {
   return out;
 }
 
-// Mirrors veritas/src/surface/readiness.mjs's PRIVATE readinessHasBlockingFailure — reads
-// Veritas's OWN recorded results; does not evaluate standards. Does NOT apply promotion_allowed
-// (see header comment above): that short-circuit is a filed veritas bug (kontourai/veritas#106),
-// not a safety signal — this stricter derivation is the settled-correct semantics.
+// Mirrors veritas/src/surface/readiness.mjs's readinessHasBlockingFailure — reads Veritas's
+// OWN recorded results; does not evaluate standards. Ignores promotion_allowed (a routing hint,
+// not a safety signal — see header comment above); since veritas#106 was fixed, Veritas's own
+// verdict functions (src/surface/readiness.mjs) apply this same blocking-failure-first semantics.
 export function hasBlockingFailure(record) {
   if (record.uncovered_path_result === "fail") return true;
   if ((record.policy_results ?? []).some((r) => r.passed === false && r.enforcementLevel === "Require")) return true;

package/dist/base/kits/veritas-governance/assets/starter-hooks/githooks/post-commit

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+if [ "${VERITAS_HOOK_SKIP:-${AI_GUIDANCE_HOOK_SKIP:-0}}" = "1" ]; then
+  exit 0
+fi
+
+if git rev-parse --verify --quiet HEAD~1 >/dev/null; then
+  npm exec -- veritas readiness --changed-from HEAD~1 --changed-to HEAD
+else
+  EMPTY_TREE="$(git hash-object -t tree /dev/null)"
+  npm exec -- veritas readiness --changed-from "$EMPTY_TREE" --changed-to HEAD
+fi

package/dist/base/kits/veritas-governance/assets/starter-hooks/githooks/pre-push

@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+
+if [ "${VERITAS_HOOK_SKIP:-${AI_GUIDANCE_HOOK_SKIP:-0}}" = "1" ]; then
+  exit 0
+fi
+
+if [ ! -f package.json ]; then
+  echo "Veritas pre-push: package.json not found; skipping."
+  exit 0
+fi
+
+npm run --if-present prepush

package/dist/base/kits/veritas-governance/assets/starter-standards/veritas/GOVERNANCE.md

@@ -0,0 +1,23 @@
+# Veritas Governance
+
+Protected Standards require authority-backed review. Do not modify without a fresh Veritas attestation:
+- `.veritas/repo-map.json`
+- `.veritas/repo-standards/`
+- `.veritas/authority/`
+
+Authority-backed attestations require an explicit human approval reference. Agents may prepare
+`veritas attest ... --approval-ref <ref>` commands, but must not invent the reference or record
+the attestation without a durable approval artifact from the human authority.
+
+Standards Growth is additive. Developers and agents may propose:
+- new work areas for new feature directories
+- advisory requirements for new work areas
+- clearer change guidance backed by evidence
+
+Do not weaken or delete existing standards without the required authority.
+
+Generated Evidence is output, not the source of standards:
+- `.kontourai/veritas/evidence/`
+- `.kontourai/veritas/standards-feedback-drafts/`
+- `.kontourai/veritas/standards-feedback/`
+- `.kontourai/veritas/repo-conformance/`

package/dist/base/kits/veritas-governance/assets/starter-standards/veritas/README.md

@@ -0,0 +1,58 @@
+# Veritas Starter Kit
+
+This repo was bootstrapped for `your-project` with a conservative starter kit for agent-guided development.
+
+## Generated Files
+
+- `.veritas/README.md`
+- `.veritas/GOVERNANCE.md`
+- `.veritas/repo-map.json`
+- `.veritas/repo-standards/default.repo-standards.json`
+- `.veritas/authority/default.authority-settings.json`
+
+## Inferred Repo Shape
+
+- Repo kind: `application`
+- Source roots: `src/` (default)
+- Tooling roots: `none`
+- Test roots: `tests/` (default)
+- GitHub workflows detected: `no`
+- Matching scripts seen: `test`
+
+## What To Do Next
+
+1. Confirm the inferred source/test roots match the real repo layout.
+2. Replace the suggested evidenceCheck if a stronger project health command exists.
+3. Keep uncertain requirements in Observe or Guide until evidence shows they should be required.
+
+
+
+## Suggested Commands
+
+```bash
+npx @kontourai/veritas readiness --working-tree
+npx @kontourai/veritas readiness --check coverage --working-tree
+npx @kontourai/veritas integrations codex status
+npx @kontourai/veritas attest bootstrap --actor <authority-id> --approval-ref <human-approval-reference> --non-interactive
+```
+
+If you prefer explicit paths:
+
+```bash
+npx @kontourai/veritas readiness --check evidence \
+  --repo-map ./.veritas/repo-map.json \
+  --repo-standards ./.veritas/repo-standards/default.repo-standards.json \
+  package.json
+```
+
+## Suggested Evidence Check
+
+`npm run test`
+
+## Work-Area Evidence Routing
+
+This starter stays on the minimal single-check path by default. Work-area evidence routing can be added later if the repo grows multiple independently verified work areas.
+
+## Why This Exists
+
+The goal is to give developers and agents just-in-time repo guidance from day one, while keeping review and CI grounded in the same starter standards.

package/dist/base/kits/veritas-governance/assets/starter-standards/veritas/authority/default.authority-settings.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "id": "your-project-default",
+  "name": "your-project Default",
+  "description": "Conservative starter settings: observe first, learn from evidence, and only require what has earned trust.",
+  "defaults": {
+    "mode": "observe",
+    "new_rule_enforcement_level": "Observe"
+  },
+  "review_preferences": {
+    "human_signoff_required_for_stage_promotion": true,
+    "reviewer_confidence_scale": [
+      "low",
+      "medium",
+      "high"
+    ],
+    "major_rewrite_definition": "A major rewrite replaces the main structure or requirement flow instead of making local edits.",
+    "attestation_approval_ref_policy": {
+      "mode": "reference-only",
+      "allowed_prefixes": []
+    }
+  },
+  "promotion_preferences": {
+    "evidence_checks_required_before_require": [
+      "npm run test"
+    ],
+    "warnings_block_in_ci": false,
+    "require_consistent_feedback_before_promotion": true
+  }
+}

package/dist/base/kits/veritas-governance/assets/starter-standards/veritas/repo-map.json

@@ -0,0 +1,115 @@
+{
+  "name": "your-project",
+  "kind": "repo-map",
+  "policy": {
+    "defaultFalsePositiveReview": "unknown",
+    "defaultPromotionCandidate": false,
+    "defaultExceptionAllowed": false
+  },
+  "graph": {
+    "version": 1,
+    "defaultResolution": {
+      "phase": "Phase 0 (Bootstrap)",
+      "workstream": "Initial Project Setup",
+      "matchedArtifacts": [
+        "README.md"
+      ]
+    },
+    "nonSliceableInvariants": [
+      "baseline evidenceCheck",
+      "repo-local guidance",
+      "tracked standards artifacts"
+    ],
+    "resolverPrecedence": [
+      "explicit task or issue reference",
+      "matching local artifact under .veritas/**",
+      "active repo roadmap or README guidance",
+      "multi-workstream fallback suppresses promotion"
+    ],
+    "resolutionRules": [
+      {
+        "id": "veritas-files",
+        "match": {
+          "patterns": [
+            ".veritas/"
+          ]
+        },
+        "resolution": {
+          "phase": "Phase 0 (Bootstrap)",
+          "workstream": "Initial Project Setup",
+          "matchedArtifacts": [
+            ".veritas/**"
+          ]
+        }
+      }
+    ],
+    "nodes": [
+      {
+        "id": "governance.guidance",
+        "kind": "protected-area",
+        "label": ".veritas/**",
+        "patterns": [
+          ".veritas/"
+        ],
+        "governance-locked": true
+      },
+      {
+        "id": "governance.root-manifests",
+        "kind": "protected-area",
+        "label": "root manifests",
+        "patterns": [
+          "package.json",
+          "package-lock.json",
+          "README.md",
+          ".gitignore",
+          "AGENTS.md"
+        ]
+      },
+      {
+        "id": "app.src",
+        "kind": "product-area",
+        "label": "src/**",
+        "patterns": [
+          "src/"
+        ]
+      },
+      {
+        "id": "verification.tests",
+        "kind": "verification-area",
+        "label": "tests/**",
+        "patterns": [
+          "tests/"
+        ]
+      }
+    ]
+  },
+  "evidence": {
+    "artifactDir": ".kontourai/veritas/evidence",
+    "evidenceChecks": [
+      {
+        "id": "required-evidence-check",
+        "command": "npm run test",
+        "method": "validation",
+        "summary": "Default repository evidenceCheck."
+      }
+    ],
+    "requiredEvidenceCheckIds": [
+      "required-evidence-check"
+    ],
+    "reportTransport": "local-json"
+  },
+  "activation": {
+    "aiInstructionFiles": [
+      {
+        "path": "AGENTS.md",
+        "tool": "codex",
+        "required": true
+      },
+      {
+        "path": "CLAUDE.md",
+        "tool": "claude-code",
+        "required": true
+      }
+    ]
+  }
+}

package/dist/base/kits/veritas-governance/assets/starter-standards/veritas/repo-standards/default.repo-standards.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "name": "your-project-default",
+  "description": "Conservative starter Repo Standards for a newly bootstrapped Veritas-enabled repository.",
+  "rules": [
+    {
+      "id": "required-veritas-artifacts",
+      "kind": "required-artifacts",
+      "classification": "hard-invariant",
+      "enforcementLevel": "Require",
+      "message": "The bootstrap Veritas artifacts must stay present so agents and reviewers share the same baseline.",
+      "owner": "repo-core",
+      "rollback_switch": null,
+      "match": {
+        "artifacts": [
+          ".veritas/README.md",
+          ".veritas/GOVERNANCE.md",
+          ".veritas/repo-map.json",
+          ".veritas/repo-standards/default.repo-standards.json",
+          ".veritas/authority/default.authority-settings.json"
+        ]
+      }
+    },
+    {
+      "id": "ai-instruction-files-synced",
+      "kind": "governance-block",
+      "classification": "hard-invariant",
+      "enforcementLevel": "Guide",
+      "message": "All required AI tool instruction files must contain the Veritas guidance block.",
+      "owner": "repo-maintainers",
+      "rollback_switch": null,
+      "match": {
+        "governance-block": [
+          "AGENTS.md",
+          "CLAUDE.md"
+        ]
+      }
+    },
+    {
+      "id": "prefer-veritas-routed-delivery",
+      "kind": "required-artifacts",
+      "classification": "promotable-policy",
+      "enforcementLevel": "Observe",
+      "message": "Prefer running new AI-guided changes through Veritas readiness checks and the documented evidenceCheck before review.",
+      "owner": "repo-maintainers",
+      "rollback_switch": "soften-veritas-route",
+      "match": {
+        "artifacts": [
+          ".veritas/README.md"
+        ]
+      }
+    }
+  ]
+}

package/dist/base/kits/veritas-governance/assets/starter-standards/veritas.claims.json

@@ -0,0 +1,179 @@
+{
+  "schemaVersion": 1,
+  "producer": "veritas",
+  "claims": [
+    {
+      "id": "your-project.surface.governance.guidance",
+      "facet": "veritas.affected-surface",
+      "claimType": "veritas-affected-surface",
+      "fieldOrBehavior": "governance.guidance",
+      "subjectType": "repo-surface",
+      "subjectId": "your-project:governance.guidance",
+      "impactLevel": "medium",
+      "verificationPolicyId": "veritas.surface",
+      "metadata": {
+        "nodeId": "governance.guidance"
+      },
+      "createdAt": "2026-07-17T04:35:28.137Z",
+      "updatedAt": "2026-07-17T04:35:28.137Z"
+    },
+    {
+      "id": "your-project.surface.governance.root-manifests",
+      "facet": "veritas.affected-surface",
+      "claimType": "veritas-affected-surface",
+      "fieldOrBehavior": "governance.root-manifests",
+      "subjectType": "repo-surface",
+      "subjectId": "your-project:governance.root-manifests",
+      "impactLevel": "medium",
+      "verificationPolicyId": "veritas.surface",
+      "metadata": {
+        "nodeId": "governance.root-manifests"
+      },
+      "createdAt": "2026-07-17T04:35:28.137Z",
+      "updatedAt": "2026-07-17T04:35:28.137Z"
+    },
+    {
+      "id": "your-project.surface.app.src",
+      "facet": "veritas.affected-surface",
+      "claimType": "veritas-affected-surface",
+      "fieldOrBehavior": "app.src",
+      "subjectType": "repo-surface",
+      "subjectId": "your-project:app.src",
+      "impactLevel": "medium",
+      "verificationPolicyId": "veritas.surface",
+      "metadata": {
+        "nodeId": "app.src"
+      },
+      "createdAt": "2026-07-17T04:35:28.137Z",
+      "updatedAt": "2026-07-17T04:35:28.137Z"
+    },
+    {
+      "id": "your-project.surface.verification.tests",
+      "facet": "veritas.affected-surface",
+      "claimType": "veritas-affected-surface",
+      "fieldOrBehavior": "verification.tests",
+      "subjectType": "repo-surface",
+      "subjectId": "your-project:verification.tests",
+      "impactLevel": "medium",
+      "verificationPolicyId": "veritas.surface",
+      "metadata": {
+        "nodeId": "verification.tests"
+      },
+      "createdAt": "2026-07-17T04:35:28.137Z",
+      "updatedAt": "2026-07-17T04:35:28.137Z"
+    },
+    {
+      "id": "your-project.governance",
+      "facet": "veritas.governance",
+      "claimType": "veritas-governance-artifact",
+      "fieldOrBehavior": "governance artifact integrity",
+      "subjectType": "repository",
+      "subjectId": "your-project",
+      "impactLevel": "high",
+      "verificationPolicyId": "veritas.governance-artifact",
+      "createdAt": "2026-07-17T04:35:28.137Z",
+      "updatedAt": "2026-07-17T04:35:28.137Z"
+    },
+    {
+      "id": "your-project.evidence-check.npm-run-test",
+      "facet": "veritas.evidence-check",
+      "claimType": "software-evidence-check",
+      "fieldOrBehavior": "npm run test",
+      "subjectType": "repository",
+      "subjectId": "your-project",
+      "impactLevel": "high",
+      "verificationPolicyId": "veritas.evidence-check",
+      "metadata": {
+        "command": "npm run test"
+      },
+      "createdAt": "2026-07-17T04:35:28.137Z",
+      "updatedAt": "2026-07-17T04:35:28.137Z"
+    }
+  ],
+  "policies": [
+    {
+      "id": "veritas.surface",
+      "claimType": "veritas-affected-surface",
+      "requiredEvidence": [
+        "policy_rule"
+      ],
+      "requiredMethods": [
+        "auditability"
+      ],
+      "requiresCorroboration": false,
+      "acceptanceCriteria": [
+        "veritas evidence artifact"
+      ],
+      "reviewAuthority": "veritas",
+      "validityRule": {
+        "kind": "commit"
+      },
+      "stalenessTriggers": [
+        "source_ref changes",
+        "affected node changes"
+      ],
+      "conflictRules": [
+        "newer evidence for the same node supersedes older evidence"
+      ],
+      "impactLevel": "medium"
+    },
+    {
+      "id": "veritas.governance-artifact",
+      "claimType": "veritas-governance-artifact",
+      "requiredEvidence": [
+        "attestation",
+        "policy_rule"
+      ],
+      "requiredMethods": [
+        "auditability",
+        "attestation"
+      ],
+      "requiresCorroboration": false,
+      "acceptanceCriteria": [
+        "Protected Standards hash inspection",
+        "authority attestation status"
+      ],
+      "reviewAuthority": "veritas plus authority attestation",
+      "validityRule": {
+        "kind": "manual"
+      },
+      "stalenessTriggers": [
+        "Repo Standards hash changes",
+        "Repo Map hash changes",
+        "authority settings hash changes",
+        "attestation expiry"
+      ],
+      "conflictRules": [
+        "hash drift disputes Protected Standards currency"
+      ],
+      "impactLevel": "high"
+    },
+    {
+      "id": "veritas.evidence-check",
+      "claimType": "software-evidence-check",
+      "requiredEvidence": [
+        "test_output"
+      ],
+      "requiredMethods": [
+        "validation"
+      ],
+      "requiresCorroboration": false,
+      "acceptanceCriteria": [
+        "selected evidenceCheck command"
+      ],
+      "reviewAuthority": "veritas",
+      "validityRule": {
+        "kind": "commit"
+      },
+      "stalenessTriggers": [
+        "source_ref changes",
+        "evidenceCheck command changes",
+        "baseline evidenceCheck fails"
+      ],
+      "conflictRules": [
+        "failed evidenceCheck rejects a previously verified evidenceCheck claim"
+      ],
+      "impactLevel": "high"
+    }
+  ]
+}