@kontourai/flow-agents 3.12.1 → 4.1.0

package/dist/pi/kits/veritas-governance/docs/README.md

@@ -11,6 +11,12 @@ CLI invocation plus a small kit-local trust.bundle adapter. It does **not** fork
 reimplement Veritas's Repo Standards / evidence-check evaluation — Veritas evaluates; the kit
 only projects Veritas's own recorded verdict into the Flow trust.bundle vocabulary.
 
+The engine/surface line this kit builds on — which veritas capabilities stay an importable
+evaluation-engine library and which product surface moves into this kit (the thick-kit
+migration, [#646](https://github.com/kontourai/flow-agents/issues/646)–652) — is ratified in
+veritas's [Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md)
+doc, which also freezes the CLI + artifact + claim-shape contract this kit's adapter consumes.
+
 ## What it contains
 
 | Asset | Path | Purpose |
@@ -20,6 +26,11 @@ only projects Veritas's own recorded verdict into the Flow trust.bundle vocabula
 | Fixtures | `fixtures/readiness/*.readiness-report.json` | Captured **real** Veritas readiness reports (a ready clean tree, and a not-ready tree with a required CLI artifact deleted) used by the eval. |
 | Flow | `flows/exemption-issuance.flow.json` | Single-gate agentless flow `request -> human-approval-gate -> issue`. The gate requires a **verified** `no-agent-delivery-exemption-approval` trust.bundle claim (`subjectType: "delivery-scope"`) before the `issue` step's write is flow-sanctioned. Issues a `delivery/DECLARED` exemption entry per ADR 0022 §2/§3. |
 | Skill | `skills/exemption-usage-review/SKILL.md` | Periodic audit skill (ADR 0022 §3): walks `delivery/DECLARED` + its `git log --follow` history and reports every standing exemption (scope, reason, approver, age since `declared_at`), flagging entries overdue for owner re-confirmation against a configurable staleness threshold. Process visibility, not enforcement — read-only, never mutates `delivery/DECLARED` or the reconciler. |
+| Provisions | `assets/starter-standards/**` → `provisions[]` | Starter `.veritas/` Repo Standards a consumer repo needs to run `veritas readiness` — a faithful snapshot of `veritas init`'s Day-0 output (Repo Map, Repo Standards, authority settings, `GOVERNANCE.md`, `README.md`, claim store), shipped as data and copied verbatim by `flow-agents kit provision`. See "Scaffolding starter standards" below. |
+| Provisions | `assets/starter-hooks/githooks/**` → `provisions[]` | The two governance git hooks (`veritas setup repo-hooks`'s static output): `.githooks/pre-push` (`npm run --if-present prepush`) and `.githooks/post-commit` (`veritas readiness`). Shipped verbatim; landed non-executable — activation (`chmod +x` + `git config core.hooksPath`) is a documented operator step a copy cannot perform. See "Provisioning the governance hooks". |
+| Flow | `flows/standards-authoring.flow.json` | Single-gate agentless flow `propose -> human-approval-gate -> apply`. The gate requires a **verified** `standards-authoring-approval` trust.bundle claim (`subjectType: "repo-governance-change"`) before `veritas init --apply` writes the derived standards. Veritas derives and writes; the kit gates the human sign-off. See "How to author standards for a repo". |
+| Skill | `skills/standards-authoring/SKILL.md` | Runbook for the standards-authoring flow: runs `veritas init --explore`/`--guided` to derive a recommendation (project name, adaptive Repo Map nodes, evidence-check inference, governance-block splice), surfaces it for human approval, then `veritas init --apply`. Wraps the veritas CLI; reimplements nothing. |
+| Skill | `skills/consult-standards/SKILL.md` | Just-in-time governance guidance before editing: tells an agent to run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, applicable Repo Standards rules (do/don't/examples), and latest surface status, then edit within them. Pull-based advisory — does not block (the PreToolUse hook is enforcement). No MCP server. See "Consulting standards just in time". |
 
 The gate uses provider-neutral Flow vocabulary (`kind: "trust.bundle"`, `bundle_claim`) — the
 same vocabulary `kits/builder/flows/build.flow.json` uses. Veritas is simply the producer that
@@ -46,6 +57,118 @@ flow evaluate readiness --gate gate-check-gate --exit-code
 #    exit 0 when readiness is ready (claim verified); exit 1 (block) otherwise.
 ```
 
+## Scaffolding starter standards
+
+A repo needs a `.veritas/` Repo Standards set before `veritas readiness` can evaluate it. For kit
+users this replaces standalone `veritas init`: the kit declares that starter set as `provisions[]`
+in `kit.json`, and the engine copies it into the repo.
+
+```bash
+# Copy the starter .veritas/ standards into the current repo (create-only; never overwrites).
+flow-agents kit provision veritas-governance
+#   -> .veritas/repo-map.json, .veritas/repo-standards/default.repo-standards.json,
+#      .veritas/authority/default.authority-settings.json, .veritas/GOVERNANCE.md,
+#      .veritas/README.md, veritas.claims.json
+# (flow-agents init --activate-kit veritas-governance provisions the same set at adoption time.)
+
+# Then run readiness against the scaffolded repo.
+veritas readiness --working-tree     # 0 failures on the fresh starter
+```
+
+The provisioned files are a **faithful snapshot of `veritas init`'s Day-0 output** — data the kit
+copies verbatim, not evaluation logic it reimplements. The project name is a `your-project`
+placeholder; edit the Repo Map's work-area graph and `evidence.evidenceChecks[0].command` for your
+repo, then regenerate the claim store with `veritas claim init`.
+
+**Beyond the static starter:** the per-repo *derivation* `veritas init` performs (project-name
+slug, repo-shape-adaptive Repo Map nodes, evidence-check inference) and the *splice* of the
+governance block into an existing `AGENTS.md`/`CLAUDE.md` (a create-only copy cannot edit files in
+place — the starter's `ai-instruction-files-synced` standard reports advisory until those blocks
+are wired) are handled by the **standards-authoring flow** below; repo-hook setup remains #648.
+
+## How to author standards for a repo
+
+Beyond the static starter set, the kit's `standards-authoring` flow drives Veritas's *adaptive*
+authoring — deriving the project name, repo-shape Repo Map nodes, and evidence-check command from
+the actual repo, and splicing the governance block into existing `AGENTS.md`/`CLAUDE.md` (the
+per-repo work a verbatim provision copy cannot do). The `standards-authoring` **skill**
+(`skills/standards-authoring/SKILL.md`) is the operator's runbook; **Veritas does the derivation
+and the write — the kit only gates the human sign-off.**
+
+```bash
+# 1. PROPOSE — derive a recommendation (writes nothing under .veritas/ yet).
+veritas init --explore          # or: veritas init --guided --answers <answers.json>
+
+# 2. APPROVE — a human reviews the recommendation, then authors a Hachure trust.bundle asserting
+#    a standards-authoring-approval / repo-governance-change claim with status verified.
+flow init
+flow start kits/veritas-governance/flows/standards-authoring.flow.json --run-id authoring
+flow attach-evidence authoring --gate human-approval-gate --file approval.bundle --bundle
+flow evaluate authoring --gate human-approval-gate --exit-code
+#    exit 0 once the approval claim is verified; exit 1 (block) otherwise.
+
+# 3. APPLY — only after the gate passes, write the approved standards (hash-verified;
+#    refuses to overwrite existing standards without --force).
+veritas init --apply --plan <path-to-recommendation-artifact>
+```
+
+Like `exemption-issuance`'s gate, "human-approved" here is an **operating convention** the claim
+encodes, not a structural human-only guarantee — see "Human-approval evidence: what is and is not
+enforced" below. This flow is **agentless** (the kit declares no `flow_step_actions`; the approval
+bundle is human-authored out of band, and the skill is the runbook, not a step-bound action). The
+kit **wraps** the `veritas` CLI and reimplements no derivation or evaluation.
+
+## Provisioning the governance hooks
+
+The kit ships the two governance git hooks (`veritas setup repo-hooks`'s static output) as
+`provisions[]`, so kit adoption drops them into the repo alongside the starter standards:
+
+- `.githooks/pre-push` — runs `npm run --if-present prepush` before a push.
+- `.githooks/post-commit` — runs `veritas readiness --changed-from HEAD~1 --changed-to HEAD` after each commit.
+
+```bash
+# 1. Land the hook files (part of `kit provision` / `init --activate-kit`).
+flow-agents kit provision veritas-governance
+
+# 2. ACTIVATE — the two steps a create-only file copy cannot perform:
+chmod +x .githooks/pre-push .githooks/post-commit
+git config core.hooksPath .githooks
+```
+
+**Activation is required and is not a copy.** A provision lands the hook files **non-executable**
+and does not touch git config — so until you `chmod +x` them and point `core.hooksPath` at
+`.githooks`, git will not run them. This is the same class of limitation as the governance-block
+splice above: the engine's file copy is deliberately agent-blind (it never sets an executable bit
+or mutates git config), so making the hooks *active* is an explicit operator step. The hooks
+themselves only **invoke** the `veritas` CLI (`npm run prepush`, `veritas readiness`); the kit
+reimplements no evaluation, and the live per-edit PreToolUse *evaluation* entry point stays in the
+engine (`evaluatePreToolUse` → `evaluateRepoStandards`), reached by the installed hook shelling
+into `veritas` — hook wiring is the kit's; per-edit evaluation is the engine's.
+
+## Consulting standards just in time
+
+The `consult-standards` skill (`skills/consult-standards/SKILL.md`) gives an agent just-in-time
+governance guidance **before** it edits a file, so it shapes the change to pass rather than
+learning about a violation only when the PreToolUse hook blocks the write:
+
+```bash
+veritas explain --file src/path/to/file.ts     # rules that apply to this file
+veritas explain --work-area <work-area-id>      # rules for a whole Repo Map work area
+```
+
+`veritas explain` prints a **`Veritas JIT Context`** briefing — the `.veritas/GOVERNANCE.md`
+excerpt, one block per matching Repo Standard (`Rule`/`Kind`/`Enforcement Level`/`Summary`/
+`Do`/`Do not`/`Good`/`Bad`/`Context`), and the latest recorded surface status for each. The skill
+is **pull-based advisory**: it never blocks (enforcement stays the engine-side PreToolUse hook)
+and reimplements no rule evaluation — `veritas explain` does the matching and projection.
+
+**No MCP server.** Just-in-time guidance here is an agent invoking `veritas explain`, not a
+standing MCP service. Per the flow-agents MCP posture (ADR 0011), MCP never carries the gate and
+enforcement stays hooks; this skill is the deliberate agent-pull replacement for a guidance
+server — the veritas-owned MCP guidance server the migration once imagined was never actually
+built (the `@modelcontextprotocol/sdk` dependency in veritas is only the evidence-check *client*),
+so this slice builds the guidance path new in the kit rather than moving one.
+
 ## How to issue a no-agent-delivery exemption
 
 `flows/exemption-issuance.flow.json` (ADR 0022 §3, "the kit issues, the anchor enforces") gives
@@ -156,13 +279,17 @@ verdict derives `verified` → the gate **passes**.
 
 This matches Veritas's own `readinessHasBlockingFailure` helper (`veritas/src/surface/readiness.mjs`)
 and Surface's weakest-link claim derivation (`buildTrustReport` downgrades a readiness claim to
-`rejected` on any rejected Require). The adapter intentionally does **not** apply Veritas's
-`promotion_allowed` short-circuit — `promotion_allowed` is a workstream-routing hint (set by
-file-pattern lane resolution in `src/repo/routing.mjs`), not a safety signal, and applying it as
-one lets a record with blocking Require failures read as ready. That short-circuit is a filed
-Veritas bug, [kontourai/veritas#106](https://github.com/kontourai/veritas/issues/106), not a
-legitimate alternate reading. Investigation conclusion: the adapter's stricter blocking-failure
-derivation is correct today and will agree with Veritas's own exported functions once #106 lands.
+`rejected` on any rejected Require). The adapter does **not** apply Veritas's `promotion_allowed`
+short-circuit as a safety signal — `promotion_allowed` is a workstream-routing hint (set by
+file-pattern lane resolution in `src/repo/routing.mjs`) and cannot account for blocking failures.
+The historical divergence this guarded against,
+[kontourai/veritas#106](https://github.com/kontourai/veritas/issues/106) (Veritas's exported
+verdict functions honored `promotion_allowed` before checking blocking failures), is **fixed**:
+`readinessVerdict`/`readinessSurfaceStatus` now check `readinessHasBlockingFailure()` first
+(regression-tested in veritas `tests/surface/readiness-verdict.test.mjs`), so the adapter's
+derivation and Veritas's exported functions agree. The adapter keeps its own derivation because
+kit code consumes Veritas's recorded artifact, not Veritas's library exports — that
+blocking-failure semantics is now frozen in veritas's Engine / Surface Seam doc (see above).
 
 ## Trust status
 
@@ -172,9 +299,13 @@ to a later slice (see the WS5 shaping's open decisions).
 
 ## Not in slice 1
 
-Skills `consult-standards` and `governance-evidence`, the fuller `merge-readiness` flow, the
-`standards-authoring` flow, and the `knowledge` dependency are later slices — see the WS5
-backlog. `exemption-usage-review` (ADR 0022 §3's periodic audit skill, walking
+Skills `consult-standards` and `governance-evidence`, the fuller `merge-readiness` flow, and the
+`knowledge` dependency are later slices — see the WS5 backlog. The **starter-standards scaffold**
+(`veritas init`'s Day-0 `.veritas/` set) **has now shipped** as `provisions[]` (see "Scaffolding
+starter standards"), and the **`standards-authoring` flow** that covers the per-repo derivation
+and governance-block splice a static copy cannot **has now shipped** too (see "How to author
+standards for a repo") — both #647 Slice 2; repo-hook setup remains #648.
+`exemption-usage-review` (ADR 0022 §3's periodic audit skill, walking
 `delivery/DECLARED` history and surfacing standing exemptions for owner re-confirmation —
 process visibility, not enforcement) **has now shipped** — see "What it contains" above and
 "How to run the review". Nothing schedules it automatically; an operator runs it periodically

package/dist/pi/kits/veritas-governance/fixtures/standards-authoring/approved.trust-bundle.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 5,
+  "source": "veritas-governance-kit/standards-authoring-fixture",
+  "claims": [
+    {
+      "id": "standards-authoring-fixture.standards-authoring-approval.your-project",
+      "subjectType": "repo-governance-change",
+      "subjectId": "repo:your-project",
+      "facet": "veritas-governance.standards-authoring",
+      "claimType": "standards-authoring-approval",
+      "fieldOrBehavior": "standardsAuthoringApproval",
+      "value": {
+        "recommendation": "veritas init --explore recommendation for your-project",
+        "reason": "human maintainer reviewed the derived starter standards and approved writing them",
+        "approved_by": "eval-fixture-approver"
+      },
+      "createdAt": "2026-07-01T00:00:00Z",
+      "updatedAt": "2026-07-01T00:00:00Z",
+      "impactLevel": "high",
+      "verificationPolicyId": "policy:standards-authoring-approval",
+      "metadata": {
+        "producer": "human-approver",
+        "source": "standards-authoring-fixture"
+      },
+      "status": "verified"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev:standards-authoring-fixture.standards-authoring-approval.your-project",
+      "claimId": "standards-authoring-fixture.standards-authoring-approval.your-project",
+      "evidenceType": "policy_rule",
+      "method": "auditability",
+      "sourceRef": "human-approver:standards-authoring-fixture",
+      "excerptOrSummary": "A human maintainer reviewed the veritas init recommendation and approved authoring the Repo Standards for your-project.",
+      "observedAt": "2026-07-01T00:00:00Z",
+      "collectedBy": "veritas-governance-kit/standards-authoring-fixture",
+      "passing": true
+    }
+  ],
+  "events": [
+    {
+      "id": "evt:standards-authoring-fixture.standards-authoring-approval.your-project",
+      "claimId": "standards-authoring-fixture.standards-authoring-approval.your-project",
+      "status": "verified",
+      "actor": "veritas-governance-kit/standards-authoring-fixture",
+      "method": "auditability",
+      "evidenceIds": [
+        "ev:standards-authoring-fixture.standards-authoring-approval.your-project"
+      ],
+      "createdAt": "2026-07-01T00:00:00Z",
+      "verifiedAt": "2026-07-01T00:00:00Z"
+    }
+  ],
+  "policies": [
+    {
+      "id": "policy:standards-authoring-approval",
+      "claimType": "standards-authoring-approval",
+      "requiredEvidence": [
+        "policy_rule"
+      ],
+      "acceptanceCriteria": [
+        "A human maintainer has reviewed the veritas init recommendation and approved authoring the Repo Standards."
+      ],
+      "reviewAuthority": "human",
+      "validityRule": {
+        "kind": "manual"
+      },
+      "stalenessTriggers": [],
+      "conflictRules": [],
+      "impactLevel": "high"
+    }
+  ]
+}

package/dist/pi/kits/veritas-governance/fixtures/standards-authoring/not-approved.trust-bundle.json

@@ -0,0 +1,74 @@
+{
+  "schemaVersion": 5,
+  "source": "veritas-governance-kit/standards-authoring-fixture",
+  "claims": [
+    {
+      "id": "standards-authoring-fixture.standards-authoring-approval.your-project",
+      "subjectType": "repo-governance-change",
+      "subjectId": "repo:your-project",
+      "facet": "veritas-governance.standards-authoring",
+      "claimType": "standards-authoring-approval",
+      "fieldOrBehavior": "standardsAuthoringApproval",
+      "value": {
+        "recommendation": "veritas init --explore recommendation for your-project",
+        "reason": "human maintainer reviewed the recommendation and did NOT approve authoring",
+        "approved_by": "eval-fixture-approver"
+      },
+      "createdAt": "2026-07-01T00:00:00Z",
+      "updatedAt": "2026-07-01T00:00:00Z",
+      "impactLevel": "high",
+      "verificationPolicyId": "policy:standards-authoring-approval",
+      "metadata": {
+        "producer": "human-approver",
+        "source": "standards-authoring-fixture"
+      },
+      "status": "disputed"
+    }
+  ],
+  "evidence": [
+    {
+      "id": "ev:standards-authoring-fixture.standards-authoring-approval.your-project",
+      "claimId": "standards-authoring-fixture.standards-authoring-approval.your-project",
+      "evidenceType": "policy_rule",
+      "method": "auditability",
+      "sourceRef": "human-approver:standards-authoring-fixture",
+      "excerptOrSummary": "A human maintainer reviewed the veritas init recommendation and approved authoring the Repo Standards for your-project.",
+      "observedAt": "2026-07-01T00:00:00Z",
+      "collectedBy": "veritas-governance-kit/standards-authoring-fixture",
+      "passing": false
+    }
+  ],
+  "events": [
+    {
+      "id": "evt:standards-authoring-fixture.standards-authoring-approval.your-project",
+      "claimId": "standards-authoring-fixture.standards-authoring-approval.your-project",
+      "status": "disputed",
+      "actor": "veritas-governance-kit/standards-authoring-fixture",
+      "method": "auditability",
+      "evidenceIds": [
+        "ev:standards-authoring-fixture.standards-authoring-approval.your-project"
+      ],
+      "createdAt": "2026-07-01T00:00:00Z",
+      "verifiedAt": "2026-07-01T00:00:00Z"
+    }
+  ],
+  "policies": [
+    {
+      "id": "policy:standards-authoring-approval",
+      "claimType": "standards-authoring-approval",
+      "requiredEvidence": [
+        "policy_rule"
+      ],
+      "acceptanceCriteria": [
+        "A human maintainer has reviewed the veritas init recommendation and approved authoring the Repo Standards."
+      ],
+      "reviewAuthority": "human",
+      "validityRule": {
+        "kind": "manual"
+      },
+      "stalenessTriggers": [],
+      "conflictRules": [],
+      "impactLevel": "high"
+    }
+  ]
+}

package/dist/pi/kits/veritas-governance/flows/standards-authoring.flow.json

@@ -0,0 +1,35 @@
+{
+  "id": "veritas-governance.standards-authoring",
+  "version": "1.0",
+  "steps": [
+    { "id": "propose", "next": "apply" },
+    { "id": "apply", "next": null }
+  ],
+  "gates": {
+    "human-approval-gate": {
+      "step": "apply",
+      "expects": [
+        {
+          "id": "standards-authoring-approval",
+          "kind": "trust.bundle",
+          "required": true,
+          "description": "A human maintainer has reviewed the proposed starter Repo Standards (the `veritas init --explore` recommendation: derived project name, adaptive Repo Map nodes, evidence-check inference, and any AGENTS.md/CLAUDE.md governance-block splice) and approved writing them, recorded as a verified standards-authoring-approval trust.bundle claim. Veritas does the derivation; the kit only gates the human sign-off before `veritas init --apply` writes.",
+          "explore_hint": "Run the standards-authoring skill (`veritas init --explore` / `--guided`) to produce a recommendation artifact, have a human approver author a Hachure trust.bundle carrying a standards-authoring-approval / repo-governance-change claim with status verified, then `flow attach-evidence <run> --gate human-approval-gate --file <bundle> --bundle`.",
+          "bundle_claim": {
+            "claimType": "standards-authoring-approval",
+            "subjectType": "repo-governance-change",
+            "accepted_statuses": ["verified"]
+          }
+        }
+      ],
+      "on_route_back": {
+        "missing_evidence": "apply",
+        "default": "apply"
+      },
+      "route_back_policy": {
+        "max_attempts": 3,
+        "on_exceeded": "block"
+      }
+    }
+  }
+}

package/dist/pi/kits/veritas-governance/kit.json

@@ -13,6 +13,11 @@
       "id": "veritas-governance.exemption-issuance",
       "path": "flows/exemption-issuance.flow.json",
       "description": "Agentless K0 flow issuing a delivery/DECLARED no-agent-delivery exemption (ADR 0022 §2/§3): step request -> gate human-approval-gate (requires a verified no-agent-delivery-exemption-approval trust.bundle claim, satisfiable only by a human-authored approval bundle by convention -- see docs/README.md) -> step issue, which appends the approved entry to delivery/DECLARED. CI-callable."
+    },
+    {
+      "id": "veritas-governance.standards-authoring",
+      "path": "flows/standards-authoring.flow.json",
+      "description": "Agentless-gate flow authoring a repo's Veritas Repo Standards: step propose (the standards-authoring skill runs `veritas init --explore`/`--guided` to derive a recommendation) -> gate human-approval-gate (requires a verified standards-authoring-approval / repo-governance-change trust.bundle claim, human-authored by convention) -> step apply (`veritas init --apply` writes the approved standards and splices the governance block). Veritas derives and writes; the kit gates the human sign-off. No evaluation reimplemented."
     }
   ],
   "skills": [
@@ -20,6 +25,16 @@
       "id": "veritas-governance.exemption-usage-review",
       "path": "skills/exemption-usage-review/SKILL.md",
       "description": "Periodic audit skill (ADR 0022 §3): walks delivery/DECLARED + its git log --follow history and reports every standing no-agent-delivery exemption (scope, reason, approver, age since declared_at), flagging entries overdue for owner re-confirmation against a configurable staleness threshold. Process visibility, not enforcement -- read-only, never mutates delivery/DECLARED or scripts/ci/trust-reconcile.js's behavior."
+    },
+    {
+      "id": "veritas-governance.standards-authoring",
+      "path": "skills/standards-authoring/SKILL.md",
+      "description": "Author or re-derive a repo's Veritas Repo Standards by running `veritas init --explore`/`--guided` (adaptive derivation + governance-block splice), surfacing the recommendation for human approval, then `veritas init --apply` once the standards-authoring flow's human-approval gate is satisfied. Wraps the veritas CLI; reimplements no evaluation or derivation. The agent action for both steps of the standards-authoring flow."
+    },
+    {
+      "id": "veritas-governance.consult-standards",
+      "path": "skills/consult-standards/SKILL.md",
+      "description": "Just-in-time governance guidance before editing: run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, the Repo Standards rules that apply, their do/don't/examples, and the latest surface status, then edit within those rules. Pull-based advisory (does not block; the PreToolUse hook is enforcement). No MCP server -- the agent-pull replacement for a guidance server (ADR 0011). Wraps the veritas CLI; reimplements no evaluation."
     }
   ],
   "assets": [
@@ -31,5 +46,55 @@
   ],
   "docs": [
     { "id": "veritas-governance.readme", "path": "docs/README.md" }
+  ],
+  "provisions": [
+    {
+      "id": "veritas-governance.starter-repo-map",
+      "path": "assets/starter-standards/veritas/repo-map.json",
+      "target": ".veritas/repo-map.json",
+      "description": "Starter Repo Map (from `veritas init`): work-area graph plus the `evidence.evidenceChecks` entry `veritas readiness` requires. Placeholder project name `your-project`; adopters edit for their repo shape and evidence-check command."
+    },
+    {
+      "id": "veritas-governance.starter-repo-standards",
+      "path": "assets/starter-standards/veritas/repo-standards/default.repo-standards.json",
+      "target": ".veritas/repo-standards/default.repo-standards.json",
+      "description": "Starter Repo Standards (from `veritas init`): the baseline required-artifacts / instruction-files-synced / routed-delivery rules the engine evaluates. Additive Standards Growth is expected on top."
+    },
+    {
+      "id": "veritas-governance.starter-authority-settings",
+      "path": "assets/starter-standards/veritas/authority/default.authority-settings.json",
+      "target": ".veritas/authority/default.authority-settings.json",
+      "description": "Starter authority settings (from `veritas init`): promotion preferences and attestation thresholds; keeps the readiness attestation-gate section clean before a bootstrap attestation is recorded."
+    },
+    {
+      "id": "veritas-governance.starter-governance",
+      "path": "assets/starter-standards/veritas/GOVERNANCE.md",
+      "target": ".veritas/GOVERNANCE.md",
+      "description": "Terse agent-facing governance instructions (from `veritas init`): names the Protected Standards and the attestation requirement. Static; no per-repo derivation."
+    },
+    {
+      "id": "veritas-governance.starter-readme",
+      "path": "assets/starter-standards/veritas/README.md",
+      "target": ".veritas/README.md",
+      "description": "Human-facing `.veritas/` orientation doc (from `veritas init`)."
+    },
+    {
+      "id": "veritas-governance.starter-claims",
+      "path": "assets/starter-standards/veritas.claims.json",
+      "target": "veritas.claims.json",
+      "description": "Starter Veritas claim store (from `veritas init`): the baseline surface claims the starter Repo Standards require to be present. A snapshot starting point; regenerate with `veritas claim init` once the Repo Map is customized."
+    },
+    {
+      "id": "veritas-governance.githook-pre-push",
+      "path": "assets/starter-hooks/githooks/pre-push",
+      "target": ".githooks/pre-push",
+      "description": "Governance pre-push git hook (from `veritas setup repo-hooks`): runs `npm run --if-present prepush` before a push. Static template. Landed non-executable — see \"Provisioning the governance hooks\" for the chmod + core.hooksPath activation a file copy cannot perform."
+    },
+    {
+      "id": "veritas-governance.githook-post-commit",
+      "path": "assets/starter-hooks/githooks/post-commit",
+      "target": ".githooks/post-commit",
+      "description": "Governance post-commit git hook (from `veritas setup repo-hooks`): runs `veritas readiness --changed-from HEAD~1 --changed-to HEAD` after each commit. Static template. Landed non-executable — see \"Provisioning the governance hooks\" for activation."
+    }
   ]
 }

package/dist/pi/kits/veritas-governance/skills/consult-standards/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: "consult-standards"
+description: "Get just-in-time Veritas governance guidance for a file or work area before editing it: run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, the Repo Standards rules that apply, their do/don't/examples, and the latest recorded surface status — then edit within those rules. Use before changing a governed repo's files, or when you want to know what standards apply to a path. Pull-based guidance; it does not block (the PreToolUse hook is the enforcement gate)."
+---
+
+# Consult Standards
+
+Before you edit a file in a Veritas-governed repo, ask Veritas what applies to it. `veritas
+explain` projects the repo's governance excerpt + the Repo Standards rules matching that file (or
+work area) + their latest surface status into one just-in-time briefing — so you edit *within* the
+rules instead of discovering a violation only when the PreToolUse hook blocks the write.
+
+**This skill wraps the `veritas` CLI. It reimplements no rule evaluation** — `veritas explain`
+does the matching and projection; the skill only tells you when and how to ask.
+
+## When to use this
+
+- **Before editing** a file in a repo that has a `.veritas/` governance config — especially a
+  file under a governed work area, or one you haven't touched before.
+- **When you want to know what standards apply** to a path or area without reading every rule in
+  `.veritas/repo-standards/` yourself.
+- Not a gate: this is **pull-based** guidance you invoke. Enforcement is separate and automatic —
+  the Veritas PreToolUse hook (engine-side; installed via the kit's governance hooks) evaluates
+  and can *block* a non-conforming write whether or not you consulted first. Consulting first
+  means you shape the edit to pass, rather than getting blocked and retrying.
+
+## How to consult
+
+```bash
+# For a specific file you're about to change:
+veritas explain --file src/path/to/file.ts
+
+# For a whole work area (a Repo Map graph node id):
+veritas explain --work-area <work-area-id>
+
+# Or pass a bare selector (auto-classified as a rule id, a file path if it contains '/', or a work-area token):
+veritas explain src/path/to/file.ts
+```
+
+`veritas explain` prints a **`Veritas JIT Context`** briefing:
+
+- **`Governance:`** — the leading lines of `.veritas/GOVERNANCE.md` (the repo's terse governance rules).
+- One block per **matching rule**: `Rule` / `Kind` / `Enforcement Level` (`Require` / `Guide` / …) /
+  `Summary` / `Do` / `Do not` / `Good` / `Bad` / `Context`.
+- **`Surface status:`** — the latest recorded status for that rule from the evidence artifacts
+  (e.g. `verified`), plus any `Surface fault:` transparency-gap lines.
+
+Read the matching rules, honor their `Do`/`Do not`, and keep the change inside the work area's
+guidance. `No matching requirement found.` means no additional Repo Standard applies to that path
+— proceed normally, it is not an error.
+
+## Source of truth
+
+`veritas explain` is a *projection* of the repo's own governance config. When you want the raw
+standards rather than the filtered view, read them directly — they are the source `explain` reads:
+
+- `.veritas/GOVERNANCE.md` — the terse agent-facing governance rules.
+- `.veritas/repo-standards/*.json` — the Repo Standards (each rule's `summary` / `mustDo` /
+  `mustNotDo` / `exampleGood` / `exampleBad` / `contextLinks`).
+- `.veritas/repo-map.json` — the work-area graph `--work-area` selects against.
+
+## Contract
+
+- **Read-only advisory.** This skill runs `veritas explain`, which reads config and evidence and
+  writes nothing. It never gates, never blocks, never attaches evidence, and has no pass/fail
+  verdict — it surfaces guidance, full stop. Enforcement stays the PreToolUse hook (engine-side).
+- **No MCP server.** Just-in-time guidance here is agent-invoked CLI (`veritas explain`), not a
+  standing MCP service. Per the flow-agents MCP posture (ADR 0011), MCP never carries the gate and
+  enforcement stays hooks; this skill is the deliberate agent-pull replacement for a guidance
+  server, not a new server.
+- **Wraps the engine; reimplements nothing.** All rule matching, governance projection, and
+  surface-status lookup live in `@kontourai/veritas` (`veritas explain` / `src/explain.mjs`). The
+  skill adds no evaluation logic.

package/dist/pi/kits/veritas-governance/skills/standards-authoring/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: "standards-authoring"
+description: "Author or update a repo's Veritas Repo Standards through the kit's standards-authoring flow: run `veritas init --explore`/`--guided` to derive a proposed starter set (project name, repo-shape-adaptive Repo Map nodes, evidence-check inference, and the AGENTS.md/CLAUDE.md governance-block splice), surface it for human approval, then `veritas init --apply` once a human-approved standards-authoring-approval trust.bundle claim satisfies the flow's human-approval gate. Use when adopting Veritas governance in a repo or re-deriving standards after its shape changes — beyond the static starter set `kit provision` scaffolds."
+---
+
+# Standards Authoring
+
+Derive a repo's Veritas Repo Standards, get a human to approve them, then write them — the
+authoring UX `veritas init` provides, driven through the kit's `standards-authoring` flow so
+the write is human-gated.
+
+**Veritas does the derivation and the write; this skill only invokes the `veritas` CLI and
+surfaces its recommendation for approval.** No standards evaluation, derivation, or splice
+logic is reimplemented here (kit non-goal: never fork or reimplement Veritas).
+
+## When to use this vs. `kit provision`
+
+- **`flow-agents kit provision veritas-governance`** copies a *static* starter `.veritas/` set
+  (placeholder project name, generic nodes) — fastest path to a repo that runs
+  `veritas readiness`. See the kit README's "Scaffolding starter standards".
+- **This skill** runs Veritas's *adaptive* authoring: it derives the project name, Repo Map
+  work-area nodes, and evidence-check command from the actual repo, and splices the governance
+  block into existing `AGENTS.md`/`CLAUDE.md` — the per-repo work a verbatim file copy cannot
+  do. Use it to author standards for real, or to re-derive after the repo's shape changes.
+
+## Flow binding
+
+This skill documents how to drive `flows/standards-authoring.flow.json` — a two-step
+**agentless-gate** flow `propose -> apply` with one gate (the kit declares no
+`flow_step_actions`; like `exemption-issuance`, the human produces the gate's approval bundle
+out of band, and this skill is the operator's runbook, not a step-bound action):
+
+- `human-approval-gate` (on `apply`) requires a **verified** `standards-authoring-approval`
+  trust.bundle claim (`subjectType: "repo-governance-change"`) before the apply write is
+  flow-sanctioned.
+
+As with `exemption-issuance`'s `human-approval-gate`, "human-approved" is an **operating
+convention** the gate's claim encodes, not a structural human-only guarantee — Flow's schema
+does not distinguish a human-authored bundle from an agent-authored one (see the kit README's
+"Human-approval evidence: what is and is not enforced"). The gate adds a named claim, a
+documented sequence, and an audit trail on top of the same mitigation `veritas init --apply`
+already carries (it refuses to overwrite existing standards without `--force`).
+
+## Sequence
+
+```bash
+# 1. PROPOSE — derive a recommendation without writing anything.
+veritas init --explore
+#    (or `veritas init --guided --answers <answers.json>` for owner Q&A)
+#    -> writes a hash-pinned recommendation artifact (schema_version, project_name,
+#       repo_insights, artifact_payloads incl. AGENTS.md/CLAUDE.md governance blocks,
+#       artifact_hashes, recommended_repo_map/standards/authority, owner_questions,
+#       reasoning_summary, apply_command). Nothing under .veritas/ is written yet.
+
+# 2. APPROVE — a human reviews the recommendation (its reasoning_summary and owner_questions),
+#    then authors a Hachure trust.bundle asserting the approval:
+#      claimType: "standards-authoring-approval", subjectType: "repo-governance-change",
+#      status: "verified".
+flow init
+flow start kits/veritas-governance/flows/standards-authoring.flow.json --run-id authoring
+flow attach-evidence authoring --gate human-approval-gate --file approval.bundle --bundle
+flow evaluate authoring --gate human-approval-gate --exit-code
+#    exit 0 once the approval claim is verified; exit 1 (block) otherwise.
+
+# 3. APPLY — only after the gate passes, write the approved recommendation.
+veritas init --apply --plan <path-to-recommendation-artifact>
+#    -> validates each artifact_hashes[path] === sha256(payload) (tamper/staleness check
+#       between propose and apply), refuses to overwrite existing starter files without
+#       --force, then writes .veritas/* and splices the governance block into the selected
+#       instruction files.
+```
+
+## Contract
+
+- **Wraps the `veritas` CLI; reimplements nothing.** Project-name derivation, adaptive Repo Map
+  nodes, evidence-check inference, and the governance-block splice all live inside `veritas`
+  (`veritas init` / `src/bootstrap/*` / `src/governance.mjs`). This skill invokes and surfaces;
+  it does not compute standards.
+- **The write is human-gated by convention, not structurally.** The flow's
+  `standards-authoring-approval` claim is the sign-off record; anyone who can
+  `flow attach-evidence --bundle` a conforming claim satisfies it. Read a passing gate as "a
+  verified approval claim of the right shape was attached," not as proof a human attached it.
+- **`veritas init --apply` is create-safe by default:** it refuses to overwrite existing
+  `.veritas/` standards without `--force`. Re-authoring an already-governed repo is therefore an
+  explicit, opt-in action — the skill never silently replaces standards.
+- **No engine dependency, no evaluation.** Nothing here runs or reimplements `veritas readiness`;
+  that stays the `readiness-check` flow's concern.

package/dist/pi/schemas/backlog-provider-settings.schema.json

@@ -103,7 +103,7 @@
             "ready_statuses": { "type": "array", "items": { "enum": ["todo", "ready"] } },
             "exclude_statuses": {
               "type": "array",
-              "items": { "enum": ["in_progress", "blocked", "review", "verification", "done"] }
+              "items": { "enum": ["triage", "in_progress", "blocked", "review", "verification", "done"] }
             }
           }
         },