@llipe.com/dev-tasks 0.11.0 → 0.16.1

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 (617) hide show
  1. package/.claude/agents/developer.md +105 -43
  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 +61 -6
  7. package/.claude/agents/ux-engineer.md +1 -0
  8. package/.claude/agents/verifier.md +48 -6
  9. package/.claude/commands/developer.md +2 -266
  10. package/.claude/commands/infra-engineer.md +92 -0
  11. package/.claude/commands/planner.md +44 -23
  12. package/.claude/commands/product-engineer.md +21 -9
  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 +483 -22
  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 +49 -4
  28. package/.claude/skills/memo-cli-usage/REFERENCE.md +230 -17
  29. package/.claude/skills/memo-cli-usage/SKILL.md +66 -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 +70 -19
  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 +25 -4
  37. package/.github/agents/product-engineer.agent.md +21 -9
  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 +60 -6
  41. package/.github/agents/verifier.agent.md +46 -5
  42. package/.github/instructions/implement.instructions.md +49 -4
  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 +66 -13
  60. package/.github/skills/supabase-ops/SKILL.md +104 -0
  61. package/.kiro/agents/developer.md +71 -20
  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 +33 -15
  66. package/.kiro/agents/product-engineer.md +24 -12
  67. package/.kiro/agents/qa-engineer.md +24 -12
  68. package/.kiro/agents/researcher.md +26 -7
  69. package/.kiro/agents/technical-writer.md +63 -9
  70. package/.kiro/agents/verifier.md +47 -6
  71. package/.kiro/skills/activity-codebase-research/SKILL.md +4 -11
  72. package/.kiro/skills/activity-generate-spec/SKILL.md +34 -10
  73. package/.kiro/skills/activity-grill/SKILL.md +150 -0
  74. package/.kiro/skills/activity-init/SKILL.md +121 -71
  75. package/.kiro/skills/activity-refine/SKILL.md +75 -15
  76. package/.kiro/skills/activity-test-standards/SKILL.md +25 -0
  77. package/.kiro/skills/aws-ops/SKILL.md +155 -0
  78. package/.kiro/skills/deploy-ops/SKILL.md +121 -0
  79. package/.kiro/skills/fly-ops/SKILL.md +138 -0
  80. package/.kiro/skills/git-ops/SKILL.md +27 -7
  81. package/.kiro/skills/memo-cli-usage/REFERENCE.md +230 -17
  82. package/.kiro/skills/memo-cli-usage/SKILL.md +66 -13
  83. package/.kiro/skills/supabase-ops/SKILL.md +109 -0
  84. package/.kiro/steering/implement.md +49 -4
  85. package/.kiro/steering/plan.md +43 -1
  86. package/AGENTS.md +60 -109
  87. package/AGENTS.md.template +124 -0
  88. package/CHANGELOG.md +163 -0
  89. package/CLAUDE.md +23 -18
  90. package/CLAUDE.md.template +103 -0
  91. package/README.md +168 -146
  92. package/TESTING.md +84 -148
  93. package/bundle-manifest.json +43 -2
  94. package/dist/bin/dev-tasks.js +65 -3
  95. package/dist/bin/dev-tasks.js.map +1 -1
  96. package/dist/{adapters/cli → bin}/parse-args.d.ts +2 -6
  97. package/dist/bin/parse-args.d.ts.map +1 -0
  98. package/dist/{adapters/cli → bin}/parse-args.js +2 -18
  99. package/dist/bin/parse-args.js.map +1 -0
  100. package/dist/core/checks/decision-log-format.d.ts +44 -0
  101. package/dist/core/checks/decision-log-format.d.ts.map +1 -0
  102. package/dist/core/checks/decision-log-format.js +171 -0
  103. package/dist/core/checks/decision-log-format.js.map +1 -0
  104. package/dist/core/checks/docs-structure.d.ts +82 -0
  105. package/dist/core/checks/docs-structure.d.ts.map +1 -0
  106. package/dist/core/checks/docs-structure.js +285 -0
  107. package/dist/core/checks/docs-structure.js.map +1 -0
  108. package/dist/core/checks/glossary.d.ts +178 -0
  109. package/dist/core/checks/glossary.d.ts.map +1 -0
  110. package/dist/core/checks/glossary.js +651 -0
  111. package/dist/core/checks/glossary.js.map +1 -0
  112. package/dist/core/checks/index.d.ts +19 -0
  113. package/dist/core/checks/index.d.ts.map +1 -0
  114. package/dist/core/checks/index.js +16 -0
  115. package/dist/core/checks/index.js.map +1 -0
  116. package/dist/core/checks/run.d.ts +22 -0
  117. package/dist/core/checks/run.d.ts.map +1 -0
  118. package/dist/core/checks/run.js +51 -0
  119. package/dist/core/checks/run.js.map +1 -0
  120. package/dist/core/distribution/doctor.d.ts +46 -1
  121. package/dist/core/distribution/doctor.d.ts.map +1 -1
  122. package/dist/core/distribution/doctor.js +161 -2
  123. package/dist/core/distribution/doctor.js.map +1 -1
  124. package/dist/core/distribution/index.d.ts +9 -3
  125. package/dist/core/distribution/index.d.ts.map +1 -1
  126. package/dist/core/distribution/index.js +5 -2
  127. package/dist/core/distribution/index.js.map +1 -1
  128. package/dist/core/distribution/install-if-absent.d.ts +46 -0
  129. package/dist/core/distribution/install-if-absent.d.ts.map +1 -0
  130. package/dist/core/distribution/install-if-absent.js +81 -0
  131. package/dist/core/distribution/install-if-absent.js.map +1 -0
  132. package/dist/core/distribution/install.d.ts.map +1 -1
  133. package/dist/core/distribution/install.js +5 -0
  134. package/dist/core/distribution/install.js.map +1 -1
  135. package/dist/core/distribution/migrate-docs.d.ts +64 -0
  136. package/dist/core/distribution/migrate-docs.d.ts.map +1 -0
  137. package/dist/core/distribution/migrate-docs.js +139 -0
  138. package/dist/core/distribution/migrate-docs.js.map +1 -0
  139. package/dist/core/distribution/profiles.d.ts +49 -0
  140. package/dist/core/distribution/profiles.d.ts.map +1 -1
  141. package/dist/core/distribution/profiles.js +45 -0
  142. package/dist/core/distribution/profiles.js.map +1 -1
  143. package/dist/core/distribution/update.d.ts +14 -0
  144. package/dist/core/distribution/update.d.ts.map +1 -1
  145. package/dist/core/distribution/update.js +77 -3
  146. package/dist/core/distribution/update.js.map +1 -1
  147. package/dist/core/distribution/workspace.d.ts +84 -0
  148. package/dist/core/distribution/workspace.d.ts.map +1 -0
  149. package/dist/core/distribution/workspace.js +276 -0
  150. package/dist/core/distribution/workspace.js.map +1 -0
  151. package/dist/core/exit-codes.d.ts +15 -35
  152. package/dist/core/exit-codes.d.ts.map +1 -1
  153. package/dist/core/exit-codes.js +15 -36
  154. package/dist/core/exit-codes.js.map +1 -1
  155. package/dist/core/index.d.ts +1 -6
  156. package/dist/core/index.d.ts.map +1 -1
  157. package/dist/core/index.js +1 -7
  158. package/dist/core/index.js.map +1 -1
  159. package/package.json +17 -32
  160. package/templates/claude/settings.json +48 -0
  161. package/templates/domain/ubiquitous-language.md +28 -0
  162. package/templates/infra/environments.yaml +16 -0
  163. package/templates/infra/redaction-patterns.txt +47 -0
  164. package/templates/runbooks/README.md +14 -0
  165. package/templates/runbooks/runbook-template.md +40 -0
  166. package/templates/scripts/deploy-status.sh +89 -0
  167. package/templates/scripts/deploy-verify.sh +85 -0
  168. package/templates/scripts/deploy.sh +284 -0
  169. package/templates/scripts/release.sh +170 -0
  170. package/templates/scripts/rollback.sh +109 -0
  171. package/templates/workflows/deploy-dev.yml +66 -0
  172. package/templates/workflows/deploy-prod.yml +66 -0
  173. package/templates/workflows/rollback.yml +77 -0
  174. package/.claude/skills/activity-contract-validation/SKILL.md +0 -167
  175. package/.github/skills/activity-contract-validation/SKILL.md +0 -167
  176. package/.kiro/skills/activity-contract-validation/SKILL.md +0 -167
  177. package/dist/adapters/cli/catalog-build.d.ts +0 -30
  178. package/dist/adapters/cli/catalog-build.d.ts.map +0 -1
  179. package/dist/adapters/cli/catalog-build.js +0 -73
  180. package/dist/adapters/cli/catalog-build.js.map +0 -1
  181. package/dist/adapters/cli/catalog-query.d.ts +0 -13
  182. package/dist/adapters/cli/catalog-query.d.ts.map +0 -1
  183. package/dist/adapters/cli/catalog-query.js +0 -329
  184. package/dist/adapters/cli/catalog-query.js.map +0 -1
  185. package/dist/adapters/cli/catalog-scaffold.d.ts +0 -24
  186. package/dist/adapters/cli/catalog-scaffold.d.ts.map +0 -1
  187. package/dist/adapters/cli/catalog-scaffold.js +0 -46
  188. package/dist/adapters/cli/catalog-scaffold.js.map +0 -1
  189. package/dist/adapters/cli/catalog-validate.d.ts +0 -35
  190. package/dist/adapters/cli/catalog-validate.d.ts.map +0 -1
  191. package/dist/adapters/cli/catalog-validate.js +0 -122
  192. package/dist/adapters/cli/catalog-validate.js.map +0 -1
  193. package/dist/adapters/cli/ctx-assemble.d.ts +0 -19
  194. package/dist/adapters/cli/ctx-assemble.d.ts.map +0 -1
  195. package/dist/adapters/cli/ctx-assemble.js +0 -293
  196. package/dist/adapters/cli/ctx-assemble.js.map +0 -1
  197. package/dist/adapters/cli/ctx-fetch.d.ts +0 -49
  198. package/dist/adapters/cli/ctx-fetch.d.ts.map +0 -1
  199. package/dist/adapters/cli/ctx-fetch.js +0 -267
  200. package/dist/adapters/cli/ctx-fetch.js.map +0 -1
  201. package/dist/adapters/cli/extract-all.d.ts +0 -31
  202. package/dist/adapters/cli/extract-all.d.ts.map +0 -1
  203. package/dist/adapters/cli/extract-all.js +0 -374
  204. package/dist/adapters/cli/extract-all.js.map +0 -1
  205. package/dist/adapters/cli/extract-asyncapi.d.ts +0 -26
  206. package/dist/adapters/cli/extract-asyncapi.d.ts.map +0 -1
  207. package/dist/adapters/cli/extract-asyncapi.js +0 -142
  208. package/dist/adapters/cli/extract-asyncapi.js.map +0 -1
  209. package/dist/adapters/cli/extract-component.d.ts +0 -24
  210. package/dist/adapters/cli/extract-component.d.ts.map +0 -1
  211. package/dist/adapters/cli/extract-component.js +0 -198
  212. package/dist/adapters/cli/extract-component.js.map +0 -1
  213. package/dist/adapters/cli/extract-detect.d.ts +0 -19
  214. package/dist/adapters/cli/extract-detect.d.ts.map +0 -1
  215. package/dist/adapters/cli/extract-detect.js +0 -98
  216. package/dist/adapters/cli/extract-detect.js.map +0 -1
  217. package/dist/adapters/cli/extract-openapi.d.ts +0 -29
  218. package/dist/adapters/cli/extract-openapi.d.ts.map +0 -1
  219. package/dist/adapters/cli/extract-openapi.js +0 -111
  220. package/dist/adapters/cli/extract-openapi.js.map +0 -1
  221. package/dist/adapters/cli/extract-schema.d.ts +0 -15
  222. package/dist/adapters/cli/extract-schema.d.ts.map +0 -1
  223. package/dist/adapters/cli/extract-schema.js +0 -39
  224. package/dist/adapters/cli/extract-schema.js.map +0 -1
  225. package/dist/adapters/cli/index.d.ts +0 -6
  226. package/dist/adapters/cli/index.d.ts.map +0 -1
  227. package/dist/adapters/cli/index.js +0 -5
  228. package/dist/adapters/cli/index.js.map +0 -1
  229. package/dist/adapters/cli/init.d.ts +0 -37
  230. package/dist/adapters/cli/init.d.ts.map +0 -1
  231. package/dist/adapters/cli/init.js +0 -336
  232. package/dist/adapters/cli/init.js.map +0 -1
  233. package/dist/adapters/cli/parse-args.d.ts.map +0 -1
  234. package/dist/adapters/cli/parse-args.js.map +0 -1
  235. package/dist/adapters/cli/scope-gate.d.ts +0 -25
  236. package/dist/adapters/cli/scope-gate.d.ts.map +0 -1
  237. package/dist/adapters/cli/scope-gate.js +0 -157
  238. package/dist/adapters/cli/scope-gate.js.map +0 -1
  239. package/dist/adapters/cli/scope.d.ts +0 -26
  240. package/dist/adapters/cli/scope.d.ts.map +0 -1
  241. package/dist/adapters/cli/scope.js +0 -172
  242. package/dist/adapters/cli/scope.js.map +0 -1
  243. package/dist/adapters/cli/validate-component.d.ts +0 -24
  244. package/dist/adapters/cli/validate-component.d.ts.map +0 -1
  245. package/dist/adapters/cli/validate-component.js +0 -62
  246. package/dist/adapters/cli/validate-component.js.map +0 -1
  247. package/dist/adapters/cli/verify-contract-diff.d.ts +0 -21
  248. package/dist/adapters/cli/verify-contract-diff.d.ts.map +0 -1
  249. package/dist/adapters/cli/verify-contract-diff.js +0 -69
  250. package/dist/adapters/cli/verify-contract-diff.js.map +0 -1
  251. package/dist/adapters/cli/verify-drift.d.ts +0 -24
  252. package/dist/adapters/cli/verify-drift.d.ts.map +0 -1
  253. package/dist/adapters/cli/verify-drift.js +0 -103
  254. package/dist/adapters/cli/verify-drift.js.map +0 -1
  255. package/dist/adapters/cli/verify-impact.d.ts +0 -23
  256. package/dist/adapters/cli/verify-impact.d.ts.map +0 -1
  257. package/dist/adapters/cli/verify-impact.js +0 -119
  258. package/dist/adapters/cli/verify-impact.js.map +0 -1
  259. package/dist/adapters/mcp/index.d.ts +0 -5
  260. package/dist/adapters/mcp/index.d.ts.map +0 -1
  261. package/dist/adapters/mcp/index.js +0 -2
  262. package/dist/adapters/mcp/index.js.map +0 -1
  263. package/dist/bin/dt.d.ts +0 -7
  264. package/dist/bin/dt.d.ts.map +0 -1
  265. package/dist/bin/dt.js +0 -647
  266. package/dist/bin/dt.js.map +0 -1
  267. package/dist/core/catalog/build.d.ts +0 -143
  268. package/dist/core/catalog/build.d.ts.map +0 -1
  269. package/dist/core/catalog/build.js +0 -475
  270. package/dist/core/catalog/build.js.map +0 -1
  271. package/dist/core/catalog/checks/index.d.ts +0 -18
  272. package/dist/core/catalog/checks/index.d.ts.map +0 -1
  273. package/dist/core/catalog/checks/index.js +0 -18
  274. package/dist/core/catalog/checks/index.js.map +0 -1
  275. package/dist/core/catalog/checks/v01-schema.d.ts +0 -17
  276. package/dist/core/catalog/checks/v01-schema.d.ts.map +0 -1
  277. package/dist/core/catalog/checks/v01-schema.js +0 -57
  278. package/dist/core/catalog/checks/v01-schema.js.map +0 -1
  279. package/dist/core/catalog/checks/v02-v03-identity.d.ts +0 -14
  280. package/dist/core/catalog/checks/v02-v03-identity.d.ts.map +0 -1
  281. package/dist/core/catalog/checks/v02-v03-identity.js +0 -60
  282. package/dist/core/catalog/checks/v02-v03-identity.js.map +0 -1
  283. package/dist/core/catalog/checks/v04-referential-integrity.d.ts +0 -7
  284. package/dist/core/catalog/checks/v04-referential-integrity.d.ts.map +0 -1
  285. package/dist/core/catalog/checks/v04-referential-integrity.js +0 -32
  286. package/dist/core/catalog/checks/v04-referential-integrity.js.map +0 -1
  287. package/dist/core/catalog/checks/v05-domain-existence.d.ts +0 -6
  288. package/dist/core/catalog/checks/v05-domain-existence.d.ts.map +0 -1
  289. package/dist/core/catalog/checks/v05-domain-existence.js +0 -23
  290. package/dist/core/catalog/checks/v05-domain-existence.js.map +0 -1
  291. package/dist/core/catalog/checks/v06-v07-paths.d.ts +0 -29
  292. package/dist/core/catalog/checks/v06-v07-paths.d.ts.map +0 -1
  293. package/dist/core/catalog/checks/v06-v07-paths.js +0 -107
  294. package/dist/core/catalog/checks/v06-v07-paths.js.map +0 -1
  295. package/dist/core/catalog/checks/v08-v10-contracts.d.ts +0 -13
  296. package/dist/core/catalog/checks/v08-v10-contracts.d.ts.map +0 -1
  297. package/dist/core/catalog/checks/v08-v10-contracts.js +0 -70
  298. package/dist/core/catalog/checks/v08-v10-contracts.js.map +0 -1
  299. package/dist/core/catalog/checks/v11-manual-fields.d.ts +0 -16
  300. package/dist/core/catalog/checks/v11-manual-fields.d.ts.map +0 -1
  301. package/dist/core/catalog/checks/v11-manual-fields.js +0 -60
  302. package/dist/core/catalog/checks/v11-manual-fields.js.map +0 -1
  303. package/dist/core/catalog/checks/v12-cycles.d.ts +0 -8
  304. package/dist/core/catalog/checks/v12-cycles.d.ts.map +0 -1
  305. package/dist/core/catalog/checks/v12-cycles.js +0 -28
  306. package/dist/core/catalog/checks/v12-cycles.js.map +0 -1
  307. package/dist/core/catalog/checks/v13-orphan-contracts.d.ts +0 -7
  308. package/dist/core/catalog/checks/v13-orphan-contracts.d.ts.map +0 -1
  309. package/dist/core/catalog/checks/v13-orphan-contracts.js +0 -33
  310. package/dist/core/catalog/checks/v13-orphan-contracts.js.map +0 -1
  311. package/dist/core/catalog/checks/v14-v15-lifecycle.d.ts +0 -8
  312. package/dist/core/catalog/checks/v14-v15-lifecycle.d.ts.map +0 -1
  313. package/dist/core/catalog/checks/v14-v15-lifecycle.js +0 -42
  314. package/dist/core/catalog/checks/v14-v15-lifecycle.js.map +0 -1
  315. package/dist/core/catalog/checks/v16-deprecated-consumers.d.ts +0 -7
  316. package/dist/core/catalog/checks/v16-deprecated-consumers.d.ts.map +0 -1
  317. package/dist/core/catalog/checks/v16-deprecated-consumers.js +0 -47
  318. package/dist/core/catalog/checks/v16-deprecated-consumers.js.map +0 -1
  319. package/dist/core/catalog/checks/v17-low-confidence.d.ts +0 -7
  320. package/dist/core/catalog/checks/v17-low-confidence.d.ts.map +0 -1
  321. package/dist/core/catalog/checks/v17-low-confidence.js +0 -32
  322. package/dist/core/catalog/checks/v17-low-confidence.js.map +0 -1
  323. package/dist/core/catalog/checks/v18-low-payload.d.ts +0 -7
  324. package/dist/core/catalog/checks/v18-low-payload.d.ts.map +0 -1
  325. package/dist/core/catalog/checks/v18-low-payload.js +0 -33
  326. package/dist/core/catalog/checks/v18-low-payload.js.map +0 -1
  327. package/dist/core/catalog/checks/v19-domain-membership.d.ts +0 -8
  328. package/dist/core/catalog/checks/v19-domain-membership.d.ts.map +0 -1
  329. package/dist/core/catalog/checks/v19-domain-membership.js +0 -55
  330. package/dist/core/catalog/checks/v19-domain-membership.js.map +0 -1
  331. package/dist/core/catalog/coverage.d.ts +0 -39
  332. package/dist/core/catalog/coverage.d.ts.map +0 -1
  333. package/dist/core/catalog/coverage.js +0 -62
  334. package/dist/core/catalog/coverage.js.map +0 -1
  335. package/dist/core/catalog/graph.d.ts +0 -49
  336. package/dist/core/catalog/graph.d.ts.map +0 -1
  337. package/dist/core/catalog/graph.js +0 -114
  338. package/dist/core/catalog/graph.js.map +0 -1
  339. package/dist/core/catalog/index-model.d.ts +0 -96
  340. package/dist/core/catalog/index-model.d.ts.map +0 -1
  341. package/dist/core/catalog/index-model.js +0 -8
  342. package/dist/core/catalog/index-model.js.map +0 -1
  343. package/dist/core/catalog/index.d.ts +0 -5
  344. package/dist/core/catalog/index.d.ts.map +0 -1
  345. package/dist/core/catalog/index.js +0 -2
  346. package/dist/core/catalog/index.js.map +0 -1
  347. package/dist/core/catalog/queries.d.ts +0 -69
  348. package/dist/core/catalog/queries.d.ts.map +0 -1
  349. package/dist/core/catalog/queries.js +0 -165
  350. package/dist/core/catalog/queries.js.map +0 -1
  351. package/dist/core/catalog/resolve.d.ts +0 -47
  352. package/dist/core/catalog/resolve.d.ts.map +0 -1
  353. package/dist/core/catalog/resolve.js +0 -318
  354. package/dist/core/catalog/resolve.js.map +0 -1
  355. package/dist/core/catalog/scaffold.d.ts +0 -31
  356. package/dist/core/catalog/scaffold.d.ts.map +0 -1
  357. package/dist/core/catalog/scaffold.js +0 -141
  358. package/dist/core/catalog/scaffold.js.map +0 -1
  359. package/dist/core/catalog/validate-component.d.ts +0 -50
  360. package/dist/core/catalog/validate-component.d.ts.map +0 -1
  361. package/dist/core/catalog/validate-component.js +0 -105
  362. package/dist/core/catalog/validate-component.js.map +0 -1
  363. package/dist/core/catalog/validate.d.ts +0 -71
  364. package/dist/core/catalog/validate.d.ts.map +0 -1
  365. package/dist/core/catalog/validate.js +0 -103
  366. package/dist/core/catalog/validate.js.map +0 -1
  367. package/dist/core/context/assemble.d.ts +0 -126
  368. package/dist/core/context/assemble.d.ts.map +0 -1
  369. package/dist/core/context/assemble.js +0 -197
  370. package/dist/core/context/assemble.js.map +0 -1
  371. package/dist/core/context/cache.d.ts +0 -60
  372. package/dist/core/context/cache.d.ts.map +0 -1
  373. package/dist/core/context/cache.js +0 -236
  374. package/dist/core/context/cache.js.map +0 -1
  375. package/dist/core/context/exit-codes.d.ts +0 -28
  376. package/dist/core/context/exit-codes.d.ts.map +0 -1
  377. package/dist/core/context/exit-codes.js +0 -28
  378. package/dist/core/context/exit-codes.js.map +0 -1
  379. package/dist/core/context/fetch.d.ts +0 -55
  380. package/dist/core/context/fetch.d.ts.map +0 -1
  381. package/dist/core/context/fetch.js +0 -112
  382. package/dist/core/context/fetch.js.map +0 -1
  383. package/dist/core/context/index.d.ts +0 -11
  384. package/dist/core/context/index.d.ts.map +0 -1
  385. package/dist/core/context/index.js +0 -8
  386. package/dist/core/context/index.js.map +0 -1
  387. package/dist/core/context/init.d.ts +0 -179
  388. package/dist/core/context/init.d.ts.map +0 -1
  389. package/dist/core/context/init.js +0 -532
  390. package/dist/core/context/init.js.map +0 -1
  391. package/dist/core/context/layers/architecture-layer.d.ts +0 -13
  392. package/dist/core/context/layers/architecture-layer.d.ts.map +0 -1
  393. package/dist/core/context/layers/architecture-layer.js +0 -24
  394. package/dist/core/context/layers/architecture-layer.js.map +0 -1
  395. package/dist/core/context/layers/contracts-layer.d.ts +0 -13
  396. package/dist/core/context/layers/contracts-layer.d.ts.map +0 -1
  397. package/dist/core/context/layers/contracts-layer.js +0 -83
  398. package/dist/core/context/layers/contracts-layer.js.map +0 -1
  399. package/dist/core/context/layers/conventions-delta-layer.d.ts +0 -13
  400. package/dist/core/context/layers/conventions-delta-layer.d.ts.map +0 -1
  401. package/dist/core/context/layers/conventions-delta-layer.js +0 -37
  402. package/dist/core/context/layers/conventions-delta-layer.js.map +0 -1
  403. package/dist/core/context/layers/flow-layer.d.ts +0 -14
  404. package/dist/core/context/layers/flow-layer.d.ts.map +0 -1
  405. package/dist/core/context/layers/flow-layer.js +0 -61
  406. package/dist/core/context/layers/flow-layer.js.map +0 -1
  407. package/dist/core/context/layers/index-layer.d.ts +0 -13
  408. package/dist/core/context/layers/index-layer.d.ts.map +0 -1
  409. package/dist/core/context/layers/index-layer.js +0 -77
  410. package/dist/core/context/layers/index-layer.js.map +0 -1
  411. package/dist/core/context/layers/primary-layer.d.ts +0 -16
  412. package/dist/core/context/layers/primary-layer.d.ts.map +0 -1
  413. package/dist/core/context/layers/primary-layer.js +0 -61
  414. package/dist/core/context/layers/primary-layer.js.map +0 -1
  415. package/dist/core/context/layers/secondary-layer.d.ts +0 -19
  416. package/dist/core/context/layers/secondary-layer.d.ts.map +0 -1
  417. package/dist/core/context/layers/secondary-layer.js +0 -52
  418. package/dist/core/context/layers/secondary-layer.js.map +0 -1
  419. package/dist/core/context/session-lock.d.ts +0 -114
  420. package/dist/core/context/session-lock.d.ts.map +0 -1
  421. package/dist/core/context/session-lock.js +0 -90
  422. package/dist/core/context/session-lock.js.map +0 -1
  423. package/dist/core/context/tokens.d.ts +0 -35
  424. package/dist/core/context/tokens.d.ts.map +0 -1
  425. package/dist/core/context/tokens.js +0 -88
  426. package/dist/core/context/tokens.js.map +0 -1
  427. package/dist/core/extract/asyncapi/declared.d.ts +0 -19
  428. package/dist/core/extract/asyncapi/declared.d.ts.map +0 -1
  429. package/dist/core/extract/asyncapi/declared.js +0 -168
  430. package/dist/core/extract/asyncapi/declared.js.map +0 -1
  431. package/dist/core/extract/asyncapi/index.d.ts +0 -12
  432. package/dist/core/extract/asyncapi/index.d.ts.map +0 -1
  433. package/dist/core/extract/asyncapi/index.js +0 -8
  434. package/dist/core/extract/asyncapi/index.js.map +0 -1
  435. package/dist/core/extract/asyncapi/payloads.d.ts +0 -20
  436. package/dist/core/extract/asyncapi/payloads.d.ts.map +0 -1
  437. package/dist/core/extract/asyncapi/payloads.js +0 -421
  438. package/dist/core/extract/asyncapi/payloads.js.map +0 -1
  439. package/dist/core/extract/asyncapi/topics.d.ts +0 -27
  440. package/dist/core/extract/asyncapi/topics.d.ts.map +0 -1
  441. package/dist/core/extract/asyncapi/topics.js +0 -368
  442. package/dist/core/extract/asyncapi/topics.js.map +0 -1
  443. package/dist/core/extract/asyncapi/types.d.ts +0 -129
  444. package/dist/core/extract/asyncapi/types.d.ts.map +0 -1
  445. package/dist/core/extract/asyncapi/types.js +0 -5
  446. package/dist/core/extract/asyncapi/types.js.map +0 -1
  447. package/dist/core/extract/asyncapi/validate.d.ts +0 -29
  448. package/dist/core/extract/asyncapi/validate.d.ts.map +0 -1
  449. package/dist/core/extract/asyncapi/validate.js +0 -156
  450. package/dist/core/extract/asyncapi/validate.js.map +0 -1
  451. package/dist/core/extract/component.d.ts +0 -204
  452. package/dist/core/extract/component.d.ts.map +0 -1
  453. package/dist/core/extract/component.js +0 -258
  454. package/dist/core/extract/component.js.map +0 -1
  455. package/dist/core/extract/detect.d.ts +0 -35
  456. package/dist/core/extract/detect.d.ts.map +0 -1
  457. package/dist/core/extract/detect.js +0 -89
  458. package/dist/core/extract/detect.js.map +0 -1
  459. package/dist/core/extract/index.d.ts +0 -12
  460. package/dist/core/extract/index.d.ts.map +0 -1
  461. package/dist/core/extract/index.js +0 -6
  462. package/dist/core/extract/index.js.map +0 -1
  463. package/dist/core/extract/ladder.d.ts +0 -79
  464. package/dist/core/extract/ladder.d.ts.map +0 -1
  465. package/dist/core/extract/ladder.js +0 -70
  466. package/dist/core/extract/ladder.js.map +0 -1
  467. package/dist/core/extract/openapi/index.d.ts +0 -43
  468. package/dist/core/extract/openapi/index.d.ts.map +0 -1
  469. package/dist/core/extract/openapi/index.js +0 -142
  470. package/dist/core/extract/openapi/index.js.map +0 -1
  471. package/dist/core/extract/openapi/route1.d.ts +0 -36
  472. package/dist/core/extract/openapi/route1.d.ts.map +0 -1
  473. package/dist/core/extract/openapi/route1.js +0 -333
  474. package/dist/core/extract/openapi/route1.js.map +0 -1
  475. package/dist/core/extract/openapi/route2-introspect.d.ts +0 -18
  476. package/dist/core/extract/openapi/route2-introspect.d.ts.map +0 -1
  477. package/dist/core/extract/openapi/route2-introspect.js +0 -249
  478. package/dist/core/extract/openapi/route2-introspect.js.map +0 -1
  479. package/dist/core/extract/openapi/route2.d.ts +0 -69
  480. package/dist/core/extract/openapi/route2.d.ts.map +0 -1
  481. package/dist/core/extract/openapi/route2.js +0 -211
  482. package/dist/core/extract/openapi/route2.js.map +0 -1
  483. package/dist/core/extract/openapi/route3.d.ts +0 -26
  484. package/dist/core/extract/openapi/route3.d.ts.map +0 -1
  485. package/dist/core/extract/openapi/route3.js +0 -737
  486. package/dist/core/extract/openapi/route3.js.map +0 -1
  487. package/dist/core/extract/openapi/types.d.ts +0 -125
  488. package/dist/core/extract/openapi/types.d.ts.map +0 -1
  489. package/dist/core/extract/openapi/types.js +0 -5
  490. package/dist/core/extract/openapi/types.js.map +0 -1
  491. package/dist/core/extract/openapi/validate.d.ts +0 -29
  492. package/dist/core/extract/openapi/validate.d.ts.map +0 -1
  493. package/dist/core/extract/openapi/validate.js +0 -200
  494. package/dist/core/extract/openapi/validate.js.map +0 -1
  495. package/dist/core/extract/orm/drizzle.d.ts +0 -20
  496. package/dist/core/extract/orm/drizzle.d.ts.map +0 -1
  497. package/dist/core/extract/orm/drizzle.js +0 -283
  498. package/dist/core/extract/orm/drizzle.js.map +0 -1
  499. package/dist/core/extract/orm/information-schema.d.ts +0 -26
  500. package/dist/core/extract/orm/information-schema.d.ts.map +0 -1
  501. package/dist/core/extract/orm/information-schema.js +0 -142
  502. package/dist/core/extract/orm/information-schema.js.map +0 -1
  503. package/dist/core/extract/orm/prisma.d.ts +0 -23
  504. package/dist/core/extract/orm/prisma.d.ts.map +0 -1
  505. package/dist/core/extract/orm/prisma.js +0 -234
  506. package/dist/core/extract/orm/prisma.js.map +0 -1
  507. package/dist/core/extract/orm/typeorm.d.ts +0 -22
  508. package/dist/core/extract/orm/typeorm.d.ts.map +0 -1
  509. package/dist/core/extract/orm/typeorm.js +0 -269
  510. package/dist/core/extract/orm/typeorm.js.map +0 -1
  511. package/dist/core/extract/orm/types.d.ts +0 -97
  512. package/dist/core/extract/orm/types.d.ts.map +0 -1
  513. package/dist/core/extract/orm/types.js +0 -6
  514. package/dist/core/extract/orm/types.js.map +0 -1
  515. package/dist/core/extract/prompt.d.ts +0 -21
  516. package/dist/core/extract/prompt.d.ts.map +0 -1
  517. package/dist/core/extract/prompt.js +0 -79
  518. package/dist/core/extract/prompt.js.map +0 -1
  519. package/dist/core/extract/provider.d.ts +0 -121
  520. package/dist/core/extract/provider.d.ts.map +0 -1
  521. package/dist/core/extract/provider.js +0 -6
  522. package/dist/core/extract/provider.js.map +0 -1
  523. package/dist/core/extract/providers/node-ts.d.ts +0 -69
  524. package/dist/core/extract/providers/node-ts.d.ts.map +0 -1
  525. package/dist/core/extract/providers/node-ts.js +0 -320
  526. package/dist/core/extract/providers/node-ts.js.map +0 -1
  527. package/dist/core/extract/render/schema-md.d.ts +0 -16
  528. package/dist/core/extract/render/schema-md.d.ts.map +0 -1
  529. package/dist/core/extract/render/schema-md.js +0 -140
  530. package/dist/core/extract/render/schema-md.js.map +0 -1
  531. package/dist/core/extract/report.d.ts +0 -125
  532. package/dist/core/extract/report.d.ts.map +0 -1
  533. package/dist/core/extract/report.js +0 -52
  534. package/dist/core/extract/report.js.map +0 -1
  535. package/dist/core/extract/schema.d.ts +0 -34
  536. package/dist/core/extract/schema.d.ts.map +0 -1
  537. package/dist/core/extract/schema.js +0 -146
  538. package/dist/core/extract/schema.js.map +0 -1
  539. package/dist/core/extract/workspaces.d.ts +0 -33
  540. package/dist/core/extract/workspaces.d.ts.map +0 -1
  541. package/dist/core/extract/workspaces.js +0 -193
  542. package/dist/core/extract/workspaces.js.map +0 -1
  543. package/dist/core/providers/index.d.ts +0 -6
  544. package/dist/core/providers/index.d.ts.map +0 -1
  545. package/dist/core/providers/index.js +0 -2
  546. package/dist/core/providers/index.js.map +0 -1
  547. package/dist/core/providers/tracker.d.ts +0 -74
  548. package/dist/core/providers/tracker.d.ts.map +0 -1
  549. package/dist/core/providers/tracker.js +0 -38
  550. package/dist/core/providers/tracker.js.map +0 -1
  551. package/dist/core/scope/calibration.d.ts +0 -25
  552. package/dist/core/scope/calibration.d.ts.map +0 -1
  553. package/dist/core/scope/calibration.js +0 -52
  554. package/dist/core/scope/calibration.js.map +0 -1
  555. package/dist/core/scope/closure.d.ts +0 -31
  556. package/dist/core/scope/closure.d.ts.map +0 -1
  557. package/dist/core/scope/closure.js +0 -68
  558. package/dist/core/scope/closure.js.map +0 -1
  559. package/dist/core/scope/gate.d.ts +0 -41
  560. package/dist/core/scope/gate.d.ts.map +0 -1
  561. package/dist/core/scope/gate.js +0 -165
  562. package/dist/core/scope/gate.js.map +0 -1
  563. package/dist/core/scope/index.d.ts +0 -18
  564. package/dist/core/scope/index.d.ts.map +0 -1
  565. package/dist/core/scope/index.js +0 -12
  566. package/dist/core/scope/index.js.map +0 -1
  567. package/dist/core/scope/partition.d.ts +0 -36
  568. package/dist/core/scope/partition.d.ts.map +0 -1
  569. package/dist/core/scope/partition.js +0 -78
  570. package/dist/core/scope/partition.js.map +0 -1
  571. package/dist/core/scope/prompt.d.ts +0 -39
  572. package/dist/core/scope/prompt.d.ts.map +0 -1
  573. package/dist/core/scope/prompt.js +0 -123
  574. package/dist/core/scope/prompt.js.map +0 -1
  575. package/dist/core/scope/scoping.d.ts +0 -52
  576. package/dist/core/scope/scoping.d.ts.map +0 -1
  577. package/dist/core/scope/scoping.js +0 -99
  578. package/dist/core/scope/scoping.js.map +0 -1
  579. package/dist/core/scope/types.d.ts +0 -77
  580. package/dist/core/scope/types.d.ts.map +0 -1
  581. package/dist/core/scope/types.js +0 -5
  582. package/dist/core/scope/types.js.map +0 -1
  583. package/dist/core/scope/validate.d.ts +0 -47
  584. package/dist/core/scope/validate.d.ts.map +0 -1
  585. package/dist/core/scope/validate.js +0 -90
  586. package/dist/core/scope/validate.js.map +0 -1
  587. package/dist/core/verify/asyncapi-diff.d.ts +0 -34
  588. package/dist/core/verify/asyncapi-diff.d.ts.map +0 -1
  589. package/dist/core/verify/asyncapi-diff.js +0 -209
  590. package/dist/core/verify/asyncapi-diff.js.map +0 -1
  591. package/dist/core/verify/contract-diff.d.ts +0 -39
  592. package/dist/core/verify/contract-diff.d.ts.map +0 -1
  593. package/dist/core/verify/contract-diff.js +0 -63
  594. package/dist/core/verify/contract-diff.js.map +0 -1
  595. package/dist/core/verify/drift.d.ts +0 -47
  596. package/dist/core/verify/drift.d.ts.map +0 -1
  597. package/dist/core/verify/drift.js +0 -122
  598. package/dist/core/verify/drift.js.map +0 -1
  599. package/dist/core/verify/impact.d.ts +0 -22
  600. package/dist/core/verify/impact.d.ts.map +0 -1
  601. package/dist/core/verify/impact.js +0 -93
  602. package/dist/core/verify/impact.js.map +0 -1
  603. package/dist/core/verify/index.d.ts +0 -10
  604. package/dist/core/verify/index.d.ts.map +0 -1
  605. package/dist/core/verify/index.js +0 -9
  606. package/dist/core/verify/index.js.map +0 -1
  607. package/dist/core/verify/openapi-diff.d.ts +0 -29
  608. package/dist/core/verify/openapi-diff.d.ts.map +0 -1
  609. package/dist/core/verify/openapi-diff.js +0 -291
  610. package/dist/core/verify/openapi-diff.js.map +0 -1
  611. package/dist/core/verify/types.d.ts +0 -138
  612. package/dist/core/verify/types.d.ts.map +0 -1
  613. package/dist/core/verify/types.js +0 -5
  614. package/dist/core/verify/types.js.map +0 -1
  615. package/schemas/component.schema.json +0 -203
  616. package/schemas/flow.schema.json +0 -75
  617. package/schemas/scope-output.schema.json +0 -62
@@ -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
+ Export the bank once per session so every subsequent command inherits it:
261
+
262
+ ```bash
263
+ export MEMO_BANK=developer-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 $MEMO_BANK`; 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 $MEMO_BANK \
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 $MEMO_BANK --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 $MEMO_BANK --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 `$MEMO_BANK` is unset** (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 $MEMO_BANK --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 $MEMO_BANK [--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 $MEMO_BANK [--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 $MEMO_BANK [--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,37 @@ 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, or export `MEMO_BANK` for the session so every command picks it up by default:
25
+
26
+ ```bash
27
+ export MEMO_BANK=developer-memory # bank id convention: <agent-name>-memory
28
+ ```
29
+
30
+ Every entry has a **kind**:
31
+
32
+ | Kind | Meaning | Default bank behavior |
33
+ | ---------- | ----------------------------------------------------------------- | -------------------------------------------------------- |
34
+ | `self` | The agent's own persona/context, never trimmed from `recall` | `kb` rejects `self`; only valid in private banks |
35
+ | `episodic` | Session-scoped narration (intent/outcome), expires automatically | requires `--session <id>`; default kind in private banks |
36
+ | `semantic` | Durable, searchable decisions — what `search`/`list` return today | default kind in `kb` |
37
+
38
+ 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`.
39
+
40
+ ---
41
+
22
42
  ## Session Start — Restore Context
23
43
 
24
- Run before writing any code:
44
+ **memo-cli 1.3.0+:** one call restores the full context bundle (SELF, POLICIES, SHARED, MINE, LAST SESSION, CONFLICTS):
45
+
46
+ ```bash
47
+ memo recall "<current task description>" --bank $MEMO_BANK --json
48
+ ```
49
+
50
+ If `$MEMO_BANK` is unset, `recall` resolves to `kb` and omits the private-only sections (`SELF`, `MINE`, `LAST SESSION`).
51
+
52
+ **Fallback (`memo --version` < 1.3.0, or `memo recall` unavailable):** run the four-command sequence instead:
25
53
 
26
54
  ```bash
27
55
  memo list --limit 20 --json
@@ -30,7 +58,7 @@ memo search "<current task description>" --limit 10 --json
30
58
  memo search "<key contract or dependency>" --scope related --limit 5 --json
31
59
  ```
32
60
 
33
- Synthesize findings into:
61
+ Synthesize findings (either path) into:
34
62
 
35
63
  - Constraints to preserve
36
64
  - Rejected alternatives to avoid
@@ -41,10 +69,13 @@ Synthesize findings into:
41
69
 
42
70
  ## Writing Entries
43
71
 
44
- ### Intent Entry (before starting a story/task)
72
+ ### Intent Entry (before starting a story/task) — episodic, in your bank
45
73
 
46
74
  ```bash
47
75
  memo write \
76
+ --kind episodic \
77
+ --session ISSUE-<number> \
78
+ --bank $MEMO_BANK \
48
79
  --rationale "Context: Starting ISSUE-<##> because <trigger>. Decision: implement via <approach>, preserving <constraints>. Impact: affects <modules/contracts>." \
49
80
  --tags "<domain>,issue-<number>,intent,<impact-tag>" \
50
81
  --entry-type decision \
@@ -54,10 +85,13 @@ memo write \
54
85
  --json
55
86
  ```
56
87
 
57
- ### Outcome Entry (after completing a story/task)
88
+ ### Outcome Entry (after completing a story/task) — episodic, in your bank
58
89
 
59
90
  ```bash
60
91
  memo write \
92
+ --kind episodic \
93
+ --session ISSUE-<number> \
94
+ --bank $MEMO_BANK \
61
95
  --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
96
  --tags "<domain>,issue-<number>,outcome,gates-pass" \
63
97
  --entry-type decision \
@@ -69,17 +103,24 @@ memo write \
69
103
  --json
70
104
  ```
71
105
 
72
- ### Decision Entry (architectural choices)
106
+ `--session` is required whenever `--kind episodic` is used; `--seq` auto-increments per session and rarely needs to be passed explicitly.
107
+
108
+ ### Decision/ADR Entry (architectural choices) — semantic, in `kb`
73
109
 
74
110
  ```bash
75
111
  memo write \
112
+ --kind semantic \
113
+ --bank kb \
76
114
  --rationale "Context: <situation>. Decision: <what was chosen>. Rationale: <why this over alternatives>." \
77
115
  --tags "<domain>,<technology>,decision" \
78
116
  --entry-type decision \
79
117
  --source agent \
118
+ --provenance "<csv of episodic entry ids this consolidates, if any>" \
80
119
  --json
81
120
  ```
82
121
 
122
+ 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.
123
+
83
124
  ---
84
125
 
85
126
  ## Entry Types
@@ -129,16 +170,28 @@ memo write \
129
170
 
130
171
  ---
131
172
 
173
+ ## Session Close
174
+
175
+ No memo action in Phase 2. `memo used` and `memo decay` arrive with memo-cli 1.4.0.
176
+
177
+ ---
178
+
132
179
  ## Quick Command Card
133
180
 
134
181
  ```
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
182
+ memo setup validate # Verify config
183
+ memo recall "<task>" --bank $MEMO_BANK --json # Restore full context (1.3.0+)
184
+ memo write --rationale "..." --tags "a,b,c" --json # Record a semantic decision (kb)
185
+ memo write --kind episodic --session ID --bank $MEMO_BANK # Record an intent/outcome entry
186
+ memo search "query" [--scope related] --json # Semantic search
187
+ memo list [--limit N] --json # Browse recent
188
+ memo timeline [--session ID] --bank $MEMO_BANK --json # Replay episodic memory in order
189
+ memo tags list [--sort frequency] --json # Discover tags
190
+ memo inspect --json # Global facets
191
+ memo bank list --json # List all banks
192
+ memo bank init --id <id> --json # Create a bank
193
+ memo migrate --to-v2 --dry-run --json # Preview legacy payload migration
194
+ memo delete --id <uuid> --json # Delete entry
142
195
  ```
143
196
 
144
- > For full flag documentation, admin operations, environment setup, and detailed examples, read [`REFERENCE.md`](./REFERENCE.md).
197
+ > For full flag documentation, admin operations, environment setup, banks/kinds, `recall`, `timeline`, `bank`, `migrate`, and detailed examples, read [`REFERENCE.md`](./REFERENCE.md).
@@ -0,0 +1,109 @@
1
+ ---
2
+ name: supabase-ops
3
+ description: "Supabase CLI command sets, db diff migration flow, drift rule, backup/revert sources, inventory findings, and Cloud log table for infra-engineer. Use when planning or applying Supabase infrastructure changes."
4
+ ---
5
+
6
+ # Supabase Operations (supabase-ops)
7
+
8
+ Per-surface mechanism skill for `infra-engineer`. It supplies the Supabase CLI command sets, resource tiers, the `db diff` migration flow, the drift rule, backup and revert sources, inventory findings, and the Supabase Cloud log table. It does not restate the agent's working loop, approval, revert, or backup rules — those live in the agent body. Supabase is the one platform with a genuine plan mechanism (`db diff`), and its keys are the highest-value secrets in the stack.
9
+
10
+ ---
11
+
12
+ > **RFC 2119 Notice:** The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**, **SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).
13
+
14
+ ## Tool declaration
15
+
16
+ | Field | Value |
17
+ | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
18
+ | `name` | `supabase` |
19
+ | `probe` | `supabase --version` (expects `2.x`) |
20
+ | `floor` | Supabase CLI `2.x`; minimum `2.11`. A `1.x` install is `below-floor`. |
21
+ | `auth_probe` | `supabase projects list` |
22
+ | `remediation` | "Install Supabase CLI v2 and run `supabase login` (or export `SUPABASE_ACCESS_TOKEN`); link the project with `supabase link --project-ref <ref>`. This skill never auto-installs and offers no fallback." |
23
+
24
+ Identity is asserted by comparing the linked project ref (from `supabase projects list` / the linked `project_ref`) with the target environment's `supabase.project_ref`; a mismatch is `wrong-identity` and blocks.
25
+
26
+ ## Resource tiers
27
+
28
+ | Tier | Supabase resources |
29
+ | --------------- | ------------------------------------------------------------------------------------- |
30
+ | **foundation** | project, plan, compute add-on, read replicas, PITR |
31
+ | **application** | schema, migrations, RLS policies, roles, storage buckets, auth config, Edge Functions |
32
+ | **ephemeral** | preview branches, which carry an `ExpiresAt` tag and a cleanup step |
33
+
34
+ Foundation changes are routed to `tier0_tool`, never written by this agent. Project deletion is refused for a production-mapped project.
35
+
36
+ ## Migration flow (db diff as plan)
37
+
38
+ 1. `supabase db diff -f "$NAME"` produces the migration SQL — this **is** the plan. Do not push before it is reviewed.
39
+ 2. **Destructive statements** (`DROP`, `TRUNCATE`, `ALTER ... DROP COLUMN`, type narrowing) are itemized separately in `plan.md`, each as its own line requiring named approval.
40
+ 3. Confirmation is required before `supabase db push` to any shared or production project. The push runs only after the human approves that step.
41
+ 4. Verification: `supabase migration list` shows the new migration applied on the remote.
42
+ 5. **Drift rule:** a non-empty `supabase db diff` against the remote with **no pending local migration** is reported as drift and **never pushed**. Drift is reported, never reconciled by pushing. The agent records the drift in `result.md` and stops.
43
+
44
+ ```sh
45
+ supabase db diff -f add_orders_table # plan
46
+ # review the generated migration; itemize destructive statements
47
+ supabase db push # apply, only after confirmation
48
+ supabase migration list # verify
49
+ ```
50
+
51
+ ## Backup
52
+
53
+ Before any production step touching schema or data, record a backup: `supabase db dump -f backup.sql --data-only` (and a schema dump) **or** a recorded PITR restore point when PITR is enabled on the project. The backup artifact reference and the restore command are recorded in `result.md` before the step applies. Revert of a schema change is a forward migration that reverses it, applied through the same confirmed flow; there is no silent `db reset` against a shared project.
54
+
55
+ ## Discovery order
56
+
57
+ Discovery prefers **Supabase MCP read-only** when present, then the **CLI**, then the **Management API**, and records which path was used in the inventory `_generated` block. Writes never go through MCP — MCP is read-only for discovery only. No MCP write, ever.
58
+
59
+ ## Inventory and findings
60
+
61
+ Inventory files under `infra/inventory/supabase/<ref>.json` carry the standard `_generated` header and these fields:
62
+
63
+ - `has_legacy_keys: bool` — reported as a finding when legacy (pre-publishable/secret) keys are still in use.
64
+ - `rls_disabled_tables: []` — tables with row-level security disabled, reported as findings.
65
+
66
+ Inventory contains **no key material**, masked or otherwise. Reporting `has_legacy_keys` or `rls_disabled_tables` never includes the key or a sample row.
67
+
68
+ ## Secrets
69
+
70
+ - Edge Function secrets are set with `supabase secrets set KEY=value` / `supabase secrets unset KEY`, from the source of truth, never a transcript.
71
+ - **Publishable versus secret keys** are distinguished at every reference: a `sb_publishable_*` key is client-safe; a `sb_secret_*` key and the `service_role` JWT are server-only and never leave a secret store.
72
+ - No AWS Secrets Manager entry for a Supabase-only workload; Supabase secrets stay on Supabase.
73
+
74
+ ## Supabase Cloud log table
75
+
76
+ Retrieval, retention, and query bounds are grounded in `workstream/research-supabase-logs.md` (researcher pass, 2025-09-12). Key facts cited from that artifact:
77
+
78
+ - **The Supabase CLI has no log command on Cloud.** The scriptable path is the Management API logs endpoint `GET /v1/projects/{ref}/analytics/endpoints/logs`, which runs a ClickHouse-dialect SQL/LQL query over a unified logs stream filtered by a `source` column; the Dashboard Logs Explorer is the interactive equivalent. `supabase inspect db ...` is Postgres diagnostics, not service logs.
79
+ - **Time bounds are mandatory in practice:** the endpoint uses `iso_timestamp_start` / `iso_timestamp_end`, the window MUST be ≤ 24 hours, and an omitted range queries only the last minute — so every triage query states an explicit UTC window before it runs.
80
+
81
+ | Service surface | Source selector / collection | Retrieval path |
82
+ | --------------- | ------------------------------------------------------------- | --------------------------------------- |
83
+ | Postgres | `source = postgres_logs` | Management API logs endpoint; Dashboard |
84
+ | API (PostgREST) | API Gateway collection | Management API logs endpoint; Dashboard |
85
+ | Auth (GoTrue) | Auth collection | Management API logs endpoint; Dashboard |
86
+ | Storage | Storage collection | Management API logs endpoint; Dashboard |
87
+ | Realtime | Realtime collection | Management API logs endpoint; Dashboard |
88
+ | Edge Functions | `source = edge_logs` / `function_edge_logs` / `function_logs` | Management API logs endpoint; Dashboard |
89
+
90
+ **Retention caveat (cite the research artifact, re-confirm at citation time):** built-in log retention is short and plan-gated — Free ≈ 1 day, Pro ≈ 7 days, Team ≈ 28 days, Enterprise ≈ 90 days. Because low-tier retention is short, logs MUST be captured at incident time; Log Drains (Team/Enterprise) is the long-retention path. Exact `source` strings for API/Auth/Storage/Realtime are UNCONFIRMED in the research and must be verified from the Logs Explorer source list before hardcoding. All log output passes through the redaction pattern set before it reaches a transcript or file.
91
+
92
+ ## Cost entries and sweep
93
+
94
+ Cost entries listed on every Supabase plan:
95
+
96
+ - **Plan** tier (Free/Pro/Team/Enterprise) base.
97
+ - **Compute** add-on size.
98
+ - **Read replicas**.
99
+ - **PITR** add-on.
100
+ - **Preview branches**.
101
+ - **Egress**.
102
+
103
+ Sweep categories (read-only, reported never remediated):
104
+
105
+ - Preview branches past their `ExpiresAt` tag.
106
+ - Preview branches without any `ExpiresAt` tag.
107
+ - Paid but idle projects.
108
+ - Read replicas with no traffic.
109
+ - PITR enabled on a non-production project.
@@ -33,26 +33,71 @@ This activity assumes:
33
33
 
34
34
  ---
35
35
 
36
+ ## Package Scope in Commits
37
+
38
+ In a monorepo the package is the Conventional Commits **scope** (FR-63):
39
+
40
+ ```
41
+ feat(api): add token-refresh endpoint
42
+ fix(web): stop double-submitting the checkout form
43
+ ```
44
+
45
+ - Take the scope from the package map in `docs/tech.md`. Use the short,
46
+ readable form of the package name, not the full specifier: `@acme/api`
47
+ becomes `api`.
48
+ - A package name that is not a valid scope — one containing a space, a
49
+ slash after stripping the org prefix, or an uppercase letter — is
50
+ reduced to a lowercase, hyphenated form and the mapping is recorded in
51
+ the package map's row so every commit uses the same one. Never invent
52
+ a different short form per commit.
53
+ - A commit spanning packages uses the broadest honest scope, or none. A
54
+ scope that names one package for a change touching four is worse than
55
+ no scope.
56
+ - In a **single-package repository the scope is optional**. Omit it —
57
+ `feat: add the endpoint` — rather than writing an empty scope `feat():`,
58
+ which is not valid Conventional Commits and which the commit hook
59
+ rejects.
60
+
61
+ ## Platform-Write Routing
62
+
63
+ - You **MUST NOT** emit or execute a platform write command (`aws`, `flyctl`, `supabase`, or Cloudflare API writes) while executing a task list.
64
+ - 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**.
65
+ - 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.
66
+
67
+ ---
68
+
36
69
  ## Before Starting Work
37
70
 
38
71
  1. You **MUST** confirm the GitHub Issue is open.
39
- 2. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
72
+ 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.
73
+ 3. **Branch gate (hard requirement):** You **MUST** verify you are on a feature branch before any implementation work:
40
74
  - Run `git rev-parse --abbrev-ref HEAD` to determine the current branch.
41
75
  - 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.
42
76
  - 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.
43
- - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 3.
77
+ - If HEAD is already a valid feature branch (matching `issue/*` or `story/*`), proceed to step 4.
44
78
  - Branch format: `issue/<issue-number>-<short-description>` or `story/<id>-<short-description>`
45
- 3. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
79
+ 4. You **MUST** open a **draft Pull Request** by delegating to `github-ops` whenever possible.
46
80
  - 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.
47
81
  - Base branch is the default branch unless an orchestrating caller explicitly provides a base-branch override.
48
82
  - PR title **MUST** follow Conventional Commits (e.g., `feat: implement issue 37`).
49
83
  - PR description **MUST** include `Closes #<issue-number>`.
50
- 4. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
84
+ 5. You **MUST** ensure the task list in the GitHub Issue matches the local `/workstream/tasks-*.md` file.
51
85
 
52
86
  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.
53
87
 
54
88
  ---
55
89
 
90
+ ## Decision-Log Citation
91
+
92
+ When `workstream/decisions-<feature>.md` exists and was read per step 2 above:
93
+
94
+ - 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).
95
+ - The PR body **MUST** reference every consumed decision ID it draws on, in its Completion Report area, alongside the existing `Closes #<issue-number>` line.
96
+ - 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.
97
+ - 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.
98
+
99
+ ---
100
+
56
101
  ## During Implementation
57
102
 
58
103
  ### Step-by-Step Execution