@kontourai/flow-agents 1.1.0 → 1.3.0

package/kits/knowledge/flows/synthesize.flow.json

@@ -14,12 +14,12 @@
       "expects": [
         {
           "id": "similar-sources-found",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "At least one compiled record similar to the target concept has been identified via the similarity detector. Similarity v1 uses category match + link-overlap heuristic. The result is a cluster of source record IDs to synthesize from.",
-          "claim": {
-            "type": "knowledge.synthesize.cluster",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.cluster",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -30,12 +30,12 @@
       "expects": [
         {
           "id": "proposal-recorded",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A proposal carrying source refs (proposer_id + source_ids in evidence) has been recorded via the store propose op. The concept body is NOT modified at this step — only a proposes link and mutation log entry are created.",
-          "claim": {
-            "type": "knowledge.synthesize.proposal",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.proposal",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -46,12 +46,12 @@
       "expects": [
         {
           "id": "proposal-carries-source-refs",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "The proposal evidence includes source_ids referencing every compiled record that contributed to the proposed summary. Gate rejects if source_ids is empty or any referenced record does not exist.",
-          "claim": {
-            "type": "knowledge.synthesize.evidence",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.evidence",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }
@@ -62,12 +62,12 @@
       "expects": [
         {
           "id": "mutation-gate-decision",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A gate decision (apply or reject) has been recorded. If applied: concept body is updated via the store apply op with rationale and all contributing source_ids in provenance. If rejected: the store reject op is called, the concept body is byte-identical to its pre-proposal state, and only a rejection log entry is appended.",
-          "claim": {
-            "type": "knowledge.synthesize.gate-decision",
-            "subject": "artifact",
+          "bundle_claim": {
+            "claimType": "knowledge.synthesize.gate-decision",
+            "subjectType": "artifact",
             "accepted_statuses": ["trusted", "accepted"]
           }
         }

package/kits/knowledge/kit.json

@@ -3,7 +3,7 @@
   "id": "knowledge",
   "name": "Knowledge Kit",
   "product_name": "Knowledge Kit",
-  "description": "A Flow Kit for durable, gated knowledge storage. Provides a store contract with defined record types, mutation operations, and provenance rules \u2014 plus a default adapter backed by markdown files, YAML frontmatter, wikilinks, and a graph index.",
+  "description": "A Flow Kit for durable, gated knowledge storage. Provides a store contract with defined record types, mutation operations, and provenance rules — plus a default adapter backed by markdown files, YAML frontmatter, wikilinks, and a graph index.",
   "flows": [
     {
       "id": "knowledge.store-contract",
@@ -13,17 +13,17 @@
     {
       "id": "knowledge.ingest",
       "path": "flows/ingest.flow.json",
-      "description": "Ingest raw captures: capture \u2192 classify \u2192 route. Gate on classify requires category + type='raw' classification evidence per the store contract create op."
+      "description": "Ingest raw captures: capture → classify → route. Gate on classify requires category + type='raw' classification evidence per the store contract create op."
     },
     {
       "id": "knowledge.compile",
       "path": "flows/compile.flow.json",
-      "description": "Compile classified raws into durable notes: select-raws \u2192 compile \u2192 link. Gate on compile requires provenance refs to every consumed raw record."
+      "description": "Compile classified raws into durable notes: select-raws → compile → link. Gate on compile requires provenance refs to every consumed raw record."
     },
     {
       "id": "knowledge.synthesize",
       "path": "flows/synthesize.flow.json",
-      "description": "Synthesize compiled sources into concept summaries: detect-cluster \u2192 propose \u2192 evidence-gate \u2192 apply-or-reject. Mutation-gate policy: no summary mutates without an approved proposal carrying source refs; rejection leaves store untouched."
+      "description": "Synthesize compiled sources into concept summaries: detect-cluster → propose → evidence-gate → apply-or-reject. Mutation-gate policy: no summary mutates without an approved proposal carrying source refs; rejection leaves store untouched."
     },
     {
       "id": "knowledge.consolidate",
@@ -33,7 +33,7 @@
     {
       "id": "knowledge.retire",
       "path": "flows/retire.flow.json",
-      "description": "Retire implemented or obsolete records from the working set via gated lifecycle: identify \u2192 propose-retirement \u2192 evidence-gate \u2192 apply-or-reject. Evidence required: retirement rationale + implementedByRef (when targeting 'implemented' status) or supersededByRef (optional, for 'retired'). Rejection leaves record status byte-identical. Retired records remain fully queryable with provenance via includeRetired flag."
+      "description": "Retire implemented or obsolete records from the working set via gated lifecycle: identify → propose-retirement → evidence-gate → apply-or-reject. Evidence required: retirement rationale + implementedByRef (when targeting 'implemented' status) or supersededByRef (optional, for 'retired'). Rejection leaves record status byte-identical. Retired records remain fully queryable with provenance via includeRetired flag."
     }
   ],
   "docs": [
@@ -55,7 +55,7 @@
     {
       "id": "knowledge.flow-runner",
       "path": "adapters/flow-runner/index.js",
-      "description": "Executable flow logic: capture(rawText, meta) \u2192 classified raw record; compile(rawIds[]) \u2192 compiled record with provenance links; synthesize(conceptId | topicSelector, options) \u2192 concept summary proposal with mutation gate; consolidate(snapshotId | topicSelector, options) \u2192 decision snapshot consolidation with supersede-not-delete; retire(recordId, options) \u2192 gated status lifecycle transition (active\u2192implemented\u2192retired) with working-set exclusion. Emits canonical telemetry events at gate points."
+      "description": "Executable flow logic: capture(rawText, meta) → classified raw record; compile(rawIds[]) → compiled record with provenance links; synthesize(conceptId | topicSelector, options) → concept summary proposal with mutation gate; consolidate(snapshotId | topicSelector, options) → decision snapshot consolidation with supersede-not-delete; retire(recordId, options) → gated status lifecycle transition (active→implemented→retired) with working-set exclusion. Emits canonical telemetry events at gate points."
     },
     {
       "id": "knowledge.similarity-vector",
@@ -82,7 +82,7 @@
     {
       "id": "knowledge.synthesis-suite",
       "path": "evals/synthesis/suite.test.js",
-      "description": "Eval cases for synthesize: AC1 (similar source \u2192 proposal not mutation), AC2 (rejection leaves concept byte-identical), AC3 (apply updates with provenance to all contributing sources), pluggable-similarity interface test, gate telemetry."
+      "description": "Eval cases for synthesize: AC1 (similar source → proposal not mutation), AC2 (rejection leaves concept byte-identical), AC3 (apply updates with provenance to all contributing sources), pluggable-similarity interface test, gate telemetry."
     },
     {
       "id": "knowledge.consolidation-suite",
@@ -92,7 +92,7 @@
     {
       "id": "knowledge.similarity-vector-suite",
       "path": "evals/similarity-vector/suite.test.js",
-      "description": "Eval cases for the vector similarity adapter: unit tests (cosineSimilarity math, injectable embed, threshold, fail-closed), drop-in proof (runner.synthesize with injected embed produces valid proposals), and live-gated tests (real ollama nomic-embed-text round-trip \u2014 skipped when ollama unavailable)."
+      "description": "Eval cases for the vector similarity adapter: unit tests (cosineSimilarity math, injectable embed, threshold, fail-closed), drop-in proof (runner.synthesize with injected embed produces valid proposals), and live-gated tests (real ollama nomic-embed-text round-trip — skipped when ollama unavailable)."
     },
     {
       "id": "knowledge.retirement-suite",
@@ -102,7 +102,14 @@
     {
       "id": "knowledge.entity-cards-suite",
       "path": "evals/entities/suite.test.js",
-      "description": "Eval cases for person/entity cards (issue #48): AC1-AC4 \u2014 entity extraction from Attendees lines, exact-match resolution, possible-duplicate detection, merge via propose/apply/reject (union aliases+backlinks, supersede duplicate), Obsidian people/ folder rendering, and extended contract suite (person type validity) on both adapters."
+      "description": "Eval cases for person/entity cards (issue #48): AC1-AC4 — entity extraction from Attendees lines, exact-match resolution, possible-duplicate detection, merge via propose/apply/reject (union aliases+backlinks, supersede duplicate), Obsidian people/ folder rendering, and extended contract suite (person type validity) on both adapters."
+    }
+  ],
+  "skills": [
+    {
+      "id": "knowledge.knowledge-capture",
+      "path": "skills/knowledge-capture/SKILL.md",
+      "description": "Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, and source references into the knowledge base."
     }
   ]
 }

package/kits/release-evidence/flows/release-evidence.flow.json

@@ -13,12 +13,12 @@
       "expects": [
         {
           "id": "release-claim-present",
-          "kind": "surface.claim",
+          "kind": "trust.bundle",
           "required": true,
           "description": "A trusted release.evidence claim must be attached before this gate can pass.",
           "explore_hint": "Attach a trust-report JSON file with claim type release.evidence and status trusted.",
-          "claim": {
-            "type": "release.evidence",
+          "bundle_claim": {
+            "claimType": "release.evidence",
             "accepted_statuses": [
               "trusted"
             ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",
@@ -36,7 +36,6 @@
     "flow-agents-context-map": "build/src/cli.js",
     "flow-agents-effective-backlog-settings": "build/src/cli.js",
     "flow-agents-filter-installed-packs": "build/src/cli.js",
-    "flow-agents-flow-kit": "build/src/cli.js",
     "flow-agents-fixture-retirement-audit": "build/src/cli.js",
     "flow-agents-promote-workflow-artifact": "build/src/cli.js",
     "flow-agents-publish-change": "build/src/cli.js",
@@ -49,7 +48,8 @@
     "flow-agents-validate-hook-influence": "build/src/cli.js",
     "flow-agents-validate-source": "build/src/cli.js",
     "flow-agents-workflow-artifact-cleanup-audit": "build/src/cli.js",
-    "flow-agents-workflow-sidecar": "build/src/cli/workflow-sidecar.js"
+    "flow-agents-workflow-sidecar": "build/src/cli/workflow-sidecar.js",
+    "flow-agents-kit": "build/src/cli.js"
   },
   "files": [
     ".github/",
@@ -100,7 +100,6 @@
     "validate:package": "npm run build --silent && node build/src/cli.js validate-package",
     "workflow:sidecar": "npm run build --silent && node build/src/cli/workflow-sidecar.js",
     "workflow:validate-artifacts": "npm run build --silent && node build/src/cli/validate-workflow-artifacts.js",
-    "flow-kit": "npm run build --silent && node build/src/cli.js flow-kit",
     "effective-backlog-settings": "npm run build --silent && node build/src/cli.js effective-backlog-settings",
     "pull-work-provider": "npm run build --silent && node build/src/cli.js pull-work-provider",
     "publish-change": "npm run build --silent && node build/src/cli.js publish-change",
@@ -125,11 +124,18 @@
     "promptfoo": "PROMPTFOO_CONFIG_DIR=.promptfoo PROMPTFOO_DISABLE_WAL_MODE=true PROMPTFOO_DISABLE_TELEMETRY=true promptfoo",
     "promptfoo:view": "PROMPTFOO_CONFIG_DIR=.promptfoo PROMPTFOO_DISABLE_WAL_MODE=true PROMPTFOO_DISABLE_TELEMETRY=true promptfoo view",
     "check:content-boundary": "node scripts/check-content-boundary.cjs",
-    "prepack": "npm run build --silent && npm run validate:source --"
+    "prepack": "npm run build --silent && npm run validate:source --",
+    "kit": "npm run build --silent && node build/src/cli.js kit"
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
     "promptfoo": "^0.121.15",
     "typescript": "^6.0.3"
+  },
+  "dependencies": {
+    "@kontourai/flow": "~1.3.0"
+  },
+  "optionalDependencies": {
+    "hachure": "^0.4.0"
   }
 }

package/packaging/packs.json

@@ -7,13 +7,6 @@
       "description": "Small default surface for reliable coding and workflow execution.",
       "skills": [
         "search-first",
-        "plan-work",
-        "execute-plan",
-        "review-work",
-        "verify-work",
-        "evidence-gate",
-        "feedback-loop",
-        "knowledge-capture",
         "browser-test"
       ],
       "agents": [
@@ -32,23 +25,10 @@
       "default": false,
       "description": "Development workflow depth for backlog, release, dependency, GitHub, TDD, and frontend work.",
       "skills": [
-        "builder-shape",
-        "idea-to-backlog",
-        "pull-work",
-        "design-probe",
-        "pickup-probe",
-        "deliver",
-        "fix-bug",
-        "tdd-workflow",
-        "release-readiness",
-        "learning-review",
         "dependency-update",
         "eval-rebuild",
-        "explore",
         "github-cli",
-        "frontend-design",
-        "agentic-engineering",
-        "context-budget"
+        "agentic-engineering"
       ],
       "agents": [
         "dev",

package/schemas/workflow-evidence.schema.json

@@ -239,7 +239,8 @@
               "properties": {
                 "artifact_kind": {
                   "type": "string",
-                  "enum": ["TrustReport", "Trust Snapshot"]
+                  "description": "Hachure-aligned artifact kind. trust.bundle is the canonical value; TrustReport and Trust Snapshot are legacy aliases.",
+                  "enum": ["trust.bundle", "TrustReport", "Trust Snapshot"]
                 },
                 "artifact_ref": {
                   "type": "string",

package/scripts/README.md

@@ -11,7 +11,7 @@ These files are stable launchers for TypeScript code compiled under `build/src/`
 | `build-universal-bundles.js` | `build/src/tools/build-universal-bundles.js` |
 | `filter-installed-packs.js` | `build/src/tools/filter-installed-packs.js` |
 | `generate-context-map.js` | `build/src/tools/generate-context-map.js` |
-| `flow-kit.js` | `build/src/cli/flow-kit.js` |
+| `kit.js` | `build/src/cli/kit.js` |
 | `pull-work-provider.js` | `build/src/cli/pull-work-provider.js` |
 | `effective-backlog-settings.js` | `build/src/cli/effective-backlog-settings.js` |
 | `publish-change-helper.js` | `build/src/cli/publish-change-helper.js` |

package/scripts/hooks/stop-goal-fit.js

@@ -80,6 +80,15 @@ function hasSidecars(dir) {
   }
 }
 
+/**
+ * Returns true if a line of validator output looks like a validator-environment
+ * error (shell/npm error, tsc missing, spawn failure) rather than a real
+ * artifact validation message. Environment errors must never block goal-fit.
+ */
+function isEnvironmentError(line) {
+  return /tsc[:\s]|command not found|npm ERR!|npm error|ENOENT|EACCES|Cannot find module|node_modules\/.bin|TypeScript version|version conflict|error TS[0-9]/i.test(line);
+}
+
 function sidecarValidation(root, artifactDir) {
   const requireSidecars = String(process.env.FLOW_AGENTS_REQUIRE_SIDECARS || '').toLowerCase() === 'true';
   const requireCritique = String(process.env.FLOW_AGENTS_REQUIRE_CRITIQUE || '').toLowerCase() === 'true';
@@ -88,8 +97,6 @@ function sidecarValidation(root, artifactDir) {
   const packageRoot = fs.existsSync(path.join(root, 'package.json'))
     ? root
     : path.resolve(__dirname, '..', '..');
-  const packageJson = path.join(packageRoot, 'package.json');
-  if (!fs.existsSync(packageJson)) return [`${relative(root, artifactDir)} sidecar validation: package.json is missing; cannot run TypeScript workflow validator.`];
 
   let sidecarFiles = [];
   try {
@@ -112,26 +119,67 @@ function sidecarValidation(root, artifactDir) {
 
   if (sidecarFiles.length === 0) return [];
 
-  const args = ['run', 'workflow:validate-artifacts', '--silent', '--'];
-  args.push('--skip-markdown-validation');
-  if (requireSidecars) args.push('--require-sidecars');
-  if (requireCritique) args.push('--require-critique');
-  args.push(artifactDir);
+  // Part 1 fix: invoke the already-built validator directly via `node`, bypassing
+  // `npm run build` (tsc). npm-installed packages ship build/ in the package files,
+  // so the compiled JS is always available. Only fall back to npm run if build/ is
+  // absent (a raw dev checkout that hasn't been built yet).
+  const builtValidator = path.join(packageRoot, 'build', 'src', 'cli', 'validate-workflow-artifacts.js');
+  const hasBuild = fs.existsSync(builtValidator);
+
+  const validatorArgs = ['--skip-markdown-validation'];
+  if (requireSidecars) validatorArgs.push('--require-sidecars');
+  if (requireCritique) validatorArgs.push('--require-critique');
+  validatorArgs.push(artifactDir);
+
+  let result;
+  if (hasBuild) {
+    // Direct node invocation: no tsc, no npm build step, works from any npm install.
+    result = spawnSync(process.execPath, [builtValidator, ...validatorArgs], {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  } else {
+    // Dev checkout without build/: fall back to npm run (may trigger tsc).
+    // If this also fails due to environment issues, Part 2 handles it below.
+    const npmArgs = ['run', 'workflow:validate-artifacts', '--silent', '--', ...validatorArgs];
+    result = spawnSync('npm', npmArgs, {
+      cwd: packageRoot,
+      encoding: 'utf8',
+      timeout: 30000,
+    });
+  }
 
-  const result = spawnSync('npm', args, {
-    cwd: packageRoot,
-    encoding: 'utf8',
-    timeout: 30000,
-  });
+  // Part 2 fix: treat validator-environment failures as SKIP, never as blocking.
+  // A spawn error (ENOENT, timeout) means the validator couldn't run at all.
+  if (result.error) {
+    // Validator couldn't be launched — environment issue, not a goal-fit failure.
+    return [`${relative(root, artifactDir)} sidecar validation skipped: validator could not run (${result.error.code || result.error.message})`];
+  }
 
   if (result.status === 0) return [];
-  const output = `${result.stdout || ''}\n${result.stderr || ''}`
+
+  // Validator ran and exited non-zero. Separate real validation errors from
+  // environment errors (tsc missing, npm ERR!, shell errors) so that a broken
+  // validator environment never blocks goal-fit.
+  const allLines = `${result.stdout || ''}\n${result.stderr || ''}`
     .split('\n')
     .map(line => line.trim())
-    .filter(Boolean)
-    .slice(0, 12);
-  if (output.length === 0) output.push(`validator exited with status ${result.status ?? 'unknown'}`);
-  return output.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
+    .filter(Boolean);
+
+  const envLines = allLines.filter(isEnvironmentError);
+  const validationLines = allLines.filter(line => !isEnvironmentError(line));
+
+  if (envLines.length > 0 && validationLines.length === 0) {
+    // Pure environment failure — skip, do not block.
+    return [`${relative(root, artifactDir)} sidecar validation skipped: validator environment error (${envLines[0].slice(0, 120)})`];
+  }
+
+  // Real validation errors (possibly mixed with a few env noise lines).
+  const output = validationLines.length > 0 ? validationLines : allLines;
+  const trimmed = output.slice(0, 12);
+  if (trimmed.length === 0) trimmed.push(`validator exited with status ${result.status ?? 'unknown'}`);
+  return trimmed.map(line => `${relative(root, artifactDir)} sidecar validation: ${line}`);
 }
 
 function isWorkflowArtifact(artifact) {
@@ -295,7 +343,7 @@ function analyze(root, now = Date.now()) {
   }
   warnings.push(...sidecarGuidance(root, path.dirname(latest.file)));
 
-  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
+  const blocking = warnings.some(w => /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action/.test(w));
   return { warnings, blocking };
 }
 

package/scripts/kit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../build/src/cli/kit.js").then(({ main }) => main().then((code) => process.exit(code)));

package/skills/README.md

@@ -0,0 +1,23 @@
+# skills/
+
+This directory contains standalone skills that are **not yet claimed by a specific kit**.
+
+## Status: Pending Tool Reclassification
+
+The 6 items here are currently classified as TOOLS pending formal reclassification in a follow-up ADR pass (tracking: #62 follow-up, ADR 0007).
+
+| Skill | Notes |
+| --- | --- |
+| agentic-engineering | Pending reclassification as a tool or context doc |
+| browser-test | Pending reclassification — closely tied to Playwright power |
+| dependency-update | Pending reclassification — tooling-oriented |
+| eval-rebuild | Pending reclassification — project-specific build hook |
+| github-cli | Pending reclassification — CLI tool wrapper |
+| search-first | Pending reclassification — research heuristic |
+
+## Kit-owned skills
+
+Builder Kit skills now live in `kits/builder/skills/`.
+Knowledge Kit skills now live in `kits/knowledge/skills/`.
+
+See `docs/adr/0007-skill-audit.md` for the full audit table and disposition rationale.