@tea-agent/loop-agent 0.13.0 → 0.14.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 (270) hide show
  1. package/AGENTS.md +157 -157
  2. package/CHANGELOG.md +73 -301
  3. package/README.md +338 -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/docs/README.md +105 -104
  50. package/docs/agent-dag-recovery-playbook.md +195 -195
  51. package/docs/agent-dag-runner.md +67 -67
  52. package/docs/architecture/README.md +26 -26
  53. package/docs/architecture/dag-execution.md +140 -140
  54. package/docs/architecture/evolution.md +54 -54
  55. package/docs/architecture/facts-and-state.md +71 -71
  56. package/docs/architecture/runtime-boundaries.md +191 -191
  57. package/docs/architecture/system-overview.md +93 -93
  58. package/docs/architecture/worker-and-feature.md +85 -85
  59. package/docs/cursor-prompt-sidecar.md +36 -36
  60. package/docs/decisions/README.md +18 -18
  61. package/docs/design/README.md +167 -167
  62. package/docs/development-principles.md +73 -73
  63. package/docs/exec-plans/README.md +6 -6
  64. package/docs/exec-plans/active/README.md +2 -1
  65. package/docs/exec-plans/completed/README.md +105 -104
  66. package/docs/feature-workflow.md +414 -414
  67. package/docs/harness-methodology-debugging.md +153 -153
  68. package/docs/harness-methodology-tdd.md +130 -130
  69. package/docs/harness-methodology-verification.md +27 -27
  70. package/docs/init-surface.manifest.json +307 -307
  71. package/docs/loop-agent-harness.md +142 -142
  72. package/docs/production-readiness.md +96 -96
  73. package/docs/progress/README.md +59 -58
  74. package/docs/reports/README.md +123 -119
  75. package/docs/skills/README.md +7 -7
  76. package/docs/skills/vetted-skill-registry.md +29 -29
  77. package/docs/templates/adr.md +60 -60
  78. package/docs/templates/agent-dag-authority-surface-audit.prompt.md +94 -94
  79. package/docs/templates/agent-dag-decision-envelope.schema.json +213 -213
  80. package/docs/templates/agent-dag-decision-gate-dogfood-report.md +117 -117
  81. package/docs/templates/agent-dag-decision-gate.prompt.md +246 -246
  82. package/docs/templates/agent-dag-process-supervisor.prompt.md +98 -98
  83. package/docs/templates/agent-dag-report.schema.json +473 -473
  84. package/docs/templates/agent-dag-review-verdict.prompt.md +68 -68
  85. package/docs/templates/agent-dag.base.json +190 -190
  86. package/docs/templates/agent-dag.final-verification.json +185 -185
  87. package/docs/templates/agent-dag.schema.json +411 -411
  88. package/docs/templates/agent-dag.supervised-implementation.json +620 -620
  89. package/docs/templates/backend-test-analysis.schema.json +44 -44
  90. package/docs/templates/backend-test-case-manifest.schema.json +190 -190
  91. package/docs/templates/backend-test-dag.classify.prompt.md +75 -75
  92. package/docs/templates/backend-test-dag.generate-pytest.prompt.md +204 -204
  93. package/docs/templates/backend-test-dag.json +559 -559
  94. package/docs/templates/backend-test-dag.retrospect.prompt.md +139 -139
  95. package/docs/templates/backend-test-dag.review-cases.prompt.md +83 -83
  96. package/docs/templates/backend-test-execution.schema.json +133 -133
  97. package/docs/templates/backend-test-result.schema.json +99 -99
  98. package/docs/templates/exec-plan.md +64 -64
  99. package/docs/templates/feature-spec.md +53 -53
  100. package/docs/templates/frontend-design-contract.md +42 -42
  101. package/docs/templates/frontend-eval/fixtures/failures/01-type-build-error.md +17 -17
  102. package/docs/templates/frontend-eval/fixtures/failures/02-unit-component-test-fail.md +16 -16
  103. package/docs/templates/frontend-eval/fixtures/failures/03-fixture-schema-drift.md +16 -16
  104. package/docs/templates/frontend-eval/fixtures/failures/04-missing-loading-empty-error-state.md +16 -16
  105. package/docs/templates/frontend-eval/fixtures/failures/05-forbidden-write-writeset-expansion.md +16 -16
  106. package/docs/templates/frontend-eval/fixtures/failures/06-unapproved-dependency-add.md +16 -16
  107. package/docs/templates/frontend-eval/fixtures/failures/07-mock-production-on.md +21 -21
  108. package/docs/templates/frontend-eval/fixtures/functional/01-simple-component-style.md +29 -29
  109. package/docs/templates/frontend-eval/fixtures/functional/02-form-validation.md +28 -28
  110. package/docs/templates/frontend-eval/fixtures/functional/03-list-detail-page.md +28 -28
  111. package/docs/templates/frontend-eval/fixtures/functional/04-api-mock.md +29 -29
  112. package/docs/templates/frontend-eval/fixtures/functional/05-permission-auth-gated-ui.md +27 -27
  113. package/docs/templates/frontend-eval/fixtures/functional/06-ssr-server-client-boundary.md +28 -28
  114. package/docs/templates/frontend-eval/fixtures/functional/07-shared-public-component-api.md +28 -28
  115. package/docs/templates/frontend-eval/fixtures/functional/08-pure-local-no-remote.md +27 -27
  116. package/docs/templates/frontend-eval/metrics.md +138 -138
  117. package/docs/templates/frontend-eval/smoke-targets.md +53 -53
  118. package/docs/templates/frontend-implementation-contract.schema.json +27 -27
  119. package/docs/templates/frontend-task-constraints.md +35 -35
  120. package/docs/templates/frontend-task-requirement.md +70 -70
  121. package/docs/templates/frontend-test-dag.generate-cases.prompt.md +5 -5
  122. package/docs/templates/frontend-test-dag.json +23 -23
  123. package/docs/templates/frontend-test-dag.retrieve-context.prompt.md +3 -3
  124. package/docs/templates/frontend-test-dag.retrospect.prompt.md +3 -3
  125. package/docs/templates/frontend-test-dag.review-cases.prompt.md +3 -3
  126. package/docs/templates/frontend-test-dag.review-execution.prompt.md +3 -3
  127. package/docs/templates/harness.schema.json +221 -221
  128. package/docs/templates/hybrid-dag.json +188 -188
  129. package/docs/templates/init-evolution-review.md +35 -35
  130. package/docs/templates/interactive-ui-round2-experiment.md +66 -66
  131. package/docs/templates/knowledge-graph-bootstrap-dag.json +118 -118
  132. package/docs/templates/knowledge-sync-dag.json +178 -178
  133. package/docs/templates/knowledge-sync-draft.schema.json +71 -71
  134. package/docs/templates/product-line/AGENTS.md +8 -8
  135. package/docs/templates/product-line/README.md +9 -9
  136. package/docs/templates/product-line/acceptance.yaml +14 -14
  137. package/docs/templates/product-line/closeout.yaml +9 -9
  138. package/docs/templates/product-line/design.md +13 -13
  139. package/docs/templates/product-line/links.md +10 -10
  140. package/docs/templates/product-line/requirement.md +17 -17
  141. package/docs/templates/product-line/task-graph.yaml +15 -15
  142. package/docs/templates/product-line/task.yaml +64 -64
  143. package/docs/templates/product-line/test-plan.md +7 -7
  144. package/docs/templates/production-readiness-checklist.md +57 -57
  145. package/docs/templates/progress-log.md +17 -17
  146. package/docs/templates/project-start-checklist.md +9 -9
  147. package/docs/templates/qa-report.md +48 -48
  148. package/docs/templates/sprint-contract.md +29 -29
  149. package/docs/templates/worker-dogfood-evidence.md +80 -80
  150. package/docs/templates/worker-dogfood-setup.md +68 -68
  151. package/docs/verification-matrix.md +70 -70
  152. package/examples/decision-gate-agent-dag.json +173 -173
  153. package/examples/example-dag.json +46 -46
  154. package/examples/hybrid-loop-agent-dag.json +188 -188
  155. package/harness.json +66 -66
  156. package/package.json +88 -52
  157. package/scripts/check-product-line-docs.sh +29 -29
  158. package/scripts/check-task-pool-root.sh +32 -32
  159. package/scripts/kb-bootstrap-init-skeleton.sh +240 -240
  160. package/scripts/kb-graph-incremental-prepare.mjs +386 -386
  161. package/scripts/kb-graph-incremental-prepare.sh +5 -5
  162. package/scripts/kb-graph-materialize.mjs +105 -105
  163. package/scripts/kb-graph-materialize.sh +4 -4
  164. package/scripts/kb-graph-promote.mjs +164 -164
  165. package/scripts/kb-graph-promote.sh +4 -4
  166. package/scripts/kb-query.mjs +554 -554
  167. package/scripts/kb-query.sh +5 -5
  168. package/skills/agent-worker/SKILL.md +39 -39
  169. package/skills/agent-worker/references/agent-worker-operator.md +60 -60
  170. package/skills/ai-engineering-context/SKILL.md +48 -48
  171. package/skills/analyze-product-dependencies/SKILL.md +67 -67
  172. package/skills/analyze-product-dependencies/agents/openai.yaml +4 -4
  173. package/skills/analyze-product-dependencies/references/api-documentation-schema.md +30 -30
  174. package/skills/analyze-product-dependencies/references/dependency-analysis-schema.md +28 -28
  175. package/skills/analyze-product-dependencies/references/example.md +76 -76
  176. package/skills/analyze-product-dependencies/references/forward-test-cases.md +35 -35
  177. package/skills/analyze-product-dependencies/references/input-contract.md +11 -11
  178. package/skills/analyze-product-dependencies/references/scouting-rules.md +61 -61
  179. package/skills/analyze-product-dependencies/scripts/test-validators.mjs +267 -267
  180. package/skills/analyze-product-dependencies/scripts/validate-api-documentation.mjs +101 -101
  181. package/skills/analyze-product-dependencies/scripts/validate-dependency-analysis.mjs +142 -142
  182. package/skills/analyze-product-dependencies/scripts/validate-product-requirement-input.mjs +76 -76
  183. package/skills/analyze-product-dependencies/scripts/validation-helpers.mjs +146 -146
  184. package/skills/analyze-product-requirements/SKILL.md +90 -90
  185. package/skills/analyze-product-requirements/agents/openai.yaml +4 -4
  186. package/skills/analyze-product-requirements/references/acceptance-criteria.md +91 -91
  187. package/skills/analyze-product-requirements/references/clarification-and-knowledge.md +56 -56
  188. package/skills/analyze-product-requirements/references/example.md +86 -86
  189. package/skills/analyze-product-requirements/references/forward-test-cases.md +66 -66
  190. package/skills/analyze-product-requirements/references/product-analysis-schema.md +32 -32
  191. package/skills/analyze-product-requirements/references/product-requirement-schema.md +33 -33
  192. package/skills/analyze-product-requirements/references/requirement-clarification-schema.md +35 -35
  193. package/skills/analyze-product-requirements/scripts/test-validators.mjs +193 -193
  194. package/skills/analyze-product-requirements/scripts/validate-product-analysis.mjs +69 -69
  195. package/skills/analyze-product-requirements/scripts/validate-product-requirement.mjs +97 -97
  196. package/skills/analyze-product-requirements/scripts/validate-requirement-clarification.mjs +98 -98
  197. package/skills/analyze-product-requirements/scripts/validation-helpers.mjs +156 -156
  198. package/skills/browser-tools/SKILL.md +196 -196
  199. package/skills/browser-tools/browser-content.js +103 -103
  200. package/skills/browser-tools/browser-cookies.js +35 -35
  201. package/skills/browser-tools/browser-eval.js +53 -53
  202. package/skills/browser-tools/browser-hn-scraper.js +108 -108
  203. package/skills/browser-tools/browser-nav.js +44 -44
  204. package/skills/browser-tools/browser-pick.js +162 -162
  205. package/skills/browser-tools/browser-screenshot.js +34 -34
  206. package/skills/browser-tools/browser-start.js +86 -86
  207. package/skills/browser-tools/package-lock.json +2556 -2556
  208. package/skills/browser-tools/package.json +19 -19
  209. package/skills/code-review-core/SKILL.md +20 -20
  210. package/skills/codebase-scout/SKILL.md +19 -19
  211. package/skills/frontend-design-review/SKILL.md +66 -66
  212. package/skills/frontend-design-review/references/review-checklist.md +58 -58
  213. package/skills/frontend-implementation/SKILL.md +49 -49
  214. package/skills/frontend-implementation/references/code-standards.md +32 -32
  215. package/skills/frontend-implementation/references/design-spec.md +46 -46
  216. package/skills/frontend-implementation/references/node-contracts.md +27 -27
  217. package/skills/frontend-review/SKILL.md +59 -59
  218. package/skills/frontend-review/references/review-findings.md +47 -47
  219. package/skills/frontend-verification/SKILL.md +53 -53
  220. package/skills/frontend-verification/references/verification-checklist.md +68 -68
  221. package/skills/grill-me/SKILL.md +10 -10
  222. package/skills/grill-with-docs/SKILL.md +88 -88
  223. package/skills/grill-with-docs/adr-format.md +47 -47
  224. package/skills/grill-with-docs/context-format.md +60 -60
  225. package/skills/init-capability-evolution/SKILL.md +70 -70
  226. package/skills/loop-agent/SKILL.md +151 -151
  227. package/skills/loop-agent/references/README.md +67 -67
  228. package/skills/loop-agent/references/command-reference.md +527 -527
  229. package/skills/loop-agent/references/docs-converge.md +126 -126
  230. package/skills/loop-agent/references/harness-policy.md +263 -263
  231. package/skills/loop-agent/references/hybrid-dag.md +243 -243
  232. package/skills/loop-agent/references/learned/README.md +21 -21
  233. package/skills/loop-agent/references/long-running-loop.md +57 -57
  234. package/skills/loop-agent/references/model-routing.md +36 -36
  235. package/skills/loop-agent/references/multi-worktree.md +54 -54
  236. package/skills/loop-agent/references/one-shot-runs.md +85 -85
  237. package/skills/loop-agent/references/orchestrator-and-interventions.md +169 -169
  238. package/skills/loop-agent/references/pi-prompt.md +23 -23
  239. package/skills/loop-agent/references/pi-subagent-assisted-mode.md +84 -84
  240. package/skills/loop-agent/references/post-implementation-and-patterns.md +44 -44
  241. package/skills/loop-agent/references/task-workflow.md +89 -89
  242. package/skills/loop-agent/references/verification-and-failure-handling.md +141 -141
  243. package/skills/playwright-cli/SKILL.md +420 -420
  244. package/skills/playwright-cli/references/element-attributes.md +23 -23
  245. package/skills/playwright-cli/references/playwright-tests.md +39 -39
  246. package/skills/playwright-cli/references/request-mocking.md +87 -87
  247. package/skills/playwright-cli/references/running-code.md +241 -241
  248. package/skills/playwright-cli/references/session-management.md +225 -225
  249. package/skills/playwright-cli/references/storage-state.md +275 -275
  250. package/skills/playwright-cli/references/test-generation.md +433 -433
  251. package/skills/playwright-cli/references/tracing.md +139 -139
  252. package/skills/playwright-cli/references/video-recording.md +143 -143
  253. package/skills/playwright-cli-case-generator/SKILL.md +74 -74
  254. package/skills/requesting-code-review/SKILL.md +101 -101
  255. package/skills/requesting-code-review/code-reviewer.md +168 -168
  256. package/skills/systematic-debugging/CREATION-LOG.md +119 -119
  257. package/skills/systematic-debugging/SKILL.md +296 -296
  258. package/skills/systematic-debugging/condition-based-waiting-example.ts +158 -158
  259. package/skills/systematic-debugging/condition-based-waiting.md +115 -115
  260. package/skills/systematic-debugging/defense-in-depth.md +122 -122
  261. package/skills/systematic-debugging/find-polluter.sh +63 -63
  262. package/skills/systematic-debugging/root-cause-tracing.md +169 -169
  263. package/skills/systematic-debugging/test-academic.md +14 -14
  264. package/skills/systematic-debugging/test-pressure-1.md +58 -58
  265. package/skills/systematic-debugging/test-pressure-2.md +68 -68
  266. package/skills/systematic-debugging/test-pressure-3.md +69 -69
  267. package/skills/test-driven-development/SKILL.md +20 -20
  268. package/skills/using-git-worktrees/SKILL.md +215 -215
  269. package/skills/verification-before-completion/SKILL.md +154 -154
  270. package/skills/webapp-testing/SKILL.md +19 -19
@@ -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();