@kontourai/flow-agents 4.0.0 → 4.1.0

package/dist/pi/schemas/workflow-waves.schema.json

@@ -0,0 +1,347 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://flow-agents.dev/schemas/workflow-waves.schema.json",
+  "title": "Flow Agents Workflow Waves",
+  "description": "Fan-out wave manifest for a workflow session. Each wave declares its expected workers (M) before dispatch; every worker lands exactly one terminal status record; the orchestrator reconciles worker_results against expected_workers at wave close and records an explicit 'N of M reported' reconciliation. A worker that never reported is recorded as not_reported — visible data, never silently absorbed. This sidecar is additive: a session without waves.json declares no fan-out and is unaffected.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "task_slug",
+    "waves"
+  ],
+  "$defs": {
+    "evidence_ref": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "source",
+            "command",
+            "artifact",
+            "provider",
+            "external"
+          ]
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "file": {
+          "type": "string",
+          "minLength": 1
+        },
+        "line_start": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "line_end": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "excerpt": {
+          "type": "string",
+          "minLength": 1
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "source"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "file",
+              "line_start",
+              "line_end",
+              "excerpt"
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "artifact"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "allOf": [
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "file"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "url"
+                    ]
+                  }
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "type": "object",
+                    "required": [
+                      "summary"
+                    ]
+                  },
+                  {
+                    "type": "object",
+                    "required": [
+                      "excerpt"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "const": "command"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "type": "object",
+                "required": [
+                  "excerpt"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "summary"
+                ]
+              },
+              {
+                "type": "object",
+                "required": [
+                  "url"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "type": "object",
+            "properties": {
+              "kind": {
+                "enum": [
+                  "provider",
+                  "external"
+                ]
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "url"
+            ]
+          }
+        }
+      ]
+    },
+    "expected_worker": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "task"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "task": {
+          "type": "string",
+          "minLength": 1
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1
+        },
+        "owned_files": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
+    },
+    "worker_result": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "worker_id",
+        "status",
+        "summary",
+        "recorded_at"
+      ],
+      "properties": {
+        "worker_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "type": "string",
+          "enum": [
+            "completed",
+            "failed",
+            "blocked",
+            "not_reported"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "recorded_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "evidence_refs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/evidence_ref"
+          }
+        }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "expected_count",
+        "reported_count",
+        "summary",
+        "reconciled_at"
+      ],
+      "properties": {
+        "status": {
+          "type": "string",
+          "enum": [
+            "complete",
+            "incomplete"
+          ]
+        },
+        "expected_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "reported_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "reconciled_at": {
+          "type": "string",
+          "format": "date-time"
+        }
+      }
+    },
+    "wave": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "wave_id",
+        "step",
+        "declared_at",
+        "expected_workers"
+      ],
+      "properties": {
+        "wave_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "step": {
+          "type": "string",
+          "minLength": 1
+        },
+        "declared_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expected_workers": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/expected_worker"
+          }
+        },
+        "worker_results": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/worker_result"
+          }
+        },
+        "reconciliation": {
+          "$ref": "#/$defs/reconciliation"
+        }
+      }
+    }
+  },
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "task_slug": {
+      "type": "string",
+      "minLength": 1
+    },
+    "waves": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/wave"
+      }
+    }
+  }
+}

package/dist/pi/scripts/check-layer-boundary.mjs

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * check-layer-boundary — kit/engine layer-doctrine ratchet.
+ *
+ * Doctrine (veritas docs/architecture/engine-surface-seam.md, Invariant 3; ADR 0008/0016):
+ * kits distribute by copy/activate/CLI and consume a product engine via CLI + artifacts, NEVER
+ * as an npm library import. A kit that `import`s the veritas evaluation engine would fork the
+ * layer boundary — the kit must wrap the engine's CLI, not link its code. This is the executable
+ * enforcement of that invariant (flow-agents#651).
+ *
+ * FAILS if any tracked file under kits/ imports `@kontourai/veritas` (or its `/engine` subpath),
+ * or if any kit.json declares it as a dependency. The kit's trust-bundle adapter may import
+ * `@kontourai/surface` (the open trust format, Layer 3) — that is the sanctioned channel and is
+ * NOT matched here. No allowlist: the count is zero today and must stay zero.
+ *
+ * Not a violation (and not matched — import-syntax-scoped): the many descriptive strings naming
+ * "@kontourai/veritas" in kit.json descriptions, docs, and recorded CLI-output fixtures are prose
+ * and data, not code imports.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+
+// Match import/require/dynamic-import of the veritas package (root or /engine subpath) only, so
+// prose/fixture mentions of the package name can never trip it — only an actual code link does.
+const PKG = String.raw`@kontourai/veritas(?:/[A-Za-z0-9_./-]+)?`;
+const IMPORT_PATTERNS = [
+  new RegExp(String.raw`from\s+['"](?:${PKG})['"]`),
+  new RegExp(String.raw`require(?:\.resolve)?\(\s*['"](?:${PKG})['"]\s*\)`),
+  new RegExp(String.raw`import\(\s*['"](?:${PKG})['"]\s*\)`),
+];
+const SOURCE_EXT = /\.(ts|tsx|mjs|cjs|js|jsx)$/;
+
+// Strip comments so an import-SHAPED example inside a doc comment (e.g. a JSDoc `* import ...`
+// line) is not a false positive. A real import statement never starts a line with `//` or `*`,
+// so this only removes prose, never a genuine dependency edge. (Line-scoped — not a full parser;
+// a package name inside a string literal remains matchable, which is intentional.)
+function codeOnly(line) {
+  const trimmed = line.trimStart();
+  if (trimmed.startsWith("//") || trimmed.startsWith("*") || trimmed.startsWith("/*")) return "";
+  return line.replace(/\/\*.*?\*\//g, "").replace(/\/\/.*$/, "");
+}
+
+function trackedFiles(dir) {
+  return execFileSync("git", ["ls-files", dir], { encoding: "utf8" })
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+const violations = [];
+
+// 1. Source imports under kits/.
+for (const file of trackedFiles("kits").filter((f) => SOURCE_EXT.test(f))) {
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch {
+    continue;
+  }
+  text.split("\n").forEach((line, index) => {
+    if (IMPORT_PATTERNS.some((re) => re.test(codeOnly(line)))) {
+      violations.push(`${file}:${index + 1}  imports @kontourai/veritas — kits wrap the engine via CLI, not as a library`);
+    }
+  });
+}
+
+// 2. kit.json dependency declarations.
+for (const file of trackedFiles("kits").filter((f) => f.endsWith("kit.json"))) {
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    continue;
+  }
+  for (const field of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+    const decl = manifest[field];
+    if (decl && typeof decl === "object" && !Array.isArray(decl)) {
+      for (const name of ["@kontourai/veritas"]) {
+        if (Object.prototype.hasOwnProperty.call(decl, name)) {
+          violations.push(`${file} ${field}.${name} — a kit must not declare the engine as an npm dependency`);
+        }
+      }
+    }
+  }
+}
+
+if (violations.length) {
+  console.error("[check-layer-boundary] FAILED — a kit imports/depends on the veritas engine as a library (engine/surface seam, Invariant 3):");
+  for (const v of violations) console.error(`  ${v}`);
+  console.error(
+    "\nKits distribute by copy/activate/CLI and consume the engine via its CLI + recorded artifacts,\n" +
+      "never as an npm library import. The trust-bundle adapter may import @kontourai/surface (the open\n" +
+      "trust format); it must not import @kontourai/veritas. See veritas docs/architecture/engine-surface-seam.md.",
+  );
+  process.exitCode = 1;
+} else {
+  console.log("[check-layer-boundary] OK — no kit imports or declares the veritas engine as a library.");
+}

package/docs/adr/0023-kit-provisioning.md

@@ -0,0 +1,47 @@
+---
+title: "ADR 0023: Declarative Kit Provisioning"
+---
+
+# ADR 0023: Declarative Kit Provisioning
+
+**Date:** 2026-07-16
+**Status:** Accepted (owner-ratified Option A in flow-agents#647)
+
+---
+
+## Context
+
+Kits sometimes need to supply repository-owned configuration or policy files in addition to runtime projections. The motivating `veritas-governance` follow-up needs this capability, but embedding kit-specific copy logic in Flow Agents would violate the kit boundary. Runtime activation is also the wrong mechanism: its projection directory is regenerable adapter state, while these files must become normal files in the consumer repository.
+
+## Decision
+
+A kit may declare a `provisions` list in `kit.json`. Each entry is inert data naming an id, a source file inside the kit, and a consumer-repository-relative target. Provision declarations are never executed.
+
+The Flow Agents engine performs agent-blind file copying through an explicit `kit provision` operation. It validates source and target containment, preflights every destination, and creates files only when no declared destination already exists. An explicit `--force` option may replace declared destination files; the default never silently overwrites an anchor-owned or consumer-owned file. `--dry-run` reports the plan without writing.
+
+`flow-agents init --activate-kit` invokes the same engine after activation with create-only semantics. Existing destinations are reported as skipped warnings so init remains safe to rerun. Provisioning remains separate from runtime activation and its projection directory.
+
+The engine records successful copies under `.kontourai/flow-agents/provisions/<kit-id>.json`. This manifest is bookkeeping and may be replaced on a later successful provisioning operation. Enforcement policy and ownership of protected paths remain anchor-side; a kit declaration does not grant permission to overwrite them.
+
+## Consequences
+
+- Kits can ship repository files without executable installers or kit-specific engine behavior.
+- Create-only defaults preserve consumer and anchor ownership; replacement requires an explicit user operation.
+- Provisioned files belong to the consumer repository once written. Uninstalling or deactivating a kit never removes or reverts them.
+- Runtime adapters continue to activate only their supported projection assets and report provisions as explicitly skipped.
+- Consumers that need stronger protected-path policy enforce it at their anchor; the generic engine remains deliberately dumb and kit-neutral.
+
+## Accepted residuals
+
+- **Copy is best-effort against concurrent interposition (both ends).** The checks and the copy
+  are separate steps (check-then-act): a file created into a declared destination between the
+  conflict preflight and the write can still be overwritten, and a source re-pointed to a link
+  between its containment check and its read could resolve elsewhere. Provisioning targets a
+  developer/CI working tree, not a hostile multi-writer path, so both TOCTOU windows are accepted
+  rather than closed with exclusive-create / open-then-fstat plumbing. The static guarantees are
+  enforced up front: reserved-directory (`.git`, the provision manifest namespace), source and
+  destination containment (link-resolved), and case-fold collision rejection; concurrent
+  interposition on either end is out of scope.
+- **Target case-folding assumes the common single-case-family repo.** Collision and reserved-path
+  checks case-fold targets so case-insensitive filesystems are safe; a genuinely case-sensitive
+  repo that intends two targets differing only in case is rejected as a portability hazard.

package/docs/adr/index.md

@@ -32,3 +32,4 @@ Numbered ADRs below are FROZEN immutable history (see the banner on each file).
 | 0020 | Trust-Reconcile Manifest, Claim Classification, and Waivers | unknown | [0020-trust-reconcile-manifest-and-claim-classification.md](./0020-trust-reconcile-manifest-and-claim-classification.md) |
 | 0021 | Assignment Leases and Stale-Claim Takeover | 2026-07-02 | [0021-assignment-leases-and-stale-claim-takeover.md](./0021-assignment-leases-and-stale-claim-takeover.md) |
 | 0022 | Fail-Closed Delivery Reconciliation with Governed Exemptions | 2026-07-02 | [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](./0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md) |
+| 0023 | Declarative Kit Provisioning | 2026-07-16 | [0023-kit-provisioning.md](./0023-kit-provisioning.md) |

package/docs/architecture-engine-and-kits.md

@@ -102,9 +102,26 @@ Kit trust is orthogonal to engine privilege. A marketplace may call a kit offici
 
 The answer is determined by validation, activation, and gate evidence, not by a privileged kit list.
 
+## The Portfolio Layer Doctrine
+
+The engine/kits split here is Flow Agents' instance of the portfolio-wide **Layer Doctrine**
+([surface/docs/architecture/portfolio-layer-doctrine.md](https://github.com/kontourai/surface/blob/main/docs/architecture/portfolio-layer-doctrine.md)):
+dependency direction is one-way up the stack (open trust format → building-block tools → Surface →
+products), and no layer reaches sideways into a peer. A product engine (e.g. `@kontourai/veritas`)
+never depends on the platform, and a **kit consumes an engine only through its CLI + recorded
+artifacts, never as an npm library import** — the whole point of the manifest/catalog model above.
+Both edges are now enforced executably: veritas-side by `check-no-flow-agents-dep.mjs` (the engine
+declares no flow-agents dependency) and here by [`scripts/check-layer-boundary.mjs`](../scripts/check-layer-boundary.mjs)
+(no kit imports the veritas engine as a library). See veritas's
+[Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md)
+for the canonical engine-vs-kit capability inventory that the Veritas Governance Kit row above
+builds on.
+
 ## Related docs
 
 - [Flow Kit Authoring Guide](kit-authoring-guide.md)
 - [Flow Kit Repository Contract](flow-kit-repository-contract.md)
 - [Runtime Hook Surface spec](spec/runtime-hook-surface.md)
 - [Verifiable Trust](verifiable-trust.md)
+- [Veritas Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md) — how `@kontourai/veritas` splits into an engine library + the kit-owned product surface
+- [Portfolio Layer Doctrine](https://github.com/kontourai/surface/blob/main/docs/architecture/portfolio-layer-doctrine.md)

package/docs/context-map.md

@@ -71,6 +71,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | workflow-learning.schema.json | Flow Agents Workflow Learning | https://flow-agents.dev/schemas/workflow-learning.schema.json |
 | workflow-release.schema.json | Flow Agents Workflow Release Readiness | https://flow-agents.dev/schemas/workflow-release.schema.json |
 | workflow-state.schema.json | Flow Agents Workflow State | https://flow-agents.dev/schemas/workflow-state.schema.json |
+| workflow-waves.schema.json | Flow Agents Workflow Waves | https://flow-agents.dev/schemas/workflow-waves.schema.json |
 
 Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validation, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`. The package-internal writer is not an agent or consumer interface.
 
@@ -100,6 +101,7 @@ Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validatio
 | agentic-engineering | skills/agentic-engineering/SKILL.md | Eval-first execution, task decomposition, and cost-aware model routing for AI-driven development workflows. |
 | browser-test | skills/browser-test/SKILL.md | Headless browser automation via Playwright — screenshots, accessibility checks, form filling, UI testing, DOM inspection. |
 | builder-shape | kits/builder/skills/builder-shape/SKILL.md | Builder Kit shaping entrypoint. Turns a raw idea into a provider-neutral, reviewable backlog proposal and stops before build selection unless the user explicitly continues. |
+| consult-standards | kits/veritas-governance/skills/consult-standards/SKILL.md | 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/exampl... |
 | dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
 | design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probe for turning unclear goals, designs, and handoffs into shared understanding. |
 | eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
@@ -108,6 +110,7 @@ Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validatio
 | knowledge-capture | kits/knowledge/skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
 | pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Provider-grounded pickup probe used at the Builder design-probe step before planning. |
 | search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
+| standards-authoring | kits/veritas-governance/skills/standards-authoring/SKILL.md | 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 infer... |
 
 ## Agents
 

package/docs/decisions/backlog-readiness-source.md

@@ -0,0 +1,89 @@
+---
+status: current
+subject: Backlog Readiness Source
+decided: 2026-07-16
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/441
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/449
+  - kind: commit
+    ref: c19c3e64a214be7d5b2585004fd3c4f2597781e5
+  - kind: url
+    ref: https://claude.ai/code/session_01SmQYjiUo1aDSXgEKyiye7M
+---
+
+# Backlog Readiness Source
+
+Which signal marks a Work Item intentionally ready for pickup, and what
+`pull-work` is allowed to do when that signal yields nothing.
+
+## Decision
+
+- **The org project board is the readiness source.** The configured
+  BoardProvider — org GitHub Project `kontourai/1` ("Flow Agents Builder
+  Platform") — carries readiness as board Status. `ready_statuses=["ready"]`
+  is the pickup filter; the board's `Priority` field ranks the cross-repo
+  ready queue.
+- **Triage is the automated intake status.** Every new `kontourai/*` issue is
+  added to the board with Status=Triage by the shared reusable workflow
+  (`kontourai/.github` `add-issue-to-project.yml`, called per-repo from
+  `.github/workflows/add-to-project.yml`); closing an issue moves it to Done.
+  Nothing reaches Ready automatically.
+- **The Triage → Ready move is the intentionality act.** Moving an item to
+  Ready (and setting Priority) is the triage responsibility that makes work
+  eligible for agent pickup. This is a deliberate human/triage-pass decision,
+  not automation.
+- **A configured readiness source that yields nothing is a surfaced warning,
+  never a silent fallback.** The board reader emits `zero_ready_items` when
+  the configured board produces an empty ready queue (landed with PR #449),
+  and the issue-listing path emits `board_provider_bypassed` whenever a
+  BoardProvider is configured but issue-level listing is used instead.
+  `pull-work` must carry these warnings into its artifact and route to
+  triage/intake rather than silently substituting unranked issue listing.
+- The settings contract declares the real board taxonomy: the schema's
+  `exclude_statuses` vocabulary includes `triage`, and this repo's settings
+  exclude `triage` explicitly. `verification` remains in the schema vocabulary
+  for provider-neutral shapes even though this board has no such column.
+
+## Evidence basis (re-verified live, 2026-07-16)
+
+Issue #441 was shaped on 2026-07-06 evidence that the board was dead (15
+items, all Done, no automation). That premise is now false:
+
+- The kontourai org has exactly **one** ProjectV2: `kontourai/1`, open, **468
+  items** (306 Triage / 14 Ready / 148 Done) spanning 13 repos; 169 of 171
+  open flow-agents issues are on it.
+- The auto-add workflow targets exactly this project
+  (`PVT_kwDOEJYCKs4BYzgP`), Status field options: Triage, Ready, In Progress,
+  Blocked, Review, Done.
+- A live board-driven `pull-work` read returns a **14-item priority-ranked
+  cross-repo ready queue** with zero warnings and zero intake gaps.
+- The agent-path `gh` token carries the `project` scope, so the read:project
+  friction recorded in #441 no longer holds.
+
+## Rejected alternative
+
+**Label-based readiness (per-repo `ready`/`blocked`/`in-progress` labels).**
+Recommended by #441 when the board was dead, because it needed no board
+maintenance and no extra token scope. Both advantages evaporated once the
+auto-add automation went live org-wide and the agent token gained `project`
+scope — and labels cannot express cross-repo priority ranking without
+inventing a parallel convention per repo. Revisit trigger: if the auto-add
+workflow or `project` token scope regresses for agent environments, reopen
+this subject rather than quietly re-deriving readiness from labels.
+
+## Follow-ups (owned elsewhere, not absorbed here)
+
+- **One-time triage sweep** of the ~306 Triage items (and any open issues
+  missing from the board) to assign Ready/Priority intentionally — owned by
+  the triage pass in #443 item 2. Not executed with this decision: the Ready
+  set was already non-empty (14 items), and bulk-moving 300+ items without
+  the accepted mechanism would manufacture fake intentionality.
+- **Board maintenance as flow responsibility** (intake adds, claim → In
+  Progress, completion Done assertion): #443.
+- **Doctor board-health checks** (configured-but-unfed board, dead readiness
+  source, missing token scope): #443 item 5 / #321. Until that surface
+  exists, the warnings live in `pull-work` provider output and the
+  `pull-work` skill contract only.
+- **Workspace-scoped pull-work** across multiple repos: #444.

package/docs/decisions/index.md

@@ -12,6 +12,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | --- | --- | --- |
 | [agent-coordination](./agent-coordination.md) | current | Agent coordination |
 | [anti-gaming-trust-security](./anti-gaming-trust-security.md) | needs-decision | Anti-gaming trust security |
+| [backlog-readiness-source](./backlog-readiness-source.md) | current | Backlog Readiness Source |
 | [context-lifecycle](./context-lifecycle.md) | needs-decision | Context lifecycle |
 | [core-domain-kit-boundary](./core-domain-kit-boundary.md) | needs-decision | Core vs domain kit boundary |
 | [decision-records](./decision-records.md) | current | Decision records |