cclaw-cli 0.55.2 → 1.0.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 (72) hide show
  1. package/README.md +3 -3
  2. package/dist/artifact-linter/brainstorm.js +45 -1
  3. package/dist/artifact-linter/design.js +32 -1
  4. package/dist/artifact-linter/plan.js +22 -1
  5. package/dist/artifact-linter/review.js +35 -1
  6. package/dist/artifact-linter/scope.js +19 -9
  7. package/dist/artifact-linter/shared.d.ts +11 -10
  8. package/dist/artifact-linter/shared.js +70 -41
  9. package/dist/artifact-linter/ship.js +36 -0
  10. package/dist/artifact-linter/spec.js +23 -1
  11. package/dist/artifact-linter/tdd.js +74 -0
  12. package/dist/artifact-linter.d.ts +1 -1
  13. package/dist/constants.d.ts +1 -1
  14. package/dist/constants.js +1 -0
  15. package/dist/content/closeout-guidance.d.ts +1 -1
  16. package/dist/content/closeout-guidance.js +10 -11
  17. package/dist/content/core-agents.d.ts +35 -36
  18. package/dist/content/core-agents.js +189 -99
  19. package/dist/content/diff-command.js +1 -1
  20. package/dist/content/examples.d.ts +0 -3
  21. package/dist/content/examples.js +197 -752
  22. package/dist/content/idea.d.ts +60 -0
  23. package/dist/content/idea.js +404 -0
  24. package/dist/content/learnings.d.ts +2 -4
  25. package/dist/content/learnings.js +10 -26
  26. package/dist/content/node-hooks.js +131 -97
  27. package/dist/content/opencode-plugin.js +12 -26
  28. package/dist/content/reference-patterns.js +2 -2
  29. package/dist/content/runtime-shared-snippets.d.ts +8 -0
  30. package/dist/content/runtime-shared-snippets.js +80 -0
  31. package/dist/content/session-hooks.js +1 -1
  32. package/dist/content/skills.d.ts +1 -0
  33. package/dist/content/skills.js +50 -0
  34. package/dist/content/stage-schema.js +107 -63
  35. package/dist/content/stages/review.js +8 -8
  36. package/dist/content/stages/schema-types.d.ts +2 -2
  37. package/dist/content/stages/scope.js +1 -1
  38. package/dist/content/stages/ship.js +1 -1
  39. package/dist/content/status-command.js +3 -3
  40. package/dist/content/subagent-context-skills.js +156 -1
  41. package/dist/content/subagents.d.ts +0 -5
  42. package/dist/content/subagents.js +12 -82
  43. package/dist/content/templates.js +87 -6
  44. package/dist/content/utility-skills.js +26 -97
  45. package/dist/flow-state.d.ts +5 -6
  46. package/dist/flow-state.js +4 -6
  47. package/dist/gate-evidence.d.ts +0 -31
  48. package/dist/gate-evidence.js +3 -181
  49. package/dist/harness-adapters.js +1 -1
  50. package/dist/install.js +38 -4
  51. package/dist/internal/advance-stage/advance.js +0 -1
  52. package/dist/internal/advance-stage/review-loop.js +1 -10
  53. package/dist/knowledge-store.d.ts +2 -20
  54. package/dist/knowledge-store.js +43 -57
  55. package/dist/policy.js +3 -3
  56. package/dist/retro-gate.js +8 -90
  57. package/dist/run-archive.js +1 -4
  58. package/dist/run-persistence.js +14 -109
  59. package/dist/runtime/run-hook.entry.d.ts +3 -0
  60. package/dist/runtime/run-hook.entry.js +5 -0
  61. package/dist/runtime/run-hook.mjs +9477 -0
  62. package/package.json +4 -2
  63. package/dist/content/hook-inline-snippets.d.ts +0 -96
  64. package/dist/content/hook-inline-snippets.js +0 -515
  65. package/dist/content/idea-command.d.ts +0 -8
  66. package/dist/content/idea-command.js +0 -322
  67. package/dist/content/idea-frames.d.ts +0 -31
  68. package/dist/content/idea-frames.js +0 -140
  69. package/dist/content/idea-ranking.d.ts +0 -25
  70. package/dist/content/idea-ranking.js +0 -65
  71. package/dist/trace-matrix.d.ts +0 -27
  72. package/dist/trace-matrix.js +0 -226
@@ -1,8 +0,0 @@
1
- import { type IdeaFrameId } from "./idea-frames.js";
2
- export interface IdeaCommandOptions {
3
- frameIds?: readonly IdeaFrameId[];
4
- mode?: "repo-grounded" | "elsewhere-software" | "elsewhere-non-software" | "narrow";
5
- }
6
- export declare function minimumDistinctIdeaFrames(frameCount: number, mode?: IdeaCommandOptions["mode"]): number;
7
- export declare function ideaCommandContract(options?: IdeaCommandOptions): string;
8
- export declare function ideaCommandSkillMarkdown(options?: IdeaCommandOptions): string;
@@ -1,322 +0,0 @@
1
- import { RUNTIME_ROOT } from "../constants.js";
2
- import { resolveIdeaFrames } from "./idea-frames.js";
3
- import { ideaStructuredAskToolsWithFallback } from "./decision-protocol.js";
4
- import { conversationLanguagePolicyMarkdown } from "./language-policy.js";
5
- const IDEA_SKILL_FOLDER = "flow-idea";
6
- const IDEA_SKILL_NAME = "flow-idea";
7
- /**
8
- * Directory + filename convention for idea artifacts. These are separate
9
- * from stage artifacts (00-..08-*.md) because `/cc-idea` runs outside the
10
- * critical-path flow state machine and must not collide with stage numbering.
11
- */
12
- const IDEA_ARTIFACT_GLOB = ".cclaw/artifacts/idea-*.md";
13
- const IDEA_ARTIFACT_PATTERN = ".cclaw/artifacts/idea-<YYYY-MM-DD-slug>.md";
14
- const IDEA_RESUME_WINDOW_DAYS = 30;
15
- const STRUCTURED_ASK_TOOLS = ideaStructuredAskToolsWithFallback();
16
- export function minimumDistinctIdeaFrames(frameCount, mode = "repo-grounded") {
17
- if (frameCount <= 0)
18
- return 0;
19
- const cap = mode === "repo-grounded" ? 4 : 2;
20
- return Math.min(cap, frameCount);
21
- }
22
- function renderFrameBullets(frameIds) {
23
- return resolveIdeaFrames(frameIds)
24
- .map((frame) => ` - ${frame.label} (\`${frame.id}\`)`)
25
- .join("\n");
26
- }
27
- function renderFrameNames(frameIds) {
28
- return resolveIdeaFrames(frameIds)
29
- .map((frame) => frame.label)
30
- .join(", ");
31
- }
32
- export function ideaCommandContract(options = {}) {
33
- const frames = resolveIdeaFrames(options.frameIds);
34
- const frameBullets = renderFrameBullets(options.frameIds);
35
- const minimumDistinctFrames = minimumDistinctIdeaFrames(frames.length, options.mode);
36
- return `# /cc-idea
37
-
38
- ## Purpose
39
-
40
- Repository-improvement idea mode. Generate a ranked backlog of
41
- high-value improvements, persist it as an artifact on disk, and end with
42
- an explicit handoff — either launch \`/cc\` on a chosen candidate in the
43
- same session, or save/discard the backlog.
44
-
45
- ## HARD-GATE
46
-
47
- ${conversationLanguagePolicyMarkdown()}
48
- - Idea mode only. Never mutate \`.cclaw/state/flow-state.json\`.
49
- - Every recommendation cites evidence from the current repository
50
- (file path, command output, or knowledge-store entry id).
51
- - Whenever you produce ideation output, persist it to
52
- \`${IDEA_ARTIFACT_PATTERN}\`. Chat-only output is not acceptable.
53
- The only exception is an explicit user-cancel from the resume prompt —
54
- in that case, write nothing and exit silently.
55
- - Always end with a structured handoff prompt, not an open question
56
- (skipped on explicit cancel).
57
-
58
- ## Algorithm
59
-
60
- 1. **Resume check.** Glob \`${IDEA_ARTIFACT_GLOB}\`. If any artifact
61
- has been modified within the last ${IDEA_RESUME_WINDOW_DAYS} days,
62
- offer the user: continue that backlog, start fresh, or cancel.
63
- 2. **Mode classification.** Explicitly classify subject:
64
- \`repo-grounded\` / \`elsewhere-software\` / \`elsewhere-non-software\` / \`narrow\`.
65
- Do not assume repo-grounded by default. Repo-grounded scans keep the
66
- broadest frame minimum; narrow and non-repo modes use the smaller minimum
67
- shown below.
68
- 3. **Mode-aware grounding (parallel).**
69
- - Repo-grounded: repo signal scan + \`${RUNTIME_ROOT}/knowledge.jsonl\`
70
- repetition scan.
71
- - Elsewhere-software: docs-first grounding (Context7 and official docs).
72
- - Elsewhere-non-software: constraints and objective grounding.
73
- 4. **Divergent ideation frames (parallel).** Generate candidates with
74
- configured frames (${frames.length} total):
75
- ${frameBullets}
76
- Keep at least ${minimumDistinctFrames} distinct frame outputs in this rendered mode.
77
- Deterministic minimum: repo-grounded = 4, narrow/non-repo = 2, always capped
78
- by configured frame count.
79
- 5. **Adversarial critique pass.** For each candidate, write the strongest
80
- counter-argument, kill weak ideas, and keep survivors only.
81
- 6. **Produce 5-10 survivors** with impact (High/Medium/Low),
82
- effort (S/M/L), confidence (High/Medium/Low), **why now**, expected user impact, risk, and one evidence path per
83
- survivor.
84
- 7. **Rank by impact/effort/confidence** using
85
- \`(impact points / effort cost) * confidence multiplier\` and recommend
86
- the top survivor.
87
- 8. **Write the artifact** at
88
- \`${IDEA_ARTIFACT_PATTERN}\` using the schema in the skill.
89
- 8.5 **Seed shelf (optional).** For critiqued-out or deferred ideas that still
90
- show upside, write seed notes to
91
- \`${RUNTIME_ROOT}/seeds/SEED-<YYYY-MM-DD>-<slug>.md\` with
92
- \`trigger_when\`, hypothesis, and suggested action.
93
- 9. **Present the handoff prompt** with four concrete options — not A/B/C
94
- letters. Default = "Start /cc on the top recommendation".
95
-
96
- ## Headless mode (CI/automation only)
97
-
98
- Headless envelopes are a machine-mode exception for CI/automation orchestration.
99
- In normal interactive ideation, respond with natural language plus the artifact path.
100
- For skill-to-skill invocation, emit exactly one JSON envelope:
101
-
102
- \`\`\`json
103
- {"version":"1","kind":"stage-output","stage":"non-flow","payload":{"command":"/cc-idea","artifact":".cclaw/artifacts/idea-<date>-<slug>.md","recommendation":"I-1"},"emittedAt":"<ISO-8601>"}
104
- \`\`\`
105
-
106
- Validate envelopes with:
107
- \`npx cclaw-cli internal envelope-validate --stdin\`
108
-
109
- ## Primary skill
110
-
111
- **${RUNTIME_ROOT}/skills/${IDEA_SKILL_FOLDER}/SKILL.md**
112
- `;
113
- }
114
- export function ideaCommandSkillMarkdown(options = {}) {
115
- const frames = resolveIdeaFrames(options.frameIds);
116
- const frameBullets = renderFrameBullets(options.frameIds);
117
- const minimumDistinctFrames = minimumDistinctIdeaFrames(frames.length, options.mode);
118
- const frameNames = renderFrameNames(options.frameIds);
119
- return `---
120
- name: ${IDEA_SKILL_NAME}
121
- description: "Repository idea mode: detect and rank high-leverage improvements, persist a backlog artifact, and hand off to /cc or save/discard."
122
- ---
123
-
124
- # /cc-idea
125
-
126
- ## Announce at start
127
-
128
- "Using flow-idea to identify highest-leverage improvements in this
129
- repository. Will persist a ranked backlog to
130
- \`${IDEA_ARTIFACT_PATTERN}\` and end with an explicit handoff."
131
-
132
- ## HARD-GATE
133
-
134
- ${conversationLanguagePolicyMarkdown()}
135
- - Do not start coding in idea mode.
136
- - Do not mutate \`.cclaw/state/flow-state.json\` — idea mode sits outside
137
- the critical-path flow.
138
- - Whenever ideation output is produced, persist the artifact file on disk
139
- before presenting the handoff. The only exception is an explicit user-cancel
140
- from the resume prompt — in that case, write nothing and exit silently.
141
- - Always end with a structured handoff that names the concrete follow-up
142
- command for each option (skipped on explicit cancel). No A/B/C letters
143
- without command context.
144
-
145
- ## Protocol
146
-
147
- ### Phase 0 — Resume and classify
148
-
149
- 1. Use the harness's file-glob tool (\`Glob\` pattern
150
- \`${IDEA_ARTIFACT_GLOB}\` or equivalent \`ls\`/\`find\`).
151
- 2. Filter to files modified within the last ${IDEA_RESUME_WINDOW_DAYS} days.
152
- 3. If one or more match, present **one** structured ask using the
153
- harness's native tool (${STRUCTURED_ASK_TOOLS}) with options:
154
- - **Continue the existing backlog** — read the most-recent
155
- idea-*.md and work from its candidate list; skip re-scanning.
156
- - **Start a fresh scan** — proceed to Phase 1; the old artifact stays
157
- on disk for history.
158
- - **Cancel** — stop; do not scan or write anything.
159
- 4. If no recent artifact exists, proceed to Phase 1 silently.
160
- 5. Classify the ideation mode before grounding:
161
- - \`repo-grounded\` — explicitly tied to this repository.
162
- - \`elsewhere-software\` — software problem not tied to this repository.
163
- - \`elsewhere-non-software\` — process/business/non-software problem.
164
- - \`narrow\` — a focused prompt where broad frame coverage would be performative.
165
- 6. Record the chosen mode in the artifact.
166
-
167
- ### Phase 1 — Mode-aware grounding
168
-
169
- Run grounding in parallel where available:
170
-
171
- - For \`repo-grounded\`:
172
- - \`rg -n 'TODO|FIXME|XXX|HACK|TBD'\` grouped by file.
173
- - Test-runner output (\`npm test\`, \`pytest\`, \`go test ./...\`) — note
174
- failures, timeouts, deprecation warnings.
175
- - Module size outliers (\`wc -l\` or \`du\`) with weak direct test coverage.
176
- - Docs drift: check that \`README.md\` / \`docs/\` reference files that still
177
- exist and flags/APIs that still match \`src/\`.
178
- - \`${RUNTIME_ROOT}/knowledge.jsonl\` entries with recurring \`type\` in \`rule | pattern | lesson | compound\` and repeated \`trigger/action\` pairs; prefer clusters that already show stable \`origin_run\` history.
179
- - For \`elsewhere-software\`:
180
- - Gather current framework/library docs first.
181
- - Add one comparison scan for established solutions.
182
- - For \`elsewhere-non-software\`:
183
- - Capture objective, constraints, and measured friction before proposing fixes.
184
-
185
- Record each finding with exact evidence (path, command, or doc source).
186
-
187
- ### Phase 2 — Divergent ideation
188
-
189
- Generate candidate ideas by frame, in parallel when possible:
190
-
191
- ${frameBullets}
192
-
193
- Require at least ${minimumDistinctFrames} distinct frames in this rendered mode. The
194
- runtime rule is deterministic: repo-grounded scans require 4 distinct frames;
195
- narrow, elsewhere-software, and elsewhere-non-software runs require 2; all modes
196
- are capped by the configured frame count. Avoid frame-collapse (same idea
197
- rewritten many times). Keep raw outputs for auditability.
198
-
199
- ### Phase 3 — Critique all, keep survivors
200
-
201
- For each raw candidate:
202
-
203
- - Write strongest argument **against** this idea.
204
- - Identify disqualifiers (duplicate, weak evidence, poor ROI, wrong timing).
205
- - Mark as \`survivor\` or \`critiqued-out\`.
206
-
207
- Only survivors advance to ranking.
208
-
209
- ### Phase 4 — Rank and write the artifact
210
-
211
- 1. Keep 5–10 survivors.
212
- 2. For each survivor, include:
213
- - **ID** — \`I-1\`, \`I-2\`, …
214
- - **Title** — one short imperative phrase
215
- - **Impact** — High / Medium / Low
216
- - **Effort** — S / M / L
217
- - **Confidence** — High / Medium / Low
218
- - **Evidence** — path(s) or command output, inline if short
219
- - **Why now** — timing signal from repo evidence, user friction, repeated knowledge, or blocked flow
220
- - **Expected impact** — concrete user-facing benefit if this lands
221
- - **Risk** — main implementation/product risk to manage
222
- - **Counter-argument** — strongest concern that survived
223
- - **Next /cc prompt** — exact \`/cc <phrase>\` that starts the work
224
- 3. Sort by score \`(impact points / effort cost) * confidence multiplier\`
225
- and break ties with rationale strength.
226
- 4. Compute the artifact filename:
227
- - \`slug\` = first 3–5 words of the top recommendation, lowercase,
228
- non-alphanumeric collapsed to \`-\`, trimmed. When idea mode is
229
- focus-hinted (user passed an argument), use the focus hint instead.
230
- - \`date\` = today in \`YYYY-MM-DD\` (local time).
231
- - Path = \`.cclaw/artifacts/idea-<date>-<slug>.md\`.
232
- 5. Use the harness's write-file tool (\`Write\`, \`apply_patch\`, or shell
233
- \`cat <<EOF > path\`) to create the artifact with this schema:
234
-
235
- \`\`\`markdown
236
- # Ideation — <date>
237
-
238
- **Focus:** <user-supplied focus or "open-ended scan">
239
- **Mode:** <repo-grounded | elsewhere-software | elsewhere-non-software | narrow>
240
- **Generated:** <ISO-8601 timestamp>
241
- **Frames used:** <comma-separated list>
242
- **Raw candidates:** <N>
243
- **Critiqued out:** <M>
244
- **Recommendation:** I-1
245
-
246
- ## Grounding evidence
247
-
248
- - <signal and evidence>
249
- - ...
250
-
251
- ## Critiqued out
252
-
253
- | Idea | Why it was rejected |
254
- |---|---|
255
- | ... | ... |
256
-
257
- ## Ranked survivors
258
-
259
- | ID | Improvement | Why now | Expected impact | Risk | Impact | Effort | Confidence | Evidence | Next /cc prompt |
260
- |---|---|---|---|---|---|---|---|---|---|
261
- | I-1 | Simplify a confusing generated prompt surface | Repeated blocker in generated UX | Faster operator recovery | Might over-trim context | High | S | High | <path-to-generated-surface> | \`/cc Simplify the confusing generated prompt surface while preserving behavior\` |
262
- | … | … | … | … | … | … |
263
-
264
- ## Candidate detail
265
-
266
- ### I-1 — Simplify a confusing generated prompt surface
267
- - **Evidence:** \`<path>\` contains repeated or stale guidance that a user would see.
268
- - **Why now:** The prompt is on the daily /cc path, so confusion compounds quickly.
269
- - **Expected impact:** Operators get a clearer next action without changing gates.
270
- - **Risk:** Trimming too hard can remove useful orientation for new users.
271
- - **Next /cc prompt:** \`/cc Simplify the confusing generated prompt surface while preserving behavior\`
272
-
273
- ### I-2 — …
274
- \`\`\`
275
-
276
- 6. Optional: for promising non-selected ideas, write
277
- \`${RUNTIME_ROOT}/seeds/SEED-<YYYY-MM-DD>-<slug>.md\` entries with:
278
- \`title\`, \`trigger_when\`, \`hypothesis\`, \`action\`, and
279
- \`source_artifact\` = idea artifact path.
280
- 7. Confirm in chat: "Wrote <path>."
281
-
282
- ### Phase 5 — Handoff prompt
283
-
284
- Present **one** structured ask using the harness's native tool
285
- (${STRUCTURED_ASK_TOOLS}). Each option must name the concrete follow-up —
286
- no bare A/B/C.
287
-
288
- Required options, in this order:
289
-
290
- 1. **Start /cc on the top recommendation** — the agent immediately loads
291
- \`${RUNTIME_ROOT}/skills/using-cclaw/SKILL.md\` and invokes
292
- \`/cc <I-1 handoff phrase>\` in the same turn. Default choice.
293
- 2. **Pick a different candidate** — the agent asks which ID (I-2, I-3, …)
294
- and then invokes \`/cc <that candidate's handoff phrase>\`.
295
- 3. **Save and close** — leave the artifact on disk, do nothing else.
296
- Next session: \`/cc-idea\` will offer to resume it.
297
- 4. **Discard** — delete the just-written artifact. Use only when the
298
- scan produced nothing actionable.
299
-
300
- When the structured-ask tool is unavailable, fall back to a plain-text
301
- lettered list with the same four labels. Do not invent extra options.
302
-
303
- ### Phase 6 — Execute the choice
304
-
305
- - **Start /cc on I-1** or **different candidate:** announce
306
- "Handing off to /cc <phrase>" and load the \`using-cclaw\` router
307
- skill. From there, the normal \`/cc\` classification and stage flow
308
- takes over. Do not produce a second artifact; the idea file is
309
- preserved as the origin document for this run.
310
- - **Save and close:** reply with the artifact path and stop.
311
- - **Discard:** delete the artifact file, confirm deletion, stop.
312
-
313
- ## Do not
314
-
315
- - Do not write into \`.cclaw/artifacts/0X-*.md\` (stage artifacts).
316
- - Do not mutate \`.cclaw/state/flow-state.json\` at any phase.
317
- - Do not end the turn with an ungrounded "pick one" question — every
318
- option in the handoff prompt must reference a concrete command.
319
- - Do not collapse all ideas into one frame; distribute across:
320
- ${frameNames}.
321
- `;
322
- }
@@ -1,31 +0,0 @@
1
- export type IdeaFrameId = "pain-friction" | "inversion" | "assumption-break" | "leverage" | "cross-domain-analogy" | "constraint-flip";
2
- export interface IdeaFrame {
3
- id: IdeaFrameId;
4
- label: string;
5
- prompt: string;
6
- examplePatterns: string[];
7
- }
8
- export interface IdeaFrameDispatchInput {
9
- focus: string;
10
- mode: "repo-grounded" | "elsewhere-software" | "elsewhere-non-software";
11
- signalSummary: string[];
12
- }
13
- export interface IdeaFrameDispatchPlanEntry {
14
- frameId: IdeaFrameId;
15
- label: string;
16
- prompt: string;
17
- }
18
- export interface IdeaCandidateDraft {
19
- title: string;
20
- evidencePath: string;
21
- summary: string;
22
- frameId: IdeaFrameId;
23
- }
24
- export interface IdeaCandidateMerged extends Omit<IdeaCandidateDraft, "frameId"> {
25
- frameIds: IdeaFrameId[];
26
- }
27
- export declare const DEFAULT_IDEA_FRAME_IDS: readonly IdeaFrameId[];
28
- export declare const IDEA_FRAMES: readonly IdeaFrame[];
29
- export declare function resolveIdeaFrames(frameIds?: readonly IdeaFrameId[]): IdeaFrame[];
30
- export declare function buildIdeaFrameDispatchPlan(input: IdeaFrameDispatchInput, frameIds?: readonly IdeaFrameId[]): IdeaFrameDispatchPlanEntry[];
31
- export declare function dedupeIdeaCandidates(drafts: readonly IdeaCandidateDraft[]): IdeaCandidateMerged[];
@@ -1,140 +0,0 @@
1
- const FRAME_REGISTRY = {
2
- "pain-friction": {
3
- id: "pain-friction",
4
- label: "pain/friction",
5
- prompt: "Find repeated friction in the repo workflow. Prioritize changes that eliminate recurring toil, fragile handoffs, or repeated manual recovery.",
6
- examplePatterns: [
7
- "Repeated TODO/FIXME hotspots in one subsystem",
8
- "Flows that require manual retries or ad-hoc scripts",
9
- "Developer loops slowed by avoidable boilerplate"
10
- ]
11
- },
12
- inversion: {
13
- id: "inversion",
14
- label: "inversion",
15
- prompt: "Invert a dominant assumption in the current implementation (e.g., push vs pull, synchronous vs queued, implicit vs explicit) and evaluate upside.",
16
- examplePatterns: [
17
- "Replace optimistic assumptions with fail-closed defaults",
18
- "Switch from post-facto checks to pre-flight validation",
19
- "Move from global policy to module-local contracts"
20
- ]
21
- },
22
- "assumption-break": {
23
- id: "assumption-break",
24
- label: "assumption-break",
25
- prompt: "List assumptions that might be false in production. Generate ideas that remain correct even when those assumptions fail.",
26
- examplePatterns: [
27
- "Edge paths currently treated as impossible",
28
- "Implicit coupling between modules with no explicit contract",
29
- "Latency, scale, or environment assumptions baked into logic"
30
- ]
31
- },
32
- leverage: {
33
- id: "leverage",
34
- label: "leverage",
35
- prompt: "Target interventions with asymmetric payoff: one change that improves multiple stages, teams, or failure classes at once.",
36
- examplePatterns: [
37
- "A shared helper replacing duplicated logic in many files",
38
- "One lint/gate that blocks an entire class of regressions",
39
- "A protocol update that improves multiple stage outputs"
40
- ]
41
- },
42
- "cross-domain-analogy": {
43
- id: "cross-domain-analogy",
44
- label: "cross-domain analogy",
45
- prompt: "Borrow a proven pattern from another domain and adapt it to this repo. Keep it concrete and grounded in local constraints.",
46
- examplePatterns: [
47
- "Apply SRE-style error budgets to planning artifacts",
48
- "Use security threat-model thinking for reliability design",
49
- "Import CI release-train discipline into stage completion gates"
50
- ]
51
- },
52
- "constraint-flip": {
53
- id: "constraint-flip",
54
- label: "constraint-flip",
55
- prompt: "Flip one assumed constraint (time, team size, risk tolerance, compatibility) and derive better options under the new boundary.",
56
- examplePatterns: [
57
- "Assume near-zero migration window and redesign rollout",
58
- "Assume one maintainer and optimize for low operational burden",
59
- "Assume strict auditability and remove ambiguous behaviors"
60
- ]
61
- }
62
- };
63
- export const DEFAULT_IDEA_FRAME_IDS = Object.freeze([
64
- "pain-friction",
65
- "inversion",
66
- "assumption-break",
67
- "leverage",
68
- "cross-domain-analogy",
69
- "constraint-flip"
70
- ]);
71
- export const IDEA_FRAMES = Object.freeze(DEFAULT_IDEA_FRAME_IDS.map((id) => FRAME_REGISTRY[id]));
72
- export function resolveIdeaFrames(frameIds) {
73
- if (!frameIds || frameIds.length === 0) {
74
- return [...IDEA_FRAMES];
75
- }
76
- const seen = new Set();
77
- const resolved = [];
78
- for (const rawId of frameIds) {
79
- if (!DEFAULT_IDEA_FRAME_IDS.includes(rawId)) {
80
- throw new Error(`Unknown idea frame id: ${rawId}`);
81
- }
82
- if (seen.has(rawId))
83
- continue;
84
- seen.add(rawId);
85
- resolved.push(FRAME_REGISTRY[rawId]);
86
- }
87
- return resolved;
88
- }
89
- export function buildIdeaFrameDispatchPlan(input, frameIds) {
90
- const signalBlock = input.signalSummary.length > 0
91
- ? input.signalSummary.map((line) => `- ${line}`).join("\n")
92
- : "- no pre-scan signals captured yet";
93
- return resolveIdeaFrames(frameIds).map((frame) => ({
94
- frameId: frame.id,
95
- label: frame.label,
96
- prompt: [
97
- `Frame: ${frame.label} (${frame.id})`,
98
- `Mode: ${input.mode}`,
99
- `Focus: ${input.focus || "open-ended scan"}`,
100
- "",
101
- "Signal summary:",
102
- signalBlock,
103
- "",
104
- `Frame prompt: ${frame.prompt}`,
105
- "",
106
- "Generate 3-5 concrete candidates with repo-grounded evidence."
107
- ].join("\n")
108
- }));
109
- }
110
- function normalizeCandidateKey(title, evidencePath) {
111
- const normalizedTitle = title.trim().toLowerCase().replace(/[^a-z0-9]+/gu, " ").trim();
112
- const normalizedEvidence = evidencePath
113
- .trim()
114
- .toLowerCase()
115
- .replace(/\\/gu, "/");
116
- return `${normalizedTitle}::${normalizedEvidence}`;
117
- }
118
- export function dedupeIdeaCandidates(drafts) {
119
- const merged = new Map();
120
- for (const draft of drafts) {
121
- const key = normalizeCandidateKey(draft.title, draft.evidencePath);
122
- const existing = merged.get(key);
123
- if (!existing) {
124
- merged.set(key, {
125
- title: draft.title,
126
- evidencePath: draft.evidencePath,
127
- summary: draft.summary,
128
- frameIds: [draft.frameId]
129
- });
130
- continue;
131
- }
132
- if (!existing.frameIds.includes(draft.frameId)) {
133
- existing.frameIds.push(draft.frameId);
134
- }
135
- if (draft.summary.length > existing.summary.length) {
136
- existing.summary = draft.summary;
137
- }
138
- }
139
- return [...merged.values()];
140
- }
@@ -1,25 +0,0 @@
1
- export type IdeaImpact = "high" | "medium" | "low";
2
- export type IdeaEffort = "s" | "m" | "l";
3
- export type IdeaConfidence = "high" | "medium" | "low";
4
- export interface IdeaCandidateEvaluationInput {
5
- id: string;
6
- title: string;
7
- impact: IdeaImpact;
8
- effort: IdeaEffort;
9
- confidence: IdeaConfidence;
10
- rationaleStrength: number;
11
- counterArgumentStrength: number;
12
- }
13
- export interface IdeaCandidateEvaluation extends IdeaCandidateEvaluationInput {
14
- disposition: "survivor" | "critiqued-out";
15
- rankingScore: number;
16
- }
17
- export interface IdeaRankingResult {
18
- survivors: IdeaCandidateEvaluation[];
19
- critiquedOut: IdeaCandidateEvaluation[];
20
- recommendationId: string | null;
21
- }
22
- export declare function isCritiquedOut(rationaleStrength: number, counterArgumentStrength: number): boolean;
23
- export declare function scoreIdeaCandidate(impact: IdeaImpact, effort: IdeaEffort, confidence: IdeaConfidence): number;
24
- export declare function evaluateIdeaCandidate(input: IdeaCandidateEvaluationInput): IdeaCandidateEvaluation;
25
- export declare function rankIdeaCandidates(inputs: readonly IdeaCandidateEvaluationInput[], maxSurvivors?: number): IdeaRankingResult;
@@ -1,65 +0,0 @@
1
- const IMPACT_POINTS = {
2
- high: 9,
3
- medium: 6,
4
- low: 3
5
- };
6
- const EFFORT_COST = {
7
- s: 1,
8
- m: 2,
9
- l: 3
10
- };
11
- const CONFIDENCE_MULTIPLIER = {
12
- high: 1,
13
- medium: 0.75,
14
- low: 0.5
15
- };
16
- function clampStrength(value) {
17
- if (!Number.isFinite(value))
18
- return 0;
19
- if (value < 0)
20
- return 0;
21
- if (value > 1)
22
- return 1;
23
- return value;
24
- }
25
- export function isCritiquedOut(rationaleStrength, counterArgumentStrength) {
26
- return clampStrength(counterArgumentStrength) > clampStrength(rationaleStrength);
27
- }
28
- export function scoreIdeaCandidate(impact, effort, confidence) {
29
- const raw = (IMPACT_POINTS[impact] / EFFORT_COST[effort]) * CONFIDENCE_MULTIPLIER[confidence];
30
- return Number(raw.toFixed(3));
31
- }
32
- export function evaluateIdeaCandidate(input) {
33
- const disposition = isCritiquedOut(input.rationaleStrength, input.counterArgumentStrength)
34
- ? "critiqued-out"
35
- : "survivor";
36
- return {
37
- ...input,
38
- disposition,
39
- rankingScore: scoreIdeaCandidate(input.impact, input.effort, input.confidence)
40
- };
41
- }
42
- export function rankIdeaCandidates(inputs, maxSurvivors = 10) {
43
- const evaluated = inputs.map(evaluateIdeaCandidate);
44
- const survivors = evaluated
45
- .filter((candidate) => candidate.disposition === "survivor")
46
- .sort((left, right) => {
47
- if (right.rankingScore !== left.rankingScore) {
48
- return right.rankingScore - left.rankingScore;
49
- }
50
- if (right.rationaleStrength !== left.rationaleStrength) {
51
- return right.rationaleStrength - left.rationaleStrength;
52
- }
53
- return left.id.localeCompare(right.id);
54
- })
55
- .slice(0, Math.max(0, maxSurvivors));
56
- const survivorIds = new Set(survivors.map((candidate) => candidate.id));
57
- const critiquedOut = evaluated
58
- .filter((candidate) => candidate.disposition === "critiqued-out" || !survivorIds.has(candidate.id))
59
- .sort((left, right) => left.id.localeCompare(right.id));
60
- return {
61
- survivors,
62
- critiquedOut,
63
- recommendationId: survivors[0]?.id ?? null
64
- };
65
- }
@@ -1,27 +0,0 @@
1
- export interface TraceEntry {
2
- criterionId: string;
3
- taskIds: string[];
4
- testSlices: string[];
5
- reviewFindings: string[];
6
- }
7
- export interface ReviewLoopTraceEntry {
8
- stage: "scope" | "design";
9
- artifactPath: string;
10
- targetScore: number;
11
- maxIterations: number;
12
- stopReason: "quality_threshold_met" | "max_iterations_reached" | "user_opt_out";
13
- finalScore: number;
14
- iterations: Array<{
15
- iteration: number;
16
- qualityScore: number;
17
- findingsCount: number;
18
- }>;
19
- }
20
- export interface TraceMatrix {
21
- entries: TraceEntry[];
22
- orphanedCriteria: string[];
23
- orphanedTasks: string[];
24
- orphanedTests: string[];
25
- reviewLoops: ReviewLoopTraceEntry[];
26
- }
27
- export declare function buildTraceMatrix(projectRoot: string): Promise<TraceMatrix>;