@tea-agent/loop-agent 0.13.0 → 0.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (272) hide show
  1. package/AGENTS.md +157 -157
  2. package/CHANGELOG.md +116 -305
  3. package/README.md +357 -334
  4. package/bin/agent-worker.js +22 -22
  5. package/bin/loop-agent.js +21 -21
  6. package/dist/commands/cursor-prompt.js +6 -6
  7. package/dist/commands/init.js +505 -505
  8. package/dist/commands/loop-benchmark.js +11 -11
  9. package/dist/commands/pi-reuse-benchmark.js +16 -16
  10. package/dist/executors/pi-event-serializer.js +33 -11
  11. package/dist/sidecars/cursor-prompt/executor.js +1 -1
  12. package/dist/task/runtime.js +27 -27
  13. package/dist/worker/observe/spec-evidence.js +19 -10
  14. package/dist/worker/observe/static/api.js +46 -46
  15. package/dist/worker/observe/static/app.js +151 -150
  16. package/dist/worker/observe/static/constants.js +156 -148
  17. package/dist/worker/observe/static/copy.js +67 -67
  18. package/dist/worker/observe/static/dag-helpers.js +201 -172
  19. package/dist/worker/observe/static/dag-layout.d.ts +31 -31
  20. package/dist/worker/observe/static/dag-layout.js +83 -83
  21. package/dist/worker/observe/static/dag-model.js +72 -72
  22. package/dist/worker/observe/static/dom.js +122 -122
  23. package/dist/worker/observe/static/format-pool.d.ts +71 -0
  24. package/dist/worker/observe/static/format-pool.js +134 -67
  25. package/dist/worker/observe/static/format.js +317 -292
  26. package/dist/worker/observe/static/index.html +350 -308
  27. package/dist/worker/observe/static/kpi.js +100 -94
  28. package/dist/worker/observe/static/markdown-render.js +124 -0
  29. package/dist/worker/observe/static/relations.js +133 -133
  30. package/dist/worker/observe/static/router.js +93 -93
  31. package/dist/worker/observe/static/run-processing.js +148 -148
  32. package/dist/worker/observe/static/shell-chrome.js +74 -68
  33. package/dist/worker/observe/static/state.js +273 -267
  34. package/dist/worker/observe/static/styles.css +2504 -1902
  35. package/dist/worker/observe/static/views/batch.js +227 -227
  36. package/dist/worker/observe/static/views/dag-graph.js +172 -172
  37. package/dist/worker/observe/static/views/dag-inspector.js +530 -627
  38. package/dist/worker/observe/static/views/dag.js +371 -371
  39. package/dist/worker/observe/static/views/dashboard.js +86 -100
  40. package/dist/worker/observe/static/views/failures.js +143 -143
  41. package/dist/worker/observe/static/views/feature.js +492 -492
  42. package/dist/worker/observe/static/views/pool.js +708 -350
  43. package/dist/worker/observe/static/views/run.js +453 -453
  44. package/dist/worker/observe/static/views/session-timeline.js +771 -219
  45. package/dist/worker/observe/static/views/shell.js +7 -7
  46. package/dist/worker/observe/static/views/task.js +314 -314
  47. package/dist/worker/observe/static/views/timeline.js +163 -163
  48. package/dist/workflows/dag/canvas-observer.js +275 -275
  49. package/dist/workflows/dag/init-hybrid.js +27 -11
  50. package/docs/README.md +106 -104
  51. package/docs/architecture/README.md +26 -26
  52. package/docs/architecture/dag-execution.md +140 -140
  53. package/docs/architecture/evolution.md +54 -54
  54. package/docs/architecture/facts-and-state.md +71 -71
  55. package/docs/architecture/runtime-boundaries.md +191 -191
  56. package/docs/architecture/system-overview.md +93 -93
  57. package/docs/architecture/worker-and-feature.md +85 -85
  58. package/docs/harness-methodology-debugging.md +153 -153
  59. package/docs/harness-methodology-tdd.md +130 -130
  60. package/docs/harness-methodology-verification.md +27 -27
  61. package/docs/init-surface.manifest.json +304 -307
  62. package/docs/skills/README.md +7 -7
  63. package/docs/skills/vetted-skill-registry.md +29 -29
  64. package/docs/templates/adr.md +60 -60
  65. package/docs/templates/agent-dag-authority-surface-audit.prompt.md +94 -94
  66. package/docs/templates/agent-dag-decision-envelope.schema.json +213 -213
  67. package/docs/templates/agent-dag-decision-gate-dogfood-report.md +117 -117
  68. package/docs/templates/agent-dag-decision-gate.prompt.md +246 -246
  69. package/docs/templates/agent-dag-process-supervisor.prompt.md +98 -98
  70. package/docs/templates/agent-dag-report.schema.json +473 -473
  71. package/docs/templates/agent-dag-review-verdict.prompt.md +68 -68
  72. package/docs/templates/agent-dag.base.json +190 -190
  73. package/docs/templates/agent-dag.final-verification.json +185 -185
  74. package/docs/templates/agent-dag.schema.json +411 -411
  75. package/docs/templates/agent-dag.supervised-implementation.json +620 -620
  76. package/docs/templates/backend-test-analysis.schema.json +44 -44
  77. package/docs/templates/backend-test-case-manifest.schema.json +190 -190
  78. package/docs/templates/backend-test-dag.classify.prompt.md +75 -75
  79. package/docs/templates/backend-test-dag.generate-pytest.prompt.md +204 -204
  80. package/docs/templates/backend-test-dag.json +559 -559
  81. package/docs/templates/backend-test-dag.retrospect.prompt.md +139 -139
  82. package/docs/templates/backend-test-dag.review-cases.prompt.md +83 -83
  83. package/docs/templates/backend-test-execution.schema.json +133 -133
  84. package/docs/templates/backend-test-result.schema.json +99 -99
  85. package/docs/templates/branch-merge-report.md +0 -1
  86. package/docs/templates/exec-plan.md +64 -64
  87. package/docs/templates/feature-spec.md +53 -53
  88. package/docs/templates/frontend-design-contract.md +42 -42
  89. package/docs/templates/frontend-eval/fixtures/failures/01-type-build-error.md +17 -17
  90. package/docs/templates/frontend-eval/fixtures/failures/02-unit-component-test-fail.md +16 -16
  91. package/docs/templates/frontend-eval/fixtures/failures/03-fixture-schema-drift.md +16 -16
  92. package/docs/templates/frontend-eval/fixtures/failures/04-missing-loading-empty-error-state.md +16 -16
  93. package/docs/templates/frontend-eval/fixtures/failures/05-forbidden-write-writeset-expansion.md +16 -16
  94. package/docs/templates/frontend-eval/fixtures/failures/06-unapproved-dependency-add.md +16 -16
  95. package/docs/templates/frontend-eval/fixtures/failures/07-mock-production-on.md +21 -21
  96. package/docs/templates/frontend-eval/fixtures/functional/01-simple-component-style.md +29 -29
  97. package/docs/templates/frontend-eval/fixtures/functional/02-form-validation.md +28 -28
  98. package/docs/templates/frontend-eval/fixtures/functional/03-list-detail-page.md +28 -28
  99. package/docs/templates/frontend-eval/fixtures/functional/04-api-mock.md +29 -29
  100. package/docs/templates/frontend-eval/fixtures/functional/05-permission-auth-gated-ui.md +27 -27
  101. package/docs/templates/frontend-eval/fixtures/functional/06-ssr-server-client-boundary.md +28 -28
  102. package/docs/templates/frontend-eval/fixtures/functional/07-shared-public-component-api.md +28 -28
  103. package/docs/templates/frontend-eval/fixtures/functional/08-pure-local-no-remote.md +27 -27
  104. package/docs/templates/frontend-eval/metrics.md +138 -138
  105. package/docs/templates/frontend-eval/smoke-targets.md +53 -53
  106. package/docs/templates/frontend-implementation-contract.schema.json +27 -27
  107. package/docs/templates/frontend-task-constraints.md +35 -35
  108. package/docs/templates/frontend-task-requirement.md +70 -70
  109. package/docs/templates/frontend-test-dag.generate-cases.prompt.md +5 -5
  110. package/docs/templates/frontend-test-dag.json +23 -23
  111. package/docs/templates/frontend-test-dag.retrieve-context.prompt.md +3 -3
  112. package/docs/templates/frontend-test-dag.retrospect.prompt.md +3 -3
  113. package/docs/templates/frontend-test-dag.review-cases.prompt.md +3 -3
  114. package/docs/templates/frontend-test-dag.review-execution.prompt.md +3 -3
  115. package/docs/templates/harness.schema.json +221 -221
  116. package/docs/templates/hybrid-dag.json +188 -188
  117. package/docs/templates/init-evolution-review.md +35 -35
  118. package/docs/templates/interactive-ui-round2-experiment.md +66 -66
  119. package/docs/templates/knowledge-graph-bootstrap-dag.json +118 -118
  120. package/docs/templates/knowledge-sync-dag.json +178 -178
  121. package/docs/templates/knowledge-sync-draft.schema.json +71 -71
  122. package/docs/templates/product-line/AGENTS.md +8 -8
  123. package/docs/templates/product-line/README.md +9 -9
  124. package/docs/templates/product-line/acceptance.yaml +14 -14
  125. package/docs/templates/product-line/closeout.yaml +9 -9
  126. package/docs/templates/product-line/design.md +13 -13
  127. package/docs/templates/product-line/links.md +10 -10
  128. package/docs/templates/product-line/requirement.md +17 -17
  129. package/docs/templates/product-line/task-graph.yaml +15 -15
  130. package/docs/templates/product-line/task.yaml +64 -64
  131. package/docs/templates/product-line/test-plan.md +7 -7
  132. package/docs/templates/production-readiness-checklist.md +57 -57
  133. package/docs/templates/progress-log.md +17 -17
  134. package/docs/templates/project-start-checklist.md +9 -9
  135. package/docs/templates/qa-report.md +48 -48
  136. package/docs/templates/sprint-contract.md +29 -29
  137. package/docs/templates/worker-dogfood-evidence.md +80 -80
  138. package/docs/templates/worker-dogfood-setup.md +68 -68
  139. package/examples/decision-gate-agent-dag.json +173 -173
  140. package/examples/example-dag.json +46 -46
  141. package/examples/hybrid-loop-agent-dag.json +188 -188
  142. package/harness.json +66 -66
  143. package/package.json +78 -52
  144. package/scripts/kb-bootstrap-init-skeleton.sh +240 -240
  145. package/scripts/kb-graph-incremental-prepare.mjs +386 -386
  146. package/scripts/kb-graph-materialize.mjs +105 -105
  147. package/scripts/kb-graph-promote.mjs +164 -164
  148. package/scripts/kb-query.mjs +554 -554
  149. package/skills/agent-worker/SKILL.md +39 -39
  150. package/skills/agent-worker/references/agent-worker-operator.md +60 -60
  151. package/skills/ai-engineering-context/SKILL.md +48 -48
  152. package/skills/analyze-product-dependencies/SKILL.md +67 -67
  153. package/skills/analyze-product-dependencies/agents/openai.yaml +4 -4
  154. package/skills/analyze-product-dependencies/references/api-documentation-schema.md +30 -30
  155. package/skills/analyze-product-dependencies/references/dependency-analysis-schema.md +28 -28
  156. package/skills/analyze-product-dependencies/references/example.md +76 -76
  157. package/skills/analyze-product-dependencies/references/forward-test-cases.md +35 -35
  158. package/skills/analyze-product-dependencies/references/input-contract.md +11 -11
  159. package/skills/analyze-product-dependencies/references/scouting-rules.md +61 -61
  160. package/skills/analyze-product-dependencies/scripts/test-validators.mjs +267 -267
  161. package/skills/analyze-product-dependencies/scripts/validate-api-documentation.mjs +101 -101
  162. package/skills/analyze-product-dependencies/scripts/validate-dependency-analysis.mjs +142 -142
  163. package/skills/analyze-product-dependencies/scripts/validate-product-requirement-input.mjs +76 -76
  164. package/skills/analyze-product-dependencies/scripts/validation-helpers.mjs +146 -146
  165. package/skills/analyze-product-requirements/SKILL.md +90 -90
  166. package/skills/analyze-product-requirements/agents/openai.yaml +4 -4
  167. package/skills/analyze-product-requirements/references/acceptance-criteria.md +91 -91
  168. package/skills/analyze-product-requirements/references/clarification-and-knowledge.md +56 -56
  169. package/skills/analyze-product-requirements/references/example.md +86 -86
  170. package/skills/analyze-product-requirements/references/forward-test-cases.md +66 -66
  171. package/skills/analyze-product-requirements/references/product-analysis-schema.md +32 -32
  172. package/skills/analyze-product-requirements/references/product-requirement-schema.md +33 -33
  173. package/skills/analyze-product-requirements/references/requirement-clarification-schema.md +35 -35
  174. package/skills/analyze-product-requirements/scripts/test-validators.mjs +193 -193
  175. package/skills/analyze-product-requirements/scripts/validate-product-analysis.mjs +69 -69
  176. package/skills/analyze-product-requirements/scripts/validate-product-requirement.mjs +97 -97
  177. package/skills/analyze-product-requirements/scripts/validate-requirement-clarification.mjs +98 -98
  178. package/skills/analyze-product-requirements/scripts/validation-helpers.mjs +156 -156
  179. package/skills/browser-tools/SKILL.md +196 -196
  180. package/skills/browser-tools/browser-content.js +103 -103
  181. package/skills/browser-tools/browser-cookies.js +35 -35
  182. package/skills/browser-tools/browser-eval.js +53 -53
  183. package/skills/browser-tools/browser-hn-scraper.js +108 -108
  184. package/skills/browser-tools/browser-nav.js +44 -44
  185. package/skills/browser-tools/browser-pick.js +162 -162
  186. package/skills/browser-tools/browser-screenshot.js +34 -34
  187. package/skills/browser-tools/browser-start.js +86 -86
  188. package/skills/browser-tools/package-lock.json +2556 -2556
  189. package/skills/browser-tools/package.json +19 -19
  190. package/skills/code-review-core/SKILL.md +20 -20
  191. package/skills/codebase-scout/SKILL.md +19 -19
  192. package/skills/frontend-design-review/SKILL.md +66 -66
  193. package/skills/frontend-design-review/references/review-checklist.md +40 -58
  194. package/skills/frontend-implementation/SKILL.md +49 -49
  195. package/skills/frontend-implementation/references/code-standards.md +32 -32
  196. package/skills/frontend-implementation/references/design-spec.md +46 -46
  197. package/skills/frontend-implementation/references/node-contracts.md +27 -27
  198. package/skills/frontend-review/SKILL.md +61 -59
  199. package/skills/frontend-review/references/review-findings.md +48 -47
  200. package/skills/frontend-verification/SKILL.md +55 -53
  201. package/skills/frontend-verification/references/verification-checklist.md +59 -68
  202. package/skills/grill-me/SKILL.md +10 -10
  203. package/skills/grill-with-docs/SKILL.md +88 -88
  204. package/skills/grill-with-docs/adr-format.md +47 -47
  205. package/skills/grill-with-docs/context-format.md +60 -60
  206. package/skills/init-capability-evolution/SKILL.md +70 -70
  207. package/skills/loop-agent/SKILL.md +151 -151
  208. package/skills/loop-agent/references/README.md +67 -67
  209. package/skills/loop-agent/references/command-reference.md +527 -527
  210. package/skills/loop-agent/references/docs-converge.md +126 -126
  211. package/skills/loop-agent/references/harness-policy.md +263 -263
  212. package/skills/loop-agent/references/hybrid-dag.md +243 -243
  213. package/skills/loop-agent/references/learned/README.md +21 -21
  214. package/skills/loop-agent/references/long-running-loop.md +57 -57
  215. package/skills/loop-agent/references/model-routing.md +36 -36
  216. package/skills/loop-agent/references/multi-worktree.md +54 -54
  217. package/skills/loop-agent/references/one-shot-runs.md +85 -85
  218. package/skills/loop-agent/references/orchestrator-and-interventions.md +169 -169
  219. package/skills/loop-agent/references/pi-prompt.md +23 -23
  220. package/skills/loop-agent/references/pi-subagent-assisted-mode.md +84 -84
  221. package/skills/loop-agent/references/post-implementation-and-patterns.md +44 -44
  222. package/skills/loop-agent/references/task-workflow.md +89 -89
  223. package/skills/loop-agent/references/verification-and-failure-handling.md +141 -141
  224. package/skills/playwright-cli/SKILL.md +420 -420
  225. package/skills/playwright-cli/references/element-attributes.md +23 -23
  226. package/skills/playwright-cli/references/playwright-tests.md +39 -39
  227. package/skills/playwright-cli/references/request-mocking.md +87 -87
  228. package/skills/playwright-cli/references/running-code.md +241 -241
  229. package/skills/playwright-cli/references/session-management.md +225 -225
  230. package/skills/playwright-cli/references/storage-state.md +275 -275
  231. package/skills/playwright-cli/references/test-generation.md +433 -433
  232. package/skills/playwright-cli/references/tracing.md +139 -139
  233. package/skills/playwright-cli/references/video-recording.md +143 -143
  234. package/skills/playwright-cli-case-generator/SKILL.md +74 -74
  235. package/skills/requesting-code-review/SKILL.md +101 -101
  236. package/skills/requesting-code-review/code-reviewer.md +168 -168
  237. package/skills/systematic-debugging/CREATION-LOG.md +119 -119
  238. package/skills/systematic-debugging/SKILL.md +296 -296
  239. package/skills/systematic-debugging/condition-based-waiting-example.ts +158 -158
  240. package/skills/systematic-debugging/condition-based-waiting.md +115 -115
  241. package/skills/systematic-debugging/defense-in-depth.md +122 -122
  242. package/skills/systematic-debugging/find-polluter.sh +63 -63
  243. package/skills/systematic-debugging/root-cause-tracing.md +169 -169
  244. package/skills/systematic-debugging/test-academic.md +14 -14
  245. package/skills/systematic-debugging/test-pressure-1.md +58 -58
  246. package/skills/systematic-debugging/test-pressure-2.md +68 -68
  247. package/skills/systematic-debugging/test-pressure-3.md +69 -69
  248. package/skills/test-driven-development/SKILL.md +20 -20
  249. package/skills/using-git-worktrees/SKILL.md +215 -215
  250. package/skills/verification-before-completion/SKILL.md +154 -154
  251. package/skills/webapp-testing/SKILL.md +19 -19
  252. package/docs/agent-dag-recovery-playbook.md +0 -195
  253. package/docs/agent-dag-runner.md +0 -67
  254. package/docs/cursor-prompt-sidecar.md +0 -36
  255. package/docs/decisions/README.md +0 -18
  256. package/docs/design/README.md +0 -167
  257. package/docs/development-principles.md +0 -73
  258. package/docs/exec-plans/README.md +0 -6
  259. package/docs/exec-plans/active/README.md +0 -12
  260. package/docs/exec-plans/completed/README.md +0 -107
  261. package/docs/feature-workflow.md +0 -414
  262. package/docs/loop-agent-harness.md +0 -142
  263. package/docs/production-readiness.md +0 -96
  264. package/docs/progress/README.md +0 -80
  265. package/docs/reports/README.md +0 -159
  266. package/docs/verification-matrix.md +0 -70
  267. package/scripts/check-product-line-docs.sh +0 -29
  268. package/scripts/check-task-pool-root.sh +0 -32
  269. package/scripts/kb-graph-incremental-prepare.sh +0 -5
  270. package/scripts/kb-graph-materialize.sh +0 -4
  271. package/scripts/kb-graph-promote.sh +0 -4
  272. package/scripts/kb-query.sh +0 -5
@@ -1,386 +1,386 @@
1
- #!/usr/bin/env node
2
- /**
3
- * Prepare narrowed scope/status for incremental knowledge-graph updates.
4
- * Reuses knowledge-graph-bootstrap DAG; does not call an LLM.
5
- */
6
- import fs from "node:fs";
7
- import path from "node:path";
8
- import process from "node:process";
9
- import { spawnSync } from "node:child_process";
10
- import { fileURLToPath } from "node:url";
11
-
12
- const scriptDir = path.dirname(fileURLToPath(import.meta.url));
13
-
14
- function usage(code = 2) {
15
- const text = `Usage: node scripts/kb-graph-incremental-prepare.mjs --root <dir> [options]
16
-
17
- Prepare an incremental graph-update run (same DAG as bootstrap, narrowed scope).
18
-
19
- --root DIR Repository root (required)
20
- --feature F-id Seed feature (repeatable)
21
- --service NAME Seed service (repeatable)
22
- --domain NAME Seed domain (repeatable)
23
- --include GLOB include_paths entry (repeatable)
24
- --reset-staging Clear knowledge/bootstrap/staging/**
25
- --force-scope Rewrite scope.yaml from seeds (default: merge seeds)
26
- --product-name NAME Used when creating missing B1 skeleton
27
- -h, --help
28
- `;
29
- if (code === 0) console.log(text);
30
- else console.error(text);
31
- process.exit(code);
32
- }
33
-
34
- function parseArgs(argv) {
35
- const out = {
36
- root: null,
37
- features: [],
38
- services: [],
39
- domains: [],
40
- includes: [],
41
- resetStaging: false,
42
- forceScope: false,
43
- productName: null,
44
- };
45
- for (let i = 0; i < argv.length; i++) {
46
- const a = argv[i];
47
- const next = () => {
48
- const v = argv[++i];
49
- if (v === undefined) throw new Error(`missing value for ${a}`);
50
- return v;
51
- };
52
- switch (a) {
53
- case "--root":
54
- out.root = path.resolve(next());
55
- break;
56
- case "--feature":
57
- out.features.push(next());
58
- break;
59
- case "--service":
60
- out.services.push(next());
61
- break;
62
- case "--domain":
63
- out.domains.push(next());
64
- break;
65
- case "--include":
66
- out.includes.push(next());
67
- break;
68
- case "--reset-staging":
69
- out.resetStaging = true;
70
- break;
71
- case "--force-scope":
72
- out.forceScope = true;
73
- break;
74
- case "--product-name":
75
- out.productName = next();
76
- break;
77
- case "-h":
78
- case "--help":
79
- usage(0);
80
- break;
81
- default:
82
- throw new Error(`unknown argument: ${a}`);
83
- }
84
- }
85
- return out;
86
- }
87
-
88
- function ensureSkeleton(root, productName) {
89
- const scope = path.join(root, "knowledge/bootstrap/scope.yaml");
90
- const status = path.join(root, "knowledge/bootstrap/status.yaml");
91
- if (fs.existsSync(scope) && fs.existsSync(status)) return;
92
- const skeleton = path.join(scriptDir, "kb-bootstrap-init-skeleton.sh");
93
- const args = ["bash", skeleton, "--root", root];
94
- if (productName) args.push("--product-name", productName);
95
- const r = spawnSync(args[0], args.slice(1), { encoding: "utf8" });
96
- if (r.status !== 0) {
97
- throw new Error(
98
- `failed to init B1 skeleton: ${r.stderr || r.stdout || r.status}`,
99
- );
100
- }
101
- }
102
-
103
- function dumpYaml(obj, indent = 0) {
104
- const sp = " ".repeat(indent);
105
- if (Array.isArray(obj)) {
106
- if (obj.length === 0) return "[]";
107
- return obj.map((item) => `${sp}- ${formatScalar(item)}`).join("\n");
108
- }
109
- if (obj && typeof obj === "object") {
110
- return Object.entries(obj)
111
- .map(([k, v]) => {
112
- if (Array.isArray(v)) {
113
- if (v.length === 0) return `${sp}${k}: []`;
114
- return `${sp}${k}:\n${v.map((item) => `${sp} - ${formatScalar(item)}`).join("\n")}`;
115
- }
116
- if (v && typeof v === "object") {
117
- return `${sp}${k}:\n${dumpYaml(v, indent + 1)}`;
118
- }
119
- return `${sp}${k}: ${formatScalar(v)}`;
120
- })
121
- .join("\n");
122
- }
123
- return `${sp}${formatScalar(obj)}`;
124
- }
125
-
126
- function formatScalar(v) {
127
- if (v === null || v === undefined) return "null";
128
- if (typeof v === "boolean" || typeof v === "number") return String(v);
129
- const s = String(v);
130
- if (/[:#{}[\],&*?|>!%@`]/.test(s) || s === "" || /\s/.test(s)) {
131
- return JSON.stringify(s);
132
- }
133
- return s;
134
- }
135
-
136
- function unique(list) {
137
- return [...new Set(list.filter(Boolean))];
138
- }
139
-
140
- function buildIncludes(args) {
141
- if (args.includes.length) return unique(args.includes);
142
- const includes = ["features/**", "docs/**", "README.md"];
143
- for (const f of args.features) includes.push(`features/${f}/**`);
144
- for (const s of args.services) {
145
- includes.push(
146
- `services/${s}/**`,
147
- `apps/${s}/**`,
148
- `packages/${s}/**`,
149
- "src/**",
150
- );
151
- }
152
- return unique(includes);
153
- }
154
-
155
- function mergeSeedsIntoScopeText(text, args) {
156
- let next = text;
157
- if (!/update_mode:\s*incremental/.test(next)) {
158
- if (/update_mode:\s*\S+/.test(next)) {
159
- next = next.replace(/update_mode:\s*\S+/, "update_mode: incremental");
160
- } else {
161
- next = next.replace(
162
- /(schema_version:\s*\d+)/,
163
- "$1\nupdate_mode: incremental",
164
- );
165
- }
166
- }
167
- const upsert = (label, items) => {
168
- if (!items.length) return;
169
- const re = new RegExp(
170
- `${label}:\\s*(\\[\\]|\\n(?:\\s+-\\s+[^\\n]+\\n)*)`,
171
- );
172
- const m = next.match(re);
173
- const existing = new Set();
174
- if (m) {
175
- for (const line of m[1].split("\n")) {
176
- const mm = line.match(/-\s+(.+?)\s*$/);
177
- if (!mm) continue;
178
- const scalar = mm[1];
179
- if (scalar.startsWith('"')) {
180
- try {
181
- existing.add(JSON.parse(scalar));
182
- continue;
183
- } catch {
184
- // Fall through to conservative quote trimming.
185
- }
186
- }
187
- existing.add(scalar.replace(/^["']|["']$/g, ""));
188
- }
189
- }
190
- for (const it of items) existing.add(it);
191
- const body = [...existing]
192
- .map((i) => ` - ${formatScalar(i)}`)
193
- .join("\n");
194
- const block = `${label}:\n${body}\n`;
195
- if (m) next = next.replace(re, block);
196
- else next += `\n${block}`;
197
- };
198
- upsert("seed_features", args.features);
199
- upsert("seed_services", args.services);
200
- upsert("seed_domains", args.domains);
201
- upsert("include_paths", args.includes);
202
- return next.endsWith("\n") ? next : `${next}\n`;
203
- }
204
-
205
- function resetStaging(root, bootstrapId) {
206
- const staging = path.join(root, "knowledge/bootstrap/staging");
207
- if (!fs.existsSync(staging)) {
208
- fs.mkdirSync(staging, { recursive: true });
209
- }
210
- for (const ent of fs.readdirSync(staging, { withFileTypes: true })) {
211
- if (ent.name === ".gitkeep") continue;
212
- fs.rmSync(path.join(staging, ent.name), { recursive: true, force: true });
213
- }
214
- for (const d of [
215
- "domains",
216
- "services",
217
- "modules",
218
- "features-links.proposed",
219
- ]) {
220
- fs.mkdirSync(path.join(staging, d), { recursive: true });
221
- }
222
- fs.writeFileSync(
223
- path.join(staging, "notes.md"),
224
- `# staging cleared for incremental run ${bootstrapId}\n`,
225
- );
226
- fs.writeFileSync(
227
- path.join(staging, "edges.proposed.yaml"),
228
- "schema_version: 1\nedges: []\n",
229
- );
230
- fs.writeFileSync(
231
- path.join(staging, "coverage-notes.md"),
232
- "# coverage notes (incremental)\n",
233
- );
234
- }
235
-
236
- function main() {
237
- let args;
238
- try {
239
- args = parseArgs(process.argv.slice(2));
240
- } catch (e) {
241
- console.error(String(e?.message || e));
242
- usage(2);
243
- }
244
- if (!args.root) {
245
- console.error("--root is required");
246
- usage(2);
247
- }
248
- if (
249
- !args.features.length &&
250
- !args.services.length &&
251
- !args.domains.length &&
252
- !args.includes.length
253
- ) {
254
- console.error(
255
- "at least one of --feature / --service / --domain / --include is required",
256
- );
257
- process.exit(2);
258
- }
259
-
260
- ensureSkeleton(args.root, args.productName);
261
- const ts = new Date().toISOString();
262
- const bootstrapId = `BR-INC-${ts.replace(/[-:TZ.]/g, "").slice(0, 14)}`;
263
- const scopePath = path.join(args.root, "knowledge/bootstrap/scope.yaml");
264
- const statusPath = path.join(args.root, "knowledge/bootstrap/status.yaml");
265
- const backupDir = path.join(
266
- args.root,
267
- "knowledge/bootstrap/runs",
268
- bootstrapId,
269
- );
270
- fs.mkdirSync(backupDir, { recursive: true });
271
- fs.copyFileSync(scopePath, path.join(backupDir, "scope.before.yaml"));
272
- fs.copyFileSync(statusPath, path.join(backupDir, "status.before.yaml"));
273
-
274
- const includes = buildIncludes(args);
275
- const product =
276
- args.productName || path.basename(args.root);
277
-
278
- if (args.forceScope || !fs.existsSync(scopePath)) {
279
- const data = {
280
- schema_version: 1,
281
- product_name: product,
282
- primary_language: "zh-CN",
283
- repo_kind: "single-service",
284
- update_mode: "incremental",
285
- include_paths: includes,
286
- exclude_paths: ["node_modules/**", "dist/**", ".harness/**"],
287
- id_namespace: {
288
- domain_prefix: "DOM",
289
- service_prefix: "SVC",
290
- api_prefix: "API",
291
- },
292
- seed_domains: args.domains,
293
- seed_services: args.services,
294
- seed_features: args.features,
295
- assumptions: [
296
- "Incremental update: do not rebuild unrelated domains/services",
297
- ],
298
- out_of_scope: ["full-repo bootstrap"],
299
- human_owners: { architect: "", qa: "" },
300
- };
301
- fs.writeFileSync(
302
- scopePath,
303
- `# Incremental graph scope\n${dumpYaml(data)}\n`,
304
- );
305
- } else {
306
- const merged = mergeSeedsIntoScopeText(
307
- fs.readFileSync(scopePath, "utf8"),
308
- args,
309
- );
310
- fs.writeFileSync(scopePath, merged);
311
- }
312
-
313
- const status = {
314
- schema_version: 1,
315
- bootstrap_id: bootstrapId,
316
- repo_root: ".",
317
- phase: "B2",
318
- update_mode: "incremental",
319
- updated_at: ts,
320
- scope_ref: "knowledge/bootstrap/scope.yaml",
321
- inventory_ref: "knowledge/bootstrap/inventory.json",
322
- last_run_dir: `knowledge/bootstrap/runs/${bootstrapId}/`,
323
- stats: {
324
- entities_proposed: 0,
325
- entities_asserted: 0,
326
- edges_proposed: 0,
327
- edges_asserted: 0,
328
- features_linked: 0,
329
- },
330
- blockers: [],
331
- next_actions: [
332
- "Review knowledge/bootstrap/scope.yaml (update_mode: incremental)",
333
- "Run knowledge-graph-bootstrap DAG (propose limited to scope seeds/includes)",
334
- "Promote merge-new-only; materialize indexes",
335
- ],
336
- };
337
- fs.writeFileSync(
338
- statusPath,
339
- `# Incremental bootstrap status\n${dumpYaml(status)}\n`,
340
- );
341
-
342
- if (args.resetStaging) resetStaging(args.root, bootstrapId);
343
-
344
- fs.writeFileSync(
345
- path.join(backupDir, "README.md"),
346
- [
347
- `# Incremental prepare ${bootstrapId}`,
348
- "",
349
- `- update_mode: incremental`,
350
- `- features: ${args.features.join(", ") || "(none)"}`,
351
- `- services: ${args.services.join(", ") || "(none)"}`,
352
- `- domains: ${args.domains.join(", ") || "(none)"}`,
353
- "",
354
- "Next:",
355
- "```bash",
356
- "# task.json: { \"taskKind\": \"knowledge-graph-bootstrap\", ... }",
357
- "loop-agent dag run-task <task-id> --execute --cwd .",
358
- `bash scripts/kb-graph-materialize.sh --root ${args.root}`,
359
- "```",
360
- "",
361
- ].join("\n"),
362
- );
363
-
364
- console.log(
365
- JSON.stringify(
366
- {
367
- ok: true,
368
- bootstrap_id: bootstrapId,
369
- update_mode: "incremental",
370
- scope: "knowledge/bootstrap/scope.yaml",
371
- status: "knowledge/bootstrap/status.yaml",
372
- backup: `knowledge/bootstrap/runs/${bootstrapId}/`,
373
- seeds: {
374
- features: args.features,
375
- services: args.services,
376
- domains: args.domains,
377
- },
378
- next: "set task.json.taskKind=knowledge-graph-bootstrap; dag run-task --execute",
379
- },
380
- null,
381
- 2,
382
- ),
383
- );
384
- }
385
-
386
- main();
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Prepare narrowed scope/status for incremental knowledge-graph updates.
4
+ * Reuses knowledge-graph-bootstrap DAG; does not call an LLM.
5
+ */
6
+ import fs from "node:fs";
7
+ import path from "node:path";
8
+ import process from "node:process";
9
+ import { spawnSync } from "node:child_process";
10
+ import { fileURLToPath } from "node:url";
11
+
12
+ const scriptDir = path.dirname(fileURLToPath(import.meta.url));
13
+
14
+ function usage(code = 2) {
15
+ const text = `Usage: node scripts/kb-graph-incremental-prepare.mjs --root <dir> [options]
16
+
17
+ Prepare an incremental graph-update run (same DAG as bootstrap, narrowed scope).
18
+
19
+ --root DIR Repository root (required)
20
+ --feature F-id Seed feature (repeatable)
21
+ --service NAME Seed service (repeatable)
22
+ --domain NAME Seed domain (repeatable)
23
+ --include GLOB include_paths entry (repeatable)
24
+ --reset-staging Clear knowledge/bootstrap/staging/**
25
+ --force-scope Rewrite scope.yaml from seeds (default: merge seeds)
26
+ --product-name NAME Used when creating missing B1 skeleton
27
+ -h, --help
28
+ `;
29
+ if (code === 0) console.log(text);
30
+ else console.error(text);
31
+ process.exit(code);
32
+ }
33
+
34
+ function parseArgs(argv) {
35
+ const out = {
36
+ root: null,
37
+ features: [],
38
+ services: [],
39
+ domains: [],
40
+ includes: [],
41
+ resetStaging: false,
42
+ forceScope: false,
43
+ productName: null,
44
+ };
45
+ for (let i = 0; i < argv.length; i++) {
46
+ const a = argv[i];
47
+ const next = () => {
48
+ const v = argv[++i];
49
+ if (v === undefined) throw new Error(`missing value for ${a}`);
50
+ return v;
51
+ };
52
+ switch (a) {
53
+ case "--root":
54
+ out.root = path.resolve(next());
55
+ break;
56
+ case "--feature":
57
+ out.features.push(next());
58
+ break;
59
+ case "--service":
60
+ out.services.push(next());
61
+ break;
62
+ case "--domain":
63
+ out.domains.push(next());
64
+ break;
65
+ case "--include":
66
+ out.includes.push(next());
67
+ break;
68
+ case "--reset-staging":
69
+ out.resetStaging = true;
70
+ break;
71
+ case "--force-scope":
72
+ out.forceScope = true;
73
+ break;
74
+ case "--product-name":
75
+ out.productName = next();
76
+ break;
77
+ case "-h":
78
+ case "--help":
79
+ usage(0);
80
+ break;
81
+ default:
82
+ throw new Error(`unknown argument: ${a}`);
83
+ }
84
+ }
85
+ return out;
86
+ }
87
+
88
+ function ensureSkeleton(root, productName) {
89
+ const scope = path.join(root, "knowledge/bootstrap/scope.yaml");
90
+ const status = path.join(root, "knowledge/bootstrap/status.yaml");
91
+ if (fs.existsSync(scope) && fs.existsSync(status)) return;
92
+ const skeleton = path.join(scriptDir, "kb-bootstrap-init-skeleton.sh");
93
+ const args = ["bash", skeleton, "--root", root];
94
+ if (productName) args.push("--product-name", productName);
95
+ const r = spawnSync(args[0], args.slice(1), { encoding: "utf8" });
96
+ if (r.status !== 0) {
97
+ throw new Error(
98
+ `failed to init B1 skeleton: ${r.stderr || r.stdout || r.status}`,
99
+ );
100
+ }
101
+ }
102
+
103
+ function dumpYaml(obj, indent = 0) {
104
+ const sp = " ".repeat(indent);
105
+ if (Array.isArray(obj)) {
106
+ if (obj.length === 0) return "[]";
107
+ return obj.map((item) => `${sp}- ${formatScalar(item)}`).join("\n");
108
+ }
109
+ if (obj && typeof obj === "object") {
110
+ return Object.entries(obj)
111
+ .map(([k, v]) => {
112
+ if (Array.isArray(v)) {
113
+ if (v.length === 0) return `${sp}${k}: []`;
114
+ return `${sp}${k}:\n${v.map((item) => `${sp} - ${formatScalar(item)}`).join("\n")}`;
115
+ }
116
+ if (v && typeof v === "object") {
117
+ return `${sp}${k}:\n${dumpYaml(v, indent + 1)}`;
118
+ }
119
+ return `${sp}${k}: ${formatScalar(v)}`;
120
+ })
121
+ .join("\n");
122
+ }
123
+ return `${sp}${formatScalar(obj)}`;
124
+ }
125
+
126
+ function formatScalar(v) {
127
+ if (v === null || v === undefined) return "null";
128
+ if (typeof v === "boolean" || typeof v === "number") return String(v);
129
+ const s = String(v);
130
+ if (/[:#{}[\],&*?|>!%@`]/.test(s) || s === "" || /\s/.test(s)) {
131
+ return JSON.stringify(s);
132
+ }
133
+ return s;
134
+ }
135
+
136
+ function unique(list) {
137
+ return [...new Set(list.filter(Boolean))];
138
+ }
139
+
140
+ function buildIncludes(args) {
141
+ if (args.includes.length) return unique(args.includes);
142
+ const includes = ["features/**", "docs/**", "README.md"];
143
+ for (const f of args.features) includes.push(`features/${f}/**`);
144
+ for (const s of args.services) {
145
+ includes.push(
146
+ `services/${s}/**`,
147
+ `apps/${s}/**`,
148
+ `packages/${s}/**`,
149
+ "src/**",
150
+ );
151
+ }
152
+ return unique(includes);
153
+ }
154
+
155
+ function mergeSeedsIntoScopeText(text, args) {
156
+ let next = text;
157
+ if (!/update_mode:\s*incremental/.test(next)) {
158
+ if (/update_mode:\s*\S+/.test(next)) {
159
+ next = next.replace(/update_mode:\s*\S+/, "update_mode: incremental");
160
+ } else {
161
+ next = next.replace(
162
+ /(schema_version:\s*\d+)/,
163
+ "$1\nupdate_mode: incremental",
164
+ );
165
+ }
166
+ }
167
+ const upsert = (label, items) => {
168
+ if (!items.length) return;
169
+ const re = new RegExp(
170
+ `${label}:\\s*(\\[\\]|\\n(?:\\s+-\\s+[^\\n]+\\n)*)`,
171
+ );
172
+ const m = next.match(re);
173
+ const existing = new Set();
174
+ if (m) {
175
+ for (const line of m[1].split("\n")) {
176
+ const mm = line.match(/-\s+(.+?)\s*$/);
177
+ if (!mm) continue;
178
+ const scalar = mm[1];
179
+ if (scalar.startsWith('"')) {
180
+ try {
181
+ existing.add(JSON.parse(scalar));
182
+ continue;
183
+ } catch {
184
+ // Fall through to conservative quote trimming.
185
+ }
186
+ }
187
+ existing.add(scalar.replace(/^["']|["']$/g, ""));
188
+ }
189
+ }
190
+ for (const it of items) existing.add(it);
191
+ const body = [...existing]
192
+ .map((i) => ` - ${formatScalar(i)}`)
193
+ .join("\n");
194
+ const block = `${label}:\n${body}\n`;
195
+ if (m) next = next.replace(re, block);
196
+ else next += `\n${block}`;
197
+ };
198
+ upsert("seed_features", args.features);
199
+ upsert("seed_services", args.services);
200
+ upsert("seed_domains", args.domains);
201
+ upsert("include_paths", args.includes);
202
+ return next.endsWith("\n") ? next : `${next}\n`;
203
+ }
204
+
205
+ function resetStaging(root, bootstrapId) {
206
+ const staging = path.join(root, "knowledge/bootstrap/staging");
207
+ if (!fs.existsSync(staging)) {
208
+ fs.mkdirSync(staging, { recursive: true });
209
+ }
210
+ for (const ent of fs.readdirSync(staging, { withFileTypes: true })) {
211
+ if (ent.name === ".gitkeep") continue;
212
+ fs.rmSync(path.join(staging, ent.name), { recursive: true, force: true });
213
+ }
214
+ for (const d of [
215
+ "domains",
216
+ "services",
217
+ "modules",
218
+ "features-links.proposed",
219
+ ]) {
220
+ fs.mkdirSync(path.join(staging, d), { recursive: true });
221
+ }
222
+ fs.writeFileSync(
223
+ path.join(staging, "notes.md"),
224
+ `# staging cleared for incremental run ${bootstrapId}\n`,
225
+ );
226
+ fs.writeFileSync(
227
+ path.join(staging, "edges.proposed.yaml"),
228
+ "schema_version: 1\nedges: []\n",
229
+ );
230
+ fs.writeFileSync(
231
+ path.join(staging, "coverage-notes.md"),
232
+ "# coverage notes (incremental)\n",
233
+ );
234
+ }
235
+
236
+ function main() {
237
+ let args;
238
+ try {
239
+ args = parseArgs(process.argv.slice(2));
240
+ } catch (e) {
241
+ console.error(String(e?.message || e));
242
+ usage(2);
243
+ }
244
+ if (!args.root) {
245
+ console.error("--root is required");
246
+ usage(2);
247
+ }
248
+ if (
249
+ !args.features.length &&
250
+ !args.services.length &&
251
+ !args.domains.length &&
252
+ !args.includes.length
253
+ ) {
254
+ console.error(
255
+ "at least one of --feature / --service / --domain / --include is required",
256
+ );
257
+ process.exit(2);
258
+ }
259
+
260
+ ensureSkeleton(args.root, args.productName);
261
+ const ts = new Date().toISOString();
262
+ const bootstrapId = `BR-INC-${ts.replace(/[-:TZ.]/g, "").slice(0, 14)}`;
263
+ const scopePath = path.join(args.root, "knowledge/bootstrap/scope.yaml");
264
+ const statusPath = path.join(args.root, "knowledge/bootstrap/status.yaml");
265
+ const backupDir = path.join(
266
+ args.root,
267
+ "knowledge/bootstrap/runs",
268
+ bootstrapId,
269
+ );
270
+ fs.mkdirSync(backupDir, { recursive: true });
271
+ fs.copyFileSync(scopePath, path.join(backupDir, "scope.before.yaml"));
272
+ fs.copyFileSync(statusPath, path.join(backupDir, "status.before.yaml"));
273
+
274
+ const includes = buildIncludes(args);
275
+ const product =
276
+ args.productName || path.basename(args.root);
277
+
278
+ if (args.forceScope || !fs.existsSync(scopePath)) {
279
+ const data = {
280
+ schema_version: 1,
281
+ product_name: product,
282
+ primary_language: "zh-CN",
283
+ repo_kind: "single-service",
284
+ update_mode: "incremental",
285
+ include_paths: includes,
286
+ exclude_paths: ["node_modules/**", "dist/**", ".harness/**"],
287
+ id_namespace: {
288
+ domain_prefix: "DOM",
289
+ service_prefix: "SVC",
290
+ api_prefix: "API",
291
+ },
292
+ seed_domains: args.domains,
293
+ seed_services: args.services,
294
+ seed_features: args.features,
295
+ assumptions: [
296
+ "Incremental update: do not rebuild unrelated domains/services",
297
+ ],
298
+ out_of_scope: ["full-repo bootstrap"],
299
+ human_owners: { architect: "", qa: "" },
300
+ };
301
+ fs.writeFileSync(
302
+ scopePath,
303
+ `# Incremental graph scope\n${dumpYaml(data)}\n`,
304
+ );
305
+ } else {
306
+ const merged = mergeSeedsIntoScopeText(
307
+ fs.readFileSync(scopePath, "utf8"),
308
+ args,
309
+ );
310
+ fs.writeFileSync(scopePath, merged);
311
+ }
312
+
313
+ const status = {
314
+ schema_version: 1,
315
+ bootstrap_id: bootstrapId,
316
+ repo_root: ".",
317
+ phase: "B2",
318
+ update_mode: "incremental",
319
+ updated_at: ts,
320
+ scope_ref: "knowledge/bootstrap/scope.yaml",
321
+ inventory_ref: "knowledge/bootstrap/inventory.json",
322
+ last_run_dir: `knowledge/bootstrap/runs/${bootstrapId}/`,
323
+ stats: {
324
+ entities_proposed: 0,
325
+ entities_asserted: 0,
326
+ edges_proposed: 0,
327
+ edges_asserted: 0,
328
+ features_linked: 0,
329
+ },
330
+ blockers: [],
331
+ next_actions: [
332
+ "Review knowledge/bootstrap/scope.yaml (update_mode: incremental)",
333
+ "Run knowledge-graph-bootstrap DAG (propose limited to scope seeds/includes)",
334
+ "Promote merge-new-only; materialize indexes",
335
+ ],
336
+ };
337
+ fs.writeFileSync(
338
+ statusPath,
339
+ `# Incremental bootstrap status\n${dumpYaml(status)}\n`,
340
+ );
341
+
342
+ if (args.resetStaging) resetStaging(args.root, bootstrapId);
343
+
344
+ fs.writeFileSync(
345
+ path.join(backupDir, "README.md"),
346
+ [
347
+ `# Incremental prepare ${bootstrapId}`,
348
+ "",
349
+ `- update_mode: incremental`,
350
+ `- features: ${args.features.join(", ") || "(none)"}`,
351
+ `- services: ${args.services.join(", ") || "(none)"}`,
352
+ `- domains: ${args.domains.join(", ") || "(none)"}`,
353
+ "",
354
+ "Next:",
355
+ "```bash",
356
+ "# task.json: { \"taskKind\": \"knowledge-graph-bootstrap\", ... }",
357
+ "loop-agent dag run-task <task-id> --execute --cwd .",
358
+ `bash scripts/kb-graph-materialize.sh --root ${args.root}`,
359
+ "```",
360
+ "",
361
+ ].join("\n"),
362
+ );
363
+
364
+ console.log(
365
+ JSON.stringify(
366
+ {
367
+ ok: true,
368
+ bootstrap_id: bootstrapId,
369
+ update_mode: "incremental",
370
+ scope: "knowledge/bootstrap/scope.yaml",
371
+ status: "knowledge/bootstrap/status.yaml",
372
+ backup: `knowledge/bootstrap/runs/${bootstrapId}/`,
373
+ seeds: {
374
+ features: args.features,
375
+ services: args.services,
376
+ domains: args.domains,
377
+ },
378
+ next: "set task.json.taskKind=knowledge-graph-bootstrap; dag run-task --execute",
379
+ },
380
+ null,
381
+ 2,
382
+ ),
383
+ );
384
+ }
385
+
386
+ main();