@jaguilar87/gaia 5.0.0-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (621) hide show
  1. package/.claude-plugin/marketplace.json +33 -0
  2. package/.claude-plugin/plugin.json +26 -0
  3. package/ARCHITECTURE.md +335 -0
  4. package/CHANGELOG.md +1298 -0
  5. package/CODE_OF_CONDUCT.md +11 -0
  6. package/CONTRIBUTING.md +146 -0
  7. package/INSTALL.md +436 -0
  8. package/LICENSE +21 -0
  9. package/README.md +222 -0
  10. package/SECURITY.md +47 -0
  11. package/agents/README.md +78 -0
  12. package/agents/cloud-troubleshooter.md +73 -0
  13. package/agents/developer.md +65 -0
  14. package/agents/gaia-operator.md +64 -0
  15. package/agents/gaia-orchestrator.md +111 -0
  16. package/agents/gaia-planner.md +53 -0
  17. package/agents/gaia-system.md +71 -0
  18. package/agents/gitops-operator.md +61 -0
  19. package/agents/terraform-architect.md +63 -0
  20. package/bin/README.md +106 -0
  21. package/bin/cli/__init__.py +1 -0
  22. package/bin/cli/approvals.py +740 -0
  23. package/bin/cli/cleanup.py +562 -0
  24. package/bin/cli/context.py +283 -0
  25. package/bin/cli/doctor.py +651 -0
  26. package/bin/cli/history.py +305 -0
  27. package/bin/cli/memory.py +483 -0
  28. package/bin/cli/metrics.py +1068 -0
  29. package/bin/cli/plans.py +515 -0
  30. package/bin/cli/status.py +302 -0
  31. package/bin/cli/update.py +382 -0
  32. package/bin/gaia +112 -0
  33. package/bin/gaia-cleanup.js +531 -0
  34. package/bin/gaia-doctor.js +635 -0
  35. package/bin/gaia-evidence +126 -0
  36. package/bin/gaia-history.js +251 -0
  37. package/bin/gaia-metrics.js +1278 -0
  38. package/bin/gaia-review.js +269 -0
  39. package/bin/gaia-scan +44 -0
  40. package/bin/gaia-scan.py +589 -0
  41. package/bin/gaia-skills-diagnose.js +929 -0
  42. package/bin/gaia-status.js +278 -0
  43. package/bin/gaia-uninstall.js +111 -0
  44. package/bin/gaia-update.js +919 -0
  45. package/bin/pre-publish-validate.js +610 -0
  46. package/bin/python-detect.js +60 -0
  47. package/bin/validate-sandbox.sh +601 -0
  48. package/commands/README.md +64 -0
  49. package/commands/gaia.md +37 -0
  50. package/commands/scan-project.md +67 -0
  51. package/config/README.md +71 -0
  52. package/config/cloud/aws.json +134 -0
  53. package/config/cloud/gcp.json +139 -0
  54. package/config/context-contracts.json +158 -0
  55. package/config/crons-schema.md +81 -0
  56. package/config/git_standards.json +72 -0
  57. package/config/surface-routing.json +417 -0
  58. package/config/universal-rules.json +102 -0
  59. package/dist/gaia-ops/.claude-plugin/plugin.json +24 -0
  60. package/dist/gaia-ops/README.md +80 -0
  61. package/dist/gaia-ops/agents/cloud-troubleshooter.md +73 -0
  62. package/dist/gaia-ops/agents/developer.md +65 -0
  63. package/dist/gaia-ops/agents/gaia-operator.md +64 -0
  64. package/dist/gaia-ops/agents/gaia-orchestrator.md +111 -0
  65. package/dist/gaia-ops/agents/gaia-planner.md +53 -0
  66. package/dist/gaia-ops/agents/gaia-system.md +71 -0
  67. package/dist/gaia-ops/agents/gitops-operator.md +61 -0
  68. package/dist/gaia-ops/agents/terraform-architect.md +63 -0
  69. package/dist/gaia-ops/commands/gaia.md +37 -0
  70. package/dist/gaia-ops/config/README.md +71 -0
  71. package/dist/gaia-ops/config/cloud/aws.json +134 -0
  72. package/dist/gaia-ops/config/cloud/gcp.json +139 -0
  73. package/dist/gaia-ops/config/context-contracts.json +158 -0
  74. package/dist/gaia-ops/config/crons-schema.md +81 -0
  75. package/dist/gaia-ops/config/git_standards.json +72 -0
  76. package/dist/gaia-ops/config/surface-routing.json +417 -0
  77. package/dist/gaia-ops/config/universal-rules.json +102 -0
  78. package/dist/gaia-ops/hooks/adapters/__init__.py +52 -0
  79. package/dist/gaia-ops/hooks/adapters/base.py +219 -0
  80. package/dist/gaia-ops/hooks/adapters/channel.py +17 -0
  81. package/dist/gaia-ops/hooks/adapters/claude_code.py +1890 -0
  82. package/dist/gaia-ops/hooks/adapters/types.py +194 -0
  83. package/dist/gaia-ops/hooks/adapters/utils.py +25 -0
  84. package/dist/gaia-ops/hooks/hooks.json +192 -0
  85. package/dist/gaia-ops/hooks/modules/__init__.py +15 -0
  86. package/dist/gaia-ops/hooks/modules/agents/__init__.py +29 -0
  87. package/dist/gaia-ops/hooks/modules/agents/contract_validator.py +647 -0
  88. package/dist/gaia-ops/hooks/modules/agents/response_contract.py +496 -0
  89. package/dist/gaia-ops/hooks/modules/agents/skill_injection_verifier.py +120 -0
  90. package/dist/gaia-ops/hooks/modules/agents/state_tracker.py +267 -0
  91. package/dist/gaia-ops/hooks/modules/agents/task_info_builder.py +74 -0
  92. package/dist/gaia-ops/hooks/modules/agents/transcript_analyzer.py +458 -0
  93. package/dist/gaia-ops/hooks/modules/agents/transcript_reader.py +152 -0
  94. package/dist/gaia-ops/hooks/modules/audit/__init__.py +28 -0
  95. package/dist/gaia-ops/hooks/modules/audit/event_detector.py +168 -0
  96. package/dist/gaia-ops/hooks/modules/audit/logger.py +131 -0
  97. package/dist/gaia-ops/hooks/modules/audit/metrics.py +134 -0
  98. package/dist/gaia-ops/hooks/modules/audit/workflow_auditor.py +611 -0
  99. package/dist/gaia-ops/hooks/modules/audit/workflow_recorder.py +296 -0
  100. package/dist/gaia-ops/hooks/modules/context/__init__.py +11 -0
  101. package/dist/gaia-ops/hooks/modules/context/agentic_loop_detector.py +165 -0
  102. package/dist/gaia-ops/hooks/modules/context/anchor_tracker.py +317 -0
  103. package/dist/gaia-ops/hooks/modules/context/compact_context_builder.py +218 -0
  104. package/dist/gaia-ops/hooks/modules/context/context_freshness.py +145 -0
  105. package/dist/gaia-ops/hooks/modules/context/context_injector.py +558 -0
  106. package/dist/gaia-ops/hooks/modules/context/context_writer.py +530 -0
  107. package/dist/gaia-ops/hooks/modules/context/contracts_loader.py +161 -0
  108. package/dist/gaia-ops/hooks/modules/core/__init__.py +40 -0
  109. package/dist/gaia-ops/hooks/modules/core/hook_entry.py +78 -0
  110. package/dist/gaia-ops/hooks/modules/core/paths.py +160 -0
  111. package/dist/gaia-ops/hooks/modules/core/plugin_mode.py +149 -0
  112. package/dist/gaia-ops/hooks/modules/core/plugin_setup.py +577 -0
  113. package/dist/gaia-ops/hooks/modules/core/state.py +179 -0
  114. package/dist/gaia-ops/hooks/modules/core/stdin.py +24 -0
  115. package/dist/gaia-ops/hooks/modules/events/__init__.py +1 -0
  116. package/dist/gaia-ops/hooks/modules/events/event_writer.py +210 -0
  117. package/dist/gaia-ops/hooks/modules/memory/__init__.py +8 -0
  118. package/dist/gaia-ops/hooks/modules/memory/episode_writer.py +216 -0
  119. package/dist/gaia-ops/hooks/modules/orchestrator/__init__.py +1 -0
  120. package/dist/gaia-ops/hooks/modules/orchestrator/delegate_mode.py +122 -0
  121. package/dist/gaia-ops/hooks/modules/scanning/__init__.py +8 -0
  122. package/dist/gaia-ops/hooks/modules/scanning/scan_trigger.py +84 -0
  123. package/dist/gaia-ops/hooks/modules/security/__init__.py +120 -0
  124. package/dist/gaia-ops/hooks/modules/security/approval_cleanup.py +87 -0
  125. package/dist/gaia-ops/hooks/modules/security/approval_constants.py +23 -0
  126. package/dist/gaia-ops/hooks/modules/security/approval_grants.py +1638 -0
  127. package/dist/gaia-ops/hooks/modules/security/approval_messages.py +71 -0
  128. package/dist/gaia-ops/hooks/modules/security/approval_scopes.py +222 -0
  129. package/dist/gaia-ops/hooks/modules/security/blocked_commands.py +595 -0
  130. package/dist/gaia-ops/hooks/modules/security/blocked_message_formatter.py +87 -0
  131. package/dist/gaia-ops/hooks/modules/security/command_semantics.py +181 -0
  132. package/dist/gaia-ops/hooks/modules/security/composition_rules.py +547 -0
  133. package/dist/gaia-ops/hooks/modules/security/flag_classifiers.py +873 -0
  134. package/dist/gaia-ops/hooks/modules/security/gitops_validator.py +179 -0
  135. package/dist/gaia-ops/hooks/modules/security/mutative_verbs.py +1131 -0
  136. package/dist/gaia-ops/hooks/modules/security/network_hosts.py +481 -0
  137. package/dist/gaia-ops/hooks/modules/security/prompt_validator.py +40 -0
  138. package/dist/gaia-ops/hooks/modules/security/shell_unwrapper.py +165 -0
  139. package/dist/gaia-ops/hooks/modules/security/tiers.py +196 -0
  140. package/dist/gaia-ops/hooks/modules/session/__init__.py +10 -0
  141. package/dist/gaia-ops/hooks/modules/session/pending_scanner.py +174 -0
  142. package/dist/gaia-ops/hooks/modules/session/session_context_writer.py +100 -0
  143. package/dist/gaia-ops/hooks/modules/session/session_event_injector.py +160 -0
  144. package/dist/gaia-ops/hooks/modules/session/session_manager.py +31 -0
  145. package/dist/gaia-ops/hooks/modules/session/session_registry.py +333 -0
  146. package/dist/gaia-ops/hooks/modules/tools/__init__.py +29 -0
  147. package/dist/gaia-ops/hooks/modules/tools/bash_validator.py +1008 -0
  148. package/dist/gaia-ops/hooks/modules/tools/cloud_pipe_validator.py +231 -0
  149. package/dist/gaia-ops/hooks/modules/tools/hook_response.py +55 -0
  150. package/dist/gaia-ops/hooks/modules/tools/shell_parser.py +227 -0
  151. package/dist/gaia-ops/hooks/modules/tools/stage_decomposer.py +315 -0
  152. package/dist/gaia-ops/hooks/modules/tools/task_validator.py +294 -0
  153. package/dist/gaia-ops/hooks/modules/validation/__init__.py +23 -0
  154. package/dist/gaia-ops/hooks/modules/validation/commit_validator.py +380 -0
  155. package/dist/gaia-ops/hooks/post_compact.py +43 -0
  156. package/dist/gaia-ops/hooks/post_tool_use.py +54 -0
  157. package/dist/gaia-ops/hooks/pre_compact.py +60 -0
  158. package/dist/gaia-ops/hooks/pre_tool_use.py +413 -0
  159. package/dist/gaia-ops/hooks/session_end_hook.py +77 -0
  160. package/dist/gaia-ops/hooks/session_start.py +81 -0
  161. package/dist/gaia-ops/hooks/stop_hook.py +70 -0
  162. package/dist/gaia-ops/hooks/subagent_start.py +71 -0
  163. package/dist/gaia-ops/hooks/subagent_stop.py +295 -0
  164. package/dist/gaia-ops/hooks/task_completed.py +70 -0
  165. package/dist/gaia-ops/hooks/user_prompt_submit.py +246 -0
  166. package/dist/gaia-ops/settings.json +72 -0
  167. package/dist/gaia-ops/skills/README.md +158 -0
  168. package/dist/gaia-ops/skills/agent-creation/SKILL.md +87 -0
  169. package/dist/gaia-ops/skills/agent-creation/examples.md +170 -0
  170. package/dist/gaia-ops/skills/agent-creation/reference.md +191 -0
  171. package/dist/gaia-ops/skills/agent-protocol/SKILL.md +93 -0
  172. package/dist/gaia-ops/skills/agent-protocol/examples.md +223 -0
  173. package/dist/gaia-ops/skills/agent-response/SKILL.md +69 -0
  174. package/dist/gaia-ops/skills/agentic-loop/SKILL.md +80 -0
  175. package/dist/gaia-ops/skills/agentic-loop/reference.md +378 -0
  176. package/dist/gaia-ops/skills/blog-writing/SKILL.md +98 -0
  177. package/dist/gaia-ops/skills/blog-writing/reference.md +130 -0
  178. package/dist/gaia-ops/skills/brief-spec/SKILL.md +185 -0
  179. package/dist/gaia-ops/skills/command-execution/SKILL.md +64 -0
  180. package/dist/gaia-ops/skills/command-execution/reference.md +83 -0
  181. package/dist/gaia-ops/skills/context-updater/SKILL.md +87 -0
  182. package/dist/gaia-ops/skills/context-updater/examples.md +71 -0
  183. package/dist/gaia-ops/skills/developer-patterns/SKILL.md +50 -0
  184. package/dist/gaia-ops/skills/developer-patterns/reference.md +112 -0
  185. package/dist/gaia-ops/skills/execution/SKILL.md +99 -0
  186. package/dist/gaia-ops/skills/fast-queries/SKILL.md +43 -0
  187. package/dist/gaia-ops/skills/gaia-compact/SKILL.md +74 -0
  188. package/dist/gaia-ops/skills/gaia-patterns/SKILL.md +108 -0
  189. package/dist/gaia-ops/skills/gaia-patterns/reference.md +395 -0
  190. package/dist/gaia-ops/skills/gaia-planner/SKILL.md +37 -0
  191. package/dist/gaia-ops/skills/gaia-planner/reference.md +107 -0
  192. package/dist/gaia-ops/skills/gaia-release/SKILL.md +85 -0
  193. package/dist/gaia-ops/skills/gaia-release/reference.md +92 -0
  194. package/dist/gaia-ops/skills/gaia-self-check/SKILL.md +114 -0
  195. package/dist/gaia-ops/skills/gaia-self-check/reference.md +453 -0
  196. package/dist/gaia-ops/skills/gaia-verify/SKILL.md +77 -0
  197. package/dist/gaia-ops/skills/gaia-verify/reference.md +80 -0
  198. package/dist/gaia-ops/skills/git-conventions/SKILL.md +47 -0
  199. package/dist/gaia-ops/skills/gitops-patterns/SKILL.md +60 -0
  200. package/dist/gaia-ops/skills/gitops-patterns/reference.md +183 -0
  201. package/dist/gaia-ops/skills/gmail-policy/SKILL.md +200 -0
  202. package/dist/gaia-ops/skills/gmail-policy/reference.md +150 -0
  203. package/dist/gaia-ops/skills/gmail-triage/SKILL.md +100 -0
  204. package/dist/gaia-ops/skills/gws-setup/SKILL.md +99 -0
  205. package/dist/gaia-ops/skills/gws-setup/reference.md +73 -0
  206. package/dist/gaia-ops/skills/investigation/SKILL.md +100 -0
  207. package/dist/gaia-ops/skills/memory-curation/SKILL.md +83 -0
  208. package/dist/gaia-ops/skills/memory-search/SKILL.md +88 -0
  209. package/dist/gaia-ops/skills/orchestrator-approval/SKILL.md +160 -0
  210. package/dist/gaia-ops/skills/orchestrator-approval/reference.md +174 -0
  211. package/dist/gaia-ops/skills/pending-approvals/SKILL.md +72 -0
  212. package/dist/gaia-ops/skills/pending-approvals/reference.md +214 -0
  213. package/dist/gaia-ops/skills/readme-writing/SKILL.md +71 -0
  214. package/dist/gaia-ops/skills/readme-writing/reference.md +188 -0
  215. package/dist/gaia-ops/skills/reference.md +135 -0
  216. package/dist/gaia-ops/skills/request-approval/SKILL.md +140 -0
  217. package/dist/gaia-ops/skills/request-approval/examples.md +140 -0
  218. package/dist/gaia-ops/skills/request-approval/reference.md +57 -0
  219. package/dist/gaia-ops/skills/schedule-task/SKILL.md +64 -0
  220. package/dist/gaia-ops/skills/schedule-task/reference.md +233 -0
  221. package/dist/gaia-ops/skills/security-tiers/SKILL.md +141 -0
  222. package/dist/gaia-ops/skills/security-tiers/destructive-commands-reference.md +623 -0
  223. package/dist/gaia-ops/skills/security-tiers/reference.md +39 -0
  224. package/dist/gaia-ops/skills/session-reflection/SKILL.md +69 -0
  225. package/dist/gaia-ops/skills/skill-creation/SKILL.md +92 -0
  226. package/dist/gaia-ops/skills/skill-creation/reference.md +29 -0
  227. package/dist/gaia-ops/skills/terraform-patterns/SKILL.md +89 -0
  228. package/dist/gaia-ops/skills/terraform-patterns/reference.md +93 -0
  229. package/dist/gaia-ops/tools/__init__.py +9 -0
  230. package/dist/gaia-ops/tools/agentic-loop/decide-status.py +210 -0
  231. package/dist/gaia-ops/tools/agentic-loop/parse-metric.py +106 -0
  232. package/dist/gaia-ops/tools/agentic-loop/record-iteration.py +221 -0
  233. package/dist/gaia-ops/tools/context/README.md +132 -0
  234. package/dist/gaia-ops/tools/context/__init__.py +42 -0
  235. package/dist/gaia-ops/tools/context/_paths.py +20 -0
  236. package/dist/gaia-ops/tools/context/context_provider.py +721 -0
  237. package/dist/gaia-ops/tools/context/context_section_reader.py +342 -0
  238. package/dist/gaia-ops/tools/context/deep_merge.py +159 -0
  239. package/dist/gaia-ops/tools/context/pending_updates.py +760 -0
  240. package/dist/gaia-ops/tools/context/surface_router.py +278 -0
  241. package/dist/gaia-ops/tools/fast-queries/README.md +65 -0
  242. package/dist/gaia-ops/tools/fast-queries/__init__.py +30 -0
  243. package/dist/gaia-ops/tools/fast-queries/appservices/quicktriage_devops_developer.sh +75 -0
  244. package/dist/gaia-ops/tools/fast-queries/cloud/aws/quicktriage_aws_troubleshooter.sh +32 -0
  245. package/dist/gaia-ops/tools/fast-queries/cloud/gcp/quicktriage_gcp_troubleshooter.sh +88 -0
  246. package/dist/gaia-ops/tools/fast-queries/gitops/quicktriage_gitops_operator.sh +48 -0
  247. package/dist/gaia-ops/tools/fast-queries/run_triage.sh +59 -0
  248. package/dist/gaia-ops/tools/fast-queries/terraform/quicktriage_terraform_architect.sh +80 -0
  249. package/dist/gaia-ops/tools/gaia_simulator/__init__.py +33 -0
  250. package/dist/gaia-ops/tools/gaia_simulator/cli.py +354 -0
  251. package/dist/gaia-ops/tools/gaia_simulator/extractor.py +457 -0
  252. package/dist/gaia-ops/tools/gaia_simulator/reporter.py +258 -0
  253. package/dist/gaia-ops/tools/gaia_simulator/routing_simulator.py +334 -0
  254. package/dist/gaia-ops/tools/gaia_simulator/runner.py +539 -0
  255. package/dist/gaia-ops/tools/gaia_simulator/skills_mapper.py +264 -0
  256. package/dist/gaia-ops/tools/memory/README.md +0 -0
  257. package/dist/gaia-ops/tools/memory/__init__.py +20 -0
  258. package/dist/gaia-ops/tools/memory/backfill_fts5.py +107 -0
  259. package/dist/gaia-ops/tools/memory/conflict_detector.py +295 -0
  260. package/dist/gaia-ops/tools/memory/episodic.py +1210 -0
  261. package/dist/gaia-ops/tools/memory/git_invalidator.py +262 -0
  262. package/dist/gaia-ops/tools/memory/paths.py +102 -0
  263. package/dist/gaia-ops/tools/memory/scoring.py +193 -0
  264. package/dist/gaia-ops/tools/memory/search_store.py +375 -0
  265. package/dist/gaia-ops/tools/persist_transcript_analysis.py +85 -0
  266. package/dist/gaia-ops/tools/review/__init__.py +1 -0
  267. package/dist/gaia-ops/tools/review/review_engine.py +157 -0
  268. package/dist/gaia-ops/tools/scan/__init__.py +35 -0
  269. package/dist/gaia-ops/tools/scan/config.py +247 -0
  270. package/dist/gaia-ops/tools/scan/merge.py +212 -0
  271. package/dist/gaia-ops/tools/scan/orchestrator.py +549 -0
  272. package/dist/gaia-ops/tools/scan/registry.py +127 -0
  273. package/dist/gaia-ops/tools/scan/scanners/__init__.py +18 -0
  274. package/dist/gaia-ops/tools/scan/scanners/base.py +137 -0
  275. package/dist/gaia-ops/tools/scan/scanners/environment.py +349 -0
  276. package/dist/gaia-ops/tools/scan/scanners/git.py +570 -0
  277. package/dist/gaia-ops/tools/scan/scanners/infrastructure.py +875 -0
  278. package/dist/gaia-ops/tools/scan/scanners/orchestration.py +600 -0
  279. package/dist/gaia-ops/tools/scan/scanners/stack.py +1085 -0
  280. package/dist/gaia-ops/tools/scan/scanners/tools.py +260 -0
  281. package/dist/gaia-ops/tools/scan/setup.py +686 -0
  282. package/dist/gaia-ops/tools/scan/tests/__init__.py +1 -0
  283. package/dist/gaia-ops/tools/scan/tests/conftest.py +796 -0
  284. package/dist/gaia-ops/tools/scan/tests/test_environment.py +323 -0
  285. package/dist/gaia-ops/tools/scan/tests/test_git.py +419 -0
  286. package/dist/gaia-ops/tools/scan/tests/test_infrastructure.py +382 -0
  287. package/dist/gaia-ops/tools/scan/tests/test_integration.py +920 -0
  288. package/dist/gaia-ops/tools/scan/tests/test_merge.py +269 -0
  289. package/dist/gaia-ops/tools/scan/tests/test_orchestration.py +304 -0
  290. package/dist/gaia-ops/tools/scan/tests/test_stack.py +604 -0
  291. package/dist/gaia-ops/tools/scan/tests/test_tools.py +349 -0
  292. package/dist/gaia-ops/tools/scan/ui.py +624 -0
  293. package/dist/gaia-ops/tools/scan/verify.py +270 -0
  294. package/dist/gaia-ops/tools/scan/walk.py +118 -0
  295. package/dist/gaia-ops/tools/scan/workspace.py +85 -0
  296. package/dist/gaia-ops/tools/validation/README.md +244 -0
  297. package/dist/gaia-ops/tools/validation/__init__.py +17 -0
  298. package/dist/gaia-ops/tools/validation/approval_gate.py +321 -0
  299. package/dist/gaia-ops/tools/validation/validate_skills.py +189 -0
  300. package/dist/gaia-security/.claude-plugin/plugin.json +24 -0
  301. package/dist/gaia-security/README.md +90 -0
  302. package/dist/gaia-security/config/universal-rules.json +102 -0
  303. package/dist/gaia-security/hooks/adapters/__init__.py +52 -0
  304. package/dist/gaia-security/hooks/adapters/base.py +219 -0
  305. package/dist/gaia-security/hooks/adapters/channel.py +17 -0
  306. package/dist/gaia-security/hooks/adapters/claude_code.py +1890 -0
  307. package/dist/gaia-security/hooks/adapters/types.py +194 -0
  308. package/dist/gaia-security/hooks/adapters/utils.py +25 -0
  309. package/dist/gaia-security/hooks/hooks.json +113 -0
  310. package/dist/gaia-security/hooks/modules/__init__.py +15 -0
  311. package/dist/gaia-security/hooks/modules/agents/__init__.py +29 -0
  312. package/dist/gaia-security/hooks/modules/agents/contract_validator.py +647 -0
  313. package/dist/gaia-security/hooks/modules/agents/response_contract.py +496 -0
  314. package/dist/gaia-security/hooks/modules/agents/skill_injection_verifier.py +120 -0
  315. package/dist/gaia-security/hooks/modules/agents/state_tracker.py +267 -0
  316. package/dist/gaia-security/hooks/modules/agents/task_info_builder.py +74 -0
  317. package/dist/gaia-security/hooks/modules/agents/transcript_analyzer.py +458 -0
  318. package/dist/gaia-security/hooks/modules/agents/transcript_reader.py +152 -0
  319. package/dist/gaia-security/hooks/modules/audit/__init__.py +28 -0
  320. package/dist/gaia-security/hooks/modules/audit/event_detector.py +168 -0
  321. package/dist/gaia-security/hooks/modules/audit/logger.py +131 -0
  322. package/dist/gaia-security/hooks/modules/audit/metrics.py +134 -0
  323. package/dist/gaia-security/hooks/modules/audit/workflow_auditor.py +611 -0
  324. package/dist/gaia-security/hooks/modules/audit/workflow_recorder.py +296 -0
  325. package/dist/gaia-security/hooks/modules/context/__init__.py +11 -0
  326. package/dist/gaia-security/hooks/modules/context/agentic_loop_detector.py +165 -0
  327. package/dist/gaia-security/hooks/modules/context/anchor_tracker.py +317 -0
  328. package/dist/gaia-security/hooks/modules/context/compact_context_builder.py +218 -0
  329. package/dist/gaia-security/hooks/modules/context/context_freshness.py +145 -0
  330. package/dist/gaia-security/hooks/modules/context/context_injector.py +558 -0
  331. package/dist/gaia-security/hooks/modules/context/context_writer.py +530 -0
  332. package/dist/gaia-security/hooks/modules/context/contracts_loader.py +161 -0
  333. package/dist/gaia-security/hooks/modules/core/__init__.py +40 -0
  334. package/dist/gaia-security/hooks/modules/core/hook_entry.py +78 -0
  335. package/dist/gaia-security/hooks/modules/core/paths.py +160 -0
  336. package/dist/gaia-security/hooks/modules/core/plugin_mode.py +149 -0
  337. package/dist/gaia-security/hooks/modules/core/plugin_setup.py +577 -0
  338. package/dist/gaia-security/hooks/modules/core/state.py +179 -0
  339. package/dist/gaia-security/hooks/modules/core/stdin.py +24 -0
  340. package/dist/gaia-security/hooks/modules/events/__init__.py +1 -0
  341. package/dist/gaia-security/hooks/modules/events/event_writer.py +210 -0
  342. package/dist/gaia-security/hooks/modules/memory/__init__.py +8 -0
  343. package/dist/gaia-security/hooks/modules/memory/episode_writer.py +216 -0
  344. package/dist/gaia-security/hooks/modules/orchestrator/__init__.py +1 -0
  345. package/dist/gaia-security/hooks/modules/orchestrator/delegate_mode.py +122 -0
  346. package/dist/gaia-security/hooks/modules/scanning/__init__.py +8 -0
  347. package/dist/gaia-security/hooks/modules/scanning/scan_trigger.py +84 -0
  348. package/dist/gaia-security/hooks/modules/security/__init__.py +120 -0
  349. package/dist/gaia-security/hooks/modules/security/approval_cleanup.py +87 -0
  350. package/dist/gaia-security/hooks/modules/security/approval_constants.py +23 -0
  351. package/dist/gaia-security/hooks/modules/security/approval_grants.py +1638 -0
  352. package/dist/gaia-security/hooks/modules/security/approval_messages.py +71 -0
  353. package/dist/gaia-security/hooks/modules/security/approval_scopes.py +222 -0
  354. package/dist/gaia-security/hooks/modules/security/blocked_commands.py +595 -0
  355. package/dist/gaia-security/hooks/modules/security/blocked_message_formatter.py +87 -0
  356. package/dist/gaia-security/hooks/modules/security/command_semantics.py +181 -0
  357. package/dist/gaia-security/hooks/modules/security/composition_rules.py +547 -0
  358. package/dist/gaia-security/hooks/modules/security/flag_classifiers.py +873 -0
  359. package/dist/gaia-security/hooks/modules/security/gitops_validator.py +179 -0
  360. package/dist/gaia-security/hooks/modules/security/mutative_verbs.py +1131 -0
  361. package/dist/gaia-security/hooks/modules/security/network_hosts.py +481 -0
  362. package/dist/gaia-security/hooks/modules/security/prompt_validator.py +40 -0
  363. package/dist/gaia-security/hooks/modules/security/shell_unwrapper.py +165 -0
  364. package/dist/gaia-security/hooks/modules/security/tiers.py +196 -0
  365. package/dist/gaia-security/hooks/modules/session/__init__.py +10 -0
  366. package/dist/gaia-security/hooks/modules/session/pending_scanner.py +174 -0
  367. package/dist/gaia-security/hooks/modules/session/session_context_writer.py +100 -0
  368. package/dist/gaia-security/hooks/modules/session/session_event_injector.py +160 -0
  369. package/dist/gaia-security/hooks/modules/session/session_manager.py +31 -0
  370. package/dist/gaia-security/hooks/modules/session/session_registry.py +333 -0
  371. package/dist/gaia-security/hooks/modules/tools/__init__.py +29 -0
  372. package/dist/gaia-security/hooks/modules/tools/bash_validator.py +1008 -0
  373. package/dist/gaia-security/hooks/modules/tools/cloud_pipe_validator.py +231 -0
  374. package/dist/gaia-security/hooks/modules/tools/hook_response.py +55 -0
  375. package/dist/gaia-security/hooks/modules/tools/shell_parser.py +227 -0
  376. package/dist/gaia-security/hooks/modules/tools/stage_decomposer.py +315 -0
  377. package/dist/gaia-security/hooks/modules/tools/task_validator.py +294 -0
  378. package/dist/gaia-security/hooks/modules/validation/__init__.py +23 -0
  379. package/dist/gaia-security/hooks/modules/validation/commit_validator.py +380 -0
  380. package/dist/gaia-security/hooks/post_tool_use.py +54 -0
  381. package/dist/gaia-security/hooks/pre_tool_use.py +413 -0
  382. package/dist/gaia-security/hooks/session_end_hook.py +77 -0
  383. package/dist/gaia-security/hooks/session_start.py +81 -0
  384. package/dist/gaia-security/hooks/stop_hook.py +70 -0
  385. package/dist/gaia-security/hooks/user_prompt_submit.py +246 -0
  386. package/dist/gaia-security/settings.json +58 -0
  387. package/git-hooks/commit-msg +41 -0
  388. package/hooks/README.md +100 -0
  389. package/hooks/adapters/__init__.py +52 -0
  390. package/hooks/adapters/base.py +219 -0
  391. package/hooks/adapters/channel.py +17 -0
  392. package/hooks/adapters/claude_code.py +1890 -0
  393. package/hooks/adapters/types.py +194 -0
  394. package/hooks/adapters/utils.py +25 -0
  395. package/hooks/elicitation_result.py +179 -0
  396. package/hooks/hooks.json +84 -0
  397. package/hooks/modules/README.md +189 -0
  398. package/hooks/modules/__init__.py +15 -0
  399. package/hooks/modules/agents/__init__.py +29 -0
  400. package/hooks/modules/agents/contract_validator.py +647 -0
  401. package/hooks/modules/agents/response_contract.py +496 -0
  402. package/hooks/modules/agents/skill_injection_verifier.py +120 -0
  403. package/hooks/modules/agents/state_tracker.py +267 -0
  404. package/hooks/modules/agents/task_info_builder.py +74 -0
  405. package/hooks/modules/agents/transcript_analyzer.py +458 -0
  406. package/hooks/modules/agents/transcript_reader.py +152 -0
  407. package/hooks/modules/audit/__init__.py +28 -0
  408. package/hooks/modules/audit/event_detector.py +168 -0
  409. package/hooks/modules/audit/logger.py +131 -0
  410. package/hooks/modules/audit/metrics.py +134 -0
  411. package/hooks/modules/audit/workflow_auditor.py +611 -0
  412. package/hooks/modules/audit/workflow_recorder.py +296 -0
  413. package/hooks/modules/context/__init__.py +11 -0
  414. package/hooks/modules/context/agentic_loop_detector.py +165 -0
  415. package/hooks/modules/context/anchor_tracker.py +317 -0
  416. package/hooks/modules/context/compact_context_builder.py +218 -0
  417. package/hooks/modules/context/context_freshness.py +145 -0
  418. package/hooks/modules/context/context_injector.py +558 -0
  419. package/hooks/modules/context/context_writer.py +530 -0
  420. package/hooks/modules/context/contracts_loader.py +161 -0
  421. package/hooks/modules/core/__init__.py +40 -0
  422. package/hooks/modules/core/hook_entry.py +78 -0
  423. package/hooks/modules/core/paths.py +160 -0
  424. package/hooks/modules/core/plugin_mode.py +149 -0
  425. package/hooks/modules/core/plugin_setup.py +577 -0
  426. package/hooks/modules/core/state.py +179 -0
  427. package/hooks/modules/core/stdin.py +24 -0
  428. package/hooks/modules/events/__init__.py +1 -0
  429. package/hooks/modules/events/event_writer.py +210 -0
  430. package/hooks/modules/evidence/__init__.py +34 -0
  431. package/hooks/modules/evidence/assertions.py +137 -0
  432. package/hooks/modules/evidence/index_writer.py +57 -0
  433. package/hooks/modules/evidence/loader.py +126 -0
  434. package/hooks/modules/evidence/runner.py +241 -0
  435. package/hooks/modules/memory/__init__.py +8 -0
  436. package/hooks/modules/memory/episode_writer.py +216 -0
  437. package/hooks/modules/orchestrator/__init__.py +1 -0
  438. package/hooks/modules/orchestrator/delegate_mode.py +122 -0
  439. package/hooks/modules/scanning/__init__.py +8 -0
  440. package/hooks/modules/scanning/scan_trigger.py +84 -0
  441. package/hooks/modules/security/__init__.py +120 -0
  442. package/hooks/modules/security/approval_cleanup.py +87 -0
  443. package/hooks/modules/security/approval_constants.py +23 -0
  444. package/hooks/modules/security/approval_grants.py +1638 -0
  445. package/hooks/modules/security/approval_messages.py +71 -0
  446. package/hooks/modules/security/approval_scopes.py +222 -0
  447. package/hooks/modules/security/blocked_commands.py +595 -0
  448. package/hooks/modules/security/blocked_message_formatter.py +87 -0
  449. package/hooks/modules/security/command_semantics.py +181 -0
  450. package/hooks/modules/security/composition_rules.py +547 -0
  451. package/hooks/modules/security/flag_classifiers.py +873 -0
  452. package/hooks/modules/security/gitops_validator.py +179 -0
  453. package/hooks/modules/security/mutative_verbs.py +1131 -0
  454. package/hooks/modules/security/network_hosts.py +481 -0
  455. package/hooks/modules/security/prompt_validator.py +40 -0
  456. package/hooks/modules/security/shell_unwrapper.py +165 -0
  457. package/hooks/modules/security/tiers.py +196 -0
  458. package/hooks/modules/session/__init__.py +10 -0
  459. package/hooks/modules/session/pending_scanner.py +174 -0
  460. package/hooks/modules/session/session_context_writer.py +100 -0
  461. package/hooks/modules/session/session_event_injector.py +160 -0
  462. package/hooks/modules/session/session_manager.py +31 -0
  463. package/hooks/modules/session/session_registry.py +333 -0
  464. package/hooks/modules/tools/__init__.py +29 -0
  465. package/hooks/modules/tools/bash_validator.py +1008 -0
  466. package/hooks/modules/tools/cloud_pipe_validator.py +231 -0
  467. package/hooks/modules/tools/hook_response.py +55 -0
  468. package/hooks/modules/tools/shell_parser.py +227 -0
  469. package/hooks/modules/tools/stage_decomposer.py +315 -0
  470. package/hooks/modules/tools/task_validator.py +294 -0
  471. package/hooks/modules/validation/__init__.py +23 -0
  472. package/hooks/modules/validation/commit_validator.py +380 -0
  473. package/hooks/post_compact.py +43 -0
  474. package/hooks/post_tool_use.py +54 -0
  475. package/hooks/pre_compact.py +60 -0
  476. package/hooks/pre_tool_use.py +413 -0
  477. package/hooks/session_end_hook.py +77 -0
  478. package/hooks/session_start.py +81 -0
  479. package/hooks/stop_hook.py +70 -0
  480. package/hooks/subagent_start.py +71 -0
  481. package/hooks/subagent_stop.py +295 -0
  482. package/hooks/task_completed.py +70 -0
  483. package/hooks/user_prompt_submit.py +246 -0
  484. package/index.js +83 -0
  485. package/package.json +103 -0
  486. package/pyproject.toml +32 -0
  487. package/skills/README.md +158 -0
  488. package/skills/agent-creation/SKILL.md +87 -0
  489. package/skills/agent-creation/examples.md +170 -0
  490. package/skills/agent-creation/reference.md +191 -0
  491. package/skills/agent-protocol/SKILL.md +93 -0
  492. package/skills/agent-protocol/examples.md +223 -0
  493. package/skills/agent-response/SKILL.md +69 -0
  494. package/skills/agentic-loop/SKILL.md +80 -0
  495. package/skills/agentic-loop/reference.md +378 -0
  496. package/skills/blog-writing/SKILL.md +98 -0
  497. package/skills/blog-writing/reference.md +130 -0
  498. package/skills/brief-spec/SKILL.md +185 -0
  499. package/skills/command-execution/SKILL.md +64 -0
  500. package/skills/command-execution/reference.md +83 -0
  501. package/skills/context-updater/SKILL.md +87 -0
  502. package/skills/context-updater/examples.md +71 -0
  503. package/skills/developer-patterns/SKILL.md +50 -0
  504. package/skills/developer-patterns/reference.md +112 -0
  505. package/skills/execution/SKILL.md +99 -0
  506. package/skills/fast-queries/SKILL.md +43 -0
  507. package/skills/gaia-compact/SKILL.md +74 -0
  508. package/skills/gaia-patterns/SKILL.md +108 -0
  509. package/skills/gaia-patterns/reference.md +395 -0
  510. package/skills/gaia-planner/SKILL.md +37 -0
  511. package/skills/gaia-planner/reference.md +107 -0
  512. package/skills/gaia-release/SKILL.md +85 -0
  513. package/skills/gaia-release/reference.md +92 -0
  514. package/skills/gaia-self-check/SKILL.md +114 -0
  515. package/skills/gaia-self-check/reference.md +453 -0
  516. package/skills/gaia-verify/SKILL.md +77 -0
  517. package/skills/gaia-verify/reference.md +80 -0
  518. package/skills/git-conventions/SKILL.md +47 -0
  519. package/skills/gitops-patterns/SKILL.md +60 -0
  520. package/skills/gitops-patterns/reference.md +183 -0
  521. package/skills/gmail-policy/SKILL.md +200 -0
  522. package/skills/gmail-policy/reference.md +150 -0
  523. package/skills/gmail-triage/SKILL.md +100 -0
  524. package/skills/gws-setup/SKILL.md +99 -0
  525. package/skills/gws-setup/reference.md +73 -0
  526. package/skills/investigation/SKILL.md +100 -0
  527. package/skills/memory-curation/SKILL.md +83 -0
  528. package/skills/memory-search/SKILL.md +88 -0
  529. package/skills/orchestrator-approval/SKILL.md +160 -0
  530. package/skills/orchestrator-approval/reference.md +174 -0
  531. package/skills/pending-approvals/SKILL.md +72 -0
  532. package/skills/pending-approvals/reference.md +214 -0
  533. package/skills/readme-writing/SKILL.md +71 -0
  534. package/skills/readme-writing/reference.md +188 -0
  535. package/skills/reference.md +135 -0
  536. package/skills/request-approval/SKILL.md +140 -0
  537. package/skills/request-approval/examples.md +140 -0
  538. package/skills/request-approval/reference.md +57 -0
  539. package/skills/schedule-task/SKILL.md +64 -0
  540. package/skills/schedule-task/reference.md +233 -0
  541. package/skills/security-tiers/SKILL.md +141 -0
  542. package/skills/security-tiers/destructive-commands-reference.md +623 -0
  543. package/skills/security-tiers/reference.md +39 -0
  544. package/skills/session-reflection/SKILL.md +69 -0
  545. package/skills/skill-creation/SKILL.md +92 -0
  546. package/skills/skill-creation/reference.md +29 -0
  547. package/skills/terraform-patterns/SKILL.md +89 -0
  548. package/skills/terraform-patterns/reference.md +93 -0
  549. package/templates/README.md +69 -0
  550. package/templates/managed-settings.template.json +43 -0
  551. package/tools/__init__.py +9 -0
  552. package/tools/agentic-loop/decide-status.py +210 -0
  553. package/tools/agentic-loop/parse-metric.py +106 -0
  554. package/tools/agentic-loop/record-iteration.py +221 -0
  555. package/tools/context/README.md +132 -0
  556. package/tools/context/__init__.py +42 -0
  557. package/tools/context/_paths.py +20 -0
  558. package/tools/context/context_provider.py +721 -0
  559. package/tools/context/context_section_reader.py +342 -0
  560. package/tools/context/deep_merge.py +159 -0
  561. package/tools/context/pending_updates.py +760 -0
  562. package/tools/context/surface_router.py +278 -0
  563. package/tools/fast-queries/README.md +65 -0
  564. package/tools/fast-queries/__init__.py +30 -0
  565. package/tools/fast-queries/appservices/quicktriage_devops_developer.sh +75 -0
  566. package/tools/fast-queries/cloud/aws/quicktriage_aws_troubleshooter.sh +32 -0
  567. package/tools/fast-queries/cloud/gcp/quicktriage_gcp_troubleshooter.sh +88 -0
  568. package/tools/fast-queries/gitops/quicktriage_gitops_operator.sh +48 -0
  569. package/tools/fast-queries/run_triage.sh +59 -0
  570. package/tools/fast-queries/terraform/quicktriage_terraform_architect.sh +80 -0
  571. package/tools/gaia_simulator/__init__.py +33 -0
  572. package/tools/gaia_simulator/cli.py +354 -0
  573. package/tools/gaia_simulator/extractor.py +457 -0
  574. package/tools/gaia_simulator/reporter.py +258 -0
  575. package/tools/gaia_simulator/routing_simulator.py +334 -0
  576. package/tools/gaia_simulator/runner.py +539 -0
  577. package/tools/gaia_simulator/skills_mapper.py +264 -0
  578. package/tools/memory/README.md +0 -0
  579. package/tools/memory/__init__.py +20 -0
  580. package/tools/memory/backfill_fts5.py +107 -0
  581. package/tools/memory/conflict_detector.py +295 -0
  582. package/tools/memory/episodic.py +1210 -0
  583. package/tools/memory/git_invalidator.py +262 -0
  584. package/tools/memory/paths.py +102 -0
  585. package/tools/memory/scoring.py +193 -0
  586. package/tools/memory/search_store.py +375 -0
  587. package/tools/persist_transcript_analysis.py +85 -0
  588. package/tools/review/__init__.py +1 -0
  589. package/tools/review/review_engine.py +157 -0
  590. package/tools/scan/__init__.py +35 -0
  591. package/tools/scan/config.py +247 -0
  592. package/tools/scan/merge.py +212 -0
  593. package/tools/scan/orchestrator.py +549 -0
  594. package/tools/scan/registry.py +127 -0
  595. package/tools/scan/scanners/__init__.py +18 -0
  596. package/tools/scan/scanners/base.py +137 -0
  597. package/tools/scan/scanners/environment.py +349 -0
  598. package/tools/scan/scanners/git.py +570 -0
  599. package/tools/scan/scanners/infrastructure.py +875 -0
  600. package/tools/scan/scanners/orchestration.py +600 -0
  601. package/tools/scan/scanners/stack.py +1085 -0
  602. package/tools/scan/scanners/tools.py +260 -0
  603. package/tools/scan/setup.py +686 -0
  604. package/tools/scan/tests/__init__.py +1 -0
  605. package/tools/scan/tests/conftest.py +796 -0
  606. package/tools/scan/tests/test_environment.py +323 -0
  607. package/tools/scan/tests/test_git.py +419 -0
  608. package/tools/scan/tests/test_infrastructure.py +382 -0
  609. package/tools/scan/tests/test_integration.py +920 -0
  610. package/tools/scan/tests/test_merge.py +269 -0
  611. package/tools/scan/tests/test_orchestration.py +304 -0
  612. package/tools/scan/tests/test_stack.py +604 -0
  613. package/tools/scan/tests/test_tools.py +349 -0
  614. package/tools/scan/ui.py +624 -0
  615. package/tools/scan/verify.py +270 -0
  616. package/tools/scan/walk.py +118 -0
  617. package/tools/scan/workspace.py +85 -0
  618. package/tools/validation/README.md +244 -0
  619. package/tools/validation/__init__.py +17 -0
  620. package/tools/validation/approval_gate.py +321 -0
  621. package/tools/validation/validate_skills.py +189 -0
package/dist/gaia-ops/skills/gmail-policy/reference.md ADDED
@@ -0,0 +1,150 @@
1
+ # Gmail Policy -- Technical Reference
2
+
3
+ Patterns learned from live sessions. Load this file when constructing drafts, encoding messages, or debugging `gws` command failures.
4
+
5
+ ## Draft Creation: Correct Schema
6
+
7
+ Three failed attempts taught this: `gws gmail users drafts create` has a specific parameter split that looks wrong but is correct.
8
+
9
+ ```bash
10
+ gws gmail users drafts create \
11
+ --params '{"userId":"me"}' \
12
+ --json '{"message":{"threadId":"<THREAD_ID>","raw":"<BASE64URL>"}}'
13
+ ```
14
+
15
+ - `--params` carries only `userId` (query parameter, not body)
16
+ - `--json` carries the request body with `message` as the top-level key -- no `resource` wrapper
17
+ - `raw` is the full RFC 2822 message encoded as **base64url** (not standard base64)
18
+ - `threadId` is optional but required to link the draft into an existing thread
19
+
20
+ Wrong patterns that look right but fail:
21
+ - `--params '{"userId":"me","message":{...}}'` -- message does not belong in params
22
+ - `--json '{"resource":{"message":{...}}}'` -- no resource wrapper in this API
23
+ - Standard base64 in raw -- Gmail rejects it; must be base64url
24
+
25
+ ## Base64url Encoding Pipeline (Shell Only)
26
+
27
+ Avoids a Python T3 approval for a simple transform:
28
+
29
+ ```bash
30
+ RAW=$(base64 -w 0 /tmp/reply.eml | tr '+/' '-_' | tr -d '=')
31
+ ```
32
+
33
+ - `base64 -w 0` disables line wrapping (required -- Gmail rejects newlines mid-string)
34
+ - `tr '+/' '-_'` converts standard base64 alphabet to URL-safe alphabet
35
+ - `tr -d '='` strips padding (Gmail requires no padding)
36
+
37
+ The result goes directly into the `raw` field of `--json`.
38
+
39
+ If writing the `.eml` first via the Write tool, then encode with the pipeline above. This is T0 (read-only transformation).
40
+
41
+ ## RFC 2822 Reply Construction
42
+
43
+ Minimum headers for a threading-aware reply:
44
+
45
+ ```
46
+ From: Nombre Apellido <email@example.com>
47
+ To: recipient@example.com
48
+ Subject: Re: Asunto Original
49
+ In-Reply-To: <message-id-of-the-message-being-replied-to@mail.gmail.com>
50
+ References: <message-id-1@...> <message-id-2@...>
51
+ MIME-Version: 1.0
52
+ Content-Type: text/plain; charset=UTF-8
53
+ Content-Transfer-Encoding: 8bit
54
+
55
+ Cuerpo del mensaje.
56
+ ```
57
+
58
+ For Spanish content with accents and UTF-8: `Content-Transfer-Encoding: 8bit` works correctly. Do not use quoted-printable for Spanish -- it creates unnecessary encoding noise.
59
+
60
+ `In-Reply-To` and `References` must use the raw `Message-ID` value from `gws gmail users messages get` -- it looks like `<some-long-hex@mail.gmail.com>` including the angle brackets.
61
+
62
+ ### HTML Reply Template with Gmail Quote Collapse
63
+
64
+ For replies where visual quality matters (external recipients, business correspondence):
65
+
66
+ ```
67
+ From: {{SENDER_NAME}} <{{SENDER_EMAIL}}>
68
+ To: {{RECIPIENT_EMAIL}}
69
+ Subject: Re: {{ORIGINAL_SUBJECT}}
70
+ In-Reply-To: <{{ORIGINAL_MESSAGE_ID}}>
71
+ References: <{{ORIGINAL_MESSAGE_ID}}>
72
+ MIME-Version: 1.0
73
+ Content-Type: multipart/alternative; boundary="----=_Part_boundary_001"
74
+
75
+ ------=_Part_boundary_001
76
+ Content-Type: text/plain; charset=UTF-8
77
+
78
+ {{PLAINTEXT_BODY}}
79
+
80
+ --
81
+ {{SENDER_NAME}}
82
+
83
+ > {{QUOTED_ORIGINAL_TEXT_SINGLE_LINE_SUMMARY}}
84
+
85
+ ------=_Part_boundary_001
86
+ Content-Type: text/html; charset=UTF-8
87
+
88
+ <html>
89
+ <body>
90
+ <p>{{HTML_BODY_PARAGRAPH_1}}</p>
91
+ <p>{{HTML_BODY_PARAGRAPH_2}}</p>
92
+ <br>
93
+ -- <br>
94
+ {{SENDER_NAME}}<br>
95
+ <br>
96
+ <div class="gmail_quote">
97
+ <div dir="ltr">On {{ORIGINAL_DATE}}, {{ORIGINAL_SENDER}} wrote:</div>
98
+ <blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
99
+ {{QUOTED_ORIGINAL_HTML}}
100
+ </blockquote>
101
+ </div>
102
+ </body>
103
+ </html>
104
+
105
+ ------=_Part_boundary_001--
106
+ ```
107
+
108
+ Key points:
109
+ - The `<div class="gmail_quote"><blockquote class="gmail_quote" style="...">` wrapper is what Gmail collapses into the "..." toggle. Without it, quoted text renders as a wall of plain text.
110
+ - Signature separator: `-- \n` (dash-dash-space-newline per RFC 3676). In HTML: `-- <br>`.
111
+ - The boundary string must match exactly between the `Content-Type` header and the body part delimiters (including the `------` prefix with 6 hyphens).
112
+
113
+ ## Multi-Source Data Lookup: Real Examples
114
+
115
+ These examples are from an actual Assetplan session (2026-04-17). They show how connecting threads avoids asking the user for data they have already shared elsewhere.
116
+
117
+ | Data needed | Where it was found |
118
+ |-------------|-------------------|
119
+ | RUT | Thread from Colmena (health insurance) -- appeared in a form confirmation |
120
+ | Property address (depto arrendado) | Thread from Samuel Aranda (previous property manager) |
121
+ | Contrato de arrendamiento | Thread from Condominio Evolución -- PDF attachment |
122
+ | m² and property details | PDF notarial (Tasación) attached to mortgage thread |
123
+ | DOB and civil status | PDF notarial (Compraventa / Hipoteca) |
124
+
125
+ Search pattern: before asking the user for any datum, run a targeted `gws gmail +search` for the topic. Examples:
126
+ - RUT: `gws gmail +search "RUT OR cédula OR 12.345"` (use known name patterns)
127
+ - Address: `gws gmail +search "{{street name}} OR {{condo name}}"`
128
+ - Contract: `gws gmail +search "contrato arrendamiento"`
129
+
130
+ If found, cite the source to the user ("Tu dirección la saqué del correo de Samuel Aranda de marzo 2025.").
131
+
132
+ ## Draft Verification
133
+
134
+ After `gws gmail users drafts create`, always verify:
135
+
136
+ ```bash
137
+ gws gmail users drafts list --params '{"userId":"me"}'
138
+ ```
139
+
140
+ Report to the user: draft ID, threadId (if linked), and snippet. This closes the loop and confirms the API call succeeded. Do not just assume the create worked.
141
+
142
+ ## PII Cleanup Protocol
143
+
144
+ After a draft is created from a `.eml` file containing sensitive data:
145
+
146
+ 1. Delete the `.eml`: `rm /tmp/reply.eml` (T3 -- file mutation, but within PII hygiene flow)
147
+ 2. Verify deletion with Glob: `Glob /tmp/*.eml`
148
+ 3. Report: "Archivo temporal eliminado."
149
+
150
+ Sensitive data includes: RUT, número de cuenta bancaria, teléfono, DOB, dirección física, números de contrato, número de pasaporte.
package/dist/gaia-ops/skills/gmail-triage/SKILL.md ADDED
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: gmail-triage
3
+ description: Use when the user wants to clean up, organize, or triage their Gmail inbox interactively
4
+ metadata:
5
+ user-invocable: false
6
+ type: technique
7
+ ---
8
+
9
+ # Gmail Triage
10
+
11
+ Interactive GTD-inspired state machine for Gmail. Gaia analyzes threads, proposes transitions. User decides. Gaia executes. The `gmail-policy` skill governs allowed operations and label definitions.
12
+
13
+ ## State Labels
14
+
15
+ Four active states (defined in `gmail-policy`):
16
+ - `_gaia/action` — user must act
17
+ - `_gaia/waiting` — user acted, awaiting reply
18
+ - `_gaia/someday` — interesting, no urgency
19
+ - `_gaia/pending` — staging (triage backlog)
20
+ - `_gaia/trash` — soft delete; never truly deleted
21
+
22
+ No `_gaia/*` label = processed/done.
23
+
24
+ ## Thread-Awareness Rule
25
+
26
+ Before presenting ANY labeled email, check the thread: message count, who sent last, when. This determines framing:
27
+ - "necesitas responder" (user is last)
28
+ - "esperando desde [date]" (user replied, waiting on them)
29
+ - "sin actividad hace 2 semanas — ¿hacer seguimiento?" (stale waiting)
30
+
31
+ ## Automatic Transitions (no confirmation needed)
32
+
33
+ - User replies to an `action` thread → move to `waiting`
34
+ - New message arrives in a `waiting` thread → move to `action`
35
+
36
+ ## Transitions Requiring Confirmation
37
+
38
+ - Anything → `trash` or `someday`
39
+ - Clearing any label (marking done)
40
+ - `someday` → `action`
41
+
42
+ ## Modes
43
+
44
+ **Modes 1–5 open with a state summary before their specific work:**
45
+ "Antes de empezar: N en action, N en waiting, N en someday." Flag `action` items stale >3 days.
46
+
47
+ ### 0. Check ("chequea mi mail" / "¿algo nuevo?")
48
+
49
+ 1. **Review `_gaia/action`** — present each item with thread framing. Did user already reply? Auto-propose → `waiting`.
50
+ 2. **Review `_gaia/waiting`** — did the other party respond? Auto-propose → `action`. Stale >1 week → flag.
51
+ 3. **Review `_gaia/someday`** — count only: "tienes 5 en someday." Detail only if asked.
52
+ 4. **Scan inbox for new signal** — Financial (large amounts, bills, due dates), personal/important (housing, legal, health), expected reply arrived → propose `action`. Interesting, no urgency → propose `someday`.
53
+ 5. **Summarize** — overall inbox state in 2-3 sentences.
54
+
55
+ ### 1. Full Triage ("organicemos el correo")
56
+
57
+ Scan inbox, group by sender/category, report counts. Present top groups. User decides per group → trash/action/someday/content-label. Report progress: "Procesamos 500 de 2000. ¿Seguimos?"
58
+
59
+ ### 2. Quick Cleanup ("limpiemos algo rápido")
60
+
61
+ Pick easiest batch (highest volume, most repetitive). "340 promos de retail. ¿Las mando a trash?" One confirmation = hundreds processed. Target: under 2 minutes.
62
+
63
+ ### 3. Post-Vacation ("acumulé mucho")
64
+
65
+ Move unprocessed to `_gaia/pending`. Report: "847 correos: 600 promos, 120 banco, 80 LinkedIn, 47 otros." Work categories in follow-up modes.
66
+
67
+ ### 4. Review ("¿qué tengo pendiente?")
68
+
69
+ Dedicated state review — all three active labels:
70
+ - `_gaia/action` — stale >3 days? move to waiting/someday/done?
71
+ - `_gaia/waiting` — any responses arrived? stale >1 week?
72
+ - `_gaia/someday` — weekly review: promote to action? trash any?
73
+
74
+ ### 5. Promo Analysis ("analiza las promos")
75
+
76
+ Group by sender, identify patterns. Flag genuinely interesting vs noise. Recommend bulk trash for repetitive senders.
77
+
78
+ ## Presentation Format
79
+
80
+ Group by sender/topic. Show count + sample subject. Flag unusual items ("movimiento de $50K en Bci"). Propose action per group. Max 5-7 groups per interaction.
81
+
82
+ ## Batch Rules
83
+
84
+ - Max 500 emails per API call. Always confirm before moving: state count and destination.
85
+ - After each batch: "Moví X a trash, Y a action. Z restantes."
86
+ - On "todo trash": double-check — "¿Seguro? Son N correos de [sender]."
87
+
88
+ ## Anti-Patterns
89
+
90
+ - Listing individual emails when hundreds exist — group first, detail on request.
91
+ - Moving without explicit confirmation — `removeLabelIds` changes visibility with no undo.
92
+ - Auto-processing `_gaia/trash` — it is the user's safety net, not Gaia's to manage.
93
+ - Assuming promos are trash — some are genuinely interesting. Always ask.
94
+ - Skipping thread check before presenting — framing without thread state misleads the user.
95
+ - More than 5-7 groups per round — decision fatigue kills triage momentum.
96
+
97
+ ## Related Skills
98
+
99
+ - `gmail-policy` — security rules, label definitions, operation tiers
100
+ - `gws-setup` — CLI installation and authentication
package/dist/gaia-ops/skills/gws-setup/SKILL.md ADDED
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: gws-setup
3
+ description: Use when installing or configuring the Google Workspace CLI (gws) for a Google account
4
+ metadata:
5
+ user-invocable: false
6
+ type: technique
7
+ ---
8
+
9
+ # GWS Setup
10
+
11
+ The gws CLI looks straightforward but breaks in subtle ways -- Google's OAuth flow has undocumented constraints that differ between personal and organizational accounts, and the gws tool itself has open bugs around scopes and multi-account. This procedure captures the working path and the traps discovered through real setup sessions, so you avoid the silent failures that waste hours.
12
+
13
+ **Prerequisites:** gcloud CLI installed, browser access for OAuth, interactive terminal for auth steps.
14
+
15
+ ## Procedure
16
+
17
+ ### 1. Install gws binary
18
+
19
+ - Download latest Linux x86_64 from https://github.com/googleworkspace/cli/releases
20
+ - Place in `~/.local/bin/`, `chmod +x`
21
+ - Verify: `gws --version`
22
+
23
+ ### 2. Add Google account to gcloud
24
+
25
+ - `gcloud auth login <email> --no-launch-browser` (interactive terminal required)
26
+ - This adds alongside existing accounts -- does NOT replace them
27
+ - After login, restore work account: `gcloud config set account <work-account>`
28
+
29
+ ### 3. Create or select GCP project
30
+
31
+ - Check existing: `gcloud projects list --account=<email>`
32
+ - Create new: `gcloud projects create gaia-<name> --name="Gaia <Name>" --account=<email>`
33
+ - Naming: `gaia-<identifier>-personal` or `gaia-<identifier>-work`
34
+
35
+ ### 4. gws auth setup
36
+
37
+ - `gws auth setup --project <project-id>`
38
+ - TRAP: When selecting scopes, DO NOT use presets ("Recommended" or "Read Only") -- they include organizational scopes that break for @gmail.com accounts
39
+
40
+ ### 5. Scope selection (CRITICAL)
41
+
42
+ For safe scopes and blocked scopes by account type, read `reference.md` in this directory.
43
+
44
+ Known bug: gws issue #119 -- `gws auth login` unusable with personal @gmail.com when organizational scopes are included. Google returns `400: invalid_scope`.
45
+
46
+ ### 6. OAuth consent screen (manual in browser)
47
+
48
+ - URL: `https://console.cloud.google.com/apis/credentials/consent?project=<project-id>`
49
+ - User Type: External | App name: gws CLI | Support email: the account email
50
+ - TRAP: Add the account as a Test User BEFORE attempting login
51
+ - Test Users section -> Add Users -> enter the email
52
+ - Without this, Google returns `403: access_denied` ("app not verified")
53
+
54
+ ### 7. OAuth client (manual in browser)
55
+
56
+ - URL: `https://console.cloud.google.com/apis/credentials?project=<project-id>`
57
+ - TRAP: Application type must be **Desktop app** (NOT "Web application")
58
+ - Web application type causes `401: invalid_client`
59
+ - Download `client_secret_*.json` -> save to `~/.config/gws/client_secret.json`
60
+
61
+ ### 8. gws auth login
62
+
63
+ - `gws auth login` -- opens browser for OAuth consent (interactive terminal required)
64
+ - If Google shows "app not verified" warning -> click "Advanced" -> "Go to gws-cli (unsafe)" -- safe for personal use
65
+
66
+ ### 9. Verification
67
+
68
+ - `gws auth status` -- confirm token valid
69
+ - `gws gmail users messages list --params '{"userId":"me","maxResults":5}'` -- test Gmail
70
+ - `gws gmail users labels list --params '{"userId":"me"}'` -- test labels
71
+
72
+ ### 10. Restore gcloud
73
+
74
+ - `gcloud config set account <original-work-account>`
75
+ - Verify: `gcloud config get account`
76
+
77
+ ## Multi-account (future)
78
+
79
+ gws supports multi-account via `gws auth login --account <email>`, `gws auth list`, `gws auth default <email>`, `gws --account <email> <command>`.
80
+
81
+ Known bug: issue #181 -- `--account` flag doesn't work correctly yet.
82
+
83
+ ## Anti-Patterns
84
+
85
+ - Using scope presets for personal @gmail.com -- causes `400: invalid_scope`
86
+ - Skipping Test User in OAuth consent screen -- causes `403: access_denied`
87
+ - Choosing "Web application" as OAuth client type -- causes `401: invalid_client`
88
+ - Forgetting to restore `gcloud config set account` after setup
89
+ - Including `admin.*`, `cloud-identity.*`, or `directory.*` scopes for personal accounts
90
+
91
+ ## Related Skills
92
+
93
+ - `gmail-policy` -- operational Gmail security (tiers, labels, no-delete rule)
94
+
95
+ ## References
96
+
97
+ - https://github.com/googleworkspace/cli
98
+ - https://github.com/googleworkspace/cli/issues/119 (personal account scope bug)
99
+ - https://github.com/googleworkspace/cli/issues/181 (multi-account bug)
package/dist/gaia-ops/skills/gws-setup/reference.md ADDED
@@ -0,0 +1,73 @@
1
+ # GWS Setup Reference
2
+
3
+ Heavy reference material for the `gws-setup` skill. Read on-demand during scope selection and command authoring.
4
+
5
+ ## Safe Scopes (personal @gmail.com)
6
+
7
+ | Scope | Purpose |
8
+ |-------|---------|
9
+ | `gmail.modify` | Read, send, label messages (no delete) |
10
+ | `gmail.readonly` | Read-only Gmail access |
11
+ | `gmail.labels` | Manage labels |
12
+ | `drive.readonly` | Read-only Drive access |
13
+ | `drive.metadata.readonly` | Read Drive file metadata |
14
+ | `drive.file` | Access files created by the app |
15
+ | `calendar.readonly` | Read-only Calendar access |
16
+ | `calendar.events.readonly` | Read calendar events |
17
+ | `contacts.readonly` | Read-only Contacts access |
18
+ | `tasks` | Manage Tasks |
19
+ | `userinfo.email` | Read email address |
20
+ | `userinfo.profile` | Read basic profile |
21
+ | `cloud-platform` | GCP platform access -- granted and working |
22
+
23
+ ## Blocked Scopes (organizational / enterprise only)
24
+
25
+ NEVER select these for personal @gmail.com accounts:
26
+
27
+ | Scope | Reason |
28
+ |-------|--------|
29
+ | `admin.*` | Google Workspace admin only |
30
+ | `cloud-identity.*` | Organizational accounts only |
31
+ | `classroom.*` | Google Classroom (educational) |
32
+ | `ediscovery.*` | Enterprise Vault only |
33
+ | `directory.*` | Organizational directory only |
34
+
35
+ Including any of these causes `400: invalid_scope` for personal accounts (gws issue #119).
36
+
37
+ ## Command Syntax
38
+
39
+ All gws gmail commands require the `userId` parameter:
40
+
41
+ ```bash
42
+ # List messages
43
+ gws gmail users messages list --params '{"userId":"me","maxResults":N}'
44
+
45
+ # List labels
46
+ gws gmail users labels list --params '{"userId":"me"}'
47
+
48
+ # Create label
49
+ gws gmail users labels create --params '{"userId":"me"}' --json '{"name":"label-name"}'
50
+
51
+ # Get message
52
+ gws gmail users messages get --params '{"userId":"me","id":"<message-id>"}'
53
+
54
+ # Modify message labels
55
+ gws gmail users messages modify --params '{"userId":"me","id":"<message-id>"}' --json '{"addLabelIds":["LABEL_ID"]}'
56
+ ```
57
+
58
+ ## Credential Paths
59
+
60
+ | File | Path | Notes |
61
+ |------|------|-------|
62
+ | Client secret | `~/.config/gws/client_secret.json` | Downloaded from GCP console |
63
+ | Encrypted credentials | `~/.config/gws/credentials.enc` | Created by `gws auth login` |
64
+ | Encryption | AES-256-GCM | Key stored in OS keyring |
65
+
66
+ ## Error Quick Reference
67
+
68
+ | Error | Cause | Fix |
69
+ |-------|-------|-----|
70
+ | `400: invalid_scope` | Organizational scope on personal account | Remove blocked scopes, re-run `gws auth setup` |
71
+ | `403: access_denied` | Missing Test User in OAuth consent | Add email to Test Users in GCP console |
72
+ | `401: invalid_client` | Wrong OAuth client type | Recreate as "Desktop app", not "Web application" |
73
+ | `403: app not verified` | Normal for dev apps | Click "Advanced" -> "Go to gws-cli (unsafe)" |
package/dist/gaia-ops/skills/investigation/SKILL.md ADDED
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: investigation
3
+ description: Use when starting an investigation, analyzing existing code or infrastructure, or building findings before proposing changes
4
+ metadata:
5
+ user-invocable: false
6
+ type: technique
7
+ ---
8
+
9
+ # Investigation
10
+
11
+ Every codebase is a record of accumulated decisions. Investigation
12
+ is not a prerequisite you rush through — it is the most important part.
13
+ The first 2-3 files you read define whether your solution fits or
14
+ fights the project.
15
+
16
+ ## Phase 1: Start From Injected Context
17
+
18
+ Before your first tool call, extract anchors from your injected
19
+ Project Context: paths, service names, resource IDs. These are
20
+ your starting point — go directly to them.
21
+
22
+ Define what you need to know that the context does NOT answer.
23
+ Those are your unknowns.
24
+
25
+ ## Phase 2: Explore Known Paths
26
+
27
+ For each path or name from context:
28
+ - Read the file or directory directly — no Glob needed
29
+ - Read 2-3 similar existing resources to understand conventions
30
+ - Extract: naming patterns, directory structure, dependencies
31
+
32
+ If context includes an `investigation_brief`, use it to prioritize
33
+ your surface, adjacent surfaces, and required checks.
34
+
35
+ ## Phase 3: Discover Unknowns
36
+
37
+ Search only for things NOT covered by context. Use Glob and Grep.
38
+
39
+ After initial evidence, check adjacency:
40
+ - **Neighbors:** Files next to your target often explain constraints
41
+ - **References:** What references this resource? What does it reference?
42
+ - **Breadth:** Find 2-3 instances of the same pattern. One example is
43
+ anecdote; three are convention.
44
+
45
+ Stop when new files confirm what you already know.
46
+
47
+ ## Phase 4: Live State
48
+
49
+ Only if drift is suspected or the task needs runtime data. Use `fast-queries` triage first.
50
+
51
+ ## Phase 5: Pattern Hierarchy
52
+
53
+ Apply in order — do not skip levels:
54
+
55
+ 1. **Codebase first** — Find 2-3 existing resources of the same type.
56
+ If found, follow them. Consistency beats preference.
57
+ This applies to every resource your plan touches — including
58
+ prerequisites and dependencies, not just your primary deliverable.
59
+ 2. **Domain skill** — If no codebase pattern, use your domain skill
60
+ (terraform-patterns, gitops-patterns, etc.)
61
+ 3. **Training knowledge** — Last resort. Mark explicitly:
62
+ *"No existing pattern found — applying best practices."*
63
+
64
+ When following patterns: **COPY** names/paths exactly.
65
+ When a pattern is problematic: **ALERT** as DEVIATION, propose alternative.
66
+
67
+ ## Phase 6: Validate Before Proposing
68
+
69
+ Before proposing, test your plan against what you found: for each
70
+ action that creates, modifies, or deletes a resource, did your
71
+ investigation reveal how the project manages that resource type?
72
+ If so, your action must use the same mechanism. If a prerequisite
73
+ falls outside your scope, report it as a dependency rather than
74
+ solving it yourself.
75
+
76
+ - Does code agree with project-context? If not → investigate drift
77
+ - Uncertain about correctness? → one more read-only validation
78
+ - Multiple valid approaches? → list options, set status `NEEDS_INPUT`
79
+
80
+ Separate what is **confirmed** (seen in code, validated) from what
81
+ is **assumed** (inferred). Never propose on assumptions.
82
+
83
+ ## Anti-Patterns
84
+
85
+ - **Searching before reading context.** Your injected context already has
86
+ paths and names. Searching for what you have wastes tool calls.
87
+ - **Planning before resolving unknowns.** A plan built on assumptions
88
+ collapses when reality disagrees. Find contradictions early.
89
+ - **Treating training knowledge as codebase convention.** The codebase
90
+ says "we do Y" -- consistency within the project matters more than
91
+ abstract best practice from your training.
92
+ - **Skipping investigation because the prompt is specific.** The orchestrator
93
+ does not see the codebase. When instructions contradict code, code wins.
94
+ - **Creating files before reading existing examples.** Without seeing how
95
+ the project structures similar resources, your output looks foreign.
96
+ - **Solving prerequisites by the fastest path instead of the project's
97
+ path.** When your task needs a resource that doesn't exist yet, the
98
+ temptation is to create it with whatever tool is quickest. But if
99
+ investigation showed the project manages that resource type through a
100
+ specific mechanism, bypassing it creates drift. Report the dependency.
package/dist/gaia-ops/skills/memory-curation/SKILL.md ADDED
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: memory-curation
3
+ description: Use when reorganizing, deduplicating, or pruning accumulated memory files and the MEMORY.md index
4
+ metadata:
5
+ user-invocable: false
6
+ type: reference
7
+ ---
8
+
9
+ # Memory Curation
10
+
11
+ Organize and maintain memory files that Claude Code saves natively. This skill does not cover creating or searching memory -- only curating what already exists.
12
+
13
+ ## Memory Structure
14
+
15
+ Memory lives at `~/.claude/projects/{project-slug}/memory/`.
16
+
17
+ | Component | Purpose |
18
+ |-----------|---------|
19
+ | `MEMORY.md` | Index file -- table of all memory files with descriptions |
20
+ | `{type}_{topic}.md` | Individual memory files, one per topic |
21
+
22
+ ## File Format
23
+
24
+ Every memory file has YAML frontmatter and markdown body:
25
+
26
+ ```yaml
27
+ ---
28
+ name: project_gaia_v5
29
+ description: Gaia v5 architecture decisions
30
+ type: project
31
+ ---
32
+ ```
33
+
34
+ | Type | Purpose | Example |
35
+ |------|---------|---------|
36
+ | `project` | Repo/system knowledge | `project_gaia_v5.md` |
37
+ | `user` | Personal preferences | `user_blog_articles.md` |
38
+ | `feedback` | Corrections/learnings | `feedback_terraform_style.md` |
39
+
40
+ ## Curation Operations
41
+
42
+ ### Index Integrity
43
+
44
+ MEMORY.md must reflect actual files. To reconcile:
45
+
46
+ 1. Scan the memory directory for all `.md` files (excluding MEMORY.md itself)
47
+ 2. Compare against the index table rows
48
+ 3. Add missing files to the index; remove rows for deleted files
49
+ 4. Update descriptions that no longer match the file's actual content
50
+
51
+ ### Deduplication
52
+
53
+ 1. Read all memory files and identify overlapping topics
54
+ 2. Merge content into the file with the broader scope
55
+ 3. Delete the narrower file
56
+ 4. Update the index
57
+
58
+ ### Pruning Stale Entries
59
+
60
+ 1. Identify entries that reference outdated projects, deprecated tools, or resolved decisions
61
+ 2. Remove or archive the stale content
62
+ 3. Update the index
63
+
64
+ ### Merging Overlapping Topics
65
+
66
+ 1. When two files cover adjacent concerns, merge into one with a clear scope
67
+ 2. Choose the name that best represents the combined topic
68
+ 3. Update frontmatter description to reflect the merged scope
69
+ 4. Delete the redundant file and update the index
70
+
71
+ ### Splitting Overgrown Files
72
+
73
+ When a file exceeds ~100 lines, split into focused subtopics. Create one file per subtopic, update the index for each.
74
+
75
+ ## Rules
76
+
77
+ | Rule | Reason |
78
+ |------|--------|
79
+ | Always update index and files together | Prevents drift between MEMORY.md and actual files |
80
+ | One topic per file | Split if a file outgrows its scope |
81
+ | Frontmatter required | Every file needs name, description, type in YAML frontmatter |
82
+ | Conciseness | Memory files are scannable references -- tables, bullets, short sections |
83
+ | Confirm before deleting | Report what will be pruned/merged and get user confirmation |