@tea-agent/loop-agent 0.13.0-alpha.0 → 0.13.0-beta.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 (262) hide show
  1. package/AGENTS.md +155 -153
  2. package/CHANGELOG.md +326 -301
  3. package/README.md +345 -326
  4. package/bin/agent-worker.js +22 -22
  5. package/bin/loop-agent.js +21 -21
  6. package/dist/application/dag/generate-task-dag.js +28 -58
  7. package/dist/application/evaluation/candidate-hash.js +75 -0
  8. package/dist/application/evaluation/candidate.js +52 -0
  9. package/dist/application/evaluation/replay.js +289 -0
  10. package/dist/application/evaluation/types.js +130 -0
  11. package/dist/cli/command-definitions.js +17 -4
  12. package/dist/cli/program.js +8 -4
  13. package/dist/commands/cursor-prompt.js +6 -6
  14. package/dist/commands/eval.js +235 -0
  15. package/dist/commands/init.js +544 -506
  16. package/dist/commands/loop-benchmark.js +11 -11
  17. package/dist/commands/pi-reuse-benchmark.js +16 -16
  18. package/dist/executors/pi-sdk-executor.js +38 -24
  19. package/dist/executors/shell-executor.js +34 -2
  20. package/dist/executors/shell-presets.js +20 -0
  21. package/dist/executors/shell-verification.js +7 -0
  22. package/dist/governance/manifest-types.js +1 -0
  23. package/dist/infrastructure/evaluation/candidate-store.js +435 -0
  24. package/dist/infrastructure/evaluation/store.js +40 -0
  25. package/dist/sidecars/cursor-prompt/executor.js +1 -1
  26. package/dist/task/config-types.js +23 -0
  27. package/dist/task/runtime.js +27 -27
  28. package/dist/worker/observe/routes.js +18 -3
  29. package/dist/worker/observe/spec-evidence.js +1 -1
  30. package/dist/worker/observe/static/api.js +46 -46
  31. package/dist/worker/observe/static/app.js +150 -150
  32. package/dist/worker/observe/static/constants.js +148 -148
  33. package/dist/worker/observe/static/copy.js +67 -67
  34. package/dist/worker/observe/static/dag-helpers.js +172 -172
  35. package/dist/worker/observe/static/dag-layout.d.ts +31 -31
  36. package/dist/worker/observe/static/dag-layout.js +83 -83
  37. package/dist/worker/observe/static/dag-model.js +72 -72
  38. package/dist/worker/observe/static/dom.js +61 -61
  39. package/dist/worker/observe/static/format-pool.js +67 -67
  40. package/dist/worker/observe/static/format.js +292 -292
  41. package/dist/worker/observe/static/index.html +308 -308
  42. package/dist/worker/observe/static/kpi.js +94 -94
  43. package/dist/worker/observe/static/relations.js +133 -133
  44. package/dist/worker/observe/static/router.js +93 -93
  45. package/dist/worker/observe/static/run-processing.js +148 -148
  46. package/dist/worker/observe/static/shell-chrome.js +68 -68
  47. package/dist/worker/observe/static/state.js +253 -253
  48. package/dist/worker/observe/static/styles.css +1902 -1902
  49. package/dist/worker/observe/static/views/batch.js +227 -227
  50. package/dist/worker/observe/static/views/dag-graph.js +172 -172
  51. package/dist/worker/observe/static/views/dag-inspector.js +607 -596
  52. package/dist/worker/observe/static/views/dag.js +362 -362
  53. package/dist/worker/observe/static/views/dashboard.js +445 -445
  54. package/dist/worker/observe/static/views/failures.js +143 -143
  55. package/dist/worker/observe/static/views/feature.js +492 -492
  56. package/dist/worker/observe/static/views/pool.js +350 -350
  57. package/dist/worker/observe/static/views/run.js +453 -453
  58. package/dist/worker/observe/static/views/session-timeline.js +205 -205
  59. package/dist/worker/observe/static/views/shell.js +7 -7
  60. package/dist/worker/observe/static/views/task.js +314 -314
  61. package/dist/worker/observe/static/views/timeline.js +163 -163
  62. package/dist/workflows/dag/backend-test-analysis-contract.js +120 -0
  63. package/dist/workflows/dag/canvas-observer.js +275 -275
  64. package/dist/workflows/dag/dynamic-runtime/map.js +90 -2
  65. package/dist/workflows/dag/init-hybrid.js +1415 -200
  66. package/dist/workflows/dag/node-execution.js +9 -0
  67. package/dist/workflows/dag/prompt.js +9 -0
  68. package/dist/workflows/dag/report.js +35 -1
  69. package/dist/workflows/dag/runner.js +28 -2
  70. package/dist/workflows/dag/task-demand-routing.js +383 -0
  71. package/dist/workflows/dag/types.js +50 -13
  72. package/dist/workflows/dag/upstream-artifacts.js +1 -0
  73. package/dist/workflows/dag/validate.js +59 -1
  74. package/docs/README.md +106 -104
  75. package/docs/agent-dag-recovery-playbook.md +195 -193
  76. package/docs/agent-dag-runner.md +67 -67
  77. package/docs/architecture/README.md +26 -26
  78. package/docs/architecture/dag-execution.md +140 -140
  79. package/docs/architecture/evolution.md +54 -54
  80. package/docs/architecture/facts-and-state.md +71 -71
  81. package/docs/architecture/runtime-boundaries.md +191 -191
  82. package/docs/architecture/system-overview.md +93 -93
  83. package/docs/architecture/worker-and-feature.md +85 -85
  84. package/docs/cursor-prompt-sidecar.md +36 -36
  85. package/docs/decisions/README.md +18 -18
  86. package/docs/design/README.md +167 -85
  87. package/docs/development-principles.md +73 -73
  88. package/docs/exec-plans/README.md +6 -6
  89. package/docs/exec-plans/active/README.md +15 -11
  90. package/docs/exec-plans/completed/README.md +85 -74
  91. package/docs/feature-workflow.md +389 -339
  92. package/docs/harness-methodology-debugging.md +153 -153
  93. package/docs/harness-methodology-tdd.md +130 -130
  94. package/docs/harness-methodology-verification.md +27 -27
  95. package/docs/init-surface.manifest.json +289 -280
  96. package/docs/loop-agent-harness.md +142 -141
  97. package/docs/production-readiness.md +96 -96
  98. package/docs/progress/README.md +64 -58
  99. package/docs/reports/README.md +117 -100
  100. package/docs/skills/README.md +7 -7
  101. package/docs/skills/vetted-skill-registry.md +29 -27
  102. package/docs/templates/adr.md +60 -60
  103. package/docs/templates/agent-dag-authority-surface-audit.prompt.md +94 -94
  104. package/docs/templates/agent-dag-decision-envelope.schema.json +213 -213
  105. package/docs/templates/agent-dag-decision-gate-dogfood-report.md +117 -117
  106. package/docs/templates/agent-dag-decision-gate.prompt.md +246 -246
  107. package/docs/templates/agent-dag-process-supervisor.prompt.md +98 -98
  108. package/docs/templates/agent-dag-report.schema.json +473 -473
  109. package/docs/templates/agent-dag-review-verdict.prompt.md +68 -68
  110. package/docs/templates/agent-dag.base.json +190 -190
  111. package/docs/templates/agent-dag.final-verification.json +185 -185
  112. package/docs/templates/agent-dag.schema.json +411 -383
  113. package/docs/templates/agent-dag.supervised-implementation.json +501 -501
  114. package/docs/templates/backend-test-analysis.schema.json +44 -0
  115. package/docs/templates/backend-test-dag.generate-pytest.prompt.md +202 -139
  116. package/docs/templates/backend-test-dag.json +311 -288
  117. package/docs/templates/backend-test-dag.retrospect.prompt.md +125 -125
  118. package/docs/templates/backend-test-dag.review-cases.prompt.md +81 -81
  119. package/docs/templates/exec-plan.md +64 -64
  120. package/docs/templates/feature-spec.md +53 -53
  121. package/docs/templates/frontend-design-contract.md +42 -33
  122. package/docs/templates/frontend-task-constraints.md +35 -25
  123. package/docs/templates/frontend-task-requirement.md +70 -61
  124. package/docs/templates/frontend-test-dag.generate-cases.prompt.md +5 -0
  125. package/docs/templates/frontend-test-dag.json +23 -0
  126. package/docs/templates/frontend-test-dag.retrieve-context.prompt.md +3 -0
  127. package/docs/templates/frontend-test-dag.retrospect.prompt.md +3 -0
  128. package/docs/templates/frontend-test-dag.review-cases.prompt.md +3 -0
  129. package/docs/templates/frontend-test-dag.review-execution.prompt.md +3 -0
  130. package/docs/templates/harness.schema.json +221 -221
  131. package/docs/templates/hybrid-dag.json +188 -188
  132. package/docs/templates/init-evolution-review.md +35 -35
  133. package/docs/templates/interactive-ui-round2-experiment.md +66 -66
  134. package/docs/templates/knowledge-graph-bootstrap-dag.json +118 -118
  135. package/docs/templates/knowledge-sync-dag.json +178 -177
  136. package/docs/templates/knowledge-sync-draft.schema.json +71 -71
  137. package/docs/templates/product-line/AGENTS.md +8 -8
  138. package/docs/templates/product-line/README.md +9 -9
  139. package/docs/templates/product-line/acceptance.yaml +14 -14
  140. package/docs/templates/product-line/closeout.yaml +9 -9
  141. package/docs/templates/product-line/design.md +13 -13
  142. package/docs/templates/product-line/links.md +10 -10
  143. package/docs/templates/product-line/requirement.md +17 -17
  144. package/docs/templates/product-line/task-graph.yaml +15 -15
  145. package/docs/templates/product-line/task.yaml +64 -64
  146. package/docs/templates/product-line/test-plan.md +7 -7
  147. package/docs/templates/production-readiness-checklist.md +57 -57
  148. package/docs/templates/progress-log.md +17 -17
  149. package/docs/templates/project-start-checklist.md +9 -9
  150. package/docs/templates/qa-report.md +48 -48
  151. package/docs/templates/sprint-contract.md +29 -29
  152. package/docs/templates/worker-dogfood-evidence.md +80 -80
  153. package/docs/templates/worker-dogfood-setup.md +68 -68
  154. package/docs/verification-matrix.md +70 -67
  155. package/examples/decision-gate-agent-dag.json +177 -177
  156. package/examples/example-dag.json +46 -46
  157. package/examples/hybrid-loop-agent-dag.json +189 -189
  158. package/harness.json +66 -66
  159. package/package.json +88 -52
  160. package/scripts/check-product-line-docs.sh +29 -29
  161. package/scripts/check-task-pool-root.sh +32 -32
  162. package/scripts/kb-bootstrap-init-skeleton.sh +240 -239
  163. package/scripts/kb-graph-incremental-prepare.mjs +386 -372
  164. package/scripts/kb-graph-incremental-prepare.sh +5 -5
  165. package/scripts/kb-graph-materialize.mjs +105 -105
  166. package/scripts/kb-graph-materialize.sh +4 -4
  167. package/scripts/kb-graph-promote.mjs +164 -153
  168. package/scripts/kb-graph-promote.sh +4 -4
  169. package/scripts/kb-query.mjs +554 -554
  170. package/scripts/kb-query.sh +5 -5
  171. package/skills/agent-worker/SKILL.md +39 -39
  172. package/skills/agent-worker/references/agent-worker-operator.md +60 -60
  173. package/skills/ai-engineering-context/SKILL.md +48 -48
  174. package/skills/analyze-product-dependencies/SKILL.md +67 -0
  175. package/skills/analyze-product-dependencies/agents/openai.yaml +4 -0
  176. package/skills/analyze-product-dependencies/references/api-documentation-schema.md +30 -0
  177. package/skills/analyze-product-dependencies/references/dependency-analysis-schema.md +28 -0
  178. package/skills/analyze-product-dependencies/references/example.md +76 -0
  179. package/skills/analyze-product-dependencies/references/forward-test-cases.md +35 -0
  180. package/skills/analyze-product-dependencies/references/input-contract.md +11 -0
  181. package/skills/analyze-product-dependencies/references/scouting-rules.md +61 -0
  182. package/skills/analyze-product-dependencies/scripts/test-validators.mjs +267 -0
  183. package/skills/analyze-product-dependencies/scripts/validate-api-documentation.mjs +101 -0
  184. package/skills/analyze-product-dependencies/scripts/validate-dependency-analysis.mjs +142 -0
  185. package/skills/analyze-product-dependencies/scripts/validate-product-requirement-input.mjs +76 -0
  186. package/skills/analyze-product-dependencies/scripts/validation-helpers.mjs +146 -0
  187. package/skills/analyze-product-requirements/SKILL.md +90 -0
  188. package/skills/analyze-product-requirements/agents/openai.yaml +4 -0
  189. package/skills/analyze-product-requirements/references/acceptance-criteria.md +91 -0
  190. package/skills/analyze-product-requirements/references/clarification-and-knowledge.md +56 -0
  191. package/skills/analyze-product-requirements/references/example.md +86 -0
  192. package/skills/analyze-product-requirements/references/forward-test-cases.md +66 -0
  193. package/skills/analyze-product-requirements/references/product-analysis-schema.md +32 -0
  194. package/skills/analyze-product-requirements/references/product-requirement-schema.md +33 -0
  195. package/skills/analyze-product-requirements/references/requirement-clarification-schema.md +35 -0
  196. package/skills/analyze-product-requirements/scripts/test-validators.mjs +193 -0
  197. package/skills/analyze-product-requirements/scripts/validate-product-analysis.mjs +69 -0
  198. package/skills/analyze-product-requirements/scripts/validate-product-requirement.mjs +97 -0
  199. package/skills/analyze-product-requirements/scripts/validate-requirement-clarification.mjs +98 -0
  200. package/skills/analyze-product-requirements/scripts/validation-helpers.mjs +156 -0
  201. package/skills/code-review-core/SKILL.md +20 -20
  202. package/skills/codebase-scout/SKILL.md +19 -19
  203. package/skills/frontend-design-review/SKILL.md +66 -61
  204. package/skills/frontend-design-review/references/review-checklist.md +58 -37
  205. package/skills/frontend-implementation/SKILL.md +45 -52
  206. package/skills/frontend-implementation/references/code-standards.md +32 -34
  207. package/skills/frontend-implementation/references/design-spec.md +46 -46
  208. package/skills/frontend-implementation/references/node-contracts.md +76 -63
  209. package/skills/frontend-review/SKILL.md +59 -53
  210. package/skills/frontend-review/references/review-findings.md +47 -42
  211. package/skills/frontend-verification/SKILL.md +53 -40
  212. package/skills/frontend-verification/references/verification-checklist.md +68 -56
  213. package/skills/grill-me/SKILL.md +10 -10
  214. package/skills/grill-with-docs/SKILL.md +88 -88
  215. package/skills/grill-with-docs/adr-format.md +47 -47
  216. package/skills/grill-with-docs/context-format.md +60 -60
  217. package/skills/init-capability-evolution/SKILL.md +70 -70
  218. package/skills/loop-agent/SKILL.md +151 -151
  219. package/skills/loop-agent/references/README.md +67 -67
  220. package/skills/loop-agent/references/command-reference.md +505 -453
  221. package/skills/loop-agent/references/docs-converge.md +126 -126
  222. package/skills/loop-agent/references/harness-policy.md +263 -263
  223. package/skills/loop-agent/references/hybrid-dag.md +238 -233
  224. package/skills/loop-agent/references/learned/README.md +21 -21
  225. package/skills/loop-agent/references/long-running-loop.md +57 -57
  226. package/skills/loop-agent/references/model-routing.md +36 -36
  227. package/skills/loop-agent/references/multi-worktree.md +54 -54
  228. package/skills/loop-agent/references/one-shot-runs.md +85 -85
  229. package/skills/loop-agent/references/orchestrator-and-interventions.md +169 -169
  230. package/skills/loop-agent/references/pi-prompt.md +23 -23
  231. package/skills/loop-agent/references/pi-subagent-assisted-mode.md +84 -84
  232. package/skills/loop-agent/references/post-implementation-and-patterns.md +44 -44
  233. package/skills/loop-agent/references/task-workflow.md +89 -89
  234. package/skills/loop-agent/references/verification-and-failure-handling.md +139 -139
  235. package/skills/playwright-cli/SKILL.md +420 -0
  236. package/skills/playwright-cli/references/element-attributes.md +23 -0
  237. package/skills/playwright-cli/references/playwright-tests.md +39 -0
  238. package/skills/playwright-cli/references/request-mocking.md +87 -0
  239. package/skills/playwright-cli/references/running-code.md +241 -0
  240. package/skills/playwright-cli/references/session-management.md +225 -0
  241. package/skills/playwright-cli/references/storage-state.md +275 -0
  242. package/skills/playwright-cli/references/test-generation.md +433 -0
  243. package/skills/playwright-cli/references/tracing.md +139 -0
  244. package/skills/playwright-cli/references/video-recording.md +143 -0
  245. package/skills/playwright-cli-case-generator/SKILL.md +74 -0
  246. package/skills/requesting-code-review/SKILL.md +101 -101
  247. package/skills/requesting-code-review/code-reviewer.md +168 -168
  248. package/skills/systematic-debugging/CREATION-LOG.md +119 -119
  249. package/skills/systematic-debugging/SKILL.md +296 -296
  250. package/skills/systematic-debugging/condition-based-waiting-example.ts +158 -158
  251. package/skills/systematic-debugging/condition-based-waiting.md +115 -115
  252. package/skills/systematic-debugging/defense-in-depth.md +122 -122
  253. package/skills/systematic-debugging/find-polluter.sh +63 -63
  254. package/skills/systematic-debugging/root-cause-tracing.md +169 -169
  255. package/skills/systematic-debugging/test-academic.md +14 -14
  256. package/skills/systematic-debugging/test-pressure-1.md +58 -58
  257. package/skills/systematic-debugging/test-pressure-2.md +68 -68
  258. package/skills/systematic-debugging/test-pressure-3.md +69 -69
  259. package/skills/test-driven-development/SKILL.md +20 -20
  260. package/skills/using-git-worktrees/SKILL.md +215 -215
  261. package/skills/verification-before-completion/SKILL.md +154 -154
  262. package/skills/webapp-testing/SKILL.md +19 -19
@@ -1,372 +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) existing.add(mm[1].replace(/^["']|["']$/g, ""));
178
- }
179
- }
180
- for (const it of items) existing.add(it);
181
- const body = [...existing].map((i) => ` - ${i}`).join("\n");
182
- const block = `${label}:\n${body}\n`;
183
- if (m) next = next.replace(re, block);
184
- else next += `\n${block}`;
185
- };
186
- upsert("seed_features", args.features);
187
- upsert("seed_services", args.services);
188
- upsert("seed_domains", args.domains);
189
- return next.endsWith("\n") ? next : `${next}\n`;
190
- }
191
-
192
- function resetStaging(root, bootstrapId) {
193
- const staging = path.join(root, "knowledge/bootstrap/staging");
194
- if (!fs.existsSync(staging)) {
195
- fs.mkdirSync(staging, { recursive: true });
196
- }
197
- for (const ent of fs.readdirSync(staging, { withFileTypes: true })) {
198
- if (ent.name === ".gitkeep") continue;
199
- fs.rmSync(path.join(staging, ent.name), { recursive: true, force: true });
200
- }
201
- for (const d of [
202
- "domains",
203
- "services",
204
- "modules",
205
- "features-links.proposed",
206
- ]) {
207
- fs.mkdirSync(path.join(staging, d), { recursive: true });
208
- }
209
- fs.writeFileSync(
210
- path.join(staging, "notes.md"),
211
- `# staging cleared for incremental run ${bootstrapId}\n`,
212
- );
213
- fs.writeFileSync(
214
- path.join(staging, "edges.proposed.yaml"),
215
- "schema_version: 1\nedges: []\n",
216
- );
217
- fs.writeFileSync(
218
- path.join(staging, "coverage-notes.md"),
219
- "# coverage notes (incremental)\n",
220
- );
221
- }
222
-
223
- function main() {
224
- let args;
225
- try {
226
- args = parseArgs(process.argv.slice(2));
227
- } catch (e) {
228
- console.error(String(e?.message || e));
229
- usage(2);
230
- }
231
- if (!args.root) {
232
- console.error("--root is required");
233
- usage(2);
234
- }
235
- if (
236
- !args.features.length &&
237
- !args.services.length &&
238
- !args.domains.length &&
239
- !args.includes.length
240
- ) {
241
- console.error(
242
- "at least one of --feature / --service / --domain / --include is required",
243
- );
244
- process.exit(2);
245
- }
246
-
247
- ensureSkeleton(args.root, args.productName);
248
- const ts = new Date().toISOString();
249
- const bootstrapId = `BR-INC-${ts.replace(/[-:TZ.]/g, "").slice(0, 14)}`;
250
- const scopePath = path.join(args.root, "knowledge/bootstrap/scope.yaml");
251
- const statusPath = path.join(args.root, "knowledge/bootstrap/status.yaml");
252
- const backupDir = path.join(
253
- args.root,
254
- "knowledge/bootstrap/runs",
255
- bootstrapId,
256
- );
257
- fs.mkdirSync(backupDir, { recursive: true });
258
- fs.copyFileSync(scopePath, path.join(backupDir, "scope.before.yaml"));
259
- fs.copyFileSync(statusPath, path.join(backupDir, "status.before.yaml"));
260
-
261
- const includes = buildIncludes(args);
262
- const product =
263
- args.productName || path.basename(args.root);
264
-
265
- if (args.forceScope || !fs.existsSync(scopePath)) {
266
- const data = {
267
- schema_version: 1,
268
- product_name: product,
269
- primary_language: "zh-CN",
270
- repo_kind: "single-service",
271
- update_mode: "incremental",
272
- include_paths: includes,
273
- exclude_paths: ["node_modules/**", "dist/**", ".harness/**"],
274
- id_namespace: {
275
- domain_prefix: "DOM",
276
- service_prefix: "SVC",
277
- api_prefix: "API",
278
- },
279
- seed_domains: args.domains,
280
- seed_services: args.services,
281
- seed_features: args.features,
282
- assumptions: [
283
- "Incremental update: do not rebuild unrelated domains/services",
284
- ],
285
- out_of_scope: ["full-repo bootstrap"],
286
- human_owners: { architect: "", qa: "" },
287
- };
288
- fs.writeFileSync(
289
- scopePath,
290
- `# Incremental graph scope\n${dumpYaml(data)}\n`,
291
- );
292
- } else {
293
- const merged = mergeSeedsIntoScopeText(
294
- fs.readFileSync(scopePath, "utf8"),
295
- args,
296
- );
297
- fs.writeFileSync(scopePath, merged);
298
- }
299
-
300
- const status = {
301
- schema_version: 1,
302
- bootstrap_id: bootstrapId,
303
- repo_root: ".",
304
- phase: "B2",
305
- update_mode: "incremental",
306
- updated_at: ts,
307
- scope_ref: "knowledge/bootstrap/scope.yaml",
308
- inventory_ref: "knowledge/bootstrap/inventory.json",
309
- last_run_dir: `knowledge/bootstrap/runs/${bootstrapId}/`,
310
- stats: {
311
- entities_proposed: 0,
312
- entities_asserted: 0,
313
- edges_proposed: 0,
314
- edges_asserted: 0,
315
- features_linked: 0,
316
- },
317
- blockers: [],
318
- next_actions: [
319
- "Review knowledge/bootstrap/scope.yaml (update_mode: incremental)",
320
- "Run knowledge-graph-bootstrap DAG (propose limited to scope seeds/includes)",
321
- "Promote merge-new-only; materialize indexes",
322
- ],
323
- };
324
- fs.writeFileSync(
325
- statusPath,
326
- `# Incremental bootstrap status\n${dumpYaml(status)}\n`,
327
- );
328
-
329
- if (args.resetStaging) resetStaging(args.root, bootstrapId);
330
-
331
- fs.writeFileSync(
332
- path.join(backupDir, "README.md"),
333
- [
334
- `# Incremental prepare ${bootstrapId}`,
335
- "",
336
- `- update_mode: incremental`,
337
- `- features: ${args.features.join(", ") || "(none)"}`,
338
- `- services: ${args.services.join(", ") || "(none)"}`,
339
- `- domains: ${args.domains.join(", ") || "(none)"}`,
340
- "",
341
- "Next:",
342
- "```bash",
343
- "loop-agent dag run-task <task-id> --profile knowledge-graph-bootstrap",
344
- `bash scripts/kb-graph-materialize.sh --root ${args.root}`,
345
- "```",
346
- "",
347
- ].join("\n"),
348
- );
349
-
350
- console.log(
351
- JSON.stringify(
352
- {
353
- ok: true,
354
- bootstrap_id: bootstrapId,
355
- update_mode: "incremental",
356
- scope: "knowledge/bootstrap/scope.yaml",
357
- status: "knowledge/bootstrap/status.yaml",
358
- backup: `knowledge/bootstrap/runs/${bootstrapId}/`,
359
- seeds: {
360
- features: args.features,
361
- services: args.services,
362
- domains: args.domains,
363
- },
364
- next: "dag run-task --profile knowledge-graph-bootstrap",
365
- },
366
- null,
367
- 2,
368
- ),
369
- );
370
- }
371
-
372
- 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();