@kontourai/flow-agents 1.3.0 → 2.0.0

package/kits/builder/skills/pickup-probe/SKILL.md

@@ -84,6 +84,35 @@ Planning is ready only when:
 - The route reason and next action are recorded in an artifact that can be recovered without chat memory.
 
 If the gate fails, stop before `plan-work` and update the artifact with the blocker or decision gap.
+## Gate Claims: Record Pickup Probe Results
+
+When the Planning Gate passes, record the two gate claims for the Builder Kit `design-probe` step before handing off to `plan-work`. These satisfy the `builder.design-probe.pickup-readiness` and `builder.design-probe.decisions` gate expectations.
+
+**Claim 1 — Pickup readiness** (probe passed, goal fit and scope confirmed):
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation pickup-probe-readiness \
+  --status pass \
+  --summary "Pickup probe passed: goal fit confirmed, blockers checked, dependencies reviewed, acceptance criteria verified." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact recording probe status, scope, and planning readiness."}'
+```
+
+**Claim 2 — Probe decisions captured** (decisions, accepted gaps, and planning readiness are recorded):
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation probe-decisions-or-accepted-gaps \
+  --status pass \
+  --summary "Probe decisions recorded: <decision-count> decisions, <gap-count> accepted gaps. Planning readiness: <ready|accepted_gap_ready>." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with decisions, accepted gaps, and planning handoff."}'
+```
+
+Record both claims together immediately when the gate passes. Use `--status fail` when the gate fails (unresolved blocker or decision gap). Use `--status not_verified` only when the session has no active flow step.
+
+When the gate fails, record `--status fail` with `--expectation pickup-probe-readiness` naming the blocker, and omit or defer the decisions claim until the blocker is resolved.
+
+
 
 ## Docs And ADR Policy
 

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

@@ -33,7 +33,18 @@ Before delegating to tool-planner, check if the goal can be solved with existing
 2. If the goal involves adding new capabilities, invoke the search-first skill
 3. Pass research findings to tool-planner as additional context
 
-Skip this step if the goal is purely about modifying existing code (bug fixes, refactors).
+**Survey existing concepts before designing new ones.** Before the plan introduces a new
+artifact, schema, type, data shape, status, or derivation/algorithm, check what the project's
+**dependencies and contracts already define** — not just the local codebase. Inspect exported
+types, schemas, and builders from dependencies (e.g. `@kontourai/*` packages and vendored
+schemas) and the resource/data contracts under `context/contracts/`. Prefer **consuming the
+canonical concept over inventing a parallel one**: follow existing patterns, understand the
+dependency surface, and leverage existing concepts. If a planned shape resembles a dependency's
+existing concept, consume theirs and record which one. This operationalizes the consume-never-fork
+guardrail of ADR 0008 and ADR 0010 at planning time — the cheapest place to catch a fork.
+
+Skip the codebase-similarity search for pure bug-fix/refactor goals, but still apply the
+survey-existing-concepts check whenever the plan would add a new shape or algorithm.
 
 ## Input
 
@@ -92,6 +103,7 @@ The `tool-planner` prompt context must include the latest-base confirmation and
    - `status: planning`, `type: plan-work`
    - Create or update `state.json` with phase `planning`
    - use `npm run workflow:sidecar -- ensure-session --source-request ... --summary ... --criterion ...` when the repository provides it; this also writes `.flow-agents/current.json`
+   - **Builder Kit build flow**: add `--flow-id builder.build` to the `ensure-session` call when `plan-work` is invoked from `deliver`, from the Builder Kit `build` flow, or from a pick-up-and-build request after `pull-work`. This activates the FlowDefinition-driven path so producers fire and gates enforce on builder.* claims. Do NOT add `--flow-id` for direct/ad-hoc primitive `plan-work` invocations that are not part of a builder-flow.
 2. Delegate to `tool-planner`:
    ```
    Goal: <goal>

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

@@ -291,6 +291,25 @@ Selected work is ready when:
 If the gate fails, update the artifact and stop with the blocker.
 
 After a merge, automatic continuation may inspect the queue and write a new pull-work artifact, but it cannot enter planning or execution for the next work item until a fresh pickup Probe record exists for that newly selected item or justified group.
+## Gate Claim: Record Selected Work
+
+When the Pickup Gate passes and work is selected (not just a shepherding scan or WIP-only audit), record the gate claim for the Builder Kit `pull-work` step before handing off to `design-probe` or `plan-work`. This satisfies the `builder.pull-work.selected` gate expectation.
+
+Use the `selected_item_ids` as the evidence artifact ref and confirm that scope and acceptance criteria are present in the pull-work artifact:
+
+```bash
+npm run workflow:sidecar -- record-gate-claim .flow-agents/<slug> \
+  --expectation selected-work \
+  --status pass \
+  --summary "Selected <work-item-ref>: scope clear, acceptance criteria present." \
+  --evidence-ref-json '{"kind":"artifact","file":".flow-agents/<slug>/<slug>--pull-work.md","summary":"Pull-work artifact with selected_item_ids, scope, and acceptance criteria."}'
+```
+
+Use `--status fail` when the gate fails (blocker recorded but no selection made). Use `--status not_verified` only when the session has no active flow step (non-Builder-Kit usage).
+
+Record `--status fail` with a summary naming the blocker when stopping before selection. Do not record `pass` until `selected_item_ids` are confirmed and the pickup gate criteria above are met.
+
+
 
 ## Flow Validation Boundary
 

package/kits/knowledge/adapters/default-store/index.js

@@ -297,6 +297,16 @@ function removeLinksFromGraph(graph, sourceId) {
   delete graph.forward[sourceId];
 }
 
+// Order-independent canonical form of a graph index, for drift comparison.
+function canonicalGraph(graph) {
+  const norm = (obj) =>
+    Object.keys(obj || {}).sort().reduce((acc, k) => {
+      acc[k] = (obj[k] || []).map((e) => JSON.stringify(e)).sort();
+      return acc;
+    }, {});
+  return JSON.stringify({ forward: norm(graph.forward), reverse: norm(graph.reverse) });
+}
+
 // ---------------------------------------------------------------------------
 // Validation helpers
 // ---------------------------------------------------------------------------
@@ -882,6 +892,34 @@ export class DefaultKnowledgeStore {
     );
   }
 
+  // -------------------------------------------------------------------------
+  // reindex — rebuild graph-index.json from records' links (recovery path)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Rebuild the graph index authoritatively from the records' own `links`.
+   * Records are the source of truth; the index is a derived cache. Use this to
+   * recover from a lost, hand-edited, or drifted `graph-index.json` (issue #106).
+   * @returns {Promise<{records:number, links:number, forwardSources:number, reverseTargets:number, changed:boolean}>}
+   */
+  async reindex() {
+    const records = this._allRecords().sort((a, b) => a.id.localeCompare(b.id));
+    const rebuilt = emptyGraph();
+    for (const record of records) {
+      addLinksToGraph(rebuilt, record.id, Array.isArray(record.links) ? record.links : []);
+    }
+    const links = Object.values(rebuilt.forward).reduce((n, arr) => n + arr.length, 0);
+    const changed = canonicalGraph(loadGraph(this._graphPath)) !== canonicalGraph(rebuilt);
+    saveGraph(this._graphPath, rebuilt);
+    return {
+      records: records.length,
+      links,
+      forwardSources: Object.keys(rebuilt.forward).length,
+      reverseTargets: Object.keys(rebuilt.reverse).length,
+      changed,
+    };
+  }
+
   // -------------------------------------------------------------------------
   // Internal: read all records
   // -------------------------------------------------------------------------