@chankov/agent-fleet 2.0.7 → 2.0.8

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 (619) hide show
  1. package/{hermes → .pi/agent-fleet/hermes}/README.md +7 -7
  2. package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/activity.py +2 -2
  3. package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/coms_registry.py +2 -2
  4. package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/coms_send.py +1 -1
  5. package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/watch.py +2 -2
  6. package/{hermes → .pi/agent-fleet/hermes}/skills/hub-conductor/SKILL.md +1 -1
  7. package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/SKILL.md +3 -3
  8. package/{hooks → .pi/agent-fleet/hooks}/coms-stop-hook.mjs +2 -2
  9. package/{scripts → .pi/agent-fleet/scripts}/claude-code-preflight.ts +1 -1
  10. package/{scripts → .pi/agent-fleet/scripts}/coms-claude-bridge.ts +6 -6
  11. package/{scripts → .pi/agent-fleet/scripts}/coms-cli.ts +1 -1
  12. package/{scripts → .pi/agent-fleet/scripts}/coms-hermes-bridge.ts +1 -1
  13. package/{scripts → .pi/agent-fleet/scripts}/fleet-codex-read.py +5 -3
  14. package/{scripts → .pi/agent-fleet/scripts}/fleet.ts +1 -1
  15. package/{scripts → .pi/agent-fleet/scripts}/flow.ts +1 -1
  16. package/{scripts → .pi/agent-fleet/scripts}/lib/claude-bridge-core.ts +2 -2
  17. package/{scripts → .pi/agent-fleet/scripts}/lib/coms-envelope.ts +1 -1
  18. package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-transport.ts +1 -1
  19. package/{scripts → .pi/agent-fleet/scripts}/lib/herdr-layout.ts +3 -3
  20. package/{scripts → .pi/agent-fleet/scripts}/lib/hermes-bridge-core.ts +1 -1
  21. package/.pi/agent-fleet/scripts/lib/hermes-monitor-events.ts +1 -0
  22. package/.pi/agent-fleet/scripts/lib/hermes-monitor-herdr.ts +2 -0
  23. package/{scripts → .pi/agent-fleet/scripts}/lib/hermes-monitor-model.ts +1 -1
  24. package/.pi/agent-fleet/scripts/lib/hermes-monitor-registry.ts +2 -0
  25. package/.pi/agent-fleet/scripts/lib/hermes-monitor-socket.ts +2 -0
  26. package/.pi/agent-fleet/scripts/lib/hermes-monitor-store.ts +2 -0
  27. package/{scripts → .pi/agent-fleet/scripts}/lib/monitor-env.ts +1 -1
  28. package/{scripts → .pi/agent-fleet/scripts}/lib/peer-launch.ts +3 -3
  29. package/{scripts → .pi/agent-fleet/scripts}/lib/persona-banner.ts +1 -1
  30. package/.pi/agent-fleet/scripts/lib/persona-dirs.ts +25 -0
  31. package/{scripts → .pi/agent-fleet/scripts}/lib/runtime-dependencies.js +1 -1
  32. package/{scripts → .pi/agent-fleet/scripts}/lib/spawn-stagger.ts +1 -1
  33. package/{scripts → .pi/agent-fleet/scripts}/lib/team-project.ts +1 -1
  34. package/{scripts → .pi/agent-fleet/scripts}/lib/team-snapshot.ts +2 -2
  35. package/{scripts → .pi/agent-fleet/scripts}/peer-banner.ts +5 -4
  36. package/{scripts → .pi/agent-fleet/scripts}/peer-launch.ts +7 -9
  37. package/{scripts → .pi/agent-fleet/scripts}/team-snapshot.ts +5 -5
  38. package/{scripts → .pi/agent-fleet/scripts}/team-up.ts +6 -6
  39. package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/agent-phase.ts +3 -3
  40. package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/envelopes.ts +1 -1
  41. package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/model-profile.ts +1 -1
  42. package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/personas.ts +2 -2
  43. package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/trace.ts +1 -1
  44. package/.pi/agents/peers.yaml +3 -1
  45. package/.pi/harnesses/agent-hub/README.md +1 -1
  46. package/.pi/harnesses/agent-hub/config/agents.ts +5 -1
  47. package/.pi/harnesses/agent-hub/debate-command.ts +1 -1
  48. package/.pi/harnesses/agent-hub/index.ts +19 -19
  49. package/.pi/harnesses/agent-hub/package.json +1 -1
  50. package/.pi/harnesses/agent-hub/peer-spawn-plan.ts +1 -1
  51. package/.pi/harnesses/agent-hub/tools/fleet-tools.ts +3 -5
  52. package/.pi/harnesses/agent-hub/tools/herdr-executors.ts +2 -2
  53. package/.pi/harnesses/ask-user-remote/index.ts +2 -2
  54. package/.pi/harnesses/coms/package.json +1 -1
  55. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  56. package/.pi/harnesses/lib/spawned-peers.js +1 -1
  57. package/.pi/prompts/af-constraints.md +31 -0
  58. package/.versions/2.0.8/.pi/agent-fleet/hermes/README.md +347 -0
  59. package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  60. package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  61. package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  62. package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  63. package/.versions/2.0.8/.pi/agent-fleet/hermes/gates/gate-o-capability.md +8 -0
  64. package/.versions/2.0.8/.pi/agent-fleet/hermes/gates/gate-o-validator-fixtures.json +1 -0
  65. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +773 -0
  66. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  67. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  68. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  69. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  70. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  71. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  72. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  73. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  74. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  75. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  76. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  77. package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  78. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-conductor/SKILL.md +84 -0
  79. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-liaison/SKILL.md +84 -0
  80. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/SKILL.md +76 -0
  81. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/manifest.json +1 -0
  82. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  83. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  84. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  85. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  86. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  87. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  88. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  89. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  90. package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  91. package/.versions/2.0.8/.pi/agent-fleet/hermes/watchdog-tests/__init__.py +0 -0
  92. package/.versions/2.0.8/.pi/agent-fleet/hooks/coms-stop-hook.mjs +84 -0
  93. package/.versions/2.0.8/.pi/agent-fleet/scripts/claude-code-preflight.ts +70 -0
  94. package/.versions/2.0.8/.pi/agent-fleet/scripts/coms-claude-bridge.ts +411 -0
  95. package/.versions/2.0.8/.pi/agent-fleet/scripts/coms-cli.ts +425 -0
  96. package/.versions/2.0.8/.pi/agent-fleet/scripts/coms-hermes-bridge.ts +413 -0
  97. package/.versions/2.0.8/.pi/agent-fleet/scripts/fleet-codex-client.ts +69 -0
  98. package/.versions/2.0.8/.pi/agent-fleet/scripts/fleet-codex-read.py +148 -0
  99. package/.versions/2.0.8/.pi/agent-fleet/scripts/fleet.ts +216 -0
  100. package/.versions/2.0.8/.pi/agent-fleet/scripts/flow.ts +137 -0
  101. package/.versions/2.0.8/.pi/agent-fleet/scripts/hermes-monitor-capability-runner.ts +25 -0
  102. package/.versions/2.0.8/.pi/agent-fleet/scripts/hermes-monitor-scenario.ts +474 -0
  103. package/.versions/2.0.8/.pi/agent-fleet/scripts/hermes-watchdog-capability-probe.ts +45 -0
  104. package/.versions/2.0.8/.pi/agent-fleet/scripts/install-hermes-plugin.sh +180 -0
  105. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/claude-bridge-core.ts +210 -0
  106. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/coms-envelope.ts +582 -0
  107. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fake-herdr-server.ts +88 -0
  108. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-catalog.ts +63 -0
  109. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-operations.ts +190 -0
  110. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-session.ts +166 -0
  111. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-transport.ts +124 -0
  112. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-command.ts +252 -0
  113. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/flow-command.ts +93 -0
  114. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/flow-maintenance.ts +230 -0
  115. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/herdr-layout.ts +281 -0
  116. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-bridge-core.ts +241 -0
  117. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-events.ts +1 -0
  118. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-herdr.ts +2 -0
  119. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-model.ts +3 -0
  120. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-registry.ts +2 -0
  121. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-socket.ts +2 -0
  122. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-store.ts +2 -0
  123. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/monitor-env.ts +146 -0
  124. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/peer-launch.ts +318 -0
  125. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/persona-banner.ts +62 -0
  126. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/persona-dirs.ts +25 -0
  127. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/runtime-dependencies.js +124 -0
  128. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/spawn-stagger.ts +101 -0
  129. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/team-project.ts +178 -0
  130. package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/team-snapshot.ts +147 -0
  131. package/.versions/2.0.8/.pi/agent-fleet/scripts/package-lock.json +35 -0
  132. package/.versions/2.0.8/.pi/agent-fleet/scripts/package.json +9 -0
  133. package/.versions/2.0.8/.pi/agent-fleet/scripts/peer-banner.ts +41 -0
  134. package/.versions/2.0.8/.pi/agent-fleet/scripts/peer-launch.ts +283 -0
  135. package/.versions/2.0.8/.pi/agent-fleet/scripts/team-snapshot.ts +237 -0
  136. package/.versions/2.0.8/.pi/agent-fleet/scripts/team-up.ts +378 -0
  137. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/agent-phase.ts +133 -0
  138. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/changes.ts +61 -0
  139. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/debate.ts +149 -0
  140. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/env.ts +34 -0
  141. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/envelopes.ts +169 -0
  142. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/gates.ts +81 -0
  143. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/git.ts +96 -0
  144. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/merge.ts +95 -0
  145. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/model-profile.ts +22 -0
  146. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/model-visibility.ts +92 -0
  147. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/permissions.ts +130 -0
  148. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/personas.ts +57 -0
  149. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/poll.ts +86 -0
  150. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/quality.ts +64 -0
  151. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/run.ts +108 -0
  152. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/trace.ts +34 -0
  153. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/voices.ts +128 -0
  154. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/writer-lease.ts +112 -0
  155. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/tsconfig.json +22 -0
  156. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-build-test.ts +61 -0
  157. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-debate.ts +87 -0
  158. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-document.ts +50 -0
  159. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-poll.ts +95 -0
  160. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-quality.ts +20 -0
  161. package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-scout.ts +38 -0
  162. package/.versions/2.0.8/.pi/agents/dispatch-policy.yaml +32 -0
  163. package/.versions/2.0.8/.pi/agents/model-profiles.yaml +83 -0
  164. package/.versions/2.0.8/.pi/agents/peers.yaml +147 -0
  165. package/.versions/2.0.8/.pi/agents/teams.yaml +41 -0
  166. package/.versions/2.0.8/.pi/agents/voices.yaml +13 -0
  167. package/.versions/2.0.8/.pi/damage-control-rules.yaml +297 -0
  168. package/.versions/2.0.8/.pi/extensions/btw/README.md +120 -0
  169. package/.versions/2.0.8/.pi/extensions/btw/index.ts +914 -0
  170. package/.versions/2.0.8/.pi/extensions/btw/package.json +6 -0
  171. package/.versions/2.0.8/.pi/extensions/btw/state.js +179 -0
  172. package/.versions/2.0.8/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  173. package/.versions/2.0.8/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  174. package/.versions/2.0.8/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  175. package/.versions/2.0.8/.pi/extensions/compact-and-continue/README.md +42 -0
  176. package/.versions/2.0.8/.pi/extensions/compact-and-continue/index.ts +120 -0
  177. package/.versions/2.0.8/.pi/extensions/compact-and-continue/package.json +6 -0
  178. package/.versions/2.0.8/.pi/extensions/mcp-bridge/README.md +46 -0
  179. package/.versions/2.0.8/.pi/extensions/mcp-bridge/index.ts +206 -0
  180. package/.versions/2.0.8/.pi/extensions/mcp-bridge/package.json +6 -0
  181. package/.versions/2.0.8/.pi/extensions/package-lock.json +1175 -0
  182. package/.versions/2.0.8/.pi/extensions/package.json +9 -0
  183. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/README.md +205 -0
  184. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/config.ts +198 -0
  185. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  186. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/index.ts +248 -0
  187. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/package.json +6 -0
  188. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  189. package/.versions/2.0.8/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  190. package/.versions/2.0.8/.pi/harnesses/agent-hub/README.md +1203 -0
  191. package/.versions/2.0.8/.pi/harnesses/agent-hub/acceptance.ts +62 -0
  192. package/.versions/2.0.8/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  193. package/.versions/2.0.8/.pi/harnesses/agent-hub/artifacts.js +146 -0
  194. package/.versions/2.0.8/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  195. package/.versions/2.0.8/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  196. package/.versions/2.0.8/.pi/harnesses/agent-hub/budget-continuation.ts +13 -0
  197. package/.versions/2.0.8/.pi/harnesses/agent-hub/budget-recovery.ts +97 -0
  198. package/.versions/2.0.8/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
  199. package/.versions/2.0.8/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
  200. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agent-model-thinking.ts +10 -0
  201. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agent-model.ts +10 -0
  202. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agent-models-substitute.ts +10 -0
  203. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-add.ts +9 -0
  204. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-drop.ts +9 -0
  205. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-history.ts +9 -0
  206. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-kill.ts +10 -0
  207. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-list.ts +9 -0
  208. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-restart.ts +10 -0
  209. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-save.ts +9 -0
  210. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-team.ts +9 -0
  211. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/budget-continue.ts +10 -0
  212. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/compound.ts +9 -0
  213. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/coms.ts +9 -0
  214. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/context-command.ts +9 -0
  215. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/context.ts +43 -0
  216. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/debate.ts +9 -0
  217. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/dispatch-policy.ts +9 -0
  218. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/handoff.ts +10 -0
  219. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/hub-report.ts +9 -0
  220. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/models.ts +10 -0
  221. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/poll.ts +9 -0
  222. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/retry.ts +10 -0
  223. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/watchdog.ts +9 -0
  224. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/work-mode.ts +29 -0
  225. package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/zoom.ts +10 -0
  226. package/.versions/2.0.8/.pi/harnesses/agent-hub/config/agents.ts +177 -0
  227. package/.versions/2.0.8/.pi/harnesses/agent-hub/config/model-profiles.ts +216 -0
  228. package/.versions/2.0.8/.pi/harnesses/agent-hub/config/overrides.ts +153 -0
  229. package/.versions/2.0.8/.pi/harnesses/agent-hub/context/agent-state.ts +30 -0
  230. package/.versions/2.0.8/.pi/harnesses/agent-hub/context/assertions-artifacts.ts +213 -0
  231. package/.versions/2.0.8/.pi/harnesses/agent-hub/context/budgets.ts +202 -0
  232. package/.versions/2.0.8/.pi/harnesses/agent-hub/context/hub-state.ts +40 -0
  233. package/.versions/2.0.8/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
  234. package/.versions/2.0.8/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
  235. package/.versions/2.0.8/.pi/harnesses/agent-hub/context-window.js +106 -0
  236. package/.versions/2.0.8/.pi/harnesses/agent-hub/debate-command.ts +176 -0
  237. package/.versions/2.0.8/.pi/harnesses/agent-hub/delegate.ts +446 -0
  238. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-coms.ts +237 -0
  239. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-core.ts +27 -0
  240. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-complete.ts +154 -0
  241. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-prepare.ts +156 -0
  242. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-spawn.ts +193 -0
  243. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-types.ts +230 -0
  244. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native.ts +213 -0
  245. package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-observability.ts +225 -0
  246. package/.versions/2.0.8/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  247. package/.versions/2.0.8/.pi/harnesses/agent-hub/drift-watchdog.js +218 -0
  248. package/.versions/2.0.8/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  249. package/.versions/2.0.8/.pi/harnesses/agent-hub/execution-evidence.ts +80 -0
  250. package/.versions/2.0.8/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  251. package/.versions/2.0.8/.pi/harnesses/agent-hub/fixtures/registration-surface.json +57 -0
  252. package/.versions/2.0.8/.pi/harnesses/agent-hub/footer.ts +30 -0
  253. package/.versions/2.0.8/.pi/harnesses/agent-hub/helpers.ts +266 -0
  254. package/.versions/2.0.8/.pi/harnesses/agent-hub/hub-state-audit.js +64 -0
  255. package/.versions/2.0.8/.pi/harnesses/agent-hub/index.ts +2151 -0
  256. package/.versions/2.0.8/.pi/harnesses/agent-hub/input/completions.ts +76 -0
  257. package/.versions/2.0.8/.pi/harnesses/agent-hub/input/shortcuts.ts +18 -0
  258. package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/context-pressure.ts +123 -0
  259. package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/monitor-session.ts +104 -0
  260. package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/session-orchestration.ts +143 -0
  261. package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/turn-handlers.ts +74 -0
  262. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  263. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  264. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  265. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  266. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  267. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  268. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  269. package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  270. package/.versions/2.0.8/.pi/harnesses/agent-hub/no-progress.ts +76 -0
  271. package/.versions/2.0.8/.pi/harnesses/agent-hub/package.json +7 -0
  272. package/.versions/2.0.8/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  273. package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/models.ts +153 -0
  274. package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/profile-activation.ts +62 -0
  275. package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/profile-runtime.ts +120 -0
  276. package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/roster.ts +94 -0
  277. package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/work-mode.ts +119 -0
  278. package/.versions/2.0.8/.pi/harnesses/agent-hub/poll-command.ts +176 -0
  279. package/.versions/2.0.8/.pi/harnesses/agent-hub/presentation.ts +48 -0
  280. package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/context.ts +47 -0
  281. package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/fragments.ts +115 -0
  282. package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/session-start.ts +90 -0
  283. package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/system-prompt.ts +112 -0
  284. package/.versions/2.0.8/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  285. package/.versions/2.0.8/.pi/harnesses/agent-hub/research/controls.ts +74 -0
  286. package/.versions/2.0.8/.pi/harnesses/agent-hub/research/runtime.ts +192 -0
  287. package/.versions/2.0.8/.pi/harnesses/agent-hub/research/spawn-run.ts +156 -0
  288. package/.versions/2.0.8/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  289. package/.versions/2.0.8/.pi/harnesses/agent-hub/return-contract.js +293 -0
  290. package/.versions/2.0.8/.pi/harnesses/agent-hub/return-extract.js +75 -0
  291. package/.versions/2.0.8/.pi/harnesses/agent-hub/review-findings.js +102 -0
  292. package/.versions/2.0.8/.pi/harnesses/agent-hub/run-budget.js +537 -0
  293. package/.versions/2.0.8/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  294. package/.versions/2.0.8/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  295. package/.versions/2.0.8/.pi/harnesses/agent-hub/scope-gate.js +123 -0
  296. package/.versions/2.0.8/.pi/harnesses/agent-hub/session-health.js +110 -0
  297. package/.versions/2.0.8/.pi/harnesses/agent-hub/session-start.ts +42 -0
  298. package/.versions/2.0.8/.pi/harnesses/agent-hub/spawn.ts +404 -0
  299. package/.versions/2.0.8/.pi/harnesses/agent-hub/timeline.ts +54 -0
  300. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/action-executors.ts +149 -0
  301. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/coms-tools.ts +139 -0
  302. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/context.ts +134 -0
  303. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/dispatch-agent.ts +82 -0
  304. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/dispatch-execution.ts +273 -0
  305. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/execution-orchestration.ts +22 -0
  306. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/fleet-tools.ts +200 -0
  307. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/herdr-executors.ts +86 -0
  308. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/set-task-tier.ts +29 -0
  309. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/spawn-research.ts +62 -0
  310. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/team-adjust.ts +29 -0
  311. package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/verification-contract.ts +77 -0
  312. package/.versions/2.0.8/.pi/harnesses/agent-hub/types.ts +63 -0
  313. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/activity-dots.ts +16 -0
  314. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/context-budget.ts +86 -0
  315. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/detail-panel.ts +178 -0
  316. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/fleet-dashboard.ts +125 -0
  317. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/grid.ts +42 -0
  318. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/history-store.ts +137 -0
  319. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/history.ts +234 -0
  320. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/pool.ts +103 -0
  321. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/running-strip.ts +139 -0
  322. package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/zoom.ts +204 -0
  323. package/.versions/2.0.8/.pi/harnesses/agent-hub/version.ts +42 -0
  324. package/.versions/2.0.8/.pi/harnesses/agent-hub/work-mode-controls.ts +56 -0
  325. package/.versions/2.0.8/.pi/harnesses/agent-hub/work-mode.ts +167 -0
  326. package/.versions/2.0.8/.pi/harnesses/ask-user-remote/README.md +59 -0
  327. package/.versions/2.0.8/.pi/harnesses/ask-user-remote/index.ts +558 -0
  328. package/.versions/2.0.8/.pi/harnesses/ask-user-remote/questions.ts +161 -0
  329. package/.versions/2.0.8/.pi/harnesses/ask-user-remote/race-core.js +124 -0
  330. package/.versions/2.0.8/.pi/harnesses/ask-user-remote/runtime-ask.ts +43 -0
  331. package/.versions/2.0.8/.pi/harnesses/coms/README.md +100 -0
  332. package/.versions/2.0.8/.pi/harnesses/coms/index.ts +282 -0
  333. package/.versions/2.0.8/.pi/harnesses/coms/package.json +7 -0
  334. package/.versions/2.0.8/.pi/harnesses/coms/version.ts +42 -0
  335. package/.versions/2.0.8/.pi/harnesses/damage-control-continue/README.md +135 -0
  336. package/.versions/2.0.8/.pi/harnesses/damage-control-continue/index.ts +541 -0
  337. package/.versions/2.0.8/.pi/harnesses/damage-control-continue/package.json +7 -0
  338. package/.versions/2.0.8/.pi/harnesses/damage-control-continue/version.ts +42 -0
  339. package/.versions/2.0.8/.pi/harnesses/lib/coms-core-io.ts +385 -0
  340. package/.versions/2.0.8/.pi/harnesses/lib/coms-core.ts +577 -0
  341. package/.versions/2.0.8/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  342. package/.versions/2.0.8/.pi/harnesses/lib/context-budget-child-prompt.ts +180 -0
  343. package/.versions/2.0.8/.pi/harnesses/lib/context-budget-hub-prompt.ts +114 -0
  344. package/.versions/2.0.8/.pi/harnesses/lib/context-budget-view.ts +107 -0
  345. package/.versions/2.0.8/.pi/harnesses/lib/context-budget.ts +114 -0
  346. package/.versions/2.0.8/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  347. package/.versions/2.0.8/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
  348. package/.versions/2.0.8/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
  349. package/.versions/2.0.8/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
  350. package/.versions/2.0.8/.pi/harnesses/lib/fleet-dashboard-ops.ts +161 -0
  351. package/.versions/2.0.8/.pi/harnesses/lib/fleet-dashboard-view.ts +148 -0
  352. package/.versions/2.0.8/.pi/harnesses/lib/fleet-detail-view.ts +247 -0
  353. package/.versions/2.0.8/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  354. package/.versions/2.0.8/.pi/harnesses/lib/fleet-panel.ts +34 -0
  355. package/.versions/2.0.8/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  356. package/.versions/2.0.8/.pi/harnesses/lib/fleet-selection.ts +24 -0
  357. package/.versions/2.0.8/.pi/harnesses/lib/fleet-transcript-store.ts +244 -0
  358. package/.versions/2.0.8/.pi/harnesses/lib/herdr-client.ts +472 -0
  359. package/.versions/2.0.8/.pi/harnesses/lib/herdr-presence.ts +399 -0
  360. package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  361. package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  362. package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  363. package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  364. package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  365. package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  366. package/.versions/2.0.8/.pi/harnesses/lib/spawned-peers.js +190 -0
  367. package/.versions/2.0.8/.pi/harnesses/lib/update-check.ts +222 -0
  368. package/.versions/2.0.8/.pi/harnesses/package-lock.json +2039 -0
  369. package/.versions/2.0.8/.pi/harnesses/package.json +10 -0
  370. package/.versions/2.0.8/.pi/prompts/af-build.md +24 -0
  371. package/.versions/2.0.8/.pi/prompts/af-code-simplify.md +22 -0
  372. package/.versions/2.0.8/.pi/prompts/af-constraints.md +31 -0
  373. package/.versions/2.0.8/.pi/prompts/af-plan.md +17 -0
  374. package/.versions/2.0.8/.pi/prompts/af-review.md +16 -0
  375. package/.versions/2.0.8/.pi/prompts/af-set-hermes-telegram.md +15 -0
  376. package/.versions/2.0.8/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  377. package/.versions/2.0.8/.pi/prompts/af-ship.md +17 -0
  378. package/.versions/2.0.8/.pi/prompts/af-spec.md +15 -0
  379. package/.versions/2.0.8/.pi/prompts/af-test.md +19 -0
  380. package/.versions/2.0.8/.pi/skills/bowser/SKILL.md +145 -0
  381. package/.versions/2.0.8/.version +1 -0
  382. package/.versions/2.0.8/agents/architect.md +25 -0
  383. package/.versions/2.0.8/agents/bowser.md +28 -0
  384. package/.versions/2.0.8/agents/builder.md +56 -0
  385. package/.versions/2.0.8/agents/code-reviewer.md +210 -0
  386. package/.versions/2.0.8/agents/deep-researcher.md +33 -0
  387. package/.versions/2.0.8/agents/documenter.md +23 -0
  388. package/.versions/2.0.8/agents/orchestrator.md +23 -0
  389. package/.versions/2.0.8/agents/plan-reviewer.md +84 -0
  390. package/.versions/2.0.8/agents/planner.md +106 -0
  391. package/.versions/2.0.8/agents/releaser.md +25 -0
  392. package/.versions/2.0.8/agents/researcher.md +31 -0
  393. package/.versions/2.0.8/agents/security-auditor.md +168 -0
  394. package/.versions/2.0.8/agents/test-engineer.md +154 -0
  395. package/.versions/2.0.8/agents/web-debugger.md +44 -0
  396. package/.versions/2.0.8/agents/web-performance-auditor.md +194 -0
  397. package/.versions/2.0.8/bin/catalog/harness-runtime-closure.json +32 -0
  398. package/.versions/2.0.8/codex/fleet-session-client/SKILL.md +34 -0
  399. package/.versions/2.0.8/codex/fleet-session-client.zip +0 -0
  400. package/.versions/2.0.8/docs/ARCHITECTURE.md +416 -0
  401. package/.versions/2.0.8/docs/agent-fleet-setup.md +568 -0
  402. package/.versions/2.0.8/docs/claude-code-coms-bridge.md +134 -0
  403. package/.versions/2.0.8/docs/codex-session-bridge.md +219 -0
  404. package/.versions/2.0.8/docs/coms-hermes-bridge.md +188 -0
  405. package/.versions/2.0.8/docs/getting-started.md +126 -0
  406. package/.versions/2.0.8/docs/npm-install.md +356 -0
  407. package/.versions/2.0.8/docs/pi-extensions.md +446 -0
  408. package/.versions/2.0.8/docs/pi-setup.md +76 -0
  409. package/.versions/2.0.8/docs/skill-anatomy.md +150 -0
  410. package/.versions/2.0.8/install-manifest.json +2991 -0
  411. package/.versions/2.0.8/justfile +247 -0
  412. package/.versions/2.0.8/manifest-meta.json +970 -0
  413. package/.versions/2.0.8/references/accessibility-checklist.md +160 -0
  414. package/.versions/2.0.8/references/communication-contract.md +26 -0
  415. package/.versions/2.0.8/references/definition-of-done.md +67 -0
  416. package/.versions/2.0.8/references/fleet-coordination-patterns.md +171 -0
  417. package/.versions/2.0.8/references/observability-checklist.md +92 -0
  418. package/.versions/2.0.8/references/orchestration-patterns.md +370 -0
  419. package/.versions/2.0.8/references/performance-checklist.md +236 -0
  420. package/.versions/2.0.8/references/prompting-patterns.md +380 -0
  421. package/.versions/2.0.8/references/security-checklist.md +245 -0
  422. package/.versions/2.0.8/references/testing-patterns.md +235 -0
  423. package/.versions/2.0.8/references/workflow-authoring.md +304 -0
  424. package/.versions/2.0.8/skills/_internal/grilling.md +59 -0
  425. package/.versions/2.0.8/skills/browser-testing-with-devtools/SKILL.md +351 -0
  426. package/.versions/2.0.8/skills/code-review-and-quality/SKILL.md +396 -0
  427. package/.versions/2.0.8/skills/compound-learning/SKILL.md +137 -0
  428. package/.versions/2.0.8/skills/constraint-driven-development/SKILL.md +338 -0
  429. package/.versions/2.0.8/skills/constraint-driven-development/references/floor-guard.md +99 -0
  430. package/.versions/2.0.8/skills/context-engineering/SKILL.md +341 -0
  431. package/.versions/2.0.8/skills/deprecation-and-migration/SKILL.md +247 -0
  432. package/.versions/2.0.8/skills/designing-agents/SKILL.md +394 -0
  433. package/.versions/2.0.8/skills/designing-agents/pi-harness-authoring.md +222 -0
  434. package/.versions/2.0.8/skills/drafting-workflows/SKILL.md +143 -0
  435. package/.versions/2.0.8/skills/drafting-workflows/scripts/make-workflow.ts +177 -0
  436. package/.versions/2.0.8/skills/frontend-ui-engineering/SKILL.md +328 -0
  437. package/.versions/2.0.8/skills/git-workflow-and-versioning/SKILL.md +316 -0
  438. package/.versions/2.0.8/skills/idea-refine/SKILL.md +182 -0
  439. package/.versions/2.0.8/skills/idea-refine/examples.md +238 -0
  440. package/.versions/2.0.8/skills/idea-refine/frameworks.md +99 -0
  441. package/.versions/2.0.8/skills/idea-refine/refinement-criteria.md +113 -0
  442. package/.versions/2.0.8/skills/idea-refine/scripts/idea-refine.sh +15 -0
  443. package/.versions/2.0.8/skills/incremental-implementation/SKILL.md +302 -0
  444. package/.versions/2.0.8/skills/interview-me/SKILL.md +226 -0
  445. package/.versions/2.0.8/skills/orchestration-verification/SKILL.md +181 -0
  446. package/.versions/2.0.8/skills/peer-coms/SKILL.md +90 -0
  447. package/.versions/2.0.8/skills/performance-optimization/SKILL.md +496 -0
  448. package/.versions/2.0.8/skills/planning-and-task-breakdown/SKILL.md +289 -0
  449. package/.versions/2.0.8/skills/security-and-hardening/SKILL.md +524 -0
  450. package/.versions/2.0.8/skills/spec-driven-development/SKILL.md +295 -0
  451. package/.versions/2.0.8/skills/using-agent-skills/SKILL.md +198 -0
  452. package/.versions/2.0.8/vendor/agent-skills-upstream/LICENSE +21 -0
  453. package/.versions/2.0.8/vendor/agent-skills-upstream/README.md +430 -0
  454. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +367 -0
  455. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  456. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  457. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  458. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  459. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/constraint-driven-development/SKILL.md +311 -0
  460. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/constraint-driven-development/references/floor-guard.md +99 -0
  461. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +337 -0
  462. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  463. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  464. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +288 -0
  465. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  466. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  467. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  468. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  469. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  470. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  471. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  472. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  473. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  474. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  475. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +238 -0
  476. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +496 -0
  477. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +257 -0
  478. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +524 -0
  479. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +330 -0
  480. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +216 -0
  481. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +245 -0
  482. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +398 -0
  483. package/.versions/2.0.8/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +192 -0
  484. package/CHANGELOG.md +39 -0
  485. package/README.md +10 -9
  486. package/bin/catalog/harness-runtime-closure.json +23 -22
  487. package/bin/cli.js +24 -1
  488. package/bin/lib/apply.js +6 -2
  489. package/bin/lib/detect-agent.js +1 -1
  490. package/bin/lib/doctor.js +3 -3
  491. package/bin/lib/manifest.js +23 -16
  492. package/bin/lib/path-boundaries.js +96 -0
  493. package/bin/lib/personas.js +15 -2
  494. package/bin/lib/set-hermes-telegram.js +2 -2
  495. package/bin/lib/set-hermes-watchdog.js +1 -1
  496. package/bin/lib/state.js +5 -1
  497. package/bin/lib/verify.js +43 -5
  498. package/bin/snapshot-version.js +6 -6
  499. package/codex/fleet-session-client/SKILL.md +3 -3
  500. package/docs/ARCHITECTURE.md +29 -20
  501. package/docs/MIGRATION-agent-fleet.md +11 -7
  502. package/docs/agent-fleet-setup.md +9 -2
  503. package/docs/claude-code-coms-bridge.md +10 -9
  504. package/docs/codex-session-bridge.md +18 -18
  505. package/docs/coms-hermes-bridge.md +6 -6
  506. package/docs/hermes-watchdog-supervisor.md +1 -1
  507. package/docs/npm-install.md +30 -1
  508. package/docs/pi-extensions.md +6 -6
  509. package/docs/workflows.md +9 -5
  510. package/install-manifest.json +202 -97
  511. package/justfile +19 -19
  512. package/manifest-meta.json +50 -38
  513. package/package.json +26 -26
  514. package/references/observability-checklist.md +1 -0
  515. package/references/performance-checklist.md +83 -0
  516. package/references/prompting-patterns.md +1 -1
  517. package/references/security-checklist.md +85 -19
  518. package/references/testing-patterns.md +12 -13
  519. package/references/workflow-authoring.md +5 -5
  520. package/skills/code-review-and-quality/SKILL.md +17 -2
  521. package/skills/constraint-driven-development/SKILL.md +338 -0
  522. package/skills/constraint-driven-development/references/floor-guard.md +99 -0
  523. package/skills/context-engineering/SKILL.md +52 -2
  524. package/skills/deprecation-and-migration/SKILL.md +42 -1
  525. package/skills/designing-agents/SKILL.md +12 -12
  526. package/skills/drafting-workflows/SKILL.md +6 -6
  527. package/skills/drafting-workflows/scripts/make-workflow.ts +3 -3
  528. package/skills/frontend-ui-engineering/SKILL.md +2 -2
  529. package/skills/git-workflow-and-versioning/SKILL.md +1 -1
  530. package/skills/incremental-implementation/SKILL.md +13 -9
  531. package/skills/peer-coms/SKILL.md +4 -4
  532. package/skills/performance-optimization/SKILL.md +152 -6
  533. package/skills/planning-and-task-breakdown/SKILL.md +32 -8
  534. package/skills/security-and-hardening/SKILL.md +84 -21
  535. package/skills/spec-driven-development/SKILL.md +41 -2
  536. package/skills/using-agent-skills/SKILL.md +3 -2
  537. package/vendor/agent-skills-upstream/README.md +427 -8
  538. package/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +73 -0
  539. package/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +2 -2
  540. package/vendor/agent-skills-upstream/skills/constraint-driven-development/SKILL.md +311 -0
  541. package/vendor/agent-skills-upstream/skills/constraint-driven-development/references/floor-guard.md +99 -0
  542. package/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +49 -1
  543. package/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +4 -4
  544. package/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +1 -1
  545. package/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +12 -2
  546. package/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +3 -3
  547. package/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +1 -1
  548. package/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +1 -1
  549. package/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +9 -9
  550. package/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +36 -1
  551. package/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +151 -5
  552. package/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +32 -9
  553. package/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +64 -7
  554. package/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +26 -6
  555. package/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +23 -1
  556. package/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +42 -3
  557. package/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +18 -3
  558. package/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +3 -2
  559. package/scripts/lib/hermes-monitor-events.ts +0 -1
  560. package/scripts/lib/hermes-monitor-herdr.ts +0 -2
  561. package/scripts/lib/hermes-monitor-registry.ts +0 -2
  562. package/scripts/lib/hermes-monitor-socket.ts +0 -2
  563. package/scripts/lib/hermes-monitor-store.ts +0 -2
  564. /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-herdr/plugin.js +0 -0
  565. /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-herdr/presentation.js +0 -0
  566. /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-monitor/plugin.js +0 -0
  567. /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-monitor/state.js +0 -0
  568. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/herdr_source.py +0 -0
  569. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/manifest.json +0 -0
  570. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/plugin_api.py +0 -0
  571. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/sessions.py +0 -0
  572. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/tasks.py +0 -0
  573. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/plugin.yaml +0 -0
  574. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/adapter.py +0 -0
  575. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/dist/index.js +0 -0
  576. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/manifest.json +0 -0
  577. /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/plugin_api.py +0 -0
  578. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-liaison/SKILL.md +0 -0
  579. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/manifest.json +0 -0
  580. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog.py +0 -0
  581. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_actions.py +0 -0
  582. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_contract.py +0 -0
  583. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_delivery.py +0 -0
  584. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_engine.py +0 -0
  585. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_judgment.py +0 -0
  586. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_recovery.py +0 -0
  587. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_state.py +0 -0
  588. /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_transport.py +0 -0
  589. /package/{scripts → .pi/agent-fleet/scripts}/fleet-codex-client.ts +0 -0
  590. /package/{scripts → .pi/agent-fleet/scripts}/hermes-watchdog-capability-probe.ts +0 -0
  591. /package/{scripts → .pi/agent-fleet/scripts}/lib/fake-herdr-server.ts +0 -0
  592. /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-catalog.ts +0 -0
  593. /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-operations.ts +0 -0
  594. /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-session.ts +0 -0
  595. /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-command.ts +0 -0
  596. /package/{scripts → .pi/agent-fleet/scripts}/lib/flow-command.ts +0 -0
  597. /package/{scripts → .pi/agent-fleet/scripts}/lib/flow-maintenance.ts +0 -0
  598. /package/{scripts → .pi/agent-fleet/scripts}/package-lock.json +0 -0
  599. /package/{scripts → .pi/agent-fleet/scripts}/package.json +0 -0
  600. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/changes.ts +0 -0
  601. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/debate.ts +0 -0
  602. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/env.ts +0 -0
  603. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/gates.ts +0 -0
  604. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/git.ts +0 -0
  605. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/merge.ts +0 -0
  606. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/model-visibility.ts +0 -0
  607. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/permissions.ts +0 -0
  608. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/poll.ts +0 -0
  609. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/quality.ts +0 -0
  610. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/run.ts +0 -0
  611. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/voices.ts +0 -0
  612. /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/writer-lease.ts +0 -0
  613. /package/{scripts → .pi/agent-fleet/scripts}/workflows/tsconfig.json +0 -0
  614. /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-build-test.ts +0 -0
  615. /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-debate.ts +0 -0
  616. /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-document.ts +0 -0
  617. /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-poll.ts +0 -0
  618. /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-quality.ts +0 -0
  619. /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-scout.ts +0 -0
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: incremental-implementation
3
- description: Delivers changes incrementally. Use when implementing any feature or change that touches more than one file. Use when you're about to write a large amount of code at once, or when a task feels too big to land in one step.
3
+ description: Delivers changes incrementally in thin, verifiable slices. Use when implementing any feature or change that touches more than one file, or when picking up the next task from a plan. Use when rolling a change out behind a feature flag, when you're about to write a large amount of code at once, or when a task feels too big to land in one step.
4
4
  ---
5
5
 
6
6
  # Incremental Implementation
@@ -190,21 +190,21 @@ When directing an agent to implement incrementally:
190
190
  Start with just the database schema change and the API endpoint.
191
191
  Don't touch the UI yet — we'll do that in the next increment.
192
192
 
193
- After implementing, run `npm test` and `npm run build` to verify
194
- nothing is broken."
193
+ After implementing, run the repository's test and build commands to
194
+ verify nothing is broken."
195
195
  ```
196
196
 
197
197
  Be explicit about what's in scope and what's NOT in scope for each increment.
198
198
 
199
199
  ## Increment Checklist
200
200
 
201
- After each increment, verify:
201
+ After each increment, verify with the repository's own commands (see the test-driven-development skill's Discover the Stack First section):
202
202
 
203
203
  - [ ] The change does one thing and does it completely
204
- - [ ] All existing tests still pass (`npm test`)
205
- - [ ] The build succeeds (`npm run build`)
206
- - [ ] Type checking passes (`npx tsc --noEmit`)
207
- - [ ] Linting passes (`npm run lint`)
204
+ - [ ] All existing tests still pass (the repository's test command: `npm test`, `./gradlew test`, `pytest`, ...)
205
+ - [ ] The build succeeds (the repository's build command)
206
+ - [ ] Type checking passes, where the stack has one (`npx tsc --noEmit`, `mypy`, ...)
207
+ - [ ] Linting passes (the repository's lint command)
208
208
  - [ ] The new functionality works as expected
209
209
  - [ ] The change is committed with a descriptive message
210
210
 
@@ -246,4 +246,4 @@ After completing all increments for a task:
246
246
 
247
247
  ## See Also
248
248
 
249
- Per-increment verification is the local check. Before declaring a task done, apply the project-wide Definition of Done as the final gate, the standing bar every increment clears regardless of the task. See `references/definition-of-done.md`.
249
+ Per-increment verification is the local check. Before declaring a task done, apply the project-wide Definition of Done as the final gate, the standing bar every increment clears regardless of the task. See `../../references/definition-of-done.md`.
@@ -88,6 +88,21 @@ app.use((req, res, next) => {
88
88
  });
89
89
  ```
90
90
 
91
+ **When several entry points write to one log, name the entry point.** A correlation ID identifies a run; it does not say which code path started it. The same job reached by a scheduler, by a replay endpoint, and by a manual CLI run produces interchangeable lines in one sink, so attributing a line falls back to elimination — cross-reading the scheduler's history, the process table, a deploy log — and that argument holds only as long as those external records happen to still exist. Stamp the entry point where the run starts, next to the correlation ID, and propagate both the same way:
92
+
93
+ ```typescript
94
+ // One helper for every entry point: the run's own logger carries both fields.
95
+ // `entryPoint`, not `source` — ECS reserves `source.*` for network fields.
96
+ export const runLog = (entryPoint: 'scheduler' | 'replay_endpoint' | 'cli', runId: string) =>
97
+ logger.child({ entryPoint, requestId: runId });
98
+
99
+ // scheduler tick -> runLog('scheduler', crypto.randomUUID())
100
+ // POST /jobs/:id/replay -> runLog('replay_endpoint', req.id)
101
+ // CLI invocation -> runLog('cli', process.env.RUN_ID ?? crypto.randomUUID())
102
+ ```
103
+
104
+ Both fields have to cross the same boundaries as the correlation ID — queue metadata, HTTP headers — or a worker re-derives the entry point and guesses. A field that merely correlates with an entry point is a hint, not an attribution: anything that can invoke the job can reproduce it.
105
+
91
106
  **Never log secrets, tokens, passwords, or full PII.** This is a hard rule from the `security-and-hardening` skill — telemetry pipelines are a classic data-leak path. Allowlist fields; don't log whole request bodies.
92
107
 
93
108
  ### 4. Metrics
@@ -154,6 +169,24 @@ Rules for every alert you create:
154
169
  3. **It has a threshold and duration** justified by the SLO or by historical data, not by a guess.
155
170
  4. Use two severities only: **page** (user-facing, act now) and **ticket** (degradation, act this week). A third tier becomes noise that trains people to ignore everything.
156
171
 
172
+ #### Writing Runbooks
173
+
174
+ Rule 2 above requires every alert to link to a runbook. A runbook's job is to answer three questions without requiring the reader to think: what is happening, what to check first, and who to call if that doesn't resolve it. Store in `docs/runbooks/` named after the alert.
175
+
176
+ **Minimum viable runbook (three lines):**
177
+
178
+ ```markdown
179
+ # Runbook: High Error Rate on /api/tasks
180
+ **Means:** DB connection pool likely exhausted, or a bad deploy.
181
+ **First check:** `SELECT count(*) FROM pg_stat_activity WHERE backend_type = 'client backend';`
182
+ — if count > pool limit, see Step 2. (Swap in the equivalent for your database.)
183
+ **Escalate to:** #db-oncall or engineering on-call rotation.
184
+ ```
185
+
186
+ **When to expand beyond three lines:** add steps only when the first check alone isn't enough to decide. A five-step runbook that covers the three most common causes is better than a twenty-step document that covers every edge case and gets skimmed.
187
+
188
+ **Keep runbooks current.** Update the runbook as part of closing every incident it was used in — a stale runbook builds false confidence. If a step was wrong or missing, fix it before marking the incident resolved.
189
+
157
190
  ### 7. Verify the telemetry itself
158
191
 
159
192
  Instrumentation is code; it can be wrong. Before calling the work done, trigger the paths and look at the actual output:
@@ -180,6 +213,7 @@ Instrumentation is code; it can be wrong. Before calling the work done, trigger
180
213
  - A feature PR with retries, queues, or external calls and zero new telemetry
181
214
  - Log lines built by string interpolation instead of structured fields
182
215
  - No correlation/request ID — each log line is an orphan
216
+ - One log stream fed by a scheduler, a webhook, and manual runs, with no field naming which one produced the line
183
217
  - Metrics labeled with user IDs, raw URLs, or error message text (cardinality bomb)
184
218
  - Latency tracked as an average with no percentiles
185
219
  - Alerts that fire daily and get acknowledged without action
@@ -193,6 +227,7 @@ After instrumenting a feature, confirm:
193
227
 
194
228
  - [ ] The on-call questions for this feature are written down, and each signal maps to one
195
229
  - [ ] All log output is structured (JSON), with stable event names and a correlation ID on every line
230
+ - [ ] Every log sink written by more than one entry point carries an entry-point field, set where the run starts and propagated with the correlation ID rather than inferred downstream
196
231
  - [ ] No secrets, tokens, or unredacted PII in any log line (spot-check actual output)
197
232
  - [ ] RED metrics exist for every new endpoint and every external dependency, with bounded label sets
198
233
  - [ ] Latency is a histogram; p95/p99 are queryable
@@ -200,4 +235,4 @@ After instrumenting a feature, confirm:
200
235
  - [ ] Every new alert is symptom-based, has a runbook link, and was test-fired once
201
236
  - [ ] An induced failure in staging was located via telemetry alone, without reading the source
202
237
 
203
- For the at-a-glance version of this list, including the pre-launch instrumentation gate, see `references/observability-checklist.md`.
238
+ For the at-a-glance version of this list, including the pre-launch instrumentation gate, see `../../references/observability-checklist.md`.
@@ -33,7 +33,7 @@ Measure before optimizing. Performance work without measurement is guessing —
33
33
  1. MEASURE → Establish baseline with real data
34
34
  2. IDENTIFY → Find the actual bottleneck (not assumed)
35
35
  3. FIX → Address the specific bottleneck
36
- 4. VERIFY → Measure again, confirm improvement
36
+ 4. VERIFY → Measure again; keep or revert
37
37
  5. GUARD → Add monitoring or tests to prevent regression
38
38
  ```
39
39
 
@@ -149,6 +149,58 @@ const tasks = await db.tasks.findMany({
149
149
  });
150
150
  ```
151
151
 
152
+ #### Queries That Ignore Their Index
153
+
154
+ "Add an index" is the guess. The query plan is the measurement:
155
+
156
+ ```sql
157
+ EXPLAIN ANALYZE
158
+ SELECT id, title FROM tasks
159
+ WHERE owner_id = 42 ORDER BY created_at DESC LIMIT 20;
160
+ ```
161
+
162
+ Three things in the output decide the fix:
163
+
164
+ | What you see | What it means |
165
+ |---|---|
166
+ | `Seq Scan` on a large table where you expected an index | No usable index for this predicate |
167
+ | Estimated `rows=` off from actual by an order of magnitude | Stale statistics; the planner is choosing on bad information |
168
+ | A `Sort` node above the scan | The index covers the filter but not the `ORDER BY` |
169
+
170
+ Index for the **shape of the query**, not the column in isolation. In a composite index, equality columns come first, then the range or sort column:
171
+
172
+ ```sql
173
+ CREATE INDEX idx_tasks_owner_created ON tasks (owner_id, created_at DESC);
174
+ ```
175
+
176
+ **When an index will not help:**
177
+
178
+ | Situation | Why |
179
+ |---|---|
180
+ | Low selectivity, querying the dominant value (a `status` column that is 95% `active`, filtered on `active`) | A sequential scan is genuinely cheaper; the planner will ignore the index. Filtering on the rare value is the opposite case, and a partial index serves it well |
181
+ | Leading wildcard (`LIKE '%term'`) | A B-tree cannot seek without a prefix; needs trigram or full-text |
182
+ | Function on the column (`WHERE lower(email) = ?`) | The plain column index is unusable; index the expression instead |
183
+ | Write-heavy table | Every index is a tax on every `INSERT`/`UPDATE`; measure the write cost, not just the read gain |
184
+
185
+ Re-run `EXPLAIN ANALYZE` after. An index that did not change the plan is a revert (Step 4), and it is not free: it still costs on every write.
186
+
187
+ #### Connection Pool Exhaustion
188
+
189
+ The signature is distinctive: **every** endpoint slows at once, the slow time is spent waiting for a connection rather than executing, and the database reports mostly idle sessions.
190
+
191
+ ```typescript
192
+ // BAD: a pool per request or per module — under serverless this multiplies
193
+ // by instance count and exhausts the database's connection limit
194
+ // GOOD: one pool per process, sized against the database's ceiling
195
+ const pool = new Pool({
196
+ max: 10, // instances × max must stay under max_connections
197
+ idleTimeoutMillis: 30_000,
198
+ connectionTimeoutMillis: 5_000, // fail fast instead of queueing forever
199
+ });
200
+ ```
201
+
202
+ **Bigger is not faster.** A pool larger than what the database can execute concurrently just relocates the queue from your app to the database, where it is harder to see. When instance count is unbounded (serverless, autoscaling), a proxy that multiplexes connections (pgbouncer, RDS Proxy) is the fix, not a higher `max`.
203
+
152
204
  #### Missing Image Optimization (Frontend)
153
205
 
154
206
  ```html
@@ -264,6 +316,16 @@ function App() {
264
316
 
265
317
  #### Missing Caching (Backend)
266
318
 
319
+ Cache what is expensive to produce and read far more often than it changes. Caching a query that was already fast adds a network hop, a staleness bug, and an eviction policy to maintain, in exchange for nothing.
320
+
321
+ **Pick the layer deliberately:**
322
+
323
+ | Layer | Visible to | Use when | Cost |
324
+ |---|---|---|---|
325
+ | In-process (`Map`, LRU) | One instance | Small, hot, per-instance staleness is acceptable | Each instance drifts independently; invalidation reaches only one |
326
+ | Shared (Redis, Memcached) | All instances | Instances must agree, or the value is expensive to recompute | A network hop, and another service to run and monitor |
327
+ | CDN / edge | Everyone, per URL | Responses are public and identical for a given key | Invalidation is the hard part; assume you cannot recall a bad response quickly |
328
+
267
329
  ```typescript
268
330
  // Cache frequently-read, rarely-changed data
269
331
  const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
@@ -289,9 +351,73 @@ app.use('/static', express.static('public', {
289
351
  res.set('Cache-Control', 'public, max-age=300'); // 5 minutes
290
352
  ```
291
353
 
292
- ## Performance Budget
354
+ **Key design decides correctness.** Every input that changes the response belongs in the key: tenant, locale, permissions, feature flags. A key that omits the viewer is how one user's data gets served to another, and that ships as a performance win.
355
+
356
+ **Choose one invalidation strategy, not three:**
357
+
358
+ | Strategy | Trade-off |
359
+ |---|---|
360
+ | TTL | Simplest. You accept staleness up to the TTL, so state the acceptable window explicitly |
361
+ | Event or tag based | Fresh on write, but writers now have to know the cache topology |
362
+ | Versioned keys (`user:42:profile:v7`) | Never invalidate, just stop reading old keys. Costs memory until eviction |
363
+
364
+ **Guard against the stampede.** A hot key expires, every concurrent request misses together, and the origin takes the full load at once, which is how a cache turns into an outage instead of preventing one. Serve stale while a single request recomputes (`stale-while-revalidate`), or coalesce concurrent misses behind one in-flight promise so N waiters cause one recompute.
365
+
366
+ **Do not cache:** anything whose staleness is a correctness bug (balances, permissions, inventory at checkout), or per-user data under a key that does not identify the user. See `../../references/performance-checklist.md` for request coalescing, write strategies, negative caching, and the cache checklist.
367
+
368
+ ### Step 4: Verify (Keep or Revert)
369
+
370
+ A fix is a hypothesis until you re-measure. This step decides whether it survives.
371
+
372
+ **Re-measure the way you measured the baseline:** same command, same conditions, same fixed budget (wall-clock, sample count, or request count). A baseline taken on a cold cache against a result taken on a warm one measures the cache, not your change.
373
+
374
+ **Change one thing at a time.** Three optimizations landed together produce one number, and you cannot attribute it. If they must ship together, measure each in isolation first.
375
+
376
+ **Beat the noise, not just the mean.** Repeat the measurement and compare the delta against run-to-run variance. A 3% gain inside ±5% variance is not a gain; it is a different sample.
377
+
378
+ Then decide, strictly:
379
+
380
+ | Result vs. baseline | Action |
381
+ |---|---|
382
+ | Past the threshold, tests green | **Keep.** Commit with the before/after numbers in the message. |
383
+ | Within noise (no measurable change) | **Revert.** |
384
+ | Worse | **Revert.** |
385
+ | Improved, but a test went red | **Revert.** A regression wearing a win's clothing. |
386
+
387
+ **"Neutral" is a revert, not a keep.** This is the step teams skip: the change is already written, throwing it away feels wasteful, so it lands unmeasured, and the codebase accretes complexity that never bought anything. Code you keep, you maintain forever. Make it pay for itself.
388
+
389
+ **Correctness gates the metric.** The suite stays green *and* the number moves. An "optimization" that wins by dropping work the product needed (skipping a validation, caching something that must be fresh, removing an `await` that was load-bearing) is a regression, not a win.
390
+
391
+ #### Log every attempt, including the reverted ones
392
+
393
+ Reverted work leaves no trace in git history, which is exactly why the same dead idea gets tried again next quarter. Keep a short ledger so a discarded idea stays discarded:
394
+
395
+ | Idea | Baseline → Result | Verdict | Why |
396
+ |---|---|---|---|
397
+ | Memoize the row component | INP 240ms → 235ms | reverted | Inside noise (±15ms). Rows weren't the bottleneck. |
398
+ | Virtualize the list | INP 240ms → 90ms | kept | Long tasks gone from the trace. |
399
+ | Preconnect to the API origin | LCP 2.8s → 2.8s | reverted | Already same-origin. |
400
+
401
+ A section in the PR description or a `PERF.md` in the repo both work. What matters is that the next person (or the next agent) reads it before proposing an experiment, and doesn't re-run one that already failed.
402
+
403
+ ### Step 5: Guard Against Regression
404
+
405
+ Guard the metric the user actually feels, not every available number. Use the
406
+ same LCP, INP, p95 latency, or other primary metric that justified the fix.
407
+
408
+ Use two complementary layers when the surface is user-facing:
409
+
410
+ - **Synthetic CI gate:** Catch reproducible regressions before merge with a
411
+ performance budget. Repeat noisy measurements or compare a median/trend so
412
+ normal run-to-run variance does not turn the gate into a flaky check.
413
+ - **Field monitoring:** Alert on a meaningful p75 movement in RUM data. Use
414
+ attributed `web-vitals` data to locate the cause; treat CrUX's rolling window
415
+ as confirmation rather than an immediate alert.
416
+
417
+ When either guard fires, return to Step 1 and establish a fresh baseline before
418
+ proposing another fix.
293
419
 
294
- Set budgets and enforce them:
420
+ **Set budgets and enforce them:**
295
421
 
296
422
  ```
297
423
  JavaScript bundle: < 200KB gzipped (initial load)
@@ -314,7 +440,7 @@ npx lhci autorun
314
440
 
315
441
  ## See Also
316
442
 
317
- For detailed performance checklists, optimization commands, and anti-pattern reference, see `references/performance-checklist.md`.
443
+ For detailed performance checklists, optimization commands, and anti-pattern reference, see `../../references/performance-checklist.md`.
318
444
 
319
445
 
320
446
  ## Common Rationalizations
@@ -326,25 +452,45 @@ For detailed performance checklists, optimization commands, and anti-pattern ref
326
452
  | "This optimization is obvious" | If you didn't measure, you don't know. Profile first. |
327
453
  | "Users won't notice 100ms" | Research shows 100ms delays impact conversion rates. Users notice more than you think. |
328
454
  | "The framework handles performance" | Frameworks prevent some issues but can't fix N+1 queries or oversized bundles. |
455
+ | "The query is slow, add an index" | Read the plan first. The index may already exist and be unusable, and every index taxes writes forever. |
456
+ | "Just cache it" | Caching an already-cheap call buys nothing and adds a staleness bug. Cache what is expensive *and* re-read far more than written. |
457
+ | "Raise the pool size, we're running out of connections" | A pool bigger than the database can serve moves the queue somewhere less visible. Find what holds connections. |
458
+ | "It didn't help much, but it doesn't hurt" | Neutral changes are a revert. You pay maintenance on them forever and got nothing back. |
459
+ | "We already wrote it, may as well keep it" | Sunk cost. The measurement doesn't care how long the change took to write. |
460
+ | "The improvement is obvious, no need to re-measure" | Then re-measuring is cheap and proves it. Unmeasured wins are how neutral complexity lands. |
329
461
 
330
462
  ## Red Flags
331
463
 
332
464
  - Optimization without profiling data to justify it
333
465
  - N+1 query patterns in data fetching
466
+ - An index added without a query plan before and after to justify it
467
+ - A cache key that omits an input the response depends on (tenant, locale, viewer)
468
+ - A cache with no stated staleness window and no invalidation strategy
469
+ - Connection pool size raised in response to exhaustion, without finding what holds connections
334
470
  - List endpoints without pagination
335
471
  - Images without dimensions, lazy loading, or responsive sizes
336
472
  - Bundle size growing without review
337
473
  - No performance monitoring in production
338
474
  - `React.memo` and `useMemo` everywhere (overusing is as bad as underusing)
475
+ - Optimizations kept without a re-measurement that justifies them
476
+ - Several optimizations bundled into one measurement, so no single change can be attributed
477
+ - A "win" that required a test to be changed, skipped, or deleted
478
+ - The same failed optimization attempted more than once because nobody recorded the first attempt
339
479
 
340
480
  ## Verification
341
481
 
342
482
  After any performance-related change:
343
483
 
344
484
  - [ ] Before and after measurements exist (specific numbers)
485
+ - [ ] The result was re-measured the same way as the baseline (same command, same conditions)
486
+ - [ ] The improvement exceeds run-to-run variance, not just the mean
487
+ - [ ] Changes that didn't beat the baseline were reverted, not kept as neutral
488
+ - [ ] Attempts are logged, kept and reverted alike, so a dead idea isn't re-run
345
489
  - [ ] The specific bottleneck is identified and addressed
346
490
  - [ ] Core Web Vitals are within "Good" thresholds
347
491
  - [ ] Bundle size hasn't increased significantly
348
492
  - [ ] No N+1 queries in new data fetching code
349
- - [ ] Performance budget passes in CI (if configured)
493
+ - [ ] Any new index is justified by a query plan before and after, and its write cost was considered
494
+ - [ ] Any new cache states what it keys on and how it goes stale
495
+ - [ ] The measured user-facing metric has a synthetic budget or field monitor that can detect regression
350
496
  - [ ] Existing tests still pass (optimization didn't break behavior)
@@ -30,7 +30,7 @@ Before writing any code, operate in read-only mode:
30
30
  - Map dependencies between components
31
31
  - Note risks and unknowns
32
32
 
33
- **Do NOT write code during planning.** The output is a plan document saved to `tasks/plan.md` and a task list saved to `tasks/todo.md`, not implementation.
33
+ **Do NOT write code during planning.** The output is a plan document saved to `tasks/plan.md` and a task list recorded in the task list target (see Output Files; default `tasks/todo.md`), not implementation.
34
34
 
35
35
  ### Step 2: Identify the Dependency Graph
36
36
 
@@ -78,7 +78,7 @@ Each vertical slice delivers working, testable functionality.
78
78
 
79
79
  ### Step 4: Write Tasks
80
80
 
81
- Each task follows this structure:
81
+ Each task follows this structure, whether it lands in the markdown task list or as an item in an external tracker (see Output Files):
82
82
 
83
83
  ```markdown
84
84
  ## Task [N]: [Short descriptive title]
@@ -90,8 +90,8 @@ Each task follows this structure:
90
90
  - [ ] [Specific, testable condition]
91
91
 
92
92
  **Verification:**
93
- - [ ] Tests pass: `npm test -- --grep "feature-name"`
94
- - [ ] Build succeeds: `npm run build`
93
+ - [ ] Tests pass: [the repository's focused-test command]
94
+ - [ ] Build succeeds: [the repository's build command]
95
95
  - [ ] Manual check: [description of what to verify]
96
96
 
97
97
  **Dependencies:** [Task numbers this depends on, or "None"]
@@ -112,7 +112,7 @@ Arrange tasks so that:
112
112
  3. Verification checkpoints occur after every 2-3 tasks
113
113
  4. High-risk tasks are early (fail fast)
114
114
 
115
- Add explicit checkpoints:
115
+ Add explicit checkpoints to the task list target:
116
116
 
117
117
  ```markdown
118
118
  ## Checkpoint: After Tasks 1-3
@@ -142,10 +142,26 @@ If a task is L or larger, it should be broken into smaller tasks. An agent perfo
142
142
 
143
143
  ## Output Files
144
144
 
145
- - **Plan document:** Save the implementation plan to `tasks/plan.md`.
146
- - **Task list:** Save the checklist-style task list to `tasks/todo.md`.
145
+ - **Plan document:** Save the implementation plan to `tasks/plan.md`. This is always a markdown file — design decisions, risks, and open questions don't map cleanly onto individual tracker issues.
146
+ - **Task list:** Record each task in the **task list target** (defined below).
147
147
 
148
- Create the `tasks/` directory if it does not exist. These paths are the convention expected by the `/build` command and other downstream tooling.
148
+ Create the `tasks/` directory if it does not exist.
149
+
150
+ **Never overwrite an incomplete plan.** Before writing `tasks/plan.md` or `tasks/todo.md`, check whether they already exist and still contain unchecked tasks:
151
+
152
+ - Same work being replanned (the user asked to revise or extend this plan) → update the existing files in place.
153
+ - Different work → **stop and ask.** The unchecked tasks may be mid-build in another session. Do not delete, overwrite, or rename the existing files on your own; present the conflict and let the user decide (finish the old plan first, explicitly discard it, or tell you where the new plan should go).
154
+
155
+ The same rule applies to an external task list target: never bulk-close or delete another plan's open tracker items to make room for new ones.
156
+
157
+ ### Task List Target
158
+
159
+ The task list target is where tasks and checkpoints are recorded. It is defined once, here; every other reference in this skill defers to it.
160
+
161
+ - **Default: a checklist-style markdown file at `tasks/todo.md`.** This is the convention the `/build` command and other downstream tooling expect. Use it unless the project says otherwise.
162
+ - **External tracker:** if the project's agent rules (`CLAUDE.md`, `AGENTS.md`, etc.) or the user designate an issue tracker (e.g. GitHub Issues, Jira, Linear, `bd`/beads), create one tracker item per task instead of writing `tasks/todo.md`. Map the Step 4 structure onto the tracker's fields: acceptance criteria and verification steps in the item body, dependencies via the tracker's linking mechanism (`bd dep add`, "blocked by", etc.). Record Step 5 checkpoints as tracker items too, or as a checklist in the plan document if the tracker has no natural equivalent.
163
+
164
+ When using an external tracker, note it in `tasks/plan.md` (e.g. "Tasks tracked in Linear project FOO") so downstream steps and future sessions know where to look, and keep the plan document's Task List section as an ordered index of tracker item IDs or links rather than a duplicate checklist.
149
165
 
150
166
  ## Plan Document Template
151
167
 
@@ -192,6 +208,8 @@ Create the `tasks/` directory if it does not exist. These paths are the conventi
192
208
  - [Question needing human input]
193
209
  ```
194
210
 
211
+ When tasks live in an external tracker, keep the Task List section above as an ordered index of tracker item IDs or links instead of a duplicate checklist.
212
+
195
213
  ## Parallelization Opportunities
196
214
 
197
215
  When multiple agents or sessions are available:
@@ -208,10 +226,13 @@ When multiple agents or sessions are available:
208
226
  | "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
209
227
  | "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
210
228
  | "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |
229
+ | "The old `tasks/plan.md` is stale, I'll just replace it" | Unchecked tasks may be mid-build in another session. Overwriting them destroys work state that exists nowhere else. Stop and ask. |
211
230
 
212
231
  ## Red Flags
213
232
 
214
233
  - Starting implementation without a written task list
234
+ - Overwriting a `tasks/plan.md` or `tasks/todo.md` that still has unchecked tasks for different work, without asking
235
+ - Writing `tasks/todo.md` when the project has designated an external tracker (or scattering tasks across both)
215
236
  - Tasks that say "implement the feature" without acceptance criteria
216
237
  - No verification steps in the plan
217
238
  - All tasks are XL-sized
@@ -225,10 +246,12 @@ Before starting implementation, confirm:
225
246
  - [ ] Every task has acceptance criteria
226
247
  - [ ] Every task has a verification step
227
248
  - [ ] Task dependencies are identified and ordered correctly
249
+ - [ ] Tasks are recorded in the task list target (default `tasks/todo.md`)
250
+ - [ ] No pre-existing incomplete plan was overwritten without explicit user confirmation
228
251
  - [ ] No task touches more than ~5 files
229
252
  - [ ] Checkpoints exist between major phases
230
253
  - [ ] The human has reviewed and approved the plan
231
254
 
232
255
  ## See Also
233
256
 
234
- Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of the project-wide Definition of Done, the standing bar every task clears before it counts as done. See `references/definition-of-done.md`.
257
+ Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of the project-wide Definition of Done, the standing bar every task clears before it counts as done. See `../../references/definition-of-done.md`.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: security-and-hardening
3
- description: Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services.
3
+ description: Hardens code against vulnerabilities. Use when auditing an input handler for vulnerabilities, when handling user input, authentication, data storage, or external integrations, or when checking a login flow is safe against the OWASP Top Ten. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. Use when auditing dependencies for known vulnerabilities, triaging package-manager audit findings, or assessing supply-chain risk in a new package. Use when personal data or privacy compliance (GDPR, CCPA) is involved.
4
4
  ---
5
5
 
6
6
  # Security and Hardening
@@ -22,7 +22,7 @@ Security-first development practices for web applications. Treat every external
22
22
 
23
23
  Controls bolted on without a threat model are guesses. Before hardening, spend five minutes thinking like an attacker:
24
24
 
25
- 1. **Map the trust boundaries.** Where does untrusted data cross into your system? HTTP requests, form fields, file uploads, webhooks, third-party APIs, message queues, and **LLM output**. Every boundary is attack surface.
25
+ 1. **Map the trust boundaries.** Where does untrusted data cross into your system? HTTP requests, form fields, file uploads, webhooks, third-party APIs, message queues, and **LLM output** — plus the local values that look internal because the OS handed them to you: another process's command line or environment, filenames on a shared volume, a path in a job payload. Trust follows who *wrote* a value, not which channel delivered it. Every boundary is attack surface.
26
26
  2. **Name the assets.** What's worth stealing or breaking? Credentials, PII, payment data, admin actions, money movement.
27
27
  3. **Run STRIDE over each boundary** — a quick lens, not a ceremony:
28
28
 
@@ -74,7 +74,7 @@ If you can't name the trust boundaries for a feature, you're not ready to secure
74
74
 
75
75
  ## OWASP Top 10 Prevention Patterns
76
76
 
77
- These are prevention patterns, not a ranking. For the 2021 ordering, see the quick-reference table in `references/security-checklist.md`.
77
+ These are prevention patterns, not a ranking. For the 2021 ordering, see the quick-reference table in `../../references/security-checklist.md`.
78
78
 
79
79
  ### Injection (SQL, NoSQL, OS Command)
80
80
 
@@ -269,6 +269,14 @@ function validateUpload(file: UploadedFile) {
269
269
  }
270
270
  ```
271
271
 
272
+ ### Destructive Operations on Derived Paths
273
+
274
+ A delete, move, or overwrite is only as safe as the value that names its target. Reading that value from the kernel, a job payload, or a sibling service proves where it *arrived from*, not who *wrote* it — another process's command line is as attacker-controlled as a form field. A shape check ("absolute path, at least one directory deep") proves well-formedness and gets mistaken for authorization; that is how a cleanup routine deletes the root instead of the leaf.
275
+
276
+ Before a destructive call, require all three: the resolved target sits under an **allowlisted root** (compare after resolving symlinks, never on the raw string); it is at least one level **below** that root, so a root is never itself the target; and it carries **evidence that it is yours**, read *before* the operation and before any teardown that removes it — otherwise "absent" and "not mine" are indistinguishable. On refusal, log the rejected target and stop: a cleanup that falls back to a broader default path is the failure this guards against. Worked example in `../../references/security-checklist.md`.
277
+
278
+ Two limits, because the check reads stronger than it is. A marker inside the tree is self-attestation — anything that can write there can write the marker — so the expected owner has to come from authenticated state, and the marker needs integrity protection (restrictive ownership, or a MAC) before it counts as authorization. And resolving a path and then operating on the *name* is a check/use race wherever an untrusted process can swap an ancestor: on a shared volume, hold the target by descriptor and use no-follow, beneath-the-root operations, or make sure the hierarchy cannot change for the duration.
279
+
272
280
  ## Triaging Dependency Audit Results
273
281
 
274
282
  Package-manager audits report known advisories; they do not prove a package is trustworthy or that vulnerable code is reachable. Use this decision tree:
@@ -300,7 +308,7 @@ When you defer a fix, document the reason and set a review date.
300
308
 
301
309
  Do not assume npm or treat the nearest manifest as the install root. Apply this order:
302
310
 
303
- 1. **Find the installation boundary and manager.** Use the workspace root that owns the lockfile, or an independent nested project only when it is outside that workspace. There, corroborate `packageManager` (when present), the lockfile, and CI; stop on disagreement or competing lockfiles. Pin the manager version and use the matrix in `references/security-checklist.md`.
311
+ 1. **Find the installation boundary and manager.** Use the workspace root that owns the lockfile, or an independent nested project only when it is outside that workspace. There, corroborate `packageManager` (when present), the lockfile, and CI; stop on disagreement or competing lockfiles. Pin the manager version and use the matrix in `../../references/security-checklist.md`.
304
312
  2. **Block dependency scripts before first execution.** Bootstrap with scripts disabled or a documented fail-closed policy, inspect the pending script source, approve only the minimum required packages, commit the policy, then verify with a clean frozen/immutable install. Never blanket-approve scripts.
305
313
 
306
314
  Audits only find known advisories; they do not catch a newly malicious or typosquatted package. Therefore:
@@ -329,6 +337,20 @@ app.use('/api/auth/', rateLimit({
329
337
  }));
330
338
  ```
331
339
 
340
+ **Count in a shared store once there is more than one process.** `express-rate-limit` keeps its counters in process memory by default. Behind a load balancer each instance holds its own count, so the effective limit is `max × instances`; on serverless or edge runtimes a fresh invocation starts from zero, so the auth limit above may never fire. Pass a shared `store` (Redis via `rate-limit-redis`), or use an HTTP-based limiter that works where a long-lived TCP connection does not (for example `@upstash/ratelimit`):
341
+
342
+ ```typescript
343
+ import { Ratelimit } from '@upstash/ratelimit';
344
+ import { Redis } from '@upstash/redis';
345
+
346
+ const authLimiter = new Ratelimit({
347
+ redis: Redis.fromEnv(), // UPSTASH_REDIS_REST_URL + _TOKEN
348
+ limiter: Ratelimit.slidingWindow(10, '15 m'), // 10 attempts per 15 minutes, across all instances
349
+ });
350
+ const { success } = await authLimiter.limit(`login:${req.ip}`);
351
+ if (!success) return res.status(429).end();
352
+ ```
353
+
332
354
  ## Secrets Management
333
355
 
334
356
  ```
@@ -353,6 +375,27 @@ git diff --cached | grep -i "password\|secret\|api_key\|token"
353
375
 
354
376
  **If a secret is ever committed, rotate it.** Deleting the line or rewriting history is not enough — assume it's compromised the moment it reaches a remote. Revoke and reissue the key first, then purge it from history.
355
377
 
378
+ ## Data Privacy & Compliance
379
+
380
+ Securing data is "can an attacker read it?" Privacy is "should *we* even hold it, and for how long?" — a separate question that hardening doesn't answer. The cheapest data to protect, breach, and comply over is the data you never collected. Treat personal data as a liability to minimize, not an asset to hoard.
381
+
382
+ **Know what you hold.** You can't protect or honor a deletion request for data you can't find. Classify fields as you add them:
383
+
384
+ | Class | Examples | Handling |
385
+ |---|---|---|
386
+ | **Non-personal** | Aggregates, anonymized counts | Normal handling |
387
+ | **Personal (PII)** | Name, email, IP, device/user IDs | Minimize, access-control, include in export/delete |
388
+ | **Sensitive** | Health, finance, location, biometrics, gov IDs, anything about minors | Extra basis to collect, stricter access, often encryption + audit logging |
389
+
390
+ **Operating rules:**
391
+ - **Minimize and set a purpose.** Collect a field only against a stated use. "It might be useful later" is not a purpose — it's latent breach scope. Don't log PII into telemetry (the `observability-and-instrumentation` skill makes the same point from the ops side).
392
+ - **Set retention up front, then actually delete.** Every personal-data store needs a TTL and a working deletion path — including backups, caches, search indexes, and analytics copies. Data with no expiry is a breach scheduled for later.
393
+ - **Support the data-subject rights your jurisdiction requires** (GDPR/CCPA and kin): export, correct, and delete on request. These are engineering features — design the schema so a user's data is *findable* and *erasable*, not smeared irreversibly across systems.
394
+ - **Get consent before collection or third-party sharing**, and make it auditable. Sending PII to an analytics/ad/LLM vendor is "sharing" — the user's choice gates it, and the vendor needs a data-processing agreement.
395
+ - **Localize defaults, don't hardcode one region's law.** Data-residency and rules differ by user location; make the policy a configurable boundary, not an assumption.
396
+
397
+ When data crosses a trust boundary, validate it as untrusted (see Input Validation above); when a privacy incident exposes personal data, the breach-notification clock is part of the postmortem — follow the `debugging-and-error-recovery` skill.
398
+
356
399
  ## Securing AI / LLM Features
357
400
 
358
401
  If your app calls an LLM — chatbots, summarizers, agents, RAG — it inherits a new attack surface. Map it to the [OWASP Top 10 for LLM Applications (2025)](https://genai.owasp.org/llm-top-10/):
@@ -400,11 +443,15 @@ container.textContent = await llm.reply(userMessage);
400
443
  - [ ] SQL queries are parameterized
401
444
  - [ ] HTML output is encoded/escaped
402
445
  - [ ] Server-side URL fetches are allowlisted (no SSRF to internal services)
446
+ - [ ] Delete/move/overwrite targets built from data are checked against an allowlisted root, a minimum depth, and ownership evidence read before the operation
403
447
 
404
448
  ### Data
405
449
  - [ ] No secrets in code or version control
406
450
  - [ ] Sensitive fields excluded from API responses
407
451
  - [ ] PII encrypted at rest (if applicable)
452
+ - [ ] Personal data is classified, collected against a stated purpose, and minimized
453
+ - [ ] Personal data has a retention limit and a working deletion path (incl. backups/indexes)
454
+ - [ ] Export/delete (data-subject) requests are supported where required; sharing with third parties has consent
408
455
 
409
456
  ### Infrastructure
410
457
  - [ ] Security headers configured (CSP, HSTS, etc.)
@@ -424,7 +471,7 @@ container.textContent = await llm.reply(userMessage);
424
471
  ```
425
472
  ## See Also
426
473
 
427
- For detailed security checklists and pre-commit verification steps, see `references/security-checklist.md`.
474
+ For detailed security checklists and pre-commit verification steps, see `../../references/security-checklist.md`.
428
475
 
429
476
  ## Common Rationalizations
430
477
 
@@ -438,19 +485,26 @@ For detailed security checklists and pre-commit verification steps, see `referen
438
485
  | "Threat modeling is overkill here" | Five minutes of "how would I attack this?" prevents the design flaws no control can patch later. |
439
486
  | "It's just LLM output, it's only text" | That "text" can be a SQL statement, a script tag, or a shell command. Treat it like any untrusted input. |
440
487
  | "The audit passed, so the dependency is safe" | Audits match known advisories. They do not detect a newly malicious package or make unreviewed install scripts safe to execute. |
488
+ | "Collect it now, we might need it later" | Data you don't hold can't be breached, subpoenaed, or mis-deleted. "Might need it" is breach scope, not a purpose. |
489
+ | "We'll handle deletion requests manually" | Manual erasure misses backups, caches, and analytics copies. If the schema can't find a user's data, you can't honor the request — design for it. |
490
+ | "Compliance is legal's problem, not ours" | Export, deletion, retention, and consent are schema and code. Legal can't bolt them on after you've smeared PII across ten systems. |
441
491
 
442
492
  ## Red Flags
443
493
 
444
494
  - User input passed directly to database queries, shell commands, or HTML rendering
495
+ - A delete, move, or overwrite whose target comes from a payload, a config value, or another process's command line, guarded only by a shape check on the path
445
496
  - Secrets in source code or commit history
446
497
  - API endpoints without authentication or authorization checks
447
498
  - Missing CORS configuration or wildcard (`*`) origins
448
- - No rate limiting on authentication endpoints
499
+ - No rate limiting on authentication endpoints, or an in-memory limiter in front of more than one instance
449
500
  - Stack traces or internal errors exposed to users
450
501
  - Dependencies with known critical vulnerabilities, competing lockfiles at one installation boundary, non-reproducible installs, or blanket-approved scripts
451
502
  - Server fetches user-supplied URLs without an allowlist (SSRF)
452
503
  - LLM/model output passed into a query, the DOM, a shell, or `eval`
453
504
  - Secrets, PII, or the full system prompt placed inside an LLM context window
505
+ - Personal data collected with no stated purpose, retention limit, or deletion path
506
+ - PII sent to analytics/ad/LLM vendors with no consent or data-processing agreement
507
+ - "Delete my account" that only flips a flag while the personal data lingers in stores and backups
454
508
 
455
509
  ## Verification
456
510
 
@@ -459,9 +513,12 @@ After implementing security-relevant code:
459
513
  - [ ] The native audit has no unmitigated reachable critical/high findings; CI preserves the authoritative lockfile and blocks unreviewed dependency scripts
460
514
  - [ ] No secrets in source code or git history
461
515
  - [ ] All user input validated at system boundaries
516
+ - [ ] Destructive filesystem operations resolve symlinks, then verify allowlisted root, minimum depth, and ownership before running
462
517
  - [ ] Authentication and authorization checked on every protected endpoint
463
518
  - [ ] Security headers present in response (check with browser DevTools)
464
519
  - [ ] Error responses don't expose internal details
465
- - [ ] Rate limiting active on auth endpoints
520
+ - [ ] Rate limiting active on auth endpoints, backed by a shared store when more than one instance serves traffic
466
521
  - [ ] Server-side URL fetches validated against an allowlist (no SSRF)
467
522
  - [ ] LLM/model output validated and encoded before use (if AI features present)
523
+ - [ ] Personal data is classified, minimized to a stated purpose, and has a retention limit
524
+ - [ ] Deletion and export requests work end-to-end (including backups, caches, and analytics copies)