@llipe.com/dev-tasks 0.11.0 → 0.16.2

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 (618) hide show
  1. package/.claude/agents/developer.md +138 -62
  2. package/.claude/agents/github-ops.md +48 -4
  3. package/.claude/agents/housekeeping.md +44 -7
  4. package/.claude/agents/qa-engineer.md +24 -11
  5. package/.claude/agents/researcher.md +26 -6
  6. package/.claude/agents/technical-writer.md +64 -7
  7. package/.claude/agents/ux-engineer.md +1 -0
  8. package/.claude/agents/verifier.md +63 -6
  9. package/.claude/commands/developer.md +2 -266
  10. package/.claude/commands/infra-engineer.md +92 -0
  11. package/.claude/commands/planner.md +98 -29
  12. package/.claude/commands/product-engineer.md +69 -11
  13. package/.claude/commands/researcher.md +4 -5
  14. package/.claude/commands/technical-writer.md +1 -1
  15. package/.claude/hooks/branch-guard.sh +30 -0
  16. package/.claude/hooks/git-guard.sh +573 -24
  17. package/.claude/skills/activity-codebase-research/SKILL.md +4 -11
  18. package/.claude/skills/activity-generate-spec/SKILL.md +34 -10
  19. package/.claude/skills/activity-grill/SKILL.md +150 -0
  20. package/.claude/skills/activity-init/SKILL.md +121 -71
  21. package/.claude/skills/activity-refine/SKILL.md +75 -15
  22. package/.claude/skills/activity-test-standards/SKILL.md +25 -0
  23. package/.claude/skills/aws-ops/SKILL.md +155 -0
  24. package/.claude/skills/deploy-ops/SKILL.md +121 -0
  25. package/.claude/skills/fly-ops/SKILL.md +138 -0
  26. package/.claude/skills/git-ops/SKILL.md +27 -7
  27. package/.claude/skills/implement/SKILL.md +61 -12
  28. package/.claude/skills/memo-cli-usage/REFERENCE.md +230 -17
  29. package/.claude/skills/memo-cli-usage/SKILL.md +68 -13
  30. package/.claude/skills/plan/SKILL.md +43 -1
  31. package/.claude/skills/supabase-ops/SKILL.md +109 -0
  32. package/.github/agents/developer.agent.md +103 -38
  33. package/.github/agents/github-ops.agent.md +46 -4
  34. package/.github/agents/housekeeping.agent.md +43 -7
  35. package/.github/agents/infra-engineer.agent.md +139 -0
  36. package/.github/agents/planner.agent.md +79 -10
  37. package/.github/agents/product-engineer.agent.md +69 -11
  38. package/.github/agents/qa-engineer.agent.md +23 -11
  39. package/.github/agents/researcher.agent.md +25 -6
  40. package/.github/agents/technical-writer.agent.md +63 -7
  41. package/.github/agents/verifier.agent.md +61 -5
  42. package/.github/instructions/implement.instructions.md +61 -12
  43. package/.github/instructions/plan.instructions.md +43 -1
  44. package/.github/prompts/infra-engineer.prompt.md +12 -0
  45. package/.github/prompts/product-engineer-init.prompt.md +5 -6
  46. package/.github/prompts/researcher.prompt.md +4 -5
  47. package/.github/prompts/technical-writer.prompt.md +1 -1
  48. package/.github/skills/activity-codebase-research/SKILL.md +4 -16
  49. package/.github/skills/activity-generate-spec/SKILL.md +34 -10
  50. package/.github/skills/activity-grill/SKILL.md +145 -0
  51. package/.github/skills/activity-init/SKILL.md +120 -70
  52. package/.github/skills/activity-refine/SKILL.md +75 -15
  53. package/.github/skills/activity-test-standards/SKILL.md +25 -0
  54. package/.github/skills/aws-ops/SKILL.md +150 -0
  55. package/.github/skills/deploy-ops/SKILL.md +116 -0
  56. package/.github/skills/fly-ops/SKILL.md +133 -0
  57. package/.github/skills/git-ops/SKILL.md +27 -7
  58. package/.github/skills/memo-cli-usage/REFERENCE.md +230 -17
  59. package/.github/skills/memo-cli-usage/SKILL.md +68 -13
  60. package/.github/skills/supabase-ops/SKILL.md +104 -0
  61. package/.kiro/agents/developer.md +104 -39
  62. package/.kiro/agents/github-ops.md +46 -4
  63. package/.kiro/agents/housekeeping.md +44 -8
  64. package/.kiro/agents/infra-engineer.md +102 -0
  65. package/.kiro/agents/planner.md +87 -21
  66. package/.kiro/agents/product-engineer.md +72 -14
  67. package/.kiro/agents/qa-engineer.md +24 -12
  68. package/.kiro/agents/researcher.md +26 -7
  69. package/.kiro/agents/technical-writer.md +66 -10
  70. package/.kiro/agents/verifier.md +62 -6
  71. package/.kiro/hooks/scripts/git-guard.sh +96 -10
  72. package/.kiro/skills/activity-codebase-research/SKILL.md +4 -11
  73. package/.kiro/skills/activity-generate-spec/SKILL.md +34 -10
  74. package/.kiro/skills/activity-grill/SKILL.md +150 -0
  75. package/.kiro/skills/activity-init/SKILL.md +121 -71
  76. package/.kiro/skills/activity-refine/SKILL.md +75 -15
  77. package/.kiro/skills/activity-test-standards/SKILL.md +25 -0
  78. package/.kiro/skills/aws-ops/SKILL.md +155 -0
  79. package/.kiro/skills/deploy-ops/SKILL.md +121 -0
  80. package/.kiro/skills/fly-ops/SKILL.md +138 -0
  81. package/.kiro/skills/git-ops/SKILL.md +27 -7
  82. package/.kiro/skills/memo-cli-usage/REFERENCE.md +230 -17
  83. package/.kiro/skills/memo-cli-usage/SKILL.md +68 -13
  84. package/.kiro/skills/supabase-ops/SKILL.md +109 -0
  85. package/.kiro/steering/implement.md +61 -12
  86. package/.kiro/steering/plan.md +43 -1
  87. package/AGENTS.md +67 -114
  88. package/AGENTS.md.template +126 -0
  89. package/CHANGELOG.md +182 -0
  90. package/CLAUDE.md +25 -19
  91. package/CLAUDE.md.template +104 -0
  92. package/README.md +168 -146
  93. package/TESTING.md +84 -148
  94. package/bundle-manifest.json +43 -2
  95. package/dist/bin/dev-tasks.js +65 -3
  96. package/dist/bin/dev-tasks.js.map +1 -1
  97. package/dist/{adapters/cli → bin}/parse-args.d.ts +2 -6
  98. package/dist/bin/parse-args.d.ts.map +1 -0
  99. package/dist/{adapters/cli → bin}/parse-args.js +2 -18
  100. package/dist/bin/parse-args.js.map +1 -0
  101. package/dist/core/checks/decision-log-format.d.ts +44 -0
  102. package/dist/core/checks/decision-log-format.d.ts.map +1 -0
  103. package/dist/core/checks/decision-log-format.js +171 -0
  104. package/dist/core/checks/decision-log-format.js.map +1 -0
  105. package/dist/core/checks/docs-structure.d.ts +82 -0
  106. package/dist/core/checks/docs-structure.d.ts.map +1 -0
  107. package/dist/core/checks/docs-structure.js +285 -0
  108. package/dist/core/checks/docs-structure.js.map +1 -0
  109. package/dist/core/checks/glossary.d.ts +178 -0
  110. package/dist/core/checks/glossary.d.ts.map +1 -0
  111. package/dist/core/checks/glossary.js +651 -0
  112. package/dist/core/checks/glossary.js.map +1 -0
  113. package/dist/core/checks/index.d.ts +19 -0
  114. package/dist/core/checks/index.d.ts.map +1 -0
  115. package/dist/core/checks/index.js +16 -0
  116. package/dist/core/checks/index.js.map +1 -0
  117. package/dist/core/checks/run.d.ts +22 -0
  118. package/dist/core/checks/run.d.ts.map +1 -0
  119. package/dist/core/checks/run.js +51 -0
  120. package/dist/core/checks/run.js.map +1 -0
  121. package/dist/core/distribution/doctor.d.ts +46 -1
  122. package/dist/core/distribution/doctor.d.ts.map +1 -1
  123. package/dist/core/distribution/doctor.js +161 -2
  124. package/dist/core/distribution/doctor.js.map +1 -1
  125. package/dist/core/distribution/index.d.ts +9 -3
  126. package/dist/core/distribution/index.d.ts.map +1 -1
  127. package/dist/core/distribution/index.js +5 -2
  128. package/dist/core/distribution/index.js.map +1 -1
  129. package/dist/core/distribution/install-if-absent.d.ts +46 -0
  130. package/dist/core/distribution/install-if-absent.d.ts.map +1 -0
  131. package/dist/core/distribution/install-if-absent.js +81 -0
  132. package/dist/core/distribution/install-if-absent.js.map +1 -0
  133. package/dist/core/distribution/install.d.ts.map +1 -1
  134. package/dist/core/distribution/install.js +5 -0
  135. package/dist/core/distribution/install.js.map +1 -1
  136. package/dist/core/distribution/migrate-docs.d.ts +64 -0
  137. package/dist/core/distribution/migrate-docs.d.ts.map +1 -0
  138. package/dist/core/distribution/migrate-docs.js +139 -0
  139. package/dist/core/distribution/migrate-docs.js.map +1 -0
  140. package/dist/core/distribution/profiles.d.ts +49 -0
  141. package/dist/core/distribution/profiles.d.ts.map +1 -1
  142. package/dist/core/distribution/profiles.js +45 -0
  143. package/dist/core/distribution/profiles.js.map +1 -1
  144. package/dist/core/distribution/update.d.ts +14 -0
  145. package/dist/core/distribution/update.d.ts.map +1 -1
  146. package/dist/core/distribution/update.js +77 -3
  147. package/dist/core/distribution/update.js.map +1 -1
  148. package/dist/core/distribution/workspace.d.ts +84 -0
  149. package/dist/core/distribution/workspace.d.ts.map +1 -0
  150. package/dist/core/distribution/workspace.js +276 -0
  151. package/dist/core/distribution/workspace.js.map +1 -0
  152. package/dist/core/exit-codes.d.ts +15 -35
  153. package/dist/core/exit-codes.d.ts.map +1 -1
  154. package/dist/core/exit-codes.js +15 -36
  155. package/dist/core/exit-codes.js.map +1 -1
  156. package/dist/core/index.d.ts +1 -6
  157. package/dist/core/index.d.ts.map +1 -1
  158. package/dist/core/index.js +1 -7
  159. package/dist/core/index.js.map +1 -1
  160. package/package.json +17 -32
  161. package/templates/claude/settings.json +48 -0
  162. package/templates/domain/ubiquitous-language.md +28 -0
  163. package/templates/infra/environments.yaml +16 -0
  164. package/templates/infra/redaction-patterns.txt +47 -0
  165. package/templates/runbooks/README.md +14 -0
  166. package/templates/runbooks/runbook-template.md +40 -0
  167. package/templates/scripts/deploy-status.sh +89 -0
  168. package/templates/scripts/deploy-verify.sh +85 -0
  169. package/templates/scripts/deploy.sh +284 -0
  170. package/templates/scripts/release.sh +170 -0
  171. package/templates/scripts/rollback.sh +109 -0
  172. package/templates/workflows/deploy-dev.yml +66 -0
  173. package/templates/workflows/deploy-prod.yml +66 -0
  174. package/templates/workflows/rollback.yml +77 -0
  175. package/.claude/skills/activity-contract-validation/SKILL.md +0 -167
  176. package/.github/skills/activity-contract-validation/SKILL.md +0 -167
  177. package/.kiro/skills/activity-contract-validation/SKILL.md +0 -167
  178. package/dist/adapters/cli/catalog-build.d.ts +0 -30
  179. package/dist/adapters/cli/catalog-build.d.ts.map +0 -1
  180. package/dist/adapters/cli/catalog-build.js +0 -73
  181. package/dist/adapters/cli/catalog-build.js.map +0 -1
  182. package/dist/adapters/cli/catalog-query.d.ts +0 -13
  183. package/dist/adapters/cli/catalog-query.d.ts.map +0 -1
  184. package/dist/adapters/cli/catalog-query.js +0 -329
  185. package/dist/adapters/cli/catalog-query.js.map +0 -1
  186. package/dist/adapters/cli/catalog-scaffold.d.ts +0 -24
  187. package/dist/adapters/cli/catalog-scaffold.d.ts.map +0 -1
  188. package/dist/adapters/cli/catalog-scaffold.js +0 -46
  189. package/dist/adapters/cli/catalog-scaffold.js.map +0 -1
  190. package/dist/adapters/cli/catalog-validate.d.ts +0 -35
  191. package/dist/adapters/cli/catalog-validate.d.ts.map +0 -1
  192. package/dist/adapters/cli/catalog-validate.js +0 -122
  193. package/dist/adapters/cli/catalog-validate.js.map +0 -1
  194. package/dist/adapters/cli/ctx-assemble.d.ts +0 -19
  195. package/dist/adapters/cli/ctx-assemble.d.ts.map +0 -1
  196. package/dist/adapters/cli/ctx-assemble.js +0 -293
  197. package/dist/adapters/cli/ctx-assemble.js.map +0 -1
  198. package/dist/adapters/cli/ctx-fetch.d.ts +0 -49
  199. package/dist/adapters/cli/ctx-fetch.d.ts.map +0 -1
  200. package/dist/adapters/cli/ctx-fetch.js +0 -267
  201. package/dist/adapters/cli/ctx-fetch.js.map +0 -1
  202. package/dist/adapters/cli/extract-all.d.ts +0 -31
  203. package/dist/adapters/cli/extract-all.d.ts.map +0 -1
  204. package/dist/adapters/cli/extract-all.js +0 -374
  205. package/dist/adapters/cli/extract-all.js.map +0 -1
  206. package/dist/adapters/cli/extract-asyncapi.d.ts +0 -26
  207. package/dist/adapters/cli/extract-asyncapi.d.ts.map +0 -1
  208. package/dist/adapters/cli/extract-asyncapi.js +0 -142
  209. package/dist/adapters/cli/extract-asyncapi.js.map +0 -1
  210. package/dist/adapters/cli/extract-component.d.ts +0 -24
  211. package/dist/adapters/cli/extract-component.d.ts.map +0 -1
  212. package/dist/adapters/cli/extract-component.js +0 -198
  213. package/dist/adapters/cli/extract-component.js.map +0 -1
  214. package/dist/adapters/cli/extract-detect.d.ts +0 -19
  215. package/dist/adapters/cli/extract-detect.d.ts.map +0 -1
  216. package/dist/adapters/cli/extract-detect.js +0 -98
  217. package/dist/adapters/cli/extract-detect.js.map +0 -1
  218. package/dist/adapters/cli/extract-openapi.d.ts +0 -29
  219. package/dist/adapters/cli/extract-openapi.d.ts.map +0 -1
  220. package/dist/adapters/cli/extract-openapi.js +0 -111
  221. package/dist/adapters/cli/extract-openapi.js.map +0 -1
  222. package/dist/adapters/cli/extract-schema.d.ts +0 -15
  223. package/dist/adapters/cli/extract-schema.d.ts.map +0 -1
  224. package/dist/adapters/cli/extract-schema.js +0 -39
  225. package/dist/adapters/cli/extract-schema.js.map +0 -1
  226. package/dist/adapters/cli/index.d.ts +0 -6
  227. package/dist/adapters/cli/index.d.ts.map +0 -1
  228. package/dist/adapters/cli/index.js +0 -5
  229. package/dist/adapters/cli/index.js.map +0 -1
  230. package/dist/adapters/cli/init.d.ts +0 -37
  231. package/dist/adapters/cli/init.d.ts.map +0 -1
  232. package/dist/adapters/cli/init.js +0 -336
  233. package/dist/adapters/cli/init.js.map +0 -1
  234. package/dist/adapters/cli/parse-args.d.ts.map +0 -1
  235. package/dist/adapters/cli/parse-args.js.map +0 -1
  236. package/dist/adapters/cli/scope-gate.d.ts +0 -25
  237. package/dist/adapters/cli/scope-gate.d.ts.map +0 -1
  238. package/dist/adapters/cli/scope-gate.js +0 -157
  239. package/dist/adapters/cli/scope-gate.js.map +0 -1
  240. package/dist/adapters/cli/scope.d.ts +0 -26
  241. package/dist/adapters/cli/scope.d.ts.map +0 -1
  242. package/dist/adapters/cli/scope.js +0 -172
  243. package/dist/adapters/cli/scope.js.map +0 -1
  244. package/dist/adapters/cli/validate-component.d.ts +0 -24
  245. package/dist/adapters/cli/validate-component.d.ts.map +0 -1
  246. package/dist/adapters/cli/validate-component.js +0 -62
  247. package/dist/adapters/cli/validate-component.js.map +0 -1
  248. package/dist/adapters/cli/verify-contract-diff.d.ts +0 -21
  249. package/dist/adapters/cli/verify-contract-diff.d.ts.map +0 -1
  250. package/dist/adapters/cli/verify-contract-diff.js +0 -69
  251. package/dist/adapters/cli/verify-contract-diff.js.map +0 -1
  252. package/dist/adapters/cli/verify-drift.d.ts +0 -24
  253. package/dist/adapters/cli/verify-drift.d.ts.map +0 -1
  254. package/dist/adapters/cli/verify-drift.js +0 -103
  255. package/dist/adapters/cli/verify-drift.js.map +0 -1
  256. package/dist/adapters/cli/verify-impact.d.ts +0 -23
  257. package/dist/adapters/cli/verify-impact.d.ts.map +0 -1
  258. package/dist/adapters/cli/verify-impact.js +0 -119
  259. package/dist/adapters/cli/verify-impact.js.map +0 -1
  260. package/dist/adapters/mcp/index.d.ts +0 -5
  261. package/dist/adapters/mcp/index.d.ts.map +0 -1
  262. package/dist/adapters/mcp/index.js +0 -2
  263. package/dist/adapters/mcp/index.js.map +0 -1
  264. package/dist/bin/dt.d.ts +0 -7
  265. package/dist/bin/dt.d.ts.map +0 -1
  266. package/dist/bin/dt.js +0 -647
  267. package/dist/bin/dt.js.map +0 -1
  268. package/dist/core/catalog/build.d.ts +0 -143
  269. package/dist/core/catalog/build.d.ts.map +0 -1
  270. package/dist/core/catalog/build.js +0 -475
  271. package/dist/core/catalog/build.js.map +0 -1
  272. package/dist/core/catalog/checks/index.d.ts +0 -18
  273. package/dist/core/catalog/checks/index.d.ts.map +0 -1
  274. package/dist/core/catalog/checks/index.js +0 -18
  275. package/dist/core/catalog/checks/index.js.map +0 -1
  276. package/dist/core/catalog/checks/v01-schema.d.ts +0 -17
  277. package/dist/core/catalog/checks/v01-schema.d.ts.map +0 -1
  278. package/dist/core/catalog/checks/v01-schema.js +0 -57
  279. package/dist/core/catalog/checks/v01-schema.js.map +0 -1
  280. package/dist/core/catalog/checks/v02-v03-identity.d.ts +0 -14
  281. package/dist/core/catalog/checks/v02-v03-identity.d.ts.map +0 -1
  282. package/dist/core/catalog/checks/v02-v03-identity.js +0 -60
  283. package/dist/core/catalog/checks/v02-v03-identity.js.map +0 -1
  284. package/dist/core/catalog/checks/v04-referential-integrity.d.ts +0 -7
  285. package/dist/core/catalog/checks/v04-referential-integrity.d.ts.map +0 -1
  286. package/dist/core/catalog/checks/v04-referential-integrity.js +0 -32
  287. package/dist/core/catalog/checks/v04-referential-integrity.js.map +0 -1
  288. package/dist/core/catalog/checks/v05-domain-existence.d.ts +0 -6
  289. package/dist/core/catalog/checks/v05-domain-existence.d.ts.map +0 -1
  290. package/dist/core/catalog/checks/v05-domain-existence.js +0 -23
  291. package/dist/core/catalog/checks/v05-domain-existence.js.map +0 -1
  292. package/dist/core/catalog/checks/v06-v07-paths.d.ts +0 -29
  293. package/dist/core/catalog/checks/v06-v07-paths.d.ts.map +0 -1
  294. package/dist/core/catalog/checks/v06-v07-paths.js +0 -107
  295. package/dist/core/catalog/checks/v06-v07-paths.js.map +0 -1
  296. package/dist/core/catalog/checks/v08-v10-contracts.d.ts +0 -13
  297. package/dist/core/catalog/checks/v08-v10-contracts.d.ts.map +0 -1
  298. package/dist/core/catalog/checks/v08-v10-contracts.js +0 -70
  299. package/dist/core/catalog/checks/v08-v10-contracts.js.map +0 -1
  300. package/dist/core/catalog/checks/v11-manual-fields.d.ts +0 -16
  301. package/dist/core/catalog/checks/v11-manual-fields.d.ts.map +0 -1
  302. package/dist/core/catalog/checks/v11-manual-fields.js +0 -60
  303. package/dist/core/catalog/checks/v11-manual-fields.js.map +0 -1
  304. package/dist/core/catalog/checks/v12-cycles.d.ts +0 -8
  305. package/dist/core/catalog/checks/v12-cycles.d.ts.map +0 -1
  306. package/dist/core/catalog/checks/v12-cycles.js +0 -28
  307. package/dist/core/catalog/checks/v12-cycles.js.map +0 -1
  308. package/dist/core/catalog/checks/v13-orphan-contracts.d.ts +0 -7
  309. package/dist/core/catalog/checks/v13-orphan-contracts.d.ts.map +0 -1
  310. package/dist/core/catalog/checks/v13-orphan-contracts.js +0 -33
  311. package/dist/core/catalog/checks/v13-orphan-contracts.js.map +0 -1
  312. package/dist/core/catalog/checks/v14-v15-lifecycle.d.ts +0 -8
  313. package/dist/core/catalog/checks/v14-v15-lifecycle.d.ts.map +0 -1
  314. package/dist/core/catalog/checks/v14-v15-lifecycle.js +0 -42
  315. package/dist/core/catalog/checks/v14-v15-lifecycle.js.map +0 -1
  316. package/dist/core/catalog/checks/v16-deprecated-consumers.d.ts +0 -7
  317. package/dist/core/catalog/checks/v16-deprecated-consumers.d.ts.map +0 -1
  318. package/dist/core/catalog/checks/v16-deprecated-consumers.js +0 -47
  319. package/dist/core/catalog/checks/v16-deprecated-consumers.js.map +0 -1
  320. package/dist/core/catalog/checks/v17-low-confidence.d.ts +0 -7
  321. package/dist/core/catalog/checks/v17-low-confidence.d.ts.map +0 -1
  322. package/dist/core/catalog/checks/v17-low-confidence.js +0 -32
  323. package/dist/core/catalog/checks/v17-low-confidence.js.map +0 -1
  324. package/dist/core/catalog/checks/v18-low-payload.d.ts +0 -7
  325. package/dist/core/catalog/checks/v18-low-payload.d.ts.map +0 -1
  326. package/dist/core/catalog/checks/v18-low-payload.js +0 -33
  327. package/dist/core/catalog/checks/v18-low-payload.js.map +0 -1
  328. package/dist/core/catalog/checks/v19-domain-membership.d.ts +0 -8
  329. package/dist/core/catalog/checks/v19-domain-membership.d.ts.map +0 -1
  330. package/dist/core/catalog/checks/v19-domain-membership.js +0 -55
  331. package/dist/core/catalog/checks/v19-domain-membership.js.map +0 -1
  332. package/dist/core/catalog/coverage.d.ts +0 -39
  333. package/dist/core/catalog/coverage.d.ts.map +0 -1
  334. package/dist/core/catalog/coverage.js +0 -62
  335. package/dist/core/catalog/coverage.js.map +0 -1
  336. package/dist/core/catalog/graph.d.ts +0 -49
  337. package/dist/core/catalog/graph.d.ts.map +0 -1
  338. package/dist/core/catalog/graph.js +0 -114
  339. package/dist/core/catalog/graph.js.map +0 -1
  340. package/dist/core/catalog/index-model.d.ts +0 -96
  341. package/dist/core/catalog/index-model.d.ts.map +0 -1
  342. package/dist/core/catalog/index-model.js +0 -8
  343. package/dist/core/catalog/index-model.js.map +0 -1
  344. package/dist/core/catalog/index.d.ts +0 -5
  345. package/dist/core/catalog/index.d.ts.map +0 -1
  346. package/dist/core/catalog/index.js +0 -2
  347. package/dist/core/catalog/index.js.map +0 -1
  348. package/dist/core/catalog/queries.d.ts +0 -69
  349. package/dist/core/catalog/queries.d.ts.map +0 -1
  350. package/dist/core/catalog/queries.js +0 -165
  351. package/dist/core/catalog/queries.js.map +0 -1
  352. package/dist/core/catalog/resolve.d.ts +0 -47
  353. package/dist/core/catalog/resolve.d.ts.map +0 -1
  354. package/dist/core/catalog/resolve.js +0 -318
  355. package/dist/core/catalog/resolve.js.map +0 -1
  356. package/dist/core/catalog/scaffold.d.ts +0 -31
  357. package/dist/core/catalog/scaffold.d.ts.map +0 -1
  358. package/dist/core/catalog/scaffold.js +0 -141
  359. package/dist/core/catalog/scaffold.js.map +0 -1
  360. package/dist/core/catalog/validate-component.d.ts +0 -50
  361. package/dist/core/catalog/validate-component.d.ts.map +0 -1
  362. package/dist/core/catalog/validate-component.js +0 -105
  363. package/dist/core/catalog/validate-component.js.map +0 -1
  364. package/dist/core/catalog/validate.d.ts +0 -71
  365. package/dist/core/catalog/validate.d.ts.map +0 -1
  366. package/dist/core/catalog/validate.js +0 -103
  367. package/dist/core/catalog/validate.js.map +0 -1
  368. package/dist/core/context/assemble.d.ts +0 -126
  369. package/dist/core/context/assemble.d.ts.map +0 -1
  370. package/dist/core/context/assemble.js +0 -197
  371. package/dist/core/context/assemble.js.map +0 -1
  372. package/dist/core/context/cache.d.ts +0 -60
  373. package/dist/core/context/cache.d.ts.map +0 -1
  374. package/dist/core/context/cache.js +0 -236
  375. package/dist/core/context/cache.js.map +0 -1
  376. package/dist/core/context/exit-codes.d.ts +0 -28
  377. package/dist/core/context/exit-codes.d.ts.map +0 -1
  378. package/dist/core/context/exit-codes.js +0 -28
  379. package/dist/core/context/exit-codes.js.map +0 -1
  380. package/dist/core/context/fetch.d.ts +0 -55
  381. package/dist/core/context/fetch.d.ts.map +0 -1
  382. package/dist/core/context/fetch.js +0 -112
  383. package/dist/core/context/fetch.js.map +0 -1
  384. package/dist/core/context/index.d.ts +0 -11
  385. package/dist/core/context/index.d.ts.map +0 -1
  386. package/dist/core/context/index.js +0 -8
  387. package/dist/core/context/index.js.map +0 -1
  388. package/dist/core/context/init.d.ts +0 -179
  389. package/dist/core/context/init.d.ts.map +0 -1
  390. package/dist/core/context/init.js +0 -532
  391. package/dist/core/context/init.js.map +0 -1
  392. package/dist/core/context/layers/architecture-layer.d.ts +0 -13
  393. package/dist/core/context/layers/architecture-layer.d.ts.map +0 -1
  394. package/dist/core/context/layers/architecture-layer.js +0 -24
  395. package/dist/core/context/layers/architecture-layer.js.map +0 -1
  396. package/dist/core/context/layers/contracts-layer.d.ts +0 -13
  397. package/dist/core/context/layers/contracts-layer.d.ts.map +0 -1
  398. package/dist/core/context/layers/contracts-layer.js +0 -83
  399. package/dist/core/context/layers/contracts-layer.js.map +0 -1
  400. package/dist/core/context/layers/conventions-delta-layer.d.ts +0 -13
  401. package/dist/core/context/layers/conventions-delta-layer.d.ts.map +0 -1
  402. package/dist/core/context/layers/conventions-delta-layer.js +0 -37
  403. package/dist/core/context/layers/conventions-delta-layer.js.map +0 -1
  404. package/dist/core/context/layers/flow-layer.d.ts +0 -14
  405. package/dist/core/context/layers/flow-layer.d.ts.map +0 -1
  406. package/dist/core/context/layers/flow-layer.js +0 -61
  407. package/dist/core/context/layers/flow-layer.js.map +0 -1
  408. package/dist/core/context/layers/index-layer.d.ts +0 -13
  409. package/dist/core/context/layers/index-layer.d.ts.map +0 -1
  410. package/dist/core/context/layers/index-layer.js +0 -77
  411. package/dist/core/context/layers/index-layer.js.map +0 -1
  412. package/dist/core/context/layers/primary-layer.d.ts +0 -16
  413. package/dist/core/context/layers/primary-layer.d.ts.map +0 -1
  414. package/dist/core/context/layers/primary-layer.js +0 -61
  415. package/dist/core/context/layers/primary-layer.js.map +0 -1
  416. package/dist/core/context/layers/secondary-layer.d.ts +0 -19
  417. package/dist/core/context/layers/secondary-layer.d.ts.map +0 -1
  418. package/dist/core/context/layers/secondary-layer.js +0 -52
  419. package/dist/core/context/layers/secondary-layer.js.map +0 -1
  420. package/dist/core/context/session-lock.d.ts +0 -114
  421. package/dist/core/context/session-lock.d.ts.map +0 -1
  422. package/dist/core/context/session-lock.js +0 -90
  423. package/dist/core/context/session-lock.js.map +0 -1
  424. package/dist/core/context/tokens.d.ts +0 -35
  425. package/dist/core/context/tokens.d.ts.map +0 -1
  426. package/dist/core/context/tokens.js +0 -88
  427. package/dist/core/context/tokens.js.map +0 -1
  428. package/dist/core/extract/asyncapi/declared.d.ts +0 -19
  429. package/dist/core/extract/asyncapi/declared.d.ts.map +0 -1
  430. package/dist/core/extract/asyncapi/declared.js +0 -168
  431. package/dist/core/extract/asyncapi/declared.js.map +0 -1
  432. package/dist/core/extract/asyncapi/index.d.ts +0 -12
  433. package/dist/core/extract/asyncapi/index.d.ts.map +0 -1
  434. package/dist/core/extract/asyncapi/index.js +0 -8
  435. package/dist/core/extract/asyncapi/index.js.map +0 -1
  436. package/dist/core/extract/asyncapi/payloads.d.ts +0 -20
  437. package/dist/core/extract/asyncapi/payloads.d.ts.map +0 -1
  438. package/dist/core/extract/asyncapi/payloads.js +0 -421
  439. package/dist/core/extract/asyncapi/payloads.js.map +0 -1
  440. package/dist/core/extract/asyncapi/topics.d.ts +0 -27
  441. package/dist/core/extract/asyncapi/topics.d.ts.map +0 -1
  442. package/dist/core/extract/asyncapi/topics.js +0 -368
  443. package/dist/core/extract/asyncapi/topics.js.map +0 -1
  444. package/dist/core/extract/asyncapi/types.d.ts +0 -129
  445. package/dist/core/extract/asyncapi/types.d.ts.map +0 -1
  446. package/dist/core/extract/asyncapi/types.js +0 -5
  447. package/dist/core/extract/asyncapi/types.js.map +0 -1
  448. package/dist/core/extract/asyncapi/validate.d.ts +0 -29
  449. package/dist/core/extract/asyncapi/validate.d.ts.map +0 -1
  450. package/dist/core/extract/asyncapi/validate.js +0 -156
  451. package/dist/core/extract/asyncapi/validate.js.map +0 -1
  452. package/dist/core/extract/component.d.ts +0 -204
  453. package/dist/core/extract/component.d.ts.map +0 -1
  454. package/dist/core/extract/component.js +0 -258
  455. package/dist/core/extract/component.js.map +0 -1
  456. package/dist/core/extract/detect.d.ts +0 -35
  457. package/dist/core/extract/detect.d.ts.map +0 -1
  458. package/dist/core/extract/detect.js +0 -89
  459. package/dist/core/extract/detect.js.map +0 -1
  460. package/dist/core/extract/index.d.ts +0 -12
  461. package/dist/core/extract/index.d.ts.map +0 -1
  462. package/dist/core/extract/index.js +0 -6
  463. package/dist/core/extract/index.js.map +0 -1
  464. package/dist/core/extract/ladder.d.ts +0 -79
  465. package/dist/core/extract/ladder.d.ts.map +0 -1
  466. package/dist/core/extract/ladder.js +0 -70
  467. package/dist/core/extract/ladder.js.map +0 -1
  468. package/dist/core/extract/openapi/index.d.ts +0 -43
  469. package/dist/core/extract/openapi/index.d.ts.map +0 -1
  470. package/dist/core/extract/openapi/index.js +0 -142
  471. package/dist/core/extract/openapi/index.js.map +0 -1
  472. package/dist/core/extract/openapi/route1.d.ts +0 -36
  473. package/dist/core/extract/openapi/route1.d.ts.map +0 -1
  474. package/dist/core/extract/openapi/route1.js +0 -333
  475. package/dist/core/extract/openapi/route1.js.map +0 -1
  476. package/dist/core/extract/openapi/route2-introspect.d.ts +0 -18
  477. package/dist/core/extract/openapi/route2-introspect.d.ts.map +0 -1
  478. package/dist/core/extract/openapi/route2-introspect.js +0 -249
  479. package/dist/core/extract/openapi/route2-introspect.js.map +0 -1
  480. package/dist/core/extract/openapi/route2.d.ts +0 -69
  481. package/dist/core/extract/openapi/route2.d.ts.map +0 -1
  482. package/dist/core/extract/openapi/route2.js +0 -211
  483. package/dist/core/extract/openapi/route2.js.map +0 -1
  484. package/dist/core/extract/openapi/route3.d.ts +0 -26
  485. package/dist/core/extract/openapi/route3.d.ts.map +0 -1
  486. package/dist/core/extract/openapi/route3.js +0 -737
  487. package/dist/core/extract/openapi/route3.js.map +0 -1
  488. package/dist/core/extract/openapi/types.d.ts +0 -125
  489. package/dist/core/extract/openapi/types.d.ts.map +0 -1
  490. package/dist/core/extract/openapi/types.js +0 -5
  491. package/dist/core/extract/openapi/types.js.map +0 -1
  492. package/dist/core/extract/openapi/validate.d.ts +0 -29
  493. package/dist/core/extract/openapi/validate.d.ts.map +0 -1
  494. package/dist/core/extract/openapi/validate.js +0 -200
  495. package/dist/core/extract/openapi/validate.js.map +0 -1
  496. package/dist/core/extract/orm/drizzle.d.ts +0 -20
  497. package/dist/core/extract/orm/drizzle.d.ts.map +0 -1
  498. package/dist/core/extract/orm/drizzle.js +0 -283
  499. package/dist/core/extract/orm/drizzle.js.map +0 -1
  500. package/dist/core/extract/orm/information-schema.d.ts +0 -26
  501. package/dist/core/extract/orm/information-schema.d.ts.map +0 -1
  502. package/dist/core/extract/orm/information-schema.js +0 -142
  503. package/dist/core/extract/orm/information-schema.js.map +0 -1
  504. package/dist/core/extract/orm/prisma.d.ts +0 -23
  505. package/dist/core/extract/orm/prisma.d.ts.map +0 -1
  506. package/dist/core/extract/orm/prisma.js +0 -234
  507. package/dist/core/extract/orm/prisma.js.map +0 -1
  508. package/dist/core/extract/orm/typeorm.d.ts +0 -22
  509. package/dist/core/extract/orm/typeorm.d.ts.map +0 -1
  510. package/dist/core/extract/orm/typeorm.js +0 -269
  511. package/dist/core/extract/orm/typeorm.js.map +0 -1
  512. package/dist/core/extract/orm/types.d.ts +0 -97
  513. package/dist/core/extract/orm/types.d.ts.map +0 -1
  514. package/dist/core/extract/orm/types.js +0 -6
  515. package/dist/core/extract/orm/types.js.map +0 -1
  516. package/dist/core/extract/prompt.d.ts +0 -21
  517. package/dist/core/extract/prompt.d.ts.map +0 -1
  518. package/dist/core/extract/prompt.js +0 -79
  519. package/dist/core/extract/prompt.js.map +0 -1
  520. package/dist/core/extract/provider.d.ts +0 -121
  521. package/dist/core/extract/provider.d.ts.map +0 -1
  522. package/dist/core/extract/provider.js +0 -6
  523. package/dist/core/extract/provider.js.map +0 -1
  524. package/dist/core/extract/providers/node-ts.d.ts +0 -69
  525. package/dist/core/extract/providers/node-ts.d.ts.map +0 -1
  526. package/dist/core/extract/providers/node-ts.js +0 -320
  527. package/dist/core/extract/providers/node-ts.js.map +0 -1
  528. package/dist/core/extract/render/schema-md.d.ts +0 -16
  529. package/dist/core/extract/render/schema-md.d.ts.map +0 -1
  530. package/dist/core/extract/render/schema-md.js +0 -140
  531. package/dist/core/extract/render/schema-md.js.map +0 -1
  532. package/dist/core/extract/report.d.ts +0 -125
  533. package/dist/core/extract/report.d.ts.map +0 -1
  534. package/dist/core/extract/report.js +0 -52
  535. package/dist/core/extract/report.js.map +0 -1
  536. package/dist/core/extract/schema.d.ts +0 -34
  537. package/dist/core/extract/schema.d.ts.map +0 -1
  538. package/dist/core/extract/schema.js +0 -146
  539. package/dist/core/extract/schema.js.map +0 -1
  540. package/dist/core/extract/workspaces.d.ts +0 -33
  541. package/dist/core/extract/workspaces.d.ts.map +0 -1
  542. package/dist/core/extract/workspaces.js +0 -193
  543. package/dist/core/extract/workspaces.js.map +0 -1
  544. package/dist/core/providers/index.d.ts +0 -6
  545. package/dist/core/providers/index.d.ts.map +0 -1
  546. package/dist/core/providers/index.js +0 -2
  547. package/dist/core/providers/index.js.map +0 -1
  548. package/dist/core/providers/tracker.d.ts +0 -74
  549. package/dist/core/providers/tracker.d.ts.map +0 -1
  550. package/dist/core/providers/tracker.js +0 -38
  551. package/dist/core/providers/tracker.js.map +0 -1
  552. package/dist/core/scope/calibration.d.ts +0 -25
  553. package/dist/core/scope/calibration.d.ts.map +0 -1
  554. package/dist/core/scope/calibration.js +0 -52
  555. package/dist/core/scope/calibration.js.map +0 -1
  556. package/dist/core/scope/closure.d.ts +0 -31
  557. package/dist/core/scope/closure.d.ts.map +0 -1
  558. package/dist/core/scope/closure.js +0 -68
  559. package/dist/core/scope/closure.js.map +0 -1
  560. package/dist/core/scope/gate.d.ts +0 -41
  561. package/dist/core/scope/gate.d.ts.map +0 -1
  562. package/dist/core/scope/gate.js +0 -165
  563. package/dist/core/scope/gate.js.map +0 -1
  564. package/dist/core/scope/index.d.ts +0 -18
  565. package/dist/core/scope/index.d.ts.map +0 -1
  566. package/dist/core/scope/index.js +0 -12
  567. package/dist/core/scope/index.js.map +0 -1
  568. package/dist/core/scope/partition.d.ts +0 -36
  569. package/dist/core/scope/partition.d.ts.map +0 -1
  570. package/dist/core/scope/partition.js +0 -78
  571. package/dist/core/scope/partition.js.map +0 -1
  572. package/dist/core/scope/prompt.d.ts +0 -39
  573. package/dist/core/scope/prompt.d.ts.map +0 -1
  574. package/dist/core/scope/prompt.js +0 -123
  575. package/dist/core/scope/prompt.js.map +0 -1
  576. package/dist/core/scope/scoping.d.ts +0 -52
  577. package/dist/core/scope/scoping.d.ts.map +0 -1
  578. package/dist/core/scope/scoping.js +0 -99
  579. package/dist/core/scope/scoping.js.map +0 -1
  580. package/dist/core/scope/types.d.ts +0 -77
  581. package/dist/core/scope/types.d.ts.map +0 -1
  582. package/dist/core/scope/types.js +0 -5
  583. package/dist/core/scope/types.js.map +0 -1
  584. package/dist/core/scope/validate.d.ts +0 -47
  585. package/dist/core/scope/validate.d.ts.map +0 -1
  586. package/dist/core/scope/validate.js +0 -90
  587. package/dist/core/scope/validate.js.map +0 -1
  588. package/dist/core/verify/asyncapi-diff.d.ts +0 -34
  589. package/dist/core/verify/asyncapi-diff.d.ts.map +0 -1
  590. package/dist/core/verify/asyncapi-diff.js +0 -209
  591. package/dist/core/verify/asyncapi-diff.js.map +0 -1
  592. package/dist/core/verify/contract-diff.d.ts +0 -39
  593. package/dist/core/verify/contract-diff.d.ts.map +0 -1
  594. package/dist/core/verify/contract-diff.js +0 -63
  595. package/dist/core/verify/contract-diff.js.map +0 -1
  596. package/dist/core/verify/drift.d.ts +0 -47
  597. package/dist/core/verify/drift.d.ts.map +0 -1
  598. package/dist/core/verify/drift.js +0 -122
  599. package/dist/core/verify/drift.js.map +0 -1
  600. package/dist/core/verify/impact.d.ts +0 -22
  601. package/dist/core/verify/impact.d.ts.map +0 -1
  602. package/dist/core/verify/impact.js +0 -93
  603. package/dist/core/verify/impact.js.map +0 -1
  604. package/dist/core/verify/index.d.ts +0 -10
  605. package/dist/core/verify/index.d.ts.map +0 -1
  606. package/dist/core/verify/index.js +0 -9
  607. package/dist/core/verify/index.js.map +0 -1
  608. package/dist/core/verify/openapi-diff.d.ts +0 -29
  609. package/dist/core/verify/openapi-diff.d.ts.map +0 -1
  610. package/dist/core/verify/openapi-diff.js +0 -291
  611. package/dist/core/verify/openapi-diff.js.map +0 -1
  612. package/dist/core/verify/types.d.ts +0 -138
  613. package/dist/core/verify/types.d.ts.map +0 -1
  614. package/dist/core/verify/types.js +0 -5
  615. package/dist/core/verify/types.js.map +0 -1
  616. package/schemas/component.schema.json +0 -203
  617. package/schemas/flow.schema.json +0 -75
  618. package/schemas/scope-output.schema.json +0 -62
@@ -39,7 +39,7 @@ git checkout -b <branch-name>
39
39
 
40
40
  - Story branches: `story/<story-id>-<short-description>`
41
41
  - Issue branches: `issue/<issue-number>-<short-description>`
42
- - Integration branches: `integrate/<milestone-or-prd-name>`
42
+ - Integration branches: `integration/<plan-id>-<short-description>`
43
43
 
44
44
  ### 2. Create Branch from Integration Branch
45
45
 
@@ -96,13 +96,13 @@ Before merging any PR or branch, verify:
96
96
 
97
97
  Choose the appropriate strategy based on context:
98
98
 
99
- | Strategy | When to Use | Command |
100
- | ---------------- | ----------------------------------------------------------------------------------- | --------------------------- |
101
- | **Squash merge** | Story/issue PRs → integration or main branch. Produces clean single-commit history. | `gh pr merge <pr> --squash` |
102
- | **Merge commit** | Integration branch → main. Preserves the full story history. | `gh pr merge <pr> --merge` |
103
- | **Rebase merge** | Small PRs with clean linear history. Avoid for multi-commit stories. | `gh pr merge <pr> --rebase` |
99
+ | Strategy | When to Use | Command |
100
+ | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------- |
101
+ | **Squash merge** | Issue/story PRs → integration (planner) or `main` (user); delete the source branch. | `gh pr merge <pr> --squash --delete-branch` |
102
+ | **Merge commit** | Integration PRs → `main` (user); preserve the story history. | `gh pr merge <pr> --merge` |
103
+ | **Rebase merge** | Not part of the issue/story/integration policy; use only when explicitly approved. | `gh pr merge <pr> --rebase` |
104
104
 
105
- **Default**: Squash merge for story PRs, merge commit for integration PRs to main.
105
+ **Default**: Issue/story PRs use squash with branch deletion; integration PRs use a merge commit. Planner handles integration targets, and the user handles `main`.
106
106
 
107
107
  ### 6. Resolve Merge Conflicts
108
108
 
@@ -197,6 +197,26 @@ git push --force-with-lease origin <branch-name>
197
197
 
198
198
  **Never use** `git push --force` without `--with-lease`.
199
199
 
200
+ ### 10. Tag Procedure (Human-Only)
201
+
202
+ Tags are the production deploy trigger and are created **only by a human**. Agents **MUST NOT** create, move, delete, or push tags; `git-guard` rule 4 enforces this. This section documents the procedure a human follows — it is not an agent action.
203
+
204
+ ```bash
205
+ # Ensure you are on main at the exact release commit
206
+ git checkout main
207
+ git pull origin main
208
+
209
+ # Create an annotated, immutable release tag (exact semver only)
210
+ git tag -a v<major>.<minor>.<patch> -m "Release v<major>.<minor>.<patch>"
211
+
212
+ # Push the tag (triggers the production deploy workflow)
213
+ git push origin v<major>.<minor>.<patch>
214
+ ```
215
+
216
+ Rules: annotated tags only (never lightweight), exact `v<major>.<minor>.<patch>` (no prerelease suffixes in v1), tag a commit on `main`, and never move or delete a pushed tag.
217
+
218
+ **Hotfix:** a hotfix ships as the next patch tag (`vX.Y.Z+1`) cut from `main` after the fix merges; never re-point or force-update an existing tag.
219
+
200
220
  ---
201
221
 
202
222
  ## Conflict Resolution Heuristics
@@ -29,26 +29,72 @@ This activity assumes:
29
29
 
30
30
  ---
31
31
 
32
+ ## Package Scope in Commits
33
+
34
+ In a monorepo the package is the Conventional Commits **scope** (FR-63):
35
+
36
+ ```
37
+ feat(api): add token-refresh endpoint
38
+ fix(web): stop double-submitting the checkout form
39
+ ```
40
+
41
+ - Take the scope from the package map in `docs/tech.md`. Use the short,
42
+ readable form of the package name, not the full specifier: `@acme/api`
43
+ becomes `api`.
44
+ - A package name that is not a valid scope — one containing a space, a
45
+ slash after stripping the org prefix, or an uppercase letter — is
46
+ reduced to a lowercase, hyphenated form and the mapping is recorded in
47
+ the package map's row so every commit uses the same one. Never invent
48
+ a different short form per commit.
49
+ - A commit spanning packages uses the broadest honest scope, or none. A
50
+ scope that names one package for a change touching four is worse than
51
+ no scope.
52
+ - In a **single-package repository the scope is optional**. Omit it —
53
+ `feat: add the endpoint` — rather than writing an empty scope `feat():`,
54
+ which is not valid Conventional Commits and which the commit hook
55
+ rejects.
56
+
57
+ ## Platform-Write Routing
58
+
59
+ - You **MUST NOT** emit or execute a platform write command (`aws`, `flyctl`, `supabase`, or Cloudflare API writes) while executing a task list.
60
+ - When a sub-task's work is a platform write, you **MUST** route it to `infra-engineer` instead of running it yourself, so the approval, revert, and backup gates bind. The sub-task kinds that route are: **secrets**, **deploy**, **DNS**, **certificates**, **IAM policy**, and **migrations against a shared or cloud project**.
61
+ - This routing is **conditional**, never mandatory: a story with no platform-write scope invokes nothing, and an infra-shaped but local-only sub-task — such as editing `.env.example` or a config template checked into the repo — stays with the implementing agent.
62
+
63
+ ---
64
+
32
65
  ## Before Starting Work
33
66
 
34
67
  1. You **MUST** confirm the GitHub Issue is open.
35
- 2. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
68
+ 2. **Decision-log read (non-mutating — runs before any branch is created):** You **MUST** read `workstream/decisions-<feature>.md` in full, alongside (not replacing) the GitHub-issue-open check in step 1 — both checks run before branch creation. This step is ordered before the branch gate (step 3) precisely because it is non-mutating: reading it first lets you answer your own procedural questions (e.g., "was this file's location already decided?") from the log before touching git. If `workstream/decisions-<feature>.md` does not exist — for example, a pre-Phase-2 feature, or a feature for which grilling never ran — you **MUST** proceed without the read, noting its absence in your status output, rather than failing or blocking. This is an enrichment, never a hard gate: a missing decision log never blocks starting work. A decision log that exists but has zero rows is treated the same as present-and-populated — there is simply nothing to cite.
69
+ 3. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
36
70
  - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
37
71
  - If HEAD is the default branch (`main`) or does not match `issue/*` or `story/*` pattern, you **MUST** create a new branch from the latest default branch by delegating branch naming and creation to `github-ops` whenever possible.
38
72
  - You **MUST NOT** proceed with any implementation sub-task, write any code, create any files, or make any commits until a feature branch is checked out.
39
- - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 3.
73
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 4.
40
74
  - Branch format: `issue/<issue-number>-<short-description>` or `story/<id>-<short-description>`
41
- 3. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
75
+ 4. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
42
76
  - A PR requires at least one commit. Open it immediately after the first commit on the feature branch — never before — and you **MUST NOT** continue past that first commit without it.
43
77
  - Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
44
78
  - PR title **MUST** follow Conventional Commits (e.g., `feat: implement issue 37`).
45
79
  - PR description **MUST** include `Closes #<issue-number>`.
46
- 4. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
80
+ 5. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
81
+ 6. **memo intent (when memo-cli is available):** Before the first implementation sub-task, you **MUST** run the memo-cli Availability Check and write the episodic intent entry defined in the `developer` agent contract (**memo-cli Integration → Intent Entry**), naming the bank literally (`--bank developer-memory`, never `--bank $MEMO_BANK`). Record `memo_intent` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)` — a failed write is retried once and then reported, never dropped silently.
47
82
 
48
83
  If `github-ops` delegation is unavailable in the current runtime, you **MUST** apply `github-ops` conventions directly and explicitly note that fallback in your status output.
49
84
 
50
85
  ---
51
86
 
87
+ ## Decision-Log Citation
88
+
89
+ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
90
+
91
+ - An implementation commit whose approach was shaped by a decision **MUST** cite it in the commit body — e.g. a trailing line `Follows D-NN: <short form>.` — using the feature's own unqualified `D-NN` form (the file belongs to one feature; the qualified `<feature>#D-NN` cross-file form is `activity-grill`/`activity-refine`/`activity-generate-spec`'s concern, not `implement`'s).
92
+ - The PR body **MUST** reference every consumed decision ID it draws on, in its Completion Report area, alongside the existing `Closes #<issue-number>` line.
93
+ - This is **additive only**, mirroring `plan`'s own citation contract: a commit or PR with no traceable decision cites none. You **MUST NOT** fabricate a citation to give a commit or PR one.
94
+ - When step 2 found no `workstream/decisions-<feature>.md` (absent or empty), there is nothing to cite — omit the citation, do not fabricate one, and do not treat the omission as a defect.
95
+
96
+ ---
97
+
52
98
  ## During Implementation
53
99
 
54
100
  ### Step-by-Step Execution
@@ -99,14 +145,17 @@ If `github-ops` delegation is unavailable in the current runtime, you **MUST** a
99
145
  5. `technical-writer` validation **MUST** include a drift/stale-doc check report, and completion **MUST NOT** proceed while unresolved drift remains.
100
146
  6. A `qa-engineer` pass **MUST** have run and `coverage_gate` **MUST** be recorded as `PASS`, `FAIL`, or `SKIPPED(<reason>)`. The reason **MUST** be non-empty when skipped; an omitted field is treated as incomplete. A `FAIL` or `SKIPPED` value does not block completion — only omission does.
101
147
  7. A `verifier` audit in `audit` mode **MUST** have run against the delivered implementation, with its human-readable summary posted to the issue/PR. This gate is mandatory and non-skippable — it **MUST NOT** be skipped regardless of drift findings, and drift findings reported by this audit **MUST NOT** block completion. This condition is satisfied once the audit has run and been posted; any resulting drift is handled by `product-engineer`'s `activity-drift-reconciliation` flow after this gate, not before it.
102
- 8. The PR **MUST** be converted from draft to ready for review.
103
- 9. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
104
- - PRs targeting an **integration branch**: `planner` reviews and approves.
105
- - PRs targeting **`main`**: the **user** reviews and approves.
106
- 10. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
107
- 11. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
108
- 12. You **MUST NOT** close the issue while the PR is still in draft or pending review.
109
- 13. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
148
+ 8. **memo outcome (when memo-cli is available):** Before the PR is converted to ready for review, you **MUST** write the episodic outcome entry defined in the `developer` agent contract (**memo-cli Integration → Outcome Entry**) and record `memo_outcome` as `written(<id>)`, `failed(<reason>)`, or `skipped(<reason>)`. A `failed` or `skipped` value does not block completion — only an omitted field does.
149
+ 9. The PR **MUST** be converted from draft to ready for review.
150
+ 10. The PR **MUST** be approved by the appropriate reviewer per the merge authority policy in `github-ops`:
151
+
152
+ - PRs targeting an **integration branch**: `planner` reviews and approves.
153
+ - PRs targeting **`main`**: the **user** reviews and approves.
154
+
155
+ 11. The PR **MUST** be merged by the authorized party (planner for integration branches, user for `main`).
156
+ 12. You **MUST NOT** close the GitHub Issue until the PR is approved **AND** merged.
157
+ 13. You **MUST NOT** close the issue while the PR is still in draft or pending review.
158
+ 14. You **MUST** notify the user when the PR is ready for review — explicitly inform them so they can review and merge.
110
159
 
111
160
  ---
112
161
 
@@ -249,6 +249,36 @@ Every entry belongs to a **repo**, **org**, and **domain** (all kebab-case). Que
249
249
 
250
250
  ---
251
251
 
252
+ ## Banks, Kinds, and Session Memory (memo-cli 1.3.0+)
253
+
254
+ memo-cli 1.3.0 adds a second axis of scoping — **banks** — and a third field on every entry — **kind** — on top of the repo/org/domain scoping above. Every command example in this section was verified against the local 1.3.0 build's `--help` output (`pnpm build && node dist/index.js <cmd> --help`).
255
+
256
+ ### `bank` — Namespace
257
+
258
+ A bank is a namespace for entries, resolved in this priority order (B3): `--bank <id>` flag > `$MEMO_BANK` env var > `config.bank.default` > `kb`. `kb` is the shared, org-wide knowledge base every repo reads from by default; any other bank id (kebab-case or UUID) is a **private** bank — conventionally named `<agent-name>-memory` (e.g. `developer-memory`, `technical-writer-memory`, `product-engineer-memory`, `planner-memory`) for a long-lived agent's own session memory.
259
+
260
+ **Agents: always pass `--bank <id>` literally on every command.** Agent runtimes run each shell command in a fresh shell, so an `export MEMO_BANK=…` from an earlier command is gone by the next one. An unquoted empty `$MEMO_BANK` is dropped by the shell, and the flag parser then reads the next token as the bank id (`--bank --rationale …` → bank `--rationale`), which memo-cli rejects with `VALIDATION_FAILED` (dev-tasks issue #253). Never write `--bank $MEMO_BANK` in an agent prompt or command.
261
+
262
+ ```bash
263
+ memo write --bank developer-memory ... # bank id convention: <agent-name>-memory
264
+ ```
265
+
266
+ `kb` and private banks are isolated from each other: a `search`/`list`/`recall` scoped to a private bank never returns `kb` entries and vice versa, unless you explicitly pass `--bank kb`.
267
+
268
+ ### `kind` — Entry Nature
269
+
270
+ | Kind | Meaning | Where it lives | Expires? |
271
+ | ---------- | ------------------------------------------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------- |
272
+ | `self` | The agent's own persona/context entries (never ranked, never trimmed) | private banks only — `kb` rejects `--kind self` | no (subject to a soft cap warning, not a hard block) |
273
+ | `episodic` | Session-scoped narration — intent/outcome entries tied to one `--session` | private banks (default kind there) | yes — `policy.expires_in_days` or `--expires-in` |
274
+ | `semantic` | Durable, searchable decisions — what `search`/`list` return by default | `kb` (default kind there); may also exist in a private bank | no |
275
+
276
+ `--kind` is case-insensitive (`--kind Self`, `--kind SELF`, `--kind self` all normalize to `self`). Default kind is `episodic` in a private bank, `semantic` in `kb`.
277
+
278
+ **Rule of thumb for agent definitions in this repository:** intent/outcome entries are `--kind episodic --session ISSUE-<n> --bank <agent>-memory`; ADR/decision entries stay `--kind semantic --bank kb`.
279
+
280
+ ---
281
+
252
282
  ## Command Reference
253
283
 
254
284
  ### `memo write` — Record a Decision
@@ -262,6 +292,22 @@ memo write \
262
292
  --json
263
293
  ```
264
294
 
295
+ Episodic example — intent entry in a private bank:
296
+
297
+ ```bash
298
+ memo write \
299
+ --kind episodic \
300
+ --session ISSUE-42 \
301
+ --bank <agent>-memory \
302
+ --rationale "Context: Starting ISSUE-42. Decision: implement via a middleware. Impact: affects the auth pipeline." \
303
+ --tags "auth,issue-42,intent,middleware" \
304
+ --entry-type decision \
305
+ --source agent \
306
+ --story "ISSUE-42" \
307
+ --on-duplicate consolidate \
308
+ --json
309
+ ```
310
+
265
311
  **Required flags:**
266
312
 
267
313
  - `--rationale` — The decision text (1–5 000 chars).
@@ -269,17 +315,29 @@ memo write \
269
315
 
270
316
  **Optional flags:**
271
317
 
272
- - `--entry-type` — `decision` (default) | `integration_point` | `structure`
273
- - `--source` — `agent` | `manual` (falls back to config default)
318
+ - `--entry-type` — `decision` (default) | `integration_point` | `structure` | `policy` | `observation` (default `observation` when `--kind episodic`)
319
+ - `--source` — `agent` | `manual` | `scan` (falls back to config default)
274
320
  - `--commit` — Git commit SHA for traceability
275
321
  - `--story` — Story or task ID
276
322
  - `--files` — Comma-separated file paths touched by the decision
277
323
  - `--relates-to` — Related repo names
278
324
  - `--on-duplicate` — `consolidate` | `update` | `replace` | `create-new`
325
+ - `--bank <id>` — Bank id (default: `$MEMO_BANK`, `config.bank.default`, or `kb`)
326
+ - `--kind <kind>` — `self` | `episodic` | `semantic` (default: `episodic` in private banks, `semantic` in `kb`)
327
+ - `--session <id>` — Session id; **required** when `--kind episodic`
328
+ - `--seq <n>` — Explicit episodic sequence number (default: auto-incremented per session)
329
+ - `--context <ctx>` — Context tag; repeatable
330
+ - `--provenance <csv>` — Comma-separated UUIDs of source episodic entries; **required** for a `semantic` entry with `--source agent` unless `--manual` is passed (PRD K3)
331
+ - `--manual` — Force `source = manual`
332
+ - `--supersedes <id>` — Id of an existing entry this write supersedes (must share the same `bank` and `kind` as the target)
333
+ - `--pin` — Pin the entry (never auto-archived by decay)
334
+ - `--expires-in <duration>` — Episodic expiry override, e.g. `2d`, `12h`, `30m` (overrides the bank's default retention policy)
279
335
  - `--json` — Machine-readable output (**always use in agent mode**)
280
336
 
281
337
  **Duplicate handling:**
282
- When memo detects a duplicate (same `repo + commit + story + entry_type + source`), interactive mode prompts for resolution. In `--json` mode you **MUST** supply `--on-duplicate` or the command will fail.
338
+ When memo detects a duplicate (same `repo + commit + story + entry_type + source`, or the equivalent v2 key including `bank`/`kind`/`session`/`seq`), interactive mode prompts for resolution. In `--json` mode you **MUST** supply `--on-duplicate` or the command will fail.
339
+
340
+ **Note:** `--confidence` is not a valid flag — confidence is inferred from `--source`.
283
341
 
284
342
  ---
285
343
 
@@ -295,11 +353,21 @@ Natural-language vector search over decision entries.
295
353
 
296
354
  - `--scope` — `repo` (default) | `related`
297
355
  - `--tags` — Comma-separated filter (AND logic)
298
- - `--entry-type` — Filter by type
299
- - `--source` — Filter by source
356
+ - `--entry-type` — Comma-separated types to include
357
+ - `--source` — Comma-separated sources to include
300
358
  - `--limit` — Max results (default 10)
359
+ - `--lexical <on|off>` — Enable/disable lexical identifier matching (default `on`)
360
+ - `--explain` — Show a per-result factor breakdown
361
+ - `--bank <id>` — Bank id (default: `$MEMO_BANK`, `config.bank.default`, or `kb`)
362
+ - `--kind <kind>` — `self` | `episodic` | `semantic` | `all` (default `all`, case-insensitive)
363
+ - `--session <id>` — Restrict to an episodic session id
364
+ - `--include-archived` — Include archived entries
365
+ - `--include-superseded` — Include superseded entries
366
+ - `--as-of <iso>` — Point-in-time read (ISO 8601 date or datetime); implies `--include-superseded`
301
367
  - `--json` — Machine-readable output
302
368
 
369
+ `--bank`, `--kind`, and `--session` isolate results the same way across `search`, `list`, `tags list`, and `read` — a query scoped to a private bank never returns `kb` results and vice versa, unless `--bank kb` is passed explicitly.
370
+
303
371
  ---
304
372
 
305
373
  ### `memo list` — Chronological Browse
@@ -315,8 +383,131 @@ Most-recent-first listing with optional date range.
315
383
  - `--scope`, `--tags`, `--entry-type`, `--source` — Same as search
316
384
  - `--from` / `--to` — ISO 8601 date boundaries
317
385
  - `--limit` — Max results (default 20)
386
+ - `--bank`, `--kind`, `--session`, `--include-archived`, `--include-superseded`, `--as-of` — Same read-side flags as `search`
387
+ - `--json` — Machine-readable output
388
+
389
+ ---
390
+
391
+ ### `memo timeline` — Replay Episodic Memory
392
+
393
+ ```bash
394
+ memo timeline --bank <agent>-memory --session ISSUE-42 --json
395
+ ```
396
+
397
+ Replays episodic memory **in sequence order** — never ranked. Two shapes:
398
+
399
+ - With `--session <id>`: entries for that session, ordered by `seq` ascending (ties broken by `timestamp_utc` ascending).
400
+ - Without `--session`: recent episodic entries across the bank, newest-first, grouped by `session_id`; JSON shape is `{ sessions: [{ session_id, entries }] }`.
401
+
402
+ **Optional flags:**
403
+
404
+ - `--bank <id>` — Bank id (default: `$MEMO_BANK`, `config.bank.default`, or `kb`)
405
+ - `--session <id>` — Restrict to one episodic session
406
+ - `--last <n>` — Maximum number of entries (default 50, max 500 — values above 500 are clamped with a stderr warning)
407
+ - `--since <iso>` — Inclusive ISO 8601 lower bound for `timestamp_utc`
318
408
  - `--json` — Machine-readable output
319
409
 
410
+ An empty bank returns exit `0` with `count: 0`. `timeline` never calls embeddings and never ranks — this is a raw sequence replay, unlike `search`.
411
+
412
+ ---
413
+
414
+ ### `memo bank` — Manage Memory Banks
415
+
416
+ ```bash
417
+ memo bank list --json
418
+ memo bank show --id developer-memory --json
419
+ memo bank init --id developer-memory --set-default --json
420
+ ```
421
+
422
+ Subcommands:
423
+
424
+ - **`bank init`** — Create a bank by writing its first `self` entry.
425
+ - `--id <id>` — Bank id (kebab-case or UUID; `kb` is rejected)
426
+ - `--rationale <text>` — Rationale for the self entry (default: `"Bank <id> initialised."`)
427
+ - `--tags <csv>` — 2–5 comma-separated tags (default: `bank,self`)
428
+ - `--set-default` — Set this bank as `config.bank.default` (writes `memo.config.json` unconditionally, every time the flag is passed)
429
+ - `--json` — Machine-readable output
430
+ - Idempotent: if the bank already has entries, `init` prints the existing summary and writes nothing.
431
+ - **`bank list`** — List every bank with counts per kind (`self`/`episodic`/`semantic`). `--json` for machine-readable output.
432
+ - **`bank show`** — Show one bank's `self` entries plus counts per kind **and per state** (`active`, `archived`, `superseded`), and `last_session_id`.
433
+ - `--id <id>` — Bank id (required)
434
+ - `--json` — Machine-readable output
435
+
436
+ `bank list`/`bank show` never accept `--orgs`/`--repos`/`--domains` — banks are an orthogonal axis to those facets, and private-bank entries may have no `repo`/`org` at all.
437
+
438
+ ---
439
+
440
+ ### `memo migrate --to-v2` — Migrate Legacy Payloads
441
+
442
+ ```bash
443
+ memo migrate --to-v2 --dry-run --json
444
+ memo migrate --to-v2 --json
445
+ ```
446
+
447
+ Migrates legacy v1 stored payloads to schema v2, idempotently (a point that already has `schema_version: '2'` is skipped on every run — the second real run always scans `0`). Nothing is archived, nothing is deleted, no vector is touched — this only rewrites payload fields (`bank = kb`, `schema_version = '2'`, `kind` per the matching rule, retention/counter defaults).
448
+
449
+ **Flags:**
450
+
451
+ - `--to-v2` — Target schema version; currently the only supported target (**required**)
452
+ - `--dry-run` — Plan only; writes nothing; exits `0`; prints counts
453
+ - `--rules <file>` — JSON file replacing the default rule set (see below)
454
+ - `--json` — Machine-readable output; without it, progress prints to stderr
455
+
456
+ **Migration guidance — always dry-run first:**
457
+
458
+ 1. Run `memo migrate --to-v2 --dry-run --json` and review the `byRule` counts and `skipped` total before doing anything else.
459
+ 2. Only run the real migration (`memo migrate --to-v2 --json`, no `--dry-run`) against your own local/dev Qdrant instance — **never** against a shared or production collection without a separate, explicit human-confirmed step. This is a `developer`-workstation operation, not something to run unattended in CI or against `infra-engineer`-owned infrastructure.
460
+ 3. Re-run `--dry-run` afterward to confirm `scanned: 0` — that's the idempotency check.
461
+
462
+ **Custom `--rules` file** (optional, replaces the default FR-2.8 rule set):
463
+
464
+ ```json
465
+ [
466
+ {
467
+ "name": "1",
468
+ "when": { "tags_any": ["intent", "outcome"] },
469
+ "set": { "kind": "episodic", "session_from": "story", "expires_in_days": 90 }
470
+ },
471
+ { "name": "2", "when": {}, "set": { "kind": "semantic" } }
472
+ ]
473
+ ```
474
+
475
+ `when` supports `tags_any`, `tags_all`, `entry_type_in`, `source_in`, `repo_in`; `set.kind` is required (any of `self`/`episodic`/`semantic`); `session_from` (`story | legacy`) and `expires_in_days` apply only to `episodic` rules. Rules are evaluated in order, first match wins. A rules file that leaves any point unmatched fails validation up front (`VALIDATION_FAILED`, "rule set is not exhaustive: add a final rule with empty `when`") — always end your custom rule set with a catch-all `{ "when": {} }` entry.
476
+
477
+ ---
478
+
479
+ ### `memo recall` — One-Call Context Restore
480
+
481
+ ```bash
482
+ memo recall "<task description>" --bank <agent>-memory --json
483
+ ```
484
+
485
+ The 1.3.0 replacement for the four-command session-start sequence (`list` + `tags list` + `search` + `search --scope related`). Gathers, in one call (≤ 4 s target):
486
+
487
+ | Section | Content | Omitted when |
488
+ | -------------- | --------------------------------------------------------------------- | --------------------------------------------------- |
489
+ | `SELF` | This agent's own persona/context entries, newest first, never trimmed | `--bank` resolves to `kb` |
490
+ | `POLICIES` | Ranked semantic policy entries from `kb` | never (empty until later phases add policy entries) |
491
+ | `SHARED` | Ranked semantic entries from `kb`, scoped by `--scope` | never |
492
+ | `MINE` | Ranked semantic entries from this agent's own bank | `--bank` resolves to `kb` |
493
+ | `LAST SESSION` | The most recent episodic session's entries, in `seq` order | `--bank` resolves to `kb` |
494
+ | `CONFLICTS` | Pending-contradiction entries (empty until a later phase) | never |
495
+
496
+ **Flags:**
497
+
498
+ - `--bank <id>` — Bank id (default: `$MEMO_BANK`, `config.bank.default`, or `kb`)
499
+ - `--scope <scope>` — `repo` | `related`, applies to `SHARED` only (default: config or `repo`)
500
+ - `--max-tokens <n>` — Token budget (default: `config.recall.max_tokens`, `2000`)
501
+ - `--json` — Machine-readable output
502
+
503
+ When the budget is tight, sections are trimmed in this order: `conflicts` → `last_session` (oldest entries first) → `mine` → `shared` → `policies`. `SELF` is **never** trimmed, even if it alone exceeds the budget — in that case `truncated` lists every other section and the response honestly reports `budget.used_tokens > max_tokens` rather than silently cutting `SELF`. `recall` performs zero writes.
504
+
505
+ **On failure:** `memo recall` exits `2` on an embeddings failure (`EMBEDDING_API_ERROR`) or a mid-gather Qdrant failure (`QDRANT_OPERATION_FAILED`) — there is no partial-bundle fallback. Treat this the same as any other exit-`2` failure: surface the warning, and continue the session without recalled context rather than blocking on it.
506
+
507
+ **When no private bank is passed** (resolves to `kb`): `SELF`, `MINE`, and `LAST SESSION` are omitted from the response entirely (omitted keys, not empty arrays) — you still get `POLICIES`, `SHARED`, `CONFLICTS`.
508
+
509
+ **Fallback when `memo recall` is unavailable** (`memo --version` below `1.3.0`, or the command errors as unrecognized): fall back to the four-command sequence documented under **Session Start — Restore Context** in `SKILL.md`.
510
+
320
511
  ---
321
512
 
322
513
  ### `memo tags list` — Discover Tags
@@ -373,7 +564,17 @@ Exactly one of `--id`, `--all-by-repo`, or `--all-by-org` is required.
373
564
 
374
565
  ### Starting a Session — Restore Context
375
566
 
376
- At the **beginning of every session**, run this sequence before writing a single line of code:
567
+ **memo-cli 1.3.0+ (preferred):** confirm config, then restore the full context bundle in one call:
568
+
569
+ ```bash
570
+ # 1. Confirm config is valid
571
+ memo setup validate
572
+
573
+ # 2. Restore SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS in one bundle
574
+ memo recall "<current task or feature description>" --bank <agent>-memory --json
575
+ ```
576
+
577
+ **Fallback (`memo --version` below `1.3.0`):** run this sequence instead, before writing a single line of code:
377
578
 
378
579
  ```bash
379
580
  # 1. Confirm config is valid
@@ -392,7 +593,11 @@ memo tags list --sort frequency --json
392
593
  memo search "<current task or feature description>" --limit 10 --json
393
594
  ```
394
595
 
395
- Read the results before proceeding. Prior entries may contain constraints, preferred patterns, or rejected alternatives that directly affect how you should approach the current task.
596
+ Read the results before proceeding, whichever path was used. Prior entries may contain constraints, preferred patterns, or rejected alternatives that directly affect how you should approach the current task. If `memo recall` exits `2` (embeddings failure), surface the warning and continue the session without recalled context.
597
+
598
+ ### Ending a Session — No Memo Action in Phase 2
599
+
600
+ Phase 2 has no session-close memo step. `memo used` (marking which recalled entries were actually useful) and `memo decay` (retention scoring) arrive with memo-cli 1.4.0 — do not invent a workaround for either in the meantime.
396
601
 
397
602
  ---
398
603
 
@@ -759,16 +964,24 @@ When a command fails:
759
964
  ## Quick Reference Card
760
965
 
761
966
  ```
762
- memo setup init --repo <r> --org <o> --domain <d> # Initialize config
763
- memo setup validate # Verify config
764
- memo setup show [--json] # Display config
765
-
766
- memo write --rationale "..." --tags "a,b,c" [--json] # Record decision
767
- memo search "query" [--scope related] [--json] # Semantic search
768
- memo list [--from DATE] [--to DATE] [--json] # Browse entries
769
- memo tags list [--sort frequency] [--json] # Discover tags
770
- memo inspect [--json] # Global facets
771
- memo delete --id <uuid> [--json] # Delete entry
967
+ memo setup init --repo <r> --org <o> --domain <d> # Initialize config
968
+ memo setup validate # Verify config
969
+ memo setup show [--json] # Display config
970
+
971
+ memo recall "<task>" --bank <agent>-memory [--json] # Restore full context (1.3.0+)
972
+ memo write --rationale "..." --tags "a,b,c" [--json] # Record a semantic decision (kb)
973
+ memo write --kind episodic --session ID --bank <agent>-memory [--json] # Record an intent/outcome entry
974
+ memo search "query" [--scope related] [--bank ID] [--kind K] [--json] # Semantic search
975
+ memo list [--from DATE] [--to DATE] [--bank ID] [--kind K] [--json] # Browse entries
976
+ memo timeline [--session ID] --bank <agent>-memory [--last N] [--json] # Replay episodic memory in order
977
+ memo tags list [--sort frequency] [--json] # Discover tags
978
+ memo inspect [--json] # Global facets
979
+ memo bank list [--json] # List all banks
980
+ memo bank show --id <id> [--json] # Show one bank's self entries + counts
981
+ memo bank init --id <id> [--set-default] [--json] # Create a bank
982
+ memo migrate --to-v2 --dry-run [--json] # Preview legacy payload migration
983
+ memo migrate --to-v2 [--json] # Apply legacy payload migration (local/dev only)
984
+ memo delete --id <uuid> [--json] # Delete entry
772
985
  ```
773
986
 
774
987
  ---
@@ -19,9 +19,39 @@ If validation fails, run: `memo setup init --repo <repo> --org <org> --domain <d
19
19
 
20
20
  ---
21
21
 
22
+ ## Banks and Kinds (memo-cli 1.3.0+)
23
+
24
+ A **bank** is a namespace an agent's entries live in — the shared `kb` (default, semantic knowledge base) or a private bank like `developer-memory`, one per long-lived agent. Set `--bank <id>` on any command.
25
+
26
+ **Agents: always pass `--bank <id>` literally on every command.** Agent runtimes run each shell command in a fresh shell, so an `export MEMO_BANK=…` from an earlier command is gone by the next one. An unquoted empty `$MEMO_BANK` is dropped by the shell, and the flag parser then reads the next token as the bank id (`--bank --rationale …` → bank `--rationale`), which memo-cli rejects with `VALIDATION_FAILED` (dev-tasks issue #253). Never write `--bank $MEMO_BANK` in an agent prompt or command.
27
+
28
+ ```bash
29
+ memo write --bank developer-memory ... # bank id convention: <agent-name>-memory
30
+ ```
31
+
32
+ Every entry has a **kind**:
33
+
34
+ | Kind | Meaning | Default bank behavior |
35
+ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
36
+ | `self` | The agent's own persona/context, never trimmed from `recall` | `kb` rejects `self`; only valid in private banks |
37
+ | `episodic` | Session-scoped narration (intent/outcome), expires automatically | requires `--session <id>`; default kind in private banks |
38
+ | `semantic` | Durable, searchable decisions — what `search`/`list` return today | default kind in `kb` |
39
+
40
+ Rule of thumb: episodic entries are per-session chatter that lives in your private bank and expires; semantic entries are durable knowledge that lives in `kb` (or is promoted there later) and never expires. See [`REFERENCE.md`](./REFERENCE.md) for bank/kind command reference, `memo recall`, `memo timeline`, `memo bank`, and `memo migrate`.
41
+
42
+ ---
43
+
22
44
  ## Session Start — Restore Context
23
45
 
24
- Run before writing any code:
46
+ **memo-cli 1.3.0+:** one call restores the full context bundle (SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS):
47
+
48
+ ```bash
49
+ memo recall "<current task description>" --bank <agent>-memory --json
50
+ ```
51
+
52
+ If no bank is passed (and `MEMO_BANK` is unset), `recall` resolves to `kb` and omits the private-only sections (`SELF`, `MINE`, `LAST SESSION`).
53
+
54
+ **Fallback (`memo --version` < 1.3.0, or `memo recall` unavailable):** run the four-command sequence instead:
25
55
 
26
56
  ```bash
27
57
  memo list --limit 20 --json
@@ -30,7 +60,7 @@ memo search "<current task description>" --limit 10 --json
30
60
  memo search "<key contract or dependency>" --scope related --limit 5 --json
31
61
  ```
32
62
 
33
- Synthesize findings into:
63
+ Synthesize findings (either path) into:
34
64
 
35
65
  - Constraints to preserve
36
66
  - Rejected alternatives to avoid
@@ -41,10 +71,13 @@ Synthesize findings into:
41
71
 
42
72
  ## Writing Entries
43
73
 
44
- ### Intent Entry (before starting a story/task)
74
+ ### Intent Entry (before starting a story/task) — episodic, in your bank
45
75
 
46
76
  ```bash
47
77
  memo write \
78
+ --kind episodic \
79
+ --session ISSUE-<number> \
80
+ --bank <agent>-memory \
48
81
  --rationale "Context: Starting ISSUE-<##> because <trigger>. Decision: implement via <approach>, preserving <constraints>. Impact: affects <modules/contracts>." \
49
82
  --tags "<domain>,issue-<number>,intent,<impact-tag>" \
50
83
  --entry-type decision \
@@ -54,10 +87,13 @@ memo write \
54
87
  --json
55
88
  ```
56
89
 
57
- ### Outcome Entry (after completing a story/task)
90
+ ### Outcome Entry (after completing a story/task) — episodic, in your bank
58
91
 
59
92
  ```bash
60
93
  memo write \
94
+ --kind episodic \
95
+ --session ISSUE-<number> \
96
+ --bank <agent>-memory \
61
97
  --rationale "Context: Completed ISSUE-<##>. Delivery: shipped <behavior>, deviations <none|details>, AC <x/y> verified. Impact: quality gates test=<p/f>; lint=<p/f>; format:check=<p/f>; typecheck=<p/f>; audit=<p/f>." \
62
98
  --tags "<domain>,issue-<number>,outcome,gates-pass" \
63
99
  --entry-type decision \
@@ -69,17 +105,24 @@ memo write \
69
105
  --json
70
106
  ```
71
107
 
72
- ### Decision Entry (architectural choices)
108
+ `--session` is required whenever `--kind episodic` is used; `--seq` auto-increments per session and rarely needs to be passed explicitly.
109
+
110
+ ### Decision/ADR Entry (architectural choices) — semantic, in `kb`
73
111
 
74
112
  ```bash
75
113
  memo write \
114
+ --kind semantic \
115
+ --bank kb \
76
116
  --rationale "Context: <situation>. Decision: <what was chosen>. Rationale: <why this over alternatives>." \
77
117
  --tags "<domain>,<technology>,decision" \
78
118
  --entry-type decision \
79
119
  --source agent \
120
+ --provenance "<csv of episodic entry ids this consolidates, if any>" \
80
121
  --json
81
122
  ```
82
123
 
124
+ A `semantic` entry with `--source agent` **MUST** carry `--provenance <csv>` unless `--manual` is passed (PRD K3) — cite the episodic intent/outcome ids the decision was distilled from.
125
+
83
126
  ---
84
127
 
85
128
  ## Entry Types
@@ -129,16 +172,28 @@ memo write \
129
172
 
130
173
  ---
131
174
 
175
+ ## Session Close
176
+
177
+ No memo action in Phase 2. `memo used` and `memo decay` arrive with memo-cli 1.4.0.
178
+
179
+ ---
180
+
132
181
  ## Quick Command Card
133
182
 
134
183
  ```
135
- memo setup validate # Verify config
136
- memo write --rationale "..." --tags "a,b,c" --json # Record decision
137
- memo search "query" [--scope related] --json # Semantic search
138
- memo list [--limit N] --json # Browse recent
139
- memo tags list [--sort frequency] --json # Discover tags
140
- memo inspect --json # Global facets
141
- memo delete --id <uuid> --json # Delete entry
184
+ memo setup validate # Verify config
185
+ memo recall "<task>" --bank <agent>-memory --json # Restore full context (1.3.0+)
186
+ memo write --rationale "..." --tags "a,b,c" --json # Record a semantic decision (kb)
187
+ memo write --kind episodic --session ID --bank <agent>-memory # Record an intent/outcome entry
188
+ memo search "query" [--scope related] --json # Semantic search
189
+ memo list [--limit N] --json # Browse recent
190
+ memo timeline [--session ID] --bank <agent>-memory --json # Replay episodic memory in order
191
+ memo tags list [--sort frequency] --json # Discover tags
192
+ memo inspect --json # Global facets
193
+ memo bank list --json # List all banks
194
+ memo bank init --id <id> --json # Create a bank
195
+ memo migrate --to-v2 --dry-run --json # Preview legacy payload migration
196
+ memo delete --id <uuid> --json # Delete entry
142
197
  ```
143
198
 
144
- > For full flag documentation, admin operations, environment setup, and detailed examples, read [`REFERENCE.md`](./REFERENCE.md).
199
+ > For full flag documentation, admin operations, environment setup, banks/kinds, `recall`, `timeline`, `bank`, `migrate`, and detailed examples, read [`REFERENCE.md`](./REFERENCE.md).