@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
@@ -0,0 +1,116 @@
1
+ # Deploy Operations (deploy-ops)
2
+
3
+ Cross-surface mechanism skill for `infra-engineer`. It supplies the deploy **script contract**, the environment mapping table, the tag policy summary, the deploy-target framing, and the workflow scaffolding procedure. It does not restate the agent's working loop, approval, revert, or backup rules — those live in the agent body — and it contains no deploy logic itself: the logic lives in the `templates/scripts/*.sh` files, which this skill only documents and wires. The skill declares the tools `yq` and `gh`.
4
+
5
+ ---
6
+
7
+ > **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).
8
+
9
+ ## Tool declaration
10
+
11
+ | Field | Value |
12
+ | ------------- | ------------------------------------------------------------------------------------------------------------------------- |
13
+ | `name` | `yq`, `gh` |
14
+ | `probe` | `yq --version`; `gh --version` |
15
+ | `floor` | `yq` 4.x (the mikefarah Go implementation); minimum `4.0`. A 3.x or Python `yq` is `below-floor`. `gh` any current 2.x. |
16
+ | `auth_probe` | `gh auth status` (for release/PR operations); `yq` needs no auth. |
17
+ | `remediation` | "Install `yq` 4.x from mikefarah/yq and `gh` from cli.github.com; this skill never auto-installs and offers no fallback." |
18
+
19
+ `yq` reads and resolves `infra/environments.yaml`; `gh` performs release and PR operations for the release flow. Every command references secrets by name, never by value, and every log or status query passes through the redaction pattern set before it reaches a transcript.
20
+
21
+ ## Script contract
22
+
23
+ The deploy surface is a fixed set of `bash` scripts under `templates/scripts/`. Each is `set -euo pipefail`, supports `--help`, reads the environment definition from `infra/environments.yaml` via `yq`, and contains no environment names or secrets of its own.
24
+
25
+ | Script | Purpose | Mutates? | `--dry-run` | Exit codes |
26
+ | ------------------ | ------------------------------------------------------------ | -------- | ----------- | ------------------------------------------ |
27
+ | `deploy.sh` | Ordered deploy pipeline for one environment | yes | yes | 0 ok · 1 error · 2 blocked · 3 verify-fail |
28
+ | `deploy-verify.sh` | Post-deploy health check; prints the rollback line on fail | no | no | 0 healthy · 2 blocked · 3 fail |
29
+ | `rollback.sh` | Roll back to the previous good version from `infra/changes/` | yes | yes | 0 ok · 1 error · 2 blocked |
30
+ | `deploy-status.sh` | Read-only current status of an environment | no | n/a | 0 ok · 2 blocked |
31
+ | `release.sh` | Generalized changelog/version/tag/push release automation | yes | yes | 0 ok · 1 error · 2 blocked |
32
+
33
+ ### `deploy.sh` ordered steps
34
+
35
+ `deploy.sh <env>` runs eight ordered steps and exits `2` on any blocked condition:
36
+
37
+ 1. **preflight** — clean tree, ref rules, identity assertion.
38
+ 2. **validate** — the project quality gate; **never** skippable by any flag.
39
+ 3. **build** — artifact tagged `vX.Y.Z` (production) or `main-<short-sha>` (non-production).
40
+ 4. **backup** — taken when the environment is production **and** the change migrates; **never** skipped for production.
41
+ 5. **migrate** — with explicit confirmation for production.
42
+ 6. **deploy** — via the detected deploy kind.
43
+ 7. **verify** — delegates to `deploy-verify.sh`.
44
+ 8. **record** — appends a change record under `infra/changes/`.
45
+
46
+ No `latest` mutable tag is ever a deploy target. The deploy kind is detected from the platform blocks present in the environment; `deploy.sh` refuses (`exit 2`) when the detection is ambiguous (more than one platform block and no explicit `deploy_kind`), per spec open question 3.
47
+
48
+ ### Failure and rollback
49
+
50
+ `deploy-verify.sh` exits `3` on a failed health check and prints the exact `rollback.sh <env>` invocation to run next. `rollback.sh <env>` resolves the previous good version from `infra/changes/` with no manual lookup; `--to <version>` overrides the resolved version.
51
+
52
+ ## Environment mapping table
53
+
54
+ Environment names and platform blocks are read from `infra/environments.yaml` via `yq`. A missing or template-status (`# status: template`) file exits `2`.
55
+
56
+ | Trigger / ref | Environment | Rule |
57
+ | ---------------------------- | ----------- | ----------------------------------------------------------------------------- |
58
+ | push to `main` | `dev` | non-production deploys `main` HEAD; artifact tagged `main-<short-sha>` |
59
+ | annotated tag `vX.Y.Z` | `prod` | production refuses any ref that is not an annotated tag on `main` |
60
+ | manual (`workflow_dispatch`) | any | dev is optional; installed only when a `production: false` environment exists |
61
+
62
+ ## Tag policy summary
63
+
64
+ Tags are human-only and owned by the policy in `github-ops`: annotated `vX.Y.Z`, created on `main` only, immutable, no prerelease in v1. `deploy-ops` never creates, moves, or deletes a tag — `git-guard` rule 4 blocks agent tag operations deterministically. `release.sh` suggests the bump type from Conventional Commits and confirms it; production deploys consume the resulting annotated tag.
65
+
66
+ ## Deploy-target framing
67
+
68
+ `deploy-ops` does not choose the platform for a consumer. It frames the decision so the operator (or `infra-engineer`) picks a **deploy target** deliberately, then records the choice in `infra/environments.yaml`.
69
+
70
+ | Decision input | Question the operator answers |
71
+ | ---------------- | -------------------------------------------------------------------- |
72
+ | compute platform | fly.io app, AWS ECS service, or another target? |
73
+ | data platform | is there a Supabase (or other) migration step to sequence? |
74
+ | environment tier | is this environment `production: true` or `false`? |
75
+ | ref discipline | does production consume an annotated tag, and does dev track `main`? |
76
+ | rollback source | is the previous good version recorded in `infra/changes/`? |
77
+
78
+ When two platform blocks are present with no explicit `deploy_kind`, the deploy target is ambiguous and `deploy.sh` refuses until the operator sets `deploy_kind`.
79
+
80
+ ## Workflow scaffolding procedure
81
+
82
+ `deploy-ops` scaffolds the GitHub Actions workflow templates (`templates/workflows/`) into a consumer repo as recorded changes delivered by a draft PR — never applied silently.
83
+
84
+ 1. Read `infra/environments.yaml`.
85
+ 2. Install `deploy-dev.yml` **only when** an environment with `production: false` is declared.
86
+ 3. Install `deploy-prod.yml` (triggered on the exact-semver tag, behind a required reviewer) and `rollback.yml` (`workflow_dispatch`) when a `production: true` environment exists.
87
+ 4. Every workflow calls the canonical scripts only — no inline deploy logic.
88
+ 5. Workflow edits are recorded changes; they are delivered by PR and reviewed by a human.
89
+
90
+ ## `package.json` wrappers for JS/TS repos
91
+
92
+ For JavaScript/TypeScript repos only, `deploy-ops` generates thin `package.json` script wrappers so the deploy surface is reachable through the project's canonical script runner. The shell scripts remain the implementation; the wrappers are one-line delegations:
93
+
94
+ ```jsonc
95
+ {
96
+ "scripts": {
97
+ "deploy": "bash templates/scripts/deploy.sh",
98
+ "deploy:verify": "bash templates/scripts/deploy-verify.sh",
99
+ "deploy:rollback": "bash templates/scripts/rollback.sh",
100
+ "deploy:status": "bash templates/scripts/deploy-status.sh",
101
+ "release": "bash templates/scripts/release.sh",
102
+ },
103
+ }
104
+ ```
105
+
106
+ Non-JS/TS repos call the scripts directly; no wrapper is generated.
107
+
108
+ ## Human-only guard
109
+
110
+ `release.sh` and `deploy.sh prod` refuse to run when `CI` is set without `INFRA_HUMAN_APPROVED=1` exported by the protected-environment job, and refuse in a non-interactive agent context. This keeps release and production deploy decisions with a human even when the scripts run inside automation.
111
+
112
+ ## Boundary rules
113
+
114
+ - No deploy logic lives in this skill or in a workflow; it lives only in `templates/scripts/*.sh`.
115
+ - No deploy targets a mutable `latest` tag.
116
+ - The agent never creates tags; tags are human-only per `github-ops`.
@@ -0,0 +1,133 @@
1
+ # Fly.io Operations (fly-ops)
2
+
3
+ Per-surface mechanism skill for `infra-engineer`. It supplies the `flyctl` command sets, resource tiers, cost inputs, backup and revert sources, and the fly.io log table. It does not restate the agent's working loop, approval, revert, or backup rules — those live in the agent body. fly.io has release history (`fly releases`) that makes revert concrete and volume snapshots that make backup concrete, so it is the cheapest surface for the manual Phase 1 verification.
4
+
5
+ ---
6
+
7
+ > **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).
8
+
9
+ ## Tool declaration
10
+
11
+ | Field | Value |
12
+ | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
13
+ | `name` | `flyctl` |
14
+ | `probe` | `flyctl version` |
15
+ | `floor` | Current major release channel; minimum `0.3`. An older channel is `below-floor`. |
16
+ | `auth_probe` | `flyctl auth whoami` |
17
+ | `remediation` | "Install `flyctl` from fly.io and run `flyctl auth login` (or export `FLY_API_TOKEN`); this skill never auto-installs and offers no fallback." |
18
+
19
+ Use `--json` wherever `flyctl` supports it. Identity is asserted by comparing the authenticated org (from `flyctl auth whoami` / `flyctl orgs list --json`) with the target environment's `fly.org`; a mismatch is `wrong-identity` and blocks.
20
+
21
+ ## Resource tiers
22
+
23
+ | Tier | Fly resources |
24
+ | --------------- | ----------------------------------------------------------------- |
25
+ | **foundation** | org |
26
+ | **application** | app, machine, volume, secret, certificate |
27
+ | **ephemeral** | throwaway apps, which carry an `ExpiresAt` tag and a cleanup step |
28
+
29
+ An ephemeral app without an `ExpiresAt` is a finding. Foundation (org) changes are routed, never written by this agent.
30
+
31
+ ## Command sets per change kind
32
+
33
+ Every command references secrets by name, never by value.
34
+
35
+ ### Discover (read-only)
36
+
37
+ ```sh
38
+ flyctl auth whoami
39
+ flyctl apps list --json
40
+ flyctl status -a "$APP" --json
41
+ flyctl machine list -a "$APP" --json
42
+ flyctl volumes list -a "$APP" --json
43
+ flyctl secrets list -a "$APP"
44
+ flyctl certs list -a "$APP"
45
+ flyctl releases -a "$APP" --json
46
+ ```
47
+
48
+ ### Create app
49
+
50
+ - Forward: `fly apps create "$APP" --org "$ORG"`
51
+ - Verify: `flyctl status -a "$APP" --json`
52
+ - Revert: `fly apps destroy "$APP" --yes` (requires the typed app name and environment name per the agent body).
53
+
54
+ ### Deploy
55
+
56
+ - Forward: `fly deploy -a "$APP" --image "$IMAGE"` or a build then deploy:
57
+ ```sh
58
+ fly deploy -a "$APP" --build-only --push --image-label "$TAG"
59
+ fly deploy -a "$APP" --image "registry.fly.io/$APP:$TAG"
60
+ ```
61
+ - Verify: `flyctl status -a "$APP" --json` shows the new release healthy.
62
+ - Revert: `fly deploy -a "$APP" --image <previous>` using the previous image from `fly releases`.
63
+
64
+ ### Secrets
65
+
66
+ - Forward: `fly secrets set KEY=value -a "$APP"` (value from its source of truth, never a transcript) / `fly secrets unset KEY -a "$APP"`.
67
+ - Revert: re-set the prior value from its source of truth; **never** reconstruct a secret from a transcript or log.
68
+
69
+ ### Volumes
70
+
71
+ - Forward: `fly volumes create "$NAME" -a "$APP" --region "$REGION" --size "$GB"`.
72
+ - Backup: `fly volumes snapshots create "$VOL_ID"` before any production step touching a volume.
73
+ - Revert: restore from the recorded snapshot; `fly volumes destroy "$VOL_ID"` only after the typed confirmation.
74
+
75
+ ### Certificates
76
+
77
+ - Forward: `fly certs add "$FQDN" -a "$APP"`; then `fly certs check "$FQDN" -a "$APP"`.
78
+ - Revert: `fly certs remove "$FQDN" -a "$APP" --yes`.
79
+
80
+ ### Scale and machines
81
+
82
+ ```sh
83
+ fly scale count "$N" -a "$APP"
84
+ fly scale vm "$SIZE" -a "$APP"
85
+ fly machine status "$MACHINE" -a "$APP" --json
86
+ ```
87
+
88
+ Revert for a scale change is the prior count/size recorded before the step.
89
+
90
+ ### Destroy
91
+
92
+ `fly apps destroy "$APP" --yes` requires the operator to type both the app name and the environment name. A production foundation target is refused.
93
+
94
+ ## Revert sources
95
+
96
+ - **Deploy:** `fly releases -a "$APP" --json` supplies the previous image; revert is `fly deploy --image <previous>`.
97
+ - **Secret:** re-set the prior value from its source of truth.
98
+ - **Volume:** the snapshot recorded as backup.
99
+ - **Scale/cert:** the prior value/record captured before the step.
100
+
101
+ ## Backup
102
+
103
+ `fly volumes snapshots create "$VOL_ID"` runs before any production step that touches a volume; the snapshot id and the restore command are recorded in `result.md` before the step applies.
104
+
105
+ ## Fly log table
106
+
107
+ Every query is time-bounded and its output passes through the redaction pattern set before it reaches a transcript or file.
108
+
109
+ | Source | Command |
110
+ | --------------- | ----------------------------------------- |
111
+ | App logs | `fly logs -a "$APP" --since "$START"` |
112
+ | App status | `fly status -a "$APP" --json` |
113
+ | Machine status | `fly machine status "$MACHINE" -a "$APP"` |
114
+ | Release history | `fly releases -a "$APP" --json` |
115
+
116
+ ## Cost entries and sweep
117
+
118
+ Cost entries listed on every fly plan:
119
+
120
+ - **Machines** by size (shared/performance vCPU + memory).
121
+ - **Volumes** by GB.
122
+ - **Dedicated IPv4** addresses.
123
+
124
+ Sweep categories (read-only, reported never remediated):
125
+
126
+ - Stopped machines still holding volumes.
127
+ - Unattached volumes.
128
+ - Apps past their `ExpiresAt` tag.
129
+
130
+ ## Boundary rules
131
+
132
+ - No AWS Secrets Manager entry for a fly-only workload; fly secrets stay on fly.
133
+ - `fly apps destroy` requires the typed app name and environment name.
@@ -34,7 +34,7 @@ git checkout -b <branch-name>
34
34
 
35
35
  - Story branches: `story/<story-id>-<short-description>`
36
36
  - Issue branches: `issue/<issue-number>-<short-description>`
37
- - Integration branches: `integrate/<milestone-or-prd-name>`
37
+ - Integration branches: `integration/<plan-id>-<short-description>`
38
38
 
39
39
  ### 2. Create Branch from Integration Branch
40
40
 
@@ -91,13 +91,13 @@ Before merging any PR or branch, verify:
91
91
 
92
92
  Choose the appropriate strategy based on context:
93
93
 
94
- | Strategy | When to Use | Command |
95
- | ---------------- | ----------------------------------------------------------------------------------- | --------------------------- |
96
- | **Squash merge** | Story/issue PRs → integration or main branch. Produces clean single-commit history. | `gh pr merge <pr> --squash` |
97
- | **Merge commit** | Integration branch → main. Preserves the full story history. | `gh pr merge <pr> --merge` |
98
- | **Rebase merge** | Small PRs with clean linear history. Avoid for multi-commit stories. | `gh pr merge <pr> --rebase` |
94
+ | Strategy | When to Use | Command |
95
+ | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------- |
96
+ | **Squash merge** | Issue/story PRs → integration (planner) or `main` (user); delete the source branch. | `gh pr merge <pr> --squash --delete-branch` |
97
+ | **Merge commit** | Integration PRs → `main` (user); preserve the story history. | `gh pr merge <pr> --merge` |
98
+ | **Rebase merge** | Not part of the issue/story/integration policy; use only when explicitly approved. | `gh pr merge <pr> --rebase` |
99
99
 
100
- **Default**: Squash merge for story PRs, merge commit for integration PRs to main.
100
+ **Default**: Issue/story PRs use squash with branch deletion; integration PRs use a merge commit. Planner handles integration targets, and the user handles `main`.
101
101
 
102
102
  ### 6. Resolve Merge Conflicts
103
103
 
@@ -192,6 +192,26 @@ git push --force-with-lease origin <branch-name>
192
192
 
193
193
  **Never use** `git push --force` without `--with-lease`.
194
194
 
195
+ ### 10. Tag Procedure (Human-Only)
196
+
197
+ 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.
198
+
199
+ ```bash
200
+ # Ensure you are on main at the exact release commit
201
+ git checkout main
202
+ git pull origin main
203
+
204
+ # Create an annotated, immutable release tag (exact semver only)
205
+ git tag -a v<major>.<minor>.<patch> -m "Release v<major>.<minor>.<patch>"
206
+
207
+ # Push the tag (triggers the production deploy workflow)
208
+ git push origin v<major>.<minor>.<patch>
209
+ ```
210
+
211
+ 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.
212
+
213
+ **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.
214
+
195
215
  ---
196
216
 
197
217
  ## Conflict Resolution Heuristics
@@ -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
  ---