cclaw-cli 7.7.1 → 8.1.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 (282) hide show
  1. package/README.md +210 -134
  2. package/dist/artifact-frontmatter.d.ts +51 -0
  3. package/dist/artifact-frontmatter.js +131 -0
  4. package/dist/artifact-paths.d.ts +7 -27
  5. package/dist/artifact-paths.js +20 -249
  6. package/dist/cancel.d.ts +16 -0
  7. package/dist/cancel.js +66 -0
  8. package/dist/cli.d.ts +2 -27
  9. package/dist/cli.js +90 -508
  10. package/dist/compound.d.ts +26 -0
  11. package/dist/compound.js +96 -0
  12. package/dist/config.d.ts +14 -51
  13. package/dist/config.js +23 -359
  14. package/dist/constants.d.ts +11 -18
  15. package/dist/constants.js +19 -106
  16. package/dist/content/antipatterns.d.ts +1 -0
  17. package/dist/content/antipatterns.js +109 -0
  18. package/dist/content/artifact-templates.d.ts +10 -0
  19. package/dist/content/artifact-templates.js +550 -0
  20. package/dist/content/cancel-command.d.ts +2 -2
  21. package/dist/content/cancel-command.js +25 -17
  22. package/dist/content/core-agents.d.ts +9 -233
  23. package/dist/content/core-agents.js +39 -768
  24. package/dist/content/decision-protocol.d.ts +1 -12
  25. package/dist/content/decision-protocol.js +27 -20
  26. package/dist/content/examples.d.ts +8 -42
  27. package/dist/content/examples.js +293 -425
  28. package/dist/content/idea-command.d.ts +2 -0
  29. package/dist/content/idea-command.js +38 -0
  30. package/dist/content/iron-laws.d.ts +4 -138
  31. package/dist/content/iron-laws.js +18 -197
  32. package/dist/content/meta-skill.d.ts +1 -3
  33. package/dist/content/meta-skill.js +57 -134
  34. package/dist/content/node-hooks.d.ts +12 -8
  35. package/dist/content/node-hooks.js +188 -838
  36. package/dist/content/recovery.d.ts +8 -0
  37. package/dist/content/recovery.js +179 -0
  38. package/dist/content/reference-patterns.d.ts +4 -13
  39. package/dist/content/reference-patterns.js +260 -389
  40. package/dist/content/research-playbooks.d.ts +8 -8
  41. package/dist/content/research-playbooks.js +108 -121
  42. package/dist/content/review-loop.d.ts +6 -192
  43. package/dist/content/review-loop.js +29 -731
  44. package/dist/content/skills.d.ts +8 -38
  45. package/dist/content/skills.js +681 -732
  46. package/dist/content/specialist-prompts/architect.d.ts +1 -0
  47. package/dist/content/specialist-prompts/architect.js +225 -0
  48. package/dist/content/specialist-prompts/brainstormer.d.ts +1 -0
  49. package/dist/content/specialist-prompts/brainstormer.js +168 -0
  50. package/dist/content/specialist-prompts/index.d.ts +2 -0
  51. package/dist/content/specialist-prompts/index.js +14 -0
  52. package/dist/content/specialist-prompts/planner.d.ts +1 -0
  53. package/dist/content/specialist-prompts/planner.js +182 -0
  54. package/dist/content/specialist-prompts/reviewer.d.ts +1 -0
  55. package/dist/content/specialist-prompts/reviewer.js +193 -0
  56. package/dist/content/specialist-prompts/security-reviewer.d.ts +1 -0
  57. package/dist/content/specialist-prompts/security-reviewer.js +133 -0
  58. package/dist/content/specialist-prompts/slice-builder.d.ts +1 -0
  59. package/dist/content/specialist-prompts/slice-builder.js +232 -0
  60. package/dist/content/stage-playbooks.d.ts +8 -0
  61. package/dist/content/stage-playbooks.js +404 -0
  62. package/dist/content/start-command.d.ts +2 -12
  63. package/dist/content/start-command.js +221 -207
  64. package/dist/flow-state.d.ts +21 -178
  65. package/dist/flow-state.js +67 -170
  66. package/dist/fs-utils.d.ts +6 -26
  67. package/dist/fs-utils.js +29 -162
  68. package/dist/gitignore.d.ts +2 -1
  69. package/dist/gitignore.js +51 -34
  70. package/dist/harness-detect.d.ts +10 -0
  71. package/dist/harness-detect.js +29 -0
  72. package/dist/install.d.ts +27 -15
  73. package/dist/install.js +230 -1342
  74. package/dist/knowledge-store.d.ts +19 -163
  75. package/dist/knowledge-store.js +56 -590
  76. package/dist/logger.d.ts +8 -3
  77. package/dist/logger.js +13 -4
  78. package/dist/orchestrator-routing.d.ts +29 -0
  79. package/dist/orchestrator-routing.js +156 -0
  80. package/dist/run-persistence.d.ts +7 -118
  81. package/dist/run-persistence.js +29 -845
  82. package/dist/runtime/run-hook.entry.d.ts +1 -3
  83. package/dist/runtime/run-hook.entry.js +19 -4
  84. package/dist/runtime/run-hook.mjs +13 -1024
  85. package/dist/types.d.ts +25 -261
  86. package/dist/types.js +8 -36
  87. package/package.json +6 -3
  88. package/dist/artifact-linter/brainstorm.d.ts +0 -2
  89. package/dist/artifact-linter/brainstorm.js +0 -353
  90. package/dist/artifact-linter/design.d.ts +0 -18
  91. package/dist/artifact-linter/design.js +0 -444
  92. package/dist/artifact-linter/findings-dedup.d.ts +0 -56
  93. package/dist/artifact-linter/findings-dedup.js +0 -232
  94. package/dist/artifact-linter/plan.d.ts +0 -2
  95. package/dist/artifact-linter/plan.js +0 -826
  96. package/dist/artifact-linter/review-army.d.ts +0 -49
  97. package/dist/artifact-linter/review-army.js +0 -520
  98. package/dist/artifact-linter/review.d.ts +0 -2
  99. package/dist/artifact-linter/review.js +0 -113
  100. package/dist/artifact-linter/scope.d.ts +0 -2
  101. package/dist/artifact-linter/scope.js +0 -158
  102. package/dist/artifact-linter/shared.d.ts +0 -637
  103. package/dist/artifact-linter/shared.js +0 -2163
  104. package/dist/artifact-linter/ship.d.ts +0 -2
  105. package/dist/artifact-linter/ship.js +0 -250
  106. package/dist/artifact-linter/spec.d.ts +0 -2
  107. package/dist/artifact-linter/spec.js +0 -176
  108. package/dist/artifact-linter/tdd.d.ts +0 -118
  109. package/dist/artifact-linter/tdd.js +0 -1404
  110. package/dist/artifact-linter.d.ts +0 -15
  111. package/dist/artifact-linter.js +0 -517
  112. package/dist/codex-feature-flag.d.ts +0 -58
  113. package/dist/codex-feature-flag.js +0 -193
  114. package/dist/content/closeout-guidance.d.ts +0 -14
  115. package/dist/content/closeout-guidance.js +0 -44
  116. package/dist/content/diff-command.d.ts +0 -1
  117. package/dist/content/diff-command.js +0 -43
  118. package/dist/content/harness-doc.d.ts +0 -1
  119. package/dist/content/harness-doc.js +0 -65
  120. package/dist/content/hook-events.d.ts +0 -9
  121. package/dist/content/hook-events.js +0 -23
  122. package/dist/content/hook-manifest.d.ts +0 -81
  123. package/dist/content/hook-manifest.js +0 -156
  124. package/dist/content/hooks.d.ts +0 -11
  125. package/dist/content/hooks.js +0 -1972
  126. package/dist/content/idea.d.ts +0 -60
  127. package/dist/content/idea.js +0 -416
  128. package/dist/content/language-policy.d.ts +0 -2
  129. package/dist/content/language-policy.js +0 -13
  130. package/dist/content/learnings.d.ts +0 -6
  131. package/dist/content/learnings.js +0 -141
  132. package/dist/content/observe.d.ts +0 -19
  133. package/dist/content/observe.js +0 -86
  134. package/dist/content/opencode-plugin.d.ts +0 -1
  135. package/dist/content/opencode-plugin.js +0 -635
  136. package/dist/content/review-prompts.d.ts +0 -1
  137. package/dist/content/review-prompts.js +0 -104
  138. package/dist/content/runtime-shared-snippets.d.ts +0 -8
  139. package/dist/content/runtime-shared-snippets.js +0 -80
  140. package/dist/content/session-hooks.d.ts +0 -7
  141. package/dist/content/session-hooks.js +0 -107
  142. package/dist/content/skills-elicitation.d.ts +0 -1
  143. package/dist/content/skills-elicitation.js +0 -167
  144. package/dist/content/stage-command.d.ts +0 -2
  145. package/dist/content/stage-command.js +0 -17
  146. package/dist/content/stage-schema.d.ts +0 -117
  147. package/dist/content/stage-schema.js +0 -955
  148. package/dist/content/stages/_lint-metadata/index.d.ts +0 -2
  149. package/dist/content/stages/_lint-metadata/index.js +0 -97
  150. package/dist/content/stages/brainstorm.d.ts +0 -2
  151. package/dist/content/stages/brainstorm.js +0 -184
  152. package/dist/content/stages/design.d.ts +0 -2
  153. package/dist/content/stages/design.js +0 -288
  154. package/dist/content/stages/index.d.ts +0 -8
  155. package/dist/content/stages/index.js +0 -11
  156. package/dist/content/stages/plan.d.ts +0 -2
  157. package/dist/content/stages/plan.js +0 -191
  158. package/dist/content/stages/review.d.ts +0 -2
  159. package/dist/content/stages/review.js +0 -240
  160. package/dist/content/stages/schema-types.d.ts +0 -203
  161. package/dist/content/stages/schema-types.js +0 -1
  162. package/dist/content/stages/scope.d.ts +0 -2
  163. package/dist/content/stages/scope.js +0 -254
  164. package/dist/content/stages/ship.d.ts +0 -2
  165. package/dist/content/stages/ship.js +0 -159
  166. package/dist/content/stages/spec.d.ts +0 -2
  167. package/dist/content/stages/spec.js +0 -170
  168. package/dist/content/stages/tdd.d.ts +0 -4
  169. package/dist/content/stages/tdd.js +0 -273
  170. package/dist/content/state-contracts.d.ts +0 -1
  171. package/dist/content/state-contracts.js +0 -63
  172. package/dist/content/status-command.d.ts +0 -4
  173. package/dist/content/status-command.js +0 -109
  174. package/dist/content/subagent-context-skills.d.ts +0 -4
  175. package/dist/content/subagent-context-skills.js +0 -279
  176. package/dist/content/subagents.d.ts +0 -3
  177. package/dist/content/subagents.js +0 -997
  178. package/dist/content/templates.d.ts +0 -26
  179. package/dist/content/templates.js +0 -1692
  180. package/dist/content/track-render-context.d.ts +0 -18
  181. package/dist/content/track-render-context.js +0 -53
  182. package/dist/content/tree-command.d.ts +0 -1
  183. package/dist/content/tree-command.js +0 -64
  184. package/dist/content/utility-skills.d.ts +0 -30
  185. package/dist/content/utility-skills.js +0 -160
  186. package/dist/content/view-command.d.ts +0 -2
  187. package/dist/content/view-command.js +0 -92
  188. package/dist/delegation.d.ts +0 -649
  189. package/dist/delegation.js +0 -1539
  190. package/dist/early-loop.d.ts +0 -70
  191. package/dist/early-loop.js +0 -302
  192. package/dist/execution-topology.d.ts +0 -44
  193. package/dist/execution-topology.js +0 -95
  194. package/dist/gate-evidence.d.ts +0 -85
  195. package/dist/gate-evidence.js +0 -631
  196. package/dist/harness-adapters.d.ts +0 -151
  197. package/dist/harness-adapters.js +0 -756
  198. package/dist/harness-selection.d.ts +0 -31
  199. package/dist/harness-selection.js +0 -214
  200. package/dist/hook-schema.d.ts +0 -6
  201. package/dist/hook-schema.js +0 -114
  202. package/dist/hook-schemas/claude-hooks.v1.json +0 -10
  203. package/dist/hook-schemas/codex-hooks.v1.json +0 -10
  204. package/dist/hook-schemas/cursor-hooks.v1.json +0 -13
  205. package/dist/init-detect.d.ts +0 -2
  206. package/dist/init-detect.js +0 -50
  207. package/dist/internal/advance-stage/advance.d.ts +0 -89
  208. package/dist/internal/advance-stage/advance.js +0 -655
  209. package/dist/internal/advance-stage/cancel-run.d.ts +0 -8
  210. package/dist/internal/advance-stage/cancel-run.js +0 -19
  211. package/dist/internal/advance-stage/flow-state-coercion.d.ts +0 -3
  212. package/dist/internal/advance-stage/flow-state-coercion.js +0 -81
  213. package/dist/internal/advance-stage/helpers.d.ts +0 -14
  214. package/dist/internal/advance-stage/helpers.js +0 -145
  215. package/dist/internal/advance-stage/hook.d.ts +0 -8
  216. package/dist/internal/advance-stage/hook.js +0 -40
  217. package/dist/internal/advance-stage/parsers.d.ts +0 -72
  218. package/dist/internal/advance-stage/parsers.js +0 -357
  219. package/dist/internal/advance-stage/proactive-delegation-trace.d.ts +0 -24
  220. package/dist/internal/advance-stage/proactive-delegation-trace.js +0 -56
  221. package/dist/internal/advance-stage/review-loop.d.ts +0 -16
  222. package/dist/internal/advance-stage/review-loop.js +0 -199
  223. package/dist/internal/advance-stage/rewind.d.ts +0 -14
  224. package/dist/internal/advance-stage/rewind.js +0 -108
  225. package/dist/internal/advance-stage/start-flow.d.ts +0 -13
  226. package/dist/internal/advance-stage/start-flow.js +0 -241
  227. package/dist/internal/advance-stage/verify.d.ts +0 -21
  228. package/dist/internal/advance-stage/verify.js +0 -185
  229. package/dist/internal/advance-stage.d.ts +0 -7
  230. package/dist/internal/advance-stage.js +0 -138
  231. package/dist/internal/cohesion-contract-stub.d.ts +0 -24
  232. package/dist/internal/cohesion-contract-stub.js +0 -148
  233. package/dist/internal/compound-readiness.d.ts +0 -23
  234. package/dist/internal/compound-readiness.js +0 -102
  235. package/dist/internal/detect-public-api-changes.d.ts +0 -5
  236. package/dist/internal/detect-public-api-changes.js +0 -45
  237. package/dist/internal/detect-supply-chain-changes.d.ts +0 -6
  238. package/dist/internal/detect-supply-chain-changes.js +0 -138
  239. package/dist/internal/early-loop-status.d.ts +0 -7
  240. package/dist/internal/early-loop-status.js +0 -93
  241. package/dist/internal/envelope-validate.d.ts +0 -7
  242. package/dist/internal/envelope-validate.js +0 -66
  243. package/dist/internal/flow-state-repair.d.ts +0 -20
  244. package/dist/internal/flow-state-repair.js +0 -104
  245. package/dist/internal/plan-split-waves.d.ts +0 -190
  246. package/dist/internal/plan-split-waves.js +0 -764
  247. package/dist/internal/runtime-integrity.d.ts +0 -7
  248. package/dist/internal/runtime-integrity.js +0 -268
  249. package/dist/internal/slice-commit.d.ts +0 -7
  250. package/dist/internal/slice-commit.js +0 -619
  251. package/dist/internal/tdd-loop-status.d.ts +0 -14
  252. package/dist/internal/tdd-loop-status.js +0 -68
  253. package/dist/internal/tdd-red-evidence.d.ts +0 -7
  254. package/dist/internal/tdd-red-evidence.js +0 -153
  255. package/dist/internal/waiver-grant.d.ts +0 -62
  256. package/dist/internal/waiver-grant.js +0 -294
  257. package/dist/internal/wave-status.d.ts +0 -74
  258. package/dist/internal/wave-status.js +0 -506
  259. package/dist/managed-resources.d.ts +0 -53
  260. package/dist/managed-resources.js +0 -313
  261. package/dist/policy.d.ts +0 -10
  262. package/dist/policy.js +0 -167
  263. package/dist/retro-gate.d.ts +0 -9
  264. package/dist/retro-gate.js +0 -47
  265. package/dist/run-archive.d.ts +0 -61
  266. package/dist/run-archive.js +0 -391
  267. package/dist/runs.d.ts +0 -2
  268. package/dist/runs.js +0 -2
  269. package/dist/stack-detection.d.ts +0 -116
  270. package/dist/stack-detection.js +0 -489
  271. package/dist/streaming/event-stream.d.ts +0 -31
  272. package/dist/streaming/event-stream.js +0 -114
  273. package/dist/tdd-cycle.d.ts +0 -107
  274. package/dist/tdd-cycle.js +0 -289
  275. package/dist/tdd-verification-evidence.d.ts +0 -17
  276. package/dist/tdd-verification-evidence.js +0 -122
  277. package/dist/track-heuristics.d.ts +0 -27
  278. package/dist/track-heuristics.js +0 -154
  279. package/dist/util/slice-id.d.ts +0 -58
  280. package/dist/util/slice-id.js +0 -89
  281. package/dist/worktree-manager.d.ts +0 -20
  282. package/dist/worktree-manager.js +0 -108
@@ -0,0 +1,2 @@
1
+ export declare const IDEA_COMMAND_BODY = "# /cc-idea \u2014 capture an idea outside of any active flow\n\nThis command does **not** participate in plan/build/review/ship. Its only job is to drop a half-formed idea into the backlog without spinning up a full flow.\n\n## Behaviour\n\n1. Open `.cclaw/ideas.md`. If it does not exist, seed it from `.cclaw/lib/templates/ideas.md`.\n2. Append a new entry with this shape:\n\n ```\n ## YYYY-MM-DDTHH:MM:SSZ \u2014 <one-line summary>\n\n <short paragraph or bullet list with the idea body>\n ```\n\n3. Save the file. Do not slugify, do not create artifacts under `.cclaw/flows/<slug>/`, do not modify `flow-state.json`, do not invoke specialists.\n\n## Hard rules\n\n- One entry per invocation. If the user pastes multiple ideas, ask whether to file them as one entry or several.\n- Never auto-promote an idea to a plan. Promotion happens only when the user explicitly invokes `/cc <task>`.\n- Never delete or edit prior ideas inside `/cc-idea`. Trimming the backlog is a separate manual step.\n\n## Suggested entry shape\n\n```\n## 2026-05-07T19:30:12Z \u2014 switch knowledge.jsonl to ndjson\n\nRight now `.cclaw/knowledge.jsonl` is one JSON object per line, but tooling\nexpects RFC 8259-compliant NDJSON. Worth verifying once the tooling adopts\nthe standard formally.\n```\n\nThe orchestrator surfaces ideas back to the user only when an explicit `/cc` invocation references them; otherwise they stay quiet.\n";
2
+ export declare function renderIdeaCommand(): string;
@@ -0,0 +1,38 @@
1
+ export const IDEA_COMMAND_BODY = `# /cc-idea — capture an idea outside of any active flow
2
+
3
+ This command does **not** participate in plan/build/review/ship. Its only job is to drop a half-formed idea into the backlog without spinning up a full flow.
4
+
5
+ ## Behaviour
6
+
7
+ 1. Open \`.cclaw/ideas.md\`. If it does not exist, seed it from \`.cclaw/lib/templates/ideas.md\`.
8
+ 2. Append a new entry with this shape:
9
+
10
+ \`\`\`
11
+ ## YYYY-MM-DDTHH:MM:SSZ — <one-line summary>
12
+
13
+ <short paragraph or bullet list with the idea body>
14
+ \`\`\`
15
+
16
+ 3. Save the file. Do not slugify, do not create artifacts under \`.cclaw/flows/<slug>/\`, do not modify \`flow-state.json\`, do not invoke specialists.
17
+
18
+ ## Hard rules
19
+
20
+ - One entry per invocation. If the user pastes multiple ideas, ask whether to file them as one entry or several.
21
+ - Never auto-promote an idea to a plan. Promotion happens only when the user explicitly invokes \`/cc <task>\`.
22
+ - Never delete or edit prior ideas inside \`/cc-idea\`. Trimming the backlog is a separate manual step.
23
+
24
+ ## Suggested entry shape
25
+
26
+ \`\`\`
27
+ ## 2026-05-07T19:30:12Z — switch knowledge.jsonl to ndjson
28
+
29
+ Right now \`.cclaw/knowledge.jsonl\` is one JSON object per line, but tooling
30
+ expects RFC 8259-compliant NDJSON. Worth verifying once the tooling adopts
31
+ the standard formally.
32
+ \`\`\`
33
+
34
+ The orchestrator surfaces ideas back to the user only when an explicit \`/cc\` invocation references them; otherwise they stay quiet.
35
+ `;
36
+ export function renderIdeaCommand() {
37
+ return IDEA_COMMAND_BODY;
38
+ }
@@ -1,141 +1,7 @@
1
- import type { FlowStage } from "../types.js";
2
- export type IronLawEnforcementPoint = "PreToolUse" | "PostToolUse" | "SessionStart" | "Stop" | "advisory";
3
- export type IronLawSeverity = "hard-gate" | "soft-gate";
4
- export interface IronLawDefinition {
1
+ export interface IronLaw {
5
2
  id: string;
6
3
  title: string;
7
- rule: string;
8
- rationale: string;
9
- enforcement: IronLawEnforcementPoint;
10
- severity: IronLawSeverity;
11
- appliesTo: "all" | FlowStage[];
12
- hookMatcher?: {
13
- toolPattern?: string;
14
- payloadPattern?: string;
15
- };
4
+ description: string;
16
5
  }
17
- export interface IronLawRuntimeRecord {
18
- id: string;
19
- title: string;
20
- rule: string;
21
- enforcement: IronLawEnforcementPoint;
22
- severity: IronLawSeverity;
23
- appliesTo: "all" | FlowStage[];
24
- strict: boolean;
25
- hookMatcher?: {
26
- toolPattern?: string;
27
- payloadPattern?: string;
28
- };
29
- }
30
- export interface IronLawRuntimeDocument {
31
- version: 1;
32
- generatedAt: string;
33
- mode: "advisory" | "strict";
34
- strictLaws: string[];
35
- laws: IronLawRuntimeRecord[];
36
- }
37
- export declare const IRON_LAWS: readonly [{
38
- readonly id: "tdd-red-before-write";
39
- readonly title: "RED before production write";
40
- readonly rule: "Do not edit production code in tdd stage before a failing RED test exists for the slice.";
41
- readonly rationale: "Prevents implementation-first behavior and keeps RED as executable specification.";
42
- readonly enforcement: "PreToolUse";
43
- readonly severity: "hard-gate";
44
- readonly appliesTo: ["tdd"];
45
- readonly hookMatcher: {
46
- readonly toolPattern: "write|edit|multiedit|applypatch|shell|bash";
47
- readonly payloadPattern: "\\.(ts|tsx|js|jsx|py|go|java|rs|rb|php|c|cc|cpp|h|hpp)";
48
- };
49
- }, {
50
- readonly id: "plan-requires-approval";
51
- readonly title: "No implementation before plan approval";
52
- readonly rule: "Do not perform write-like actions while plan stage is pending WAIT_FOR_CONFIRM approval.";
53
- readonly rationale: "Locks intent before execution and reduces expensive rework from unapproved paths.";
54
- readonly enforcement: "PreToolUse";
55
- readonly severity: "hard-gate";
56
- readonly appliesTo: ["plan"];
57
- }, {
58
- readonly id: "runtime-writes-managed-only";
59
- readonly title: "Runtime writes are managed";
60
- readonly rule: "Do not mutate .cclaw/state, .cclaw/hooks, or .cclaw/skills by ad-hoc edits unless using cclaw-managed commands.";
61
- readonly rationale: "Protects generated runtime integrity and avoids drift that silently breaks hooks or skills.";
62
- readonly enforcement: "PreToolUse";
63
- readonly severity: "hard-gate";
64
- readonly appliesTo: "all";
65
- readonly hookMatcher: {
66
- readonly toolPattern: "write|edit|multiedit|delete|applypatch|shell|bash";
67
- readonly payloadPattern: "\\.cclaw/(state|hooks|skills)";
68
- };
69
- }, {
70
- readonly id: "flow-state-read-fresh";
71
- readonly title: "Fresh flow-state read required";
72
- readonly rule: "Before mutating actions, a fresh read of .cclaw/state/flow-state.json must exist within guard freshness window.";
73
- readonly rationale: "Prevents stale-stage mutations after context shifts or multi-agent divergence.";
74
- readonly enforcement: "PreToolUse";
75
- readonly severity: "hard-gate";
76
- readonly appliesTo: "all";
77
- }, {
78
- readonly id: "review-layer-order";
79
- readonly title: "Review layers are sequential";
80
- readonly rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.";
81
- readonly rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.";
82
- readonly enforcement: "PreToolUse";
83
- readonly severity: "hard-gate";
84
- readonly appliesTo: ["review"];
85
- }, {
86
- readonly id: "review-criticals-close-before-ship";
87
- readonly title: "No ship with open criticals";
88
- readonly rule: "Ship decisions are blocked when review-army contains open Critical findings or ship blockers.";
89
- readonly rationale: "Enforces explicit risk closure before release finalization.";
90
- readonly enforcement: "PreToolUse";
91
- readonly severity: "hard-gate";
92
- readonly appliesTo: ["ship"];
93
- }, {
94
- readonly id: "ship-preflight-required";
95
- readonly title: "Preflight required before finalization";
96
- readonly rule: "Do not execute release finalization actions until ship preflight gate is passed.";
97
- readonly rationale: "Catches regressions before irreversible release steps.";
98
- readonly enforcement: "PreToolUse";
99
- readonly severity: "hard-gate";
100
- readonly appliesTo: ["ship"];
101
- }, {
102
- readonly id: "review-coverage-complete-before-ship";
103
- readonly title: "Review layer coverage before ship";
104
- readonly rule: "Block ship finalization when review-army does not confirm full Layer 1/2 coverage map.";
105
- readonly rationale: "Prevents finalization when multi-pass review evidence is incomplete or partially missing.";
106
- readonly enforcement: "PreToolUse";
107
- readonly severity: "hard-gate";
108
- readonly appliesTo: ["ship"];
109
- }, {
110
- readonly id: "subagent-task-self-contained";
111
- readonly title: "Subagent tasks are self-contained";
112
- readonly rule: "Delegated tasks must include explicit objective, constraints, and expected output, not just references.";
113
- readonly rationale: "Avoids context loss and low-quality delegation in isolated worker contexts.";
114
- readonly enforcement: "advisory";
115
- readonly severity: "soft-gate";
116
- readonly appliesTo: "all";
117
- }, {
118
- readonly id: "no-secrets-in-artifacts";
119
- readonly title: "Never log secrets in artifacts";
120
- readonly rule: "Secrets/tokens/passwords must not be written to review, ship, or runtime state artifacts.";
121
- readonly rationale: "Prevents accidental credential leakage through generated workflow artifacts.";
122
- readonly enforcement: "PostToolUse";
123
- readonly severity: "hard-gate";
124
- readonly appliesTo: "all";
125
- }, {
126
- readonly id: "stop-clean-or-handoff";
127
- readonly title: "Stop only from clean handoff";
128
- readonly rule: "Do not end a session with dirty state unless the current artifact records unresolved work and blockers.";
129
- readonly rationale: "Protects continuity and prevents silent half-finished sessions.";
130
- readonly enforcement: "Stop";
131
- readonly severity: "hard-gate";
132
- readonly appliesTo: "all";
133
- }];
134
- export declare function isIronLawId(value: string): boolean;
135
- export declare function normalizeStrictLawIds(ids: string[] | undefined): string[];
136
- export declare function ironLawRuntimeDocument(options?: {
137
- mode?: "advisory" | "strict";
138
- strictLaws?: string[];
139
- nowIso?: string;
140
- }): IronLawRuntimeDocument;
141
- export declare function ironLawsSkillMarkdown(): string;
6
+ export declare const IRON_LAWS: IronLaw[];
7
+ export declare function ironLawsMarkdown(): string;
@@ -1,210 +1,31 @@
1
- import { RUNTIME_ROOT } from "../constants.js";
2
1
  export const IRON_LAWS = [
3
2
  {
4
- id: "tdd-red-before-write",
5
- title: "RED before production write",
6
- rule: "Do not edit production code in tdd stage before a failing RED test exists for the slice.",
7
- rationale: "Prevents implementation-first behavior and keeps RED as executable specification.",
8
- enforcement: "PreToolUse",
9
- severity: "hard-gate",
10
- appliesTo: ["tdd"],
11
- hookMatcher: {
12
- toolPattern: "write|edit|multiedit|applypatch|shell|bash",
13
- payloadPattern: "\\.(ts|tsx|js|jsx|py|go|java|rs|rb|php|c|cc|cpp|h|hpp)"
14
- }
3
+ id: "think-before-coding",
4
+ title: "Think Before Coding",
5
+ description: "Read enough of the codebase to write the change correctly the first time. Skipping the read step is the most common cause of cascading errors and hallucinated actions."
15
6
  },
16
7
  {
17
- id: "plan-requires-approval",
18
- title: "No implementation before plan approval",
19
- rule: "Do not perform write-like actions while plan stage is pending WAIT_FOR_CONFIRM approval.",
20
- rationale: "Locks intent before execution and reduces expensive rework from unapproved paths.",
21
- enforcement: "PreToolUse",
22
- severity: "hard-gate",
23
- appliesTo: ["plan"]
8
+ id: "simplicity-first",
9
+ title: "Simplicity First",
10
+ description: "Pick the smallest design that satisfies the acceptance criteria. Resist abstractions, configuration knobs, and indirection that no AC asks for."
24
11
  },
25
12
  {
26
- id: "runtime-writes-managed-only",
27
- title: "Runtime writes are managed",
28
- rule: `Do not mutate ${RUNTIME_ROOT}/state, ${RUNTIME_ROOT}/hooks, or ${RUNTIME_ROOT}/skills by ad-hoc edits unless using cclaw-managed commands.`,
29
- rationale: "Protects generated runtime integrity and avoids drift that silently breaks hooks or skills.",
30
- enforcement: "PreToolUse",
31
- severity: "hard-gate",
32
- appliesTo: "all",
33
- hookMatcher: {
34
- toolPattern: "write|edit|multiedit|delete|applypatch|shell|bash",
35
- payloadPattern: "\\.cclaw/(state|hooks|skills)"
36
- }
13
+ id: "surgical-changes",
14
+ title: "Surgical Changes",
15
+ description: "Touch only what each AC requires. If a change starts pulling in unrelated files, stop and split the task scope creep is one of the five review failure modes."
37
16
  },
38
17
  {
39
- id: "flow-state-read-fresh",
40
- title: "Fresh flow-state read required",
41
- rule: `Before mutating actions, a fresh read of ${RUNTIME_ROOT}/state/flow-state.json must exist within guard freshness window.`,
42
- rationale: "Prevents stale-stage mutations after context shifts or multi-agent divergence.",
43
- enforcement: "PreToolUse",
44
- severity: "hard-gate",
45
- appliesTo: "all"
18
+ id: "goal-driven-execution",
19
+ title: "Goal-Driven Execution",
20
+ description: "Every action must move a specific AC closer to committed status. If the action does not, do not run it; record the question for the user."
46
21
  },
47
22
  {
48
- id: "review-layer-order",
49
- title: "Review layers are sequential",
50
- rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.",
51
- rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.",
52
- enforcement: "PreToolUse",
53
- severity: "hard-gate",
54
- appliesTo: ["review"]
55
- },
56
- {
57
- id: "review-criticals-close-before-ship",
58
- title: "No ship with open criticals",
59
- rule: "Ship decisions are blocked when review-army contains open Critical findings or ship blockers.",
60
- rationale: "Enforces explicit risk closure before release finalization.",
61
- enforcement: "PreToolUse",
62
- severity: "hard-gate",
63
- appliesTo: ["ship"]
64
- },
65
- {
66
- id: "ship-preflight-required",
67
- title: "Preflight required before finalization",
68
- rule: "Do not execute release finalization actions until ship preflight gate is passed.",
69
- rationale: "Catches regressions before irreversible release steps.",
70
- enforcement: "PreToolUse",
71
- severity: "hard-gate",
72
- appliesTo: ["ship"]
73
- },
74
- {
75
- id: "review-coverage-complete-before-ship",
76
- title: "Review layer coverage before ship",
77
- rule: "Block ship finalization when review-army does not confirm full Layer 1/2 coverage map.",
78
- rationale: "Prevents finalization when multi-pass review evidence is incomplete or partially missing.",
79
- enforcement: "PreToolUse",
80
- severity: "hard-gate",
81
- appliesTo: ["ship"]
82
- },
83
- {
84
- id: "subagent-task-self-contained",
85
- title: "Subagent tasks are self-contained",
86
- rule: "Delegated tasks must include explicit objective, constraints, and expected output, not just references.",
87
- rationale: "Avoids context loss and low-quality delegation in isolated worker contexts.",
88
- enforcement: "advisory",
89
- severity: "soft-gate",
90
- appliesTo: "all"
91
- },
92
- {
93
- id: "no-secrets-in-artifacts",
94
- title: "Never log secrets in artifacts",
95
- rule: "Secrets/tokens/passwords must not be written to review, ship, or runtime state artifacts.",
96
- rationale: "Prevents accidental credential leakage through generated workflow artifacts.",
97
- enforcement: "PostToolUse",
98
- severity: "hard-gate",
99
- appliesTo: "all"
100
- },
101
- {
102
- id: "stop-clean-or-handoff",
103
- title: "Stop only from clean handoff",
104
- rule: "Do not end a session with dirty state unless the current artifact records unresolved work and blockers.",
105
- rationale: "Protects continuity and prevents silent half-finished sessions.",
106
- enforcement: "Stop",
107
- severity: "hard-gate",
108
- appliesTo: "all"
23
+ id: "red-before-green",
24
+ title: "No Production Code Without a Failing Test First",
25
+ description: "Build is a TDD cycle. Every AC starts with a failing test (RED), then the minimal implementation that makes it pass (GREEN), then the refactor that keeps it passing (REFACTOR). The RED failure is the spec; never write production code before it exists."
109
26
  }
110
27
  ];
111
- export function isIronLawId(value) {
112
- return IRON_LAWS.some((law) => law.id === value);
113
- }
114
- export function normalizeStrictLawIds(ids) {
115
- if (!Array.isArray(ids))
116
- return [];
117
- const unique = new Set();
118
- for (const id of ids) {
119
- if (typeof id !== "string")
120
- continue;
121
- const trimmed = id.trim();
122
- if (!trimmed || !isIronLawId(trimmed))
123
- continue;
124
- unique.add(trimmed);
125
- }
126
- return [...unique];
127
- }
128
- export function ironLawRuntimeDocument(options = {}) {
129
- const mode = options.mode === "strict" ? "strict" : "advisory";
130
- const strictLawSet = new Set(normalizeStrictLawIds(options.strictLaws));
131
- const laws = IRON_LAWS.map((law) => ({
132
- id: law.id,
133
- title: law.title,
134
- rule: law.rule,
135
- enforcement: law.enforcement,
136
- severity: law.severity,
137
- appliesTo: law.appliesTo === "all" ? "all" : [...law.appliesTo],
138
- strict: mode === "strict" || strictLawSet.has(law.id),
139
- hookMatcher: "hookMatcher" in law ? law.hookMatcher : undefined
140
- }));
141
- return {
142
- version: 1,
143
- generatedAt: options.nowIso ?? new Date().toISOString(),
144
- mode,
145
- strictLaws: [...strictLawSet],
146
- laws
147
- };
148
- }
149
- function appliesToLabel(law) {
150
- return law.appliesTo === "all" ? "all stages" : law.appliesTo.join(", ");
151
- }
152
- function hardGateReference(law) {
153
- if (law.appliesTo === "all") {
154
- return "the active stage `HARD-GATE` block in `.cclaw/skills/<stage>/SKILL.md`";
155
- }
156
- return law.appliesTo
157
- .map((stage) => `\`${RUNTIME_ROOT}/skills/${stage}/SKILL.md\` (${stage} HARD-GATE)`)
158
- .join(", ");
159
- }
160
- export function ironLawsSkillMarkdown() {
161
- // Phase A purged the `PreToolUse` / `PostToolUse` / pre-tool
162
- // pipeline handlers, so `review-coverage-complete-before-ship` is no
163
- // longer hook-enforced — it now lives in the ship stage HARD-GATE.
164
- // Only `stop-clean-or-handoff` (Stop hook) is still hook-enforced;
165
- // everything else is stage-owned advisory.
166
- const enforcedLawIds = new Set([
167
- "stop-clean-or-handoff"
168
- ]);
169
- const enforced = IRON_LAWS.filter((law) => enforcedLawIds.has(law.id));
170
- const advisory = IRON_LAWS.filter((law) => !enforcedLawIds.has(law.id));
171
- const enforcedSections = enforced.map((law, index) => {
172
- return `### ${index + 1}. ${law.title}
173
-
174
- - **ID:** \`${law.id}\`
175
- - **Rule:** ${law.rule}
176
- - **Why:** ${law.rationale}
177
- - **Applies to:** ${appliesToLabel(law)}
178
- - **Enforced by:** ${law.enforcement} (${law.severity})
179
- `;
180
- }).join("\n");
181
- const advisoryList = advisory
182
- .map((law) => `- \`${law.id}\` — applies to ${appliesToLabel(law)}; see ${hardGateReference(law)}.`)
183
- .join("\n");
184
- return `---
185
- name: iron-laws
186
- description: "Non-negotiable workflow constraints enforced by cclaw hooks and routing."
187
- ---
188
-
189
- # Iron Laws
190
-
191
- These are cclaw's non-negotiable constraints for harness sessions.
192
- Use them as the final arbitration layer when local instructions conflict.
193
-
194
- ## Hook-Enforced Runtime Laws
195
-
196
- ${enforcedSections}
197
-
198
- ## Advisory Laws (Stage-Owned)
199
-
200
- The following laws remain active guidance, but their canonical enforcement surface
201
- is each stage's \`HARD-GATE\` contract:
202
-
203
- ${advisoryList}
204
-
205
- ## Practical rule
206
-
207
- If a law says stop, stop and surface the blocking reason with the smallest safe
208
- next step.
209
- `;
28
+ export function ironLawsMarkdown() {
29
+ const sections = IRON_LAWS.map((law, index) => `${index + 1}. **${law.title}** ${law.description}`).join("\n");
30
+ return `## Iron Laws (Karpathy)\n\n${sections}\n`;
210
31
  }
@@ -1,3 +1 @@
1
- export declare const META_SKILL_NAME = "using-cclaw";
2
- export declare const META_SKILL_GENERATED_HELPER_SKILLS: readonly ["subagent-dev", "parallel-dispatch", "session", "iron-laws"];
3
- export declare function usingCclawSkillMarkdown(): string;
1
+ export declare const META_SKILL = "---\nname: cclaw-meta\ntrigger: always-on; loaded with every /cc invocation\n---\n\n# Meta-skill \u2014 how to be a cclaw orchestrator\n\nThis skill is loaded by the harness with every `/cc` invocation. It does not duplicate `/cc` itself; it tells you **how to use** the rest of cclaw's content.\n\n## What is in your context\n\nWhen `/cc` runs, the harness has access to:\n\n- `.cursor/commands/cc.md` \u2014 your operating manual (also in `.cursor/skills/cclaw/` mirrors).\n- `.cclaw/lib/agents/*.md` \u2014 six specialist prompts.\n- `.cclaw/lib/skills/*.md` \u2014 six auto-trigger skills.\n- `.cclaw/lib/templates/*.md` \u2014 ten artifact templates.\n- `.cclaw/lib/runbooks/*.md` \u2014 four stage runbooks.\n- `.cclaw/lib/patterns/*.md` \u2014 eight task patterns.\n- `.cclaw/lib/research/*.md` \u2014 five research playbooks.\n- `.cclaw/lib/recovery/*.md` \u2014 five recovery playbooks.\n- `.cclaw/lib/decision-protocol.md` \u2014 D-N record format.\n- `.cclaw/lib/examples/*.md` \u2014 thirteen worked examples.\n- `.cclaw/lib/antipatterns.md` \u2014 twelve known failure modes.\n\n## How to read this content efficiently\n\nYou do not need to read everything. The right loading pattern:\n\n1. **Always read `/cc`** \u2014 your operating manual.\n2. **Read the runbook** for the stage you are in (`.cclaw/lib/runbooks/<stage>.md`).\n3. **Read the pattern(s)** that match the task (`.cclaw/lib/patterns/`).\n4. **Read the specialist prompt** when you invoke a specialist (`.cclaw/lib/agents/<id>.md`).\n5. **Read the recovery playbook** when an automated check fails.\n6. **Read examples** when authoring an artifact you have not seen before.\n\nDon't read research playbooks unless you're invoking planner mode=`research`. Don't read antipatterns proactively; the reviewer cites them as findings.\n\n## Your responsibilities as orchestrator\n\n1. **Sanity check first.** Always verify `flow-state.json` schemaVersion=2 before doing anything.\n2. **Detect existing plans.** Always run existing-plan detection before authoring a new plan.\n3. **Calibrate routing.** Always run Phase 0 calibration; never skip to specialists for a trivial task.\n4. **Ask before invoking specialists.** Never silently invoke. The user picks.\n5. **Ask before push / PR.** Always; every time; per turn.\n6. **Surface, don't decide.** When a checkpoint, conflict, or cap-reached situation appears, present options to the user. Do not decide on their behalf.\n7. **Cite, don't invent.** Every file:line reference in your output must be real. Reviewer adversarial mode will catch you.\n\n## Your boundaries\n\n- You do not write code. `slice-builder` does.\n- You do not author decisions alone. `architect` does.\n- You do not enforce AC traceability. `commit-helper.mjs` does.\n- You do not delete artifacts. `/cc-cancel` does.\n- You do not push or open PRs without explicit user approval.\n\n## Iron laws (always-on)\n\n1. **Think before coding.** Read the targets first. Cite `file:line`.\n2. **Simplicity first.** The smallest correct change wins.\n3. **Surgical changes.** Touch only declared files.\n4. **Goal-driven execution.** AC are the contract; everything else is implementation detail.\n\n## Five failure modes (always-on)\n\nWhen in doubt, ask: am I about to commit one of these?\n\n1. Hallucinated actions (invented files / ids / flags).\n2. Scope creep (changes outside declared AC).\n3. Cascading errors (fix breaks something else).\n4. Context loss (forgot earlier decision).\n5. Tool misuse (wrong mode / destructive action).\n\nIf yes, stop and surface.\n\n## When the user pushes back\n\nTrust the user's calibration. If they say \"this feels weak\", they are not asking for reassurance \u2014 they are asking for more depth. Open more content (patterns, examples, recovery), broaden the AC set, invoke the missing specialist. Do not defend the current state.\n\nIf they say \"this feels overcomplicated\", they are asking for less. Skip specialists, shorten Context, drop optional sections. Trivial tasks should not run the full chain.\n";