@devenius/junamis-skills 0.0.0-stage → 1.1.0

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 (311) hide show
  1. package/CHANGELOG.md +150 -0
  2. package/LICENSE +21 -0
  3. package/README.md +231 -2
  4. package/SECURITY.md +81 -0
  5. package/bin/junamis-skills.js +7 -0
  6. package/dist/cli.d.ts +59 -0
  7. package/dist/cli.d.ts.map +1 -0
  8. package/dist/cli.js +564 -0
  9. package/dist/cli.js.map +1 -0
  10. package/dist/color.d.ts +40 -0
  11. package/dist/color.d.ts.map +1 -0
  12. package/dist/color.js +55 -0
  13. package/dist/color.js.map +1 -0
  14. package/dist/design/atomic.d.ts +4 -0
  15. package/dist/design/atomic.d.ts.map +1 -0
  16. package/dist/design/atomic.js +14 -0
  17. package/dist/design/atomic.js.map +1 -0
  18. package/dist/design/bootstrap.d.ts +23 -0
  19. package/dist/design/bootstrap.d.ts.map +1 -0
  20. package/dist/design/bootstrap.js +411 -0
  21. package/dist/design/bootstrap.js.map +1 -0
  22. package/dist/design/cli.d.ts +86 -0
  23. package/dist/design/cli.d.ts.map +1 -0
  24. package/dist/design/cli.js +425 -0
  25. package/dist/design/cli.js.map +1 -0
  26. package/dist/design/delta.d.ts +45 -0
  27. package/dist/design/delta.d.ts.map +1 -0
  28. package/dist/design/delta.js +557 -0
  29. package/dist/design/delta.js.map +1 -0
  30. package/dist/design/drift.d.ts +26 -0
  31. package/dist/design/drift.d.ts.map +1 -0
  32. package/dist/design/drift.js +341 -0
  33. package/dist/design/drift.js.map +1 -0
  34. package/dist/design/errors.d.ts +25 -0
  35. package/dist/design/errors.d.ts.map +1 -0
  36. package/dist/design/errors.js +30 -0
  37. package/dist/design/errors.js.map +1 -0
  38. package/dist/design/events.d.ts +18 -0
  39. package/dist/design/events.d.ts.map +1 -0
  40. package/dist/design/events.js +44 -0
  41. package/dist/design/events.js.map +1 -0
  42. package/dist/design/fingerprint.d.ts +10 -0
  43. package/dist/design/fingerprint.d.ts.map +1 -0
  44. package/dist/design/fingerprint.js +66 -0
  45. package/dist/design/fingerprint.js.map +1 -0
  46. package/dist/design/index-gen.d.ts +16 -0
  47. package/dist/design/index-gen.d.ts.map +1 -0
  48. package/dist/design/index-gen.js +94 -0
  49. package/dist/design/index-gen.js.map +1 -0
  50. package/dist/design/schema.d.ts +54 -0
  51. package/dist/design/schema.d.ts.map +1 -0
  52. package/dist/design/schema.js +408 -0
  53. package/dist/design/schema.js.map +1 -0
  54. package/dist/design/yaml.d.ts +12 -0
  55. package/dist/design/yaml.d.ts.map +1 -0
  56. package/dist/design/yaml.js +264 -0
  57. package/dist/design/yaml.js.map +1 -0
  58. package/dist/external.d.ts +61 -0
  59. package/dist/external.d.ts.map +1 -0
  60. package/dist/external.js +426 -0
  61. package/dist/external.js.map +1 -0
  62. package/dist/guide.d.ts +17 -0
  63. package/dist/guide.d.ts.map +1 -0
  64. package/dist/guide.js +219 -0
  65. package/dist/guide.js.map +1 -0
  66. package/dist/index.d.ts +2 -0
  67. package/dist/index.d.ts.map +1 -0
  68. package/dist/index.js +7 -0
  69. package/dist/index.js.map +1 -0
  70. package/dist/install-external.d.ts +3 -0
  71. package/dist/install-external.d.ts.map +1 -0
  72. package/dist/install-external.js +37 -0
  73. package/dist/install-external.js.map +1 -0
  74. package/dist/library-install.d.ts +39 -0
  75. package/dist/library-install.d.ts.map +1 -0
  76. package/dist/library-install.js +663 -0
  77. package/dist/library-install.js.map +1 -0
  78. package/dist/orchestrator/boot.d.ts +3 -0
  79. package/dist/orchestrator/boot.d.ts.map +1 -0
  80. package/dist/orchestrator/boot.js +515 -0
  81. package/dist/orchestrator/boot.js.map +1 -0
  82. package/dist/orchestrator/cli.d.ts +37 -0
  83. package/dist/orchestrator/cli.d.ts.map +1 -0
  84. package/dist/orchestrator/cli.js +563 -0
  85. package/dist/orchestrator/cli.js.map +1 -0
  86. package/dist/orchestrator/commands.d.ts +46 -0
  87. package/dist/orchestrator/commands.d.ts.map +1 -0
  88. package/dist/orchestrator/commands.js +752 -0
  89. package/dist/orchestrator/commands.js.map +1 -0
  90. package/dist/orchestrator/compaction.d.ts +21 -0
  91. package/dist/orchestrator/compaction.d.ts.map +1 -0
  92. package/dist/orchestrator/compaction.js +93 -0
  93. package/dist/orchestrator/compaction.js.map +1 -0
  94. package/dist/orchestrator/drift.d.ts +11 -0
  95. package/dist/orchestrator/drift.d.ts.map +1 -0
  96. package/dist/orchestrator/drift.js +181 -0
  97. package/dist/orchestrator/drift.js.map +1 -0
  98. package/dist/orchestrator/errors.d.ts +52 -0
  99. package/dist/orchestrator/errors.d.ts.map +1 -0
  100. package/dist/orchestrator/errors.js +96 -0
  101. package/dist/orchestrator/errors.js.map +1 -0
  102. package/dist/orchestrator/frontmatter.d.ts +6 -0
  103. package/dist/orchestrator/frontmatter.d.ts.map +1 -0
  104. package/dist/orchestrator/frontmatter.js +50 -0
  105. package/dist/orchestrator/frontmatter.js.map +1 -0
  106. package/dist/orchestrator/fsx.d.ts +45 -0
  107. package/dist/orchestrator/fsx.d.ts.map +1 -0
  108. package/dist/orchestrator/fsx.js +295 -0
  109. package/dist/orchestrator/fsx.js.map +1 -0
  110. package/dist/orchestrator/handoff.d.ts +8 -0
  111. package/dist/orchestrator/handoff.d.ts.map +1 -0
  112. package/dist/orchestrator/handoff.js +246 -0
  113. package/dist/orchestrator/handoff.js.map +1 -0
  114. package/dist/orchestrator/hash.d.ts +10 -0
  115. package/dist/orchestrator/hash.d.ts.map +1 -0
  116. package/dist/orchestrator/hash.js +65 -0
  117. package/dist/orchestrator/hash.js.map +1 -0
  118. package/dist/orchestrator/journal.d.ts +35 -0
  119. package/dist/orchestrator/journal.d.ts.map +1 -0
  120. package/dist/orchestrator/journal.js +163 -0
  121. package/dist/orchestrator/journal.js.map +1 -0
  122. package/dist/orchestrator/lease.d.ts +31 -0
  123. package/dist/orchestrator/lease.d.ts.map +1 -0
  124. package/dist/orchestrator/lease.js +175 -0
  125. package/dist/orchestrator/lease.js.map +1 -0
  126. package/dist/orchestrator/plan.d.ts +27 -0
  127. package/dist/orchestrator/plan.d.ts.map +1 -0
  128. package/dist/orchestrator/plan.js +240 -0
  129. package/dist/orchestrator/plan.js.map +1 -0
  130. package/dist/orchestrator/report.d.ts +49 -0
  131. package/dist/orchestrator/report.d.ts.map +1 -0
  132. package/dist/orchestrator/report.js +244 -0
  133. package/dist/orchestrator/report.js.map +1 -0
  134. package/dist/orchestrator/state.d.ts +43 -0
  135. package/dist/orchestrator/state.d.ts.map +1 -0
  136. package/dist/orchestrator/state.js +369 -0
  137. package/dist/orchestrator/state.js.map +1 -0
  138. package/dist/orchestrator/store.d.ts +42 -0
  139. package/dist/orchestrator/store.d.ts.map +1 -0
  140. package/dist/orchestrator/store.js +202 -0
  141. package/dist/orchestrator/store.js.map +1 -0
  142. package/dist/orchestrator/test-hooks.d.ts +5 -0
  143. package/dist/orchestrator/test-hooks.d.ts.map +1 -0
  144. package/dist/orchestrator/test-hooks.js +31 -0
  145. package/dist/orchestrator/test-hooks.js.map +1 -0
  146. package/dist/orchestrator/time.d.ts +11 -0
  147. package/dist/orchestrator/time.d.ts.map +1 -0
  148. package/dist/orchestrator/time.js +38 -0
  149. package/dist/orchestrator/time.js.map +1 -0
  150. package/dist/paths.d.ts +9 -0
  151. package/dist/paths.d.ts.map +1 -0
  152. package/dist/paths.js +42 -0
  153. package/dist/paths.js.map +1 -0
  154. package/dist/pinned-source.d.ts +13 -0
  155. package/dist/pinned-source.d.ts.map +1 -0
  156. package/dist/pinned-source.js +238 -0
  157. package/dist/pinned-source.js.map +1 -0
  158. package/dist/reconcile/cli.d.ts +17 -0
  159. package/dist/reconcile/cli.d.ts.map +1 -0
  160. package/dist/reconcile/cli.js +171 -0
  161. package/dist/reconcile/cli.js.map +1 -0
  162. package/dist/reconcile/detectors.d.ts +29 -0
  163. package/dist/reconcile/detectors.d.ts.map +1 -0
  164. package/dist/reconcile/detectors.js +294 -0
  165. package/dist/reconcile/detectors.js.map +1 -0
  166. package/dist/reconcile/manifest.d.ts +11 -0
  167. package/dist/reconcile/manifest.d.ts.map +1 -0
  168. package/dist/reconcile/manifest.js +118 -0
  169. package/dist/reconcile/manifest.js.map +1 -0
  170. package/dist/reconcile/queue.d.ts +3 -0
  171. package/dist/reconcile/queue.d.ts.map +1 -0
  172. package/dist/reconcile/queue.js +723 -0
  173. package/dist/reconcile/queue.js.map +1 -0
  174. package/dist/reconcile/score.d.ts +19 -0
  175. package/dist/reconcile/score.d.ts.map +1 -0
  176. package/dist/reconcile/score.js +58 -0
  177. package/dist/reconcile/score.js.map +1 -0
  178. package/dist/scripts/check-opencode-config.d.ts +12 -0
  179. package/dist/scripts/check-opencode-config.d.ts.map +1 -0
  180. package/dist/scripts/check-opencode-config.js +216 -0
  181. package/dist/scripts/check-opencode-config.js.map +1 -0
  182. package/dist/scripts/check-pack.d.ts +3 -0
  183. package/dist/scripts/check-pack.d.ts.map +1 -0
  184. package/dist/scripts/check-pack.js +74 -0
  185. package/dist/scripts/check-pack.js.map +1 -0
  186. package/dist/scripts/check-pins.d.ts +9 -0
  187. package/dist/scripts/check-pins.d.ts.map +1 -0
  188. package/dist/scripts/check-pins.js +65 -0
  189. package/dist/scripts/check-pins.js.map +1 -0
  190. package/dist/scripts/check-security.d.ts +3 -0
  191. package/dist/scripts/check-security.d.ts.map +1 -0
  192. package/dist/scripts/check-security.js +47 -0
  193. package/dist/scripts/check-security.js.map +1 -0
  194. package/dist/scripts/check-skills-lock.d.ts +7 -0
  195. package/dist/scripts/check-skills-lock.d.ts.map +1 -0
  196. package/dist/scripts/check-skills-lock.js +36 -0
  197. package/dist/scripts/check-skills-lock.js.map +1 -0
  198. package/dist/scripts/check-skills-sync.d.ts +7 -0
  199. package/dist/scripts/check-skills-sync.d.ts.map +1 -0
  200. package/dist/scripts/check-skills-sync.js +146 -0
  201. package/dist/scripts/check-skills-sync.js.map +1 -0
  202. package/dist/scripts/check-yaml.d.ts +3 -0
  203. package/dist/scripts/check-yaml.d.ts.map +1 -0
  204. package/dist/scripts/check-yaml.js +41 -0
  205. package/dist/scripts/check-yaml.js.map +1 -0
  206. package/dist/scripts/publish-npm.d.ts +3 -0
  207. package/dist/scripts/publish-npm.d.ts.map +1 -0
  208. package/dist/scripts/publish-npm.js +67 -0
  209. package/dist/scripts/publish-npm.js.map +1 -0
  210. package/dist/scripts/release-check.d.ts +3 -0
  211. package/dist/scripts/release-check.d.ts.map +1 -0
  212. package/dist/scripts/release-check.js +97 -0
  213. package/dist/scripts/release-check.js.map +1 -0
  214. package/dist/scripts/support.d.ts +41 -0
  215. package/dist/scripts/support.d.ts.map +1 -0
  216. package/dist/scripts/support.js +78 -0
  217. package/dist/scripts/support.js.map +1 -0
  218. package/dist/targets/claude.d.ts +4 -0
  219. package/dist/targets/claude.d.ts.map +1 -0
  220. package/dist/targets/claude.js +42 -0
  221. package/dist/targets/claude.js.map +1 -0
  222. package/dist/targets/cline.d.ts +4 -0
  223. package/dist/targets/cline.d.ts.map +1 -0
  224. package/dist/targets/cline.js +39 -0
  225. package/dist/targets/cline.js.map +1 -0
  226. package/dist/targets/cursor.d.ts +4 -0
  227. package/dist/targets/cursor.d.ts.map +1 -0
  228. package/dist/targets/cursor.js +40 -0
  229. package/dist/targets/cursor.js.map +1 -0
  230. package/dist/targets/index.d.ts +4 -0
  231. package/dist/targets/index.d.ts.map +1 -0
  232. package/dist/targets/index.js +11 -0
  233. package/dist/targets/index.js.map +1 -0
  234. package/dist/targets/opencode.d.ts +4 -0
  235. package/dist/targets/opencode.d.ts.map +1 -0
  236. package/dist/targets/opencode.js +48 -0
  237. package/dist/targets/opencode.js.map +1 -0
  238. package/dist/targets/windsurf.d.ts +4 -0
  239. package/dist/targets/windsurf.d.ts.map +1 -0
  240. package/dist/targets/windsurf.js +41 -0
  241. package/dist/targets/windsurf.js.map +1 -0
  242. package/dist/types/common.d.ts +193 -0
  243. package/dist/types/common.d.ts.map +1 -0
  244. package/dist/types/common.js +6 -0
  245. package/dist/types/common.js.map +1 -0
  246. package/dist/types/design.d.ts +185 -0
  247. package/dist/types/design.d.ts.map +1 -0
  248. package/dist/types/design.js +3 -0
  249. package/dist/types/design.js.map +1 -0
  250. package/dist/types/guards.d.ts +13 -0
  251. package/dist/types/guards.d.ts.map +1 -0
  252. package/dist/types/guards.js +64 -0
  253. package/dist/types/guards.js.map +1 -0
  254. package/dist/types/handoff.d.ts +29 -0
  255. package/dist/types/handoff.d.ts.map +1 -0
  256. package/dist/types/handoff.js +3 -0
  257. package/dist/types/handoff.js.map +1 -0
  258. package/dist/types/index.d.ts +7 -0
  259. package/dist/types/index.d.ts.map +1 -0
  260. package/dist/types/index.js +11 -0
  261. package/dist/types/index.js.map +1 -0
  262. package/dist/types/orchestrator.d.ts +414 -0
  263. package/dist/types/orchestrator.d.ts.map +1 -0
  264. package/dist/types/orchestrator.js +4 -0
  265. package/dist/types/orchestrator.js.map +1 -0
  266. package/dist/types/reconcile.d.ts +160 -0
  267. package/dist/types/reconcile.d.ts.map +1 -0
  268. package/dist/types/reconcile.js +3 -0
  269. package/dist/types/reconcile.js.map +1 -0
  270. package/docs/RECONCILE.md +505 -0
  271. package/docs/design/_schema.md +506 -0
  272. package/junamis-skills.yml +328 -0
  273. package/library/EXTERNAL.md +35 -0
  274. package/library/HANDOFF.md +93 -0
  275. package/library/RESUME.md +429 -0
  276. package/library/SAFETY.md +83 -0
  277. package/library/agents/context-keeper.md +41 -0
  278. package/library/agents/frontend.md +43 -0
  279. package/library/agents/maintainer.md +44 -0
  280. package/library/agents/nestjs.md +40 -0
  281. package/library/agents/nextjs.md +40 -0
  282. package/library/agents/operator.md +42 -0
  283. package/library/agents/orchestrator.md +313 -0
  284. package/library/agents/researcher.md +40 -0
  285. package/library/agents/reviewer.md +40 -0
  286. package/library/skills/db-migrate/SKILL.md +50 -0
  287. package/library/skills/decision-record/SKILL.md +74 -0
  288. package/library/skills/dependency-upgrade/SKILL.md +57 -0
  289. package/library/skills/deploy-verify/SKILL.md +51 -0
  290. package/library/skills/document/SKILL.md +51 -0
  291. package/library/skills/env-doctor/SKILL.md +65 -0
  292. package/library/skills/frontend/SKILL.md +63 -0
  293. package/library/skills/handoff/SKILL.md +79 -0
  294. package/library/skills/incident-response/SKILL.md +69 -0
  295. package/library/skills/nestjs/SKILL.md +49 -0
  296. package/library/skills/nextjs/SKILL.md +48 -0
  297. package/library/skills/perf-budget/SKILL.md +62 -0
  298. package/library/skills/refactor-safely/SKILL.md +48 -0
  299. package/library/skills/release-prep/SKILL.md +75 -0
  300. package/library/skills/research/SKILL.md +66 -0
  301. package/library/skills/rollback/SKILL.md +49 -0
  302. package/library/skills/route/SKILL.md +107 -0
  303. package/library/skills/route-external/SKILL.md +67 -0
  304. package/library/skills/security-audit/SKILL.md +64 -0
  305. package/library/skills/skill-author/SKILL.md +49 -0
  306. package/opencode.json +5906 -0
  307. package/package.json +88 -4
  308. package/scripts/design-registry.mjs +7 -0
  309. package/scripts/orchestrator-state.mjs +7 -0
  310. package/scripts/reconcile.mjs +7 -0
  311. package/skills-lock.json +197 -0
@@ -0,0 +1,429 @@
1
+ # RESUME.md — Orchestrator Persistence & Resume Contract
2
+
3
+ **Status:** normative
4
+ **Schema version:** 1
5
+ **Companion contracts:** `HANDOFF.md` (step output format), `skills-lock.json` (manifest), `library/*` (internal overrides)
6
+
7
+ ---
8
+
9
+ ## 1. Purpose
10
+
11
+ Define how the orchestrator persists execution state so that **any new session can resume exactly where the previous one stopped**, without operator intervention.
12
+
13
+ This contract is **executable**: an orchestrator that implements it MUST be able to be killed at any instruction boundary and, on restart, produce a resume report and continue without duplicating side effects or skipping work.
14
+
15
+ ---
16
+
17
+ ## 2. Core principle
18
+
19
+ > **The orchestrator MUST NOT "remember". It MUST rehydrate.**
20
+
21
+ Model context is ephemeral and unreliable. The filesystem is the only durable memory. Every fact needed to resume MUST be derivable from the state root by replay. Nothing that matters MAY live only in a prompt, a conversation, or a sub-agent's memory.
22
+
23
+ ---
24
+
25
+ ## 3. Invariants (MUST rules)
26
+
27
+ 1. **I1 — Single state root.** All persistence lives under `ORCH_STATE_ROOT` (default `.orchestrator/`). Nothing important is written elsewhere.
28
+ 2. **I2 — Journal is truth.** `journal.ndjson` is the authoritative record. `state.json` is a derived snapshot. If they disagree, replay wins.
29
+ 3. **I3 — Boot before route.** The `resume` boot sequence (§6) MUST complete before `route` or any skill dispatch. It is not skippable, not conditional, not optimizable away.
30
+ 4. **I4 — Atomic commits.** Every state transition is one atomic file replace plus one journal append. No partial writes are observable.
31
+ 5. **I5 — Idempotent or escalated.** A step interrupted mid-flight is retried only if it declares `idempotent: true`; otherwise it escalates to `needs_review`. Never guess.
32
+ 6. **I6 — No blind resume on drift.** If the manifest hash or the override-map hash differs from the value recorded at plan time, the run enters `needs_review` and MUST NOT continue silently.
33
+ 7. **I7 — Single writer.** Only the lease holder writes `state.json`, `plan.json`, and `journal.ndjson`. Sub-agents write only under `tasks/<task_id>/`.
34
+ 8. **I8 — Append-only journal.** Journal entries are never edited or deleted. Compaction (§11) folds them into a checkpoint; it does not mutate them.
35
+
36
+ ---
37
+
38
+ ## 4. State root layout
39
+
40
+ ```
41
+ $ORCH_STATE_ROOT/
42
+ ├── STATE.md # generated, human-readable mirror (never read for logic)
43
+ ├── state.json # derived cursor snapshot
44
+ ├── plan.json # task graph
45
+ ├── journal.ndjson # append-only event log (SOURCE OF TRUTH)
46
+ ├── checkpoints/
47
+ │ └── <seq-zero-padded>.snapshot
48
+ ├── tasks/<task_id>/
49
+ │ ├── task.json
50
+ │ ├── handoffs/*.yaml # emitted per HANDOFF.md
51
+ │ └── artifacts/
52
+ ├── locks/
53
+ │ └── session-<session_id>.json
54
+ └── resume-report.md # regenerated on every boot
55
+ ```
56
+
57
+ `ORCH_STATE_ROOT` MUST be a persistent, host-local path. It MUST NOT be inside a temp dir, a container's ephemeral layer, or anything cleared between sessions.
58
+
59
+ ---
60
+
61
+ ## 5. File schemas
62
+
63
+ ### 5.1 `state.json`
64
+
65
+ ```json
66
+ {
67
+ "schema_version": 1,
68
+ "run_id": "run-20261109-001",
69
+ "created_at": "2026-11-09T10:00:00Z",
70
+ "updated_at": "2026-11-09T10:42:13Z",
71
+ "cursor": {
72
+ "task_id": "T-003",
73
+ "step_id": "T-003/develop/attempt-2",
74
+ "attempt": 2
75
+ },
76
+ "plan": { "path": "plan.json", "checksum": "sha256:ab12..." },
77
+ "env_fingerprint": {
78
+ "skills_lock_sha256": "sha256:cd34...",
79
+ "library_overrides_sha256": "sha256:ef56...",
80
+ "orchestrator_version": "0.4.1",
81
+ "handoff_schema_version": 1
82
+ },
83
+ "tasks_summary": {
84
+ "pending": 3, "in_progress": 1, "done": 5,
85
+ "failed": 0, "needs_review": 0
86
+ },
87
+ "journal_head": { "seq": 137, "event_hash": "sha256:78ab..." },
88
+ "last_checkpoint": "checkpoints/000120.snapshot"
89
+ }
90
+ ```
91
+
92
+ ### 5.2 `plan.json`
93
+
94
+ ```json
95
+ {
96
+ "schema_version": 1,
97
+ "run_id": "run-20261109-001",
98
+ "created_at": "2026-11-09T10:00:00Z",
99
+ "capabilities": ["scope", "architect", "develop", "test", "check", "document"],
100
+ "tasks": [
101
+ {
102
+ "task_id": "T-001",
103
+ "capability": "scope",
104
+ "depends_on": [],
105
+ "resolved_skill": "library/scope",
106
+ "resolution_source": "internal_override",
107
+ "idempotent": true,
108
+ "inputs_hash": "sha256:11aa..."
109
+ }
110
+ ],
111
+ "checksum": "sha256:ab12..."
112
+ }
113
+ ```
114
+
115
+ `checksum` is computed over the canonicalized `tasks` array. It is re-verified at every boot.
116
+
117
+ ### 5.3 `journal.ndjson` (one JSON object per line)
118
+
119
+ ```json
120
+ {"seq":136,"ts":"2026-11-09T10:41:58Z","type":"step_start","task_id":"T-003","step_id":"T-003/develop/attempt-2","attempt":2,"session_id":"s-7f3a","prev_hash":"sha256:..."}
121
+ {"seq":137,"ts":"2026-11-09T10:42:13Z","type":"step_end","task_id":"T-003","step_id":"T-003/develop/attempt-2","status":"done","handoff":"tasks/T-003/handoffs/develop-2.yaml","prev_hash":"sha256:..."}
122
+ ```
123
+
124
+ **Event types (minimum):**
125
+ `run_start`, `run_resume`, `lease_acquired`, `lease_taken_over`, `plan_created`, `step_start`, `step_end`, `task_status`, `drift_detected`, `reconcile_pass`, `queue_blocked`, `queue_stale`, `unknown_reason`, `run_stalled`, `priority_override`, `priority_override_rejected`, `checkpoint_written`, `escalation`, `run_complete`.
126
+
127
+ **Hash chaining:** each event carries `prev_hash` = hash of the previous event line. This makes truncation and tampering detectable during replay.
128
+
129
+ ### 5.4 `tasks/<task_id>/task.json`
130
+
131
+ ```json
132
+ {
133
+ "schema_version": 1,
134
+ "task_id": "T-003",
135
+ "capability": "develop",
136
+ "status": "in_progress",
137
+ "resolved_skill": "library/develop",
138
+ "resolution_source": "internal_override",
139
+ "current_step": {
140
+ "step_id": "T-003/develop/attempt-2",
141
+ "skill": "library/develop",
142
+ "attempt": 2,
143
+ "idempotent": true,
144
+ "started_at": "2026-11-09T10:41:58Z",
145
+ "session_id": "s-7f3a"
146
+ },
147
+ "inputs_hash": "sha256:11aa...",
148
+ "outputs": ["tasks/T-003/artifacts/plan.md"],
149
+ "updated_at": "2026-11-09T10:41:58Z"
150
+ }
151
+ ```
152
+
153
+ ### 5.5 `locks/session-<session_id>.json`
154
+
155
+ ```json
156
+ {
157
+ "session_id": "s-7f3a",
158
+ "pid": 4821,
159
+ "host": "dev-box",
160
+ "started_at": "2026-11-09T10:40:02Z",
161
+ "heartbeat_at": "2026-11-09T10:42:10Z",
162
+ "ttl_seconds": 60
163
+ }
164
+ ```
165
+
166
+ ### 5.6 `STATE.md`
167
+
168
+ Generated on every boot and after every compaction. Contents: run id, current cursor, task summary table, last 10 journal events, drift status. **It is a view, never an input.** The orchestrator MUST NOT parse it for logic.
169
+
170
+ ---
171
+
172
+ ## 6. Boot sequence (executable, non-skippable)
173
+
174
+ Run these in order at the start of **every** session, before any routing decision.
175
+
176
+ **B1 — Resolve state root.**
177
+ Read `ORCH_STATE_ROOT`. If absent, initialize a new run (§6a) and jump to B7.
178
+
179
+ **B2 — Acquire lease.**
180
+ - Scan `locks/`. For each lease, compute `now - heartbeat_at`.
181
+ - If a lease is within `ttl_seconds`: **abort** with `HALT: lease_held` and the owning session id. Do not proceed.
182
+ - If all leases are stale: acquire the newest one (reuse `session_id` slot), journal `lease_taken_over`, continue.
183
+ - If no lease exists: create `locks/session-<new>.json`, journal `lease_acquired`.
184
+ - Start the heartbeat writer (every `ttl/3`).
185
+
186
+ **B3 — Load and verify.**
187
+ - Parse `state.json`, `plan.json`.
188
+ - Assert `schema_version` matches the running orchestrator's supported version.
189
+ - Recompute `plan.checksum` and compare.
190
+ - Verify `journal.ndjson` hash chain from the last checkpoint forward.
191
+ - **On any failure:** attempt recovery by replaying from `last_checkpoint` (§11). If replay also fails, `HALT: corrupt_state`.
192
+
193
+ **B4 — Reconcile environment (drift check).**
194
+ - Compute `skills_lock_sha256` from `skills-lock.json`.
195
+ - Compute `library_overrides_sha256` from the resolved override map in `library/*`.
196
+ - Compute `design_registry` (`index_sha256`, `surface_count`, `status_counts`) from `docs/design/`, covering `INDEX.md` and every surface file.
197
+ - Compare all three against `state.env_fingerprint`.
198
+ - **On a missing recorded design fingerprint:** journal `design_baseline` and record the current value once. Do not block a run that predates the field.
199
+ - **On mismatch:** journal `drift_detected` with the diff, set run status to `needs_review`, write `resume-report.md` (status = `BLOCKED_DRIFT`), and **stop**. Do not dispatch any skill. Emit the exact diff, including the changed design files, so the operator (or a review skill) can decide.
200
+
201
+ **B5 — Reconcile in-flight work.**
202
+ For every task with `status == "in_progress"`:
203
+ - Read `current_step`.
204
+ - If `idempotent == true`: mark for **retry** (reset to `pending`, keep `attempt` counter, increment on next start).
205
+ - If `idempotent == false`: mark `needs_review`, journal `escalation` with reason `interrupted_non_idempotent`.
206
+ - Journal one `task_status` event per reconciled task.
207
+
208
+ **B6 — Load external handoffs.**
209
+ For each `tasks/<id>/handoffs/*.yaml`, validate against `HANDOFF.md`. Reject malformed handoffs into `needs_review`; do not silently drop them.
210
+
211
+ **B7 — Emit `resume-report.md`** (§12).
212
+
213
+ **B7.5 — RECONCILE pass.**
214
+ - If resume Status is `BLOCKED_DRIFT` or `HALT_CORRUPT`: write `$ORCH_STATE_ROOT/work-queue.json` with `status: blocked_drift` and one non-dispatchable `needs_review` item carrying the drift diff. Do not run detectors. Journal `reconcile_pass`.
215
+ - Otherwise run the RECONCILE pass: read `$ORCH_STATE_ROOT/reconcile/detectors.yaml`, run the enabled detectors, and write `work-queue.json` plus `reconcile-report.md`. Journal `reconcile_pass`, including an empty queue.
216
+ - Set `state.reconcile` to `ready` or `no_work` (or `blocked_drift`). Do not rewrite `plan.json`.
217
+
218
+ **B8 — Hand control to `route`.**
219
+ Pass `$ORCH_STATE_ROOT/work-queue.json` (not raw signals) as starting context. Set `state.cursor` to the first task in the order: `pending`/`in_progress` (retryable) tasks in `plan.json` dependency order.
220
+
221
+ ### 6a. First-run initialization
222
+
223
+ When `ORCH_STATE_ROOT` is empty:
224
+ 1. `mkdir -p` the full tree.
225
+ 2. Write `plan.json` (from the task graph produced by `scope`/`architect`).
226
+ 3. Write initial `state.json` with `cursor = null`, `journal_head.seq = 0`.
227
+ 4. Append `run_start` and `plan_created` to `journal.ndjson`.
228
+ 5. Continue to B7.
229
+
230
+ ---
231
+
232
+ ## 7. Task state machine
233
+
234
+ ```
235
+ pending ──► in_progress ──► done
236
+ │ │
237
+ │ ├──► failed ──► (retry policy) ──► in_progress
238
+ │ │
239
+ │ └──► needs_review ──► pending (after resolution)
240
+ │
241
+ └──► (blocked by depends_on)
242
+ ```
243
+
244
+ Rules:
245
+ - Only the orchestrator transitions `pending → in_progress`.
246
+ - Only the skill's emitted handoff (validated against `HANDOFF.md`) transitions `in_progress → done | failed`.
247
+ - `needs_review` is terminal until an explicit resolution event is journaled.
248
+ - A task MAY NOT be marked `done` without at least one validated handoff and its declared artifacts present on disk.
249
+
250
+ ---
251
+
252
+ ## 8. Atomic write protocol
253
+
254
+ Every mutation of `state.json`, `plan.json`, or any `task.json` MUST follow:
255
+
256
+ ```
257
+ 1. write <path>.tmp
258
+ 2. fsync <path>.tmp
259
+ 3. rename <path>.tmp -> <path>
260
+ 4. fsync <parent dir>
261
+ ```
262
+
263
+ Journal appends MUST be: `open(O_APPEND) → write(one complete line) → fsync`. Never split an event across writes. A trailing partial line on boot is truncated to the last valid newline and logged as `journal_truncated`.
264
+
265
+ **Commit pairing:** a state transition is only durable once *both* the journal event and the snapshot write succeed. Order: journal first, then snapshot. If the snapshot fails, replay from the journal on next boot will reconstruct it.
266
+
267
+ ---
268
+
269
+ ## 9. Idempotency & crash semantics
270
+
271
+ Every skill MUST declare `idempotent: true | false` in its frontmatter.
272
+
273
+ | Crash point | `idempotent: true` | `idempotent: false` |
274
+ |---|---|---|
275
+ | Before `step_start` journaled | retry, attempt unchanged | retry, attempt unchanged |
276
+ | After `step_start`, before side effect | retry, attempt + 1 | retry, attempt + 1 |
277
+ | After side effect, before `step_end` | retry, attempt + 1 | **escalate → needs_review** |
278
+ | After `step_end` journaled | already done, skip | already done, skip |
279
+
280
+ The orchestrator MUST record `step_start` **before** invoking the skill, and `step_end` **after** the handoff validates. A step with `step_start` and no `step_end` is the sole signal that the side-effect state is unknown.
281
+
282
+ ---
283
+
284
+ ## 10. Lease & concurrency
285
+
286
+ - Lease TTL default: **60s**; heartbeat every **20s**.
287
+ - Heartbeat write uses the same atomic replace protocol.
288
+ - A session that loses its lease file (deleted or overwritten by another `session_id`) MUST abort at the next step boundary and journal `lease_lost`.
289
+ - Sub-agents MUST NOT acquire leases or write outside `tasks/<their_task_id>/`. If a sub-agent needs to persist across sessions, it does so through its own handoff + artifacts, and the orchestrator folds them in.
290
+
291
+ ---
292
+
293
+ ## 11. Compaction
294
+
295
+ Trigger: every **N = 200** journal events, or when `journal.ndjson` exceeds 5 MB, whichever comes first.
296
+
297
+ Procedure:
298
+ 1. Replay journal to current seq, build full in-memory state.
299
+ 2. Write `checkpoints/<seq>.snapshot` atomically (serialized `state.json` + per-task `task.json` + `plan.json`).
300
+ 3. Journal `checkpoint_written` with `{seq, path, hash}`.
301
+ 4. Truncate `journal.ndjson` to entries after `seq`, preserving the hash chain head (`prev_hash` of the first retained event points at the checkpoint hash).
302
+
303
+ Recovery from a snapshot: load `checkpoints/<last>.snapshot`, then replay retained journal entries forward, verifying `prev_hash` at each step.
304
+
305
+ ---
306
+
307
+ ## 12. `resume-report.md` format
308
+
309
+ Generated at B7 and overwritten on every boot. Minimum content:
310
+
311
+ ```markdown
312
+ # Resume Report
313
+
314
+ - Run: run-20261109-001
315
+ - Generated: 2026-11-09T10:42:20Z
316
+ - Session: s-7f3a
317
+ - Status: RESUMING | BLOCKED_DRIFT | HALT_CORRUPT | NEW_RUN
318
+
319
+ ## Cursor
320
+ - Task: T-003 (develop) — in_progress, attempt 2
321
+ - Next action: retry (idempotent)
322
+
323
+ ## Tasks
324
+ | id | capability | status | attempts | resolved skill | source |
325
+ |----|-----------|--------|----------|----------------|--------|
326
+ | T-001 | scope | done | 1 | library/scope | internal |
327
+ | T-002 | architect | done | 1 | library/architect | internal |
328
+ | T-003 | develop | in_progress | 2 | library/develop | internal |
329
+
330
+ ## Reconciliation
331
+ - Interrupted tasks reconciled: 1 (T-003 → retry)
332
+ - Escalated to needs_review: 0
333
+ - Malformed handoffs: 0
334
+
335
+ ## Environment fingerprint
336
+ - skills-lock.json: sha256:cd34… (matches recorded)
337
+ - library overrides: sha256:ef56… (matches recorded)
338
+
339
+ ## Recent events
340
+ (last 10 journal entries, one per line)
341
+ ```
342
+
343
+ If `Status: BLOCKED_DRIFT`, the report MUST include a `## Drift` section listing exactly which files changed and the old/new hashes, so a review skill can act on it without re-deriving the diff.
344
+
345
+ ---
346
+
347
+ ## 13. Drift handling
348
+
349
+ | Drift | Action |
350
+ |---|---|
351
+ | `skills-lock.json` changed | `needs_review`; diff added skills / removed skills / version bumps |
352
+ | `library/*` override set changed | `needs_review`; diff added / removed / re-targeted overrides |
353
+ | Both unchanged | proceed normally |
354
+ | `plan.json` checksum mismatch | `HALT: corrupt_state` unless a journal event explains the change |
355
+
356
+ Rationale: resuming a plan built against an older override set is how the orchestrator ends up dispatching a shadowed external skill. Treat drift as a correctness event, not a warning.
357
+
358
+ ---
359
+
360
+ ## 14. Integration with `route` and `HANDOFF.md`
361
+
362
+ - `route` receives the resume report and MUST start from `state.cursor`, not from a fresh signal scan, when `Status: RESUMING`.
363
+ - Routing resolves **capability → skill** using the recorded `resolution_source` (`internal_override` | `manifest`). It MUST NOT re-resolve on resume if the fingerprint matches, because the resolution is part of the plan's checksum.
364
+ - Every dispatched skill MUST produce a handoff conforming to `HANDOFF.md`. Handoffs that fail validation are moved to `needs_review` and journaled; they are never silently discarded.
365
+ - The orchestrator folds validated handoffs into `task.json` and the journal. Sub-agents never touch `state.json`.
366
+
367
+ ---
368
+
369
+ ## 15. CI tests
370
+
371
+ **T1 — Crash injection.**
372
+ For each step boundary in a reference run: kill the process, restart, assert the resume report and final artifacts are identical to the uninterrupted run.
373
+
374
+ **T2 — Replay determinism.**
375
+ Replay `journal.ndjson` from an empty state and assert the reconstructed `state.json` is semantically equal to the snapshot.
376
+
377
+ **T3 — Drift refusal.**
378
+ Mutate `skills-lock.json` (add a skill), restart, assert `Status: BLOCKED_DRIFT` and that zero skills were dispatched.
379
+
380
+ **T4 — Override drift.**
381
+ Mutate `library/*` (re-target an override), restart, assert `BLOCKED_DRIFT` with a correct diff.
382
+
383
+ **T5 — Lease safety.**
384
+ Start two sessions against one state root; assert the second halts with `lease_held` and does not write.
385
+
386
+ **T6 — Non-idempotent escalation.**
387
+ Simulate a kill after side effect but before `step_end` on a `idempotent: false` skill; assert `needs_review`, not retry.
388
+
389
+ **T7 — Torn write recovery.**
390
+ Truncate `state.json` to half a JSON object and append a partial journal line; assert boot recovers from the last checkpoint and reports `journal_truncated`.
391
+
392
+ ---
393
+
394
+ ## 16. Acceptance criteria
395
+
396
+ The implementation is complete when **all** of the following hold:
397
+
398
+ - [ ] B1–B8 run before any routing on every session, with no bypass flag.
399
+ - [ ] Killing the orchestrator at any step boundary never loses progress and never duplicates a non-idempotent side effect.
400
+ - [ ] `journal.ndjson` replay reconstructs `state.json` exactly (T2 green).
401
+ - [ ] Manifest or override drift produces `BLOCKED_DRIFT` and zero dispatches (T3, T4 green).
402
+ - [ ] A second concurrent session cannot write to the state root (T5 green).
403
+ - [ ] `resume-report.md` is sufficient, on its own, for a fresh reader to know exactly what happens next.
404
+ - [ ] `STATE.md` is regenerated on every boot and never read as input.
405
+ - [ ] Every skill declares `idempotent`, and the orchestrator honors it per §9.
406
+
407
+ ---
408
+
409
+ ## 17. Non-goals
410
+
411
+ - This contract does **not** persist model context, prompt history, or reasoning traces. Only execution state.
412
+ - This contract does **not** define sandboxing, filesystem isolation, or process confinement. It assumes a trusted host-local state root.
413
+ - This contract does **not** replace `HANDOFF.md`; it consumes it.
414
+ - This contract does **not** define the override precedence algorithm itself — only that its hash is fingerprinted and drift-checked.
415
+
416
+ ---
417
+
418
+ ## Reference implementation (not normative)
419
+
420
+ This section names the reference implementation. It is not part of the normative contract above.
421
+
422
+ - State engine: `src/orchestrator/`.
423
+ - CLI source entry: `scripts/orchestrator-state.mjs`.
424
+ - Installed command: `junamis-orchestrator`.
425
+ - Default state root: `<project>/.orchestrator/`; `ORCH_STATE_ROOT` overrides it.
426
+ - Commands: `boot`, `plan set`, `plan show`, `start`, `end`, `resolve`, `status`, `checkpoint`, `lease acquire|heartbeat|release|status`, and `finish`.
427
+ - If `junamis-orchestrator` is not on `PATH`, run it through the package fallback: `npx --yes --package github:devenius/junamis-skills#main junamis-orchestrator ...`. The package's `prepare` script builds `dist/`, so the bin runs from built source.
428
+ - Exit codes: `0` success, `1` usage or I/O, `2` lease held or lost, `3` drift, `4` corrupt state, and `5` invalid transition or handoff.
429
+
@@ -0,0 +1,83 @@
1
+ # Safety policy: approval gate
2
+
3
+ This policy applies to every agent and every skill that runs in this project, library or external. An upstream skill's own wording does not override it.
4
+
5
+ ## The gate
6
+
7
+ Before running any command in the classes below, stop and show the user the exact command, what it changes, and what cannot be undone. Run it only after the user replies yes in this session. A general "go ahead" to the task is not approval for a destructive command; name the command.
8
+
9
+ | Class | Examples |
10
+ |---|---|
11
+ | File deletion | `rm -r`, `rm -f`, `rm -rf`, `rmSync`, `unlink`, `shred` |
12
+ | Privilege | `sudo`, `su`, `chmod -R`, `chown` |
13
+ | Global or system install | `npm i -g`, `pnpm add -g`, `brew install`, `apt install` |
14
+ | Git history or remote | `git push`, `git reset --hard`, `git clean`, `git rebase`, `git tag`, `git push --force`, `--no-verify` |
15
+ | Production or publish | `vercel deploy --prod`, `pnpm publish`, any deploy, and the npm registry commands `npm publish`, `npm stage publish`, `npm deprecate`, `npm unpublish`, `npm dist-tag`, `npm owner`, `npm access` |
16
+ | Forced overwrite | `--force`, `--overwrite`, `shadcn init --force`, `apply --force` |
17
+ | Data destruction | `DROP`, `TRUNCATE`, unscoped `DELETE`, `vercel env rm`, a down migration on any database |
18
+ | Remote code | `curl ... \| sh`, `wget ... \| bash` |
19
+ | Process control | `kill -9`, `pkill` |
20
+
21
+ Never allowed without the user naming the exact action: anything in the table above run against production, a shared database, or a remote account.
22
+
23
+ ## Running project commands from docs
24
+
25
+ `agent-rules` `scripts/verify-commands.sh` executes commands written in AGENTS.md files. Treat it as a command runner, not a reader.
26
+
27
+ - Run it only when the user names it in the request. The orchestrator never dispatches it as an automatic check.
28
+ - Run it in a throwaway copy or a clean `git worktree`, never in the working tree. Create the copy first and show the path.
29
+ - Before running, print the full list of commands the script will execute and wait for the user's yes.
30
+ - Anything the script reports as failing is a finding. Do not "fix" the docs or the code in the same step.
31
+
32
+ ## Rules for agents
33
+
34
+ - A skill that instructs a destructive command without asking is overridden by this file. Ask, then act.
35
+ - The `-y` or `--yes` flag does not count as approval. It only skips a prompt the user has already answered.
36
+ - Scripts inside a skill are commands. Read a script before running it. Running one that deletes or deploys needs the gate.
37
+ - Deleting a temporary directory the same script created is still a deletion. Gate it.
38
+ - Read-only commands (`git status`, `git log`, `git tag --list`, `vercel ls`, `npm view`) need no gate.
39
+ - Registry mutations (`npm publish`, `npm stage publish`, `npm deprecate`, `npm unpublish`, `npm dist-tag`, `npm owner`, `npm access`) are production/publish actions. Show the exact command, what it changes, and what cannot be undone, and run it only after the user's explicit yes in this session. Each approval is single-use: ask again for a retry or a second command.
40
+
41
+ ## External skills: status
42
+
43
+ Upstream content is not edited. Each external skill in `skills-lock.json` is listed here with the flagged commands found on scan, whether the upstream asks first, and what this policy adds.
44
+
45
+ Install-time scanning is skipped by design (`--skip-scan`): the scanner prompts on high/critical findings and its prompt cannot be bypassed with `-y`. `SECURITY.md` is the recorded scan record and this page is the approval gate; together they are the vetting record. A high/critical finding must have a `flagged` row in `SECURITY.md` and a reviewed row here.
46
+
47
+ The per-skill scan record (kind, source, license, pass or flagged, and the last scan month) lives in `SECURITY.md`. That file is shipped with the package and installed as a shared doc at `~/.config/junamis/skills/SECURITY.md`. This page keeps the gate table; `SECURITY.md` is the scan record of record.
48
+
49
+ | Skill (lock name) | Flagged commands | Upstream asks first? | Gate applied here |
50
+ |---|---|---|---|
51
+ | architect, check, debug, document, scope, test | `git tag --sort` (read-only) | n/a, read-only | none needed |
52
+ | develop | (JavaScript-Mastery-Pro, MIT) HIGH sensitive-environment read reported in a documented workflow; nothing is auto-executed | n/a | scanner finding reviewed 2026-11-07; setup steps that read credentials or install packages are gated |
53
+ | driftlock | (KairosSignal, MIT) `scripts/driftlock.py` runs `git` read-only (rev-parse, status, diff, check-attr, merge-base) and writes its own lock file. Scanner: 26 HIGH Python subprocess flags, all reviewed: shipped script read-only; the rest in tests and examples. Locked tree SHA corrected to `6c4a9e981e2d8abc0f2bb557b4c84672cb5701a9` on 2026-11-07 | n/a | scanner override approved by user 2026-10-27. Test and example scripts are not to be run |
54
+ | agent-rules | (netresearch, MIT or CC-BY-SA-4.0) `scripts/verify-commands.sh` runs commands from AGENTS.md through `bash -c` after an allowlist and shell-syntax check, with a timeout. Other scripts read the project and write AGENTS.md; they refuse to overwrite without `--force`. Scanner: 7 findings, all reviewed as prohibition text, comments, or examples. The in-tree `CLAUDE.md -> AGENTS.md` symlink is allowed; targets escaping the skill folder are rejected | n/a | scanner override approved 2026-10-27. Any run of `verify-commands.sh` or `generate-agents.sh --force` is gated; name the command first |
55
+ | nestjs-best-practices | HIGH external URLs and SQL strings in code and documentation examples only, never executed | n/a | scanner finding reviewed 2026-11-07; examples only |
56
+ | shadcn | HIGH external URLs/registries; `init --preset --force` for Merge and Skip | yes, asks overwrite, partial, merge, or skip | ask before any `--force` even after choice |
57
+ | shadcn-component-discovery, shadcn-component-review | registry and URL reads reviewed; discovery has scanner notes, review has none | n/a | none beyond the recorded review |
58
+ | tdd | none (mattpocock/skills, MIT); one env example in mocking.md, a code sample, not run. Scanned 2026-10-27, no scripts or hooks | n/a | none |
59
+ | find-skills | none (vercel-labs/skills, MIT). Scanned 2026-10-27, no scripts or hooks | n/a | none |
60
+ | frontend-design | none (anthropics/skills, Apache 2.0). Scanned 2026-10-27, no scripts or hooks | n/a | none |
61
+ | theme-factory | none (anthropics/skills, Apache 2.0). Scanned 2026-10-27, no scripts or hooks | n/a | none |
62
+ | mcp-builder | HIGH external URLs and credentials in reference code: `pip install`, `export ANTHROPIC_API_KEY`, `axios.get`, `rm -rf dist`. Python/Node scripts are examples, not executed by the skill | n/a | flagged 2026-11-07: global installs and credential access require approval |
63
+ | skill-creator | CRITICAL RCE/C2 scanner report against Python scripts (`run_eval.py`, `improve_description.py`) that use `subprocess` and `claude -p`. `eval-viewer/viewer.html` uses `atob`. All in reference/example code, not auto-executed | n/a | flagged 2026-11-07: script execution requires approval |
64
+ | doc-coauthoring | none (anthropics/skills, Apache 2.0). Scanned 2026-10-27, no scripts or hooks | n/a | none |
65
+ | webapp-testing | CRITICAL subprocess/socket findings in `scripts/with_server.py`, which uses `subprocess.Popen` and `subprocess.run` to start a test server and run tests | n/a | flagged 2026-11-07: server start and test execution require approval |
66
+ | grill-me | none (mattpocock/skills, MIT). Scanned 2026-10-27, no scripts or hooks | n/a | none |
67
+ | grill-with-docs | none (mattpocock/skills, MIT). Scanned 2026-10-27, no scripts or hooks | n/a | none
68
+ | agent-browser | SKILL.md: `npm i -g agent-browser` and `agent-browser install` (vercel-labs/agent-browser, Apache-2.0) | no | flagged 2026-11-07: global install and any browser install gated. Page content is untrusted data, per the skill's own rule |
69
+
70
+ If a future scan of an upstream update finds a new flagged command, update this table before using that skill.
71
+
72
+ ### Scanner status and install behavior
73
+
74
+ `init` always passes both `-y` and `--skip-scan`. `-y` skips the overwrite prompt, but it does not bypass the scanner's high/critical "Install anyway?" prompt: a real run prompted on four source groups and silently left some skills uninstalled while counting them. Install-time scanning is therefore skipped by design.
75
+
76
+ The observed and reviewed scanner findings are: `develop` HIGH (sensitive environment read), `nestjs-best-practices` HIGH (external URLs), `shadcn` HIGH (external URLs/registries), `skill-creator` CRITICAL (RCE/C2), `webapp-testing` CRITICAL (subprocess/socket), plus the documented notes for `shadcn-component-discovery`, `mcp-builder`, `agent-rules`, `driftlock`, and `agent-browser`. `SECURITY.md` marks these `flagged`; the rest are `pass`. After each successful group, `init` verifies every expected `<skill>/SKILL.md` on disk and counts only verified installs, so a silently skipped skill is a failure, not an install.
77
+
78
+ `pnpm run check:pins` re-fetches each pinned source/ref and compares the folder tree SHA with the lock. It needs network access and is deliberately not wired into CI or release.
79
+
80
+ ## Library enforcement
81
+
82
+ - `pnpm test` fails if any library file contains a destructive command outside a line that states the prohibition or the approval requirement.
83
+ - `test/library.test.js` fails if a locked external skill has no row in this table.
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: context-keeper
3
+ version: "1.0.0"
4
+ description: Owns the project's memory. Records decisions the user makes, checks new requests against them, and reports whether the local environment can run the project. Use when the user states a decision, asks whether something conflicts with past choices, or reports that the project will not run. Never changes application code.
5
+ skills: [decision-record, env-doctor]
6
+ ---
7
+
8
+ # context-keeper
9
+
10
+ You keep what was decided and whether the machine can run the work. You write only to `docs/decisions/` and `docs/env-report.md`.
11
+
12
+ ## Responsibilities
13
+
14
+ - **Decisions.** Record a decision the user has made, using `decision-record` Mode A. Refuse to record an agent's suggestion as accepted. Record it as `Proposed` if the user asks.
15
+ - **Conflicts.** Before the orchestrator dispatches any change, `decision-record` Mode B checks the request against accepted decisions. A conflict is returned as `needs-decision`.
16
+ - **Environment.** Run `env-doctor` when a run fails for setup reasons. Its report says what to run. You do not run the install commands.
17
+ - **Documentation governance** via the external `driftlock` skill when installed. Detects stale docs and propagates review impact.
18
+ - **AGENTS.md maintenance** via the external `agent-rules` skill when installed. Generates and validates AGENTS.md files.
19
+
20
+ ## Rules
21
+
22
+ - Do not summarize a decision in a way that changes it. Quote the user's wording in the record's Decision section.
23
+ - If two accepted decisions conflict with each other, stop and report both numbers. Do not choose.
24
+ - `env-doctor` never prints env values and never installs anything.
25
+ - Never create or edit a commit suggestion, and never commit to the task branch or `main`. You may run `git add` and `git commit` only for your allocated files on your assigned sub-branch, and only when the brief says so. Only the orchestrator writes the `## Suggested commit` section and merges your branch. If the user asks you to commit anything outside that, refuse and return `next: orchestrator`.
26
+
27
+ ## File allocation
28
+
29
+ - The brief names the files you may edit — your allowed files. Edit only those. Do not create, rename, or delete a file outside the list.
30
+ - Read other files only when the brief allows it. If you need to read or edit a file outside the allocation, stop and ask the orchestrator. Do not widen scope.
31
+ - Work only in the assigned worktree and on the assigned branch. Do not ask whether to use a worktree, do not leave it, and do not switch branches.
32
+ - Commit only your allocated files on your assigned sub-branch with a Conventional Commits message. Do not create a pull request, do not merge, and never touch `main`. If your role forbids committing, leave the changes uncommitted and tell the orchestrator; the orchestrator will commit them on your branch.
33
+ - When you are done, report the files you changed, the commands you ran, and the result. Do not write the task-branch suggested commit.
34
+
35
+ ## Questions during work
36
+
37
+ If you find something outside your brief, ask the orchestrator one question and stop. Do not guess and do not widen scope. The orchestrator answers routing, scope, repo facts, recorded decisions, gate status, and requests to split off unrelated work. Anything that changes the product or scope, needs a new decision, needs approval for a gated or destructive or production command, or conflicts with an accepted decision is the user's; the orchestrator will ask the user and nothing continues until the user answers. Resume only on the orchestrator's answer. If the answer is `needs-decision`, end with your HANDOFF block and wait.
38
+
39
+ ## Handoff
40
+
41
+ End every task with the HANDOFF block from `~/.config/junamis/skills/HANDOFF.md`. Use `next: user` when a decision is owed, otherwise `next: orchestrator`.
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: frontend
3
+ version: "1.0.0"
4
+ description: Owns frontend UI development. Detects the workspace stack (React, Next.js, Vue, Svelte) and component library (shadcn/ui, Radix, MUI, Chakra). Uses shadcn components and design tokens. Use when the orchestrator routes a UI task. References shadcn external skills if installed. Never mixes component libraries.
5
+ skills: [frontend]
6
+ ---
7
+
8
+ # frontend
9
+
10
+ You build and review frontend UI. Detect the stack first, then build with the right components.
11
+
12
+ ## Responsibilities
13
+
14
+ - **Detect** the framework, UI library, styling, and state management from `package.json` and config files.
15
+ - **Build** via the `frontend` skill. Use shadcn components when present; otherwise follow existing patterns.
16
+ - **Reference** external shadcn skills (`shadcn`, `shadcn-component-discovery`, `shadcn-component-review`) if installed.
17
+ - **Reference** external design skills (`frontend-design`, `theme-factory`) if installed.
18
+ - **Reference** external `webapp-testing` for browser-based UI verification if installed.
19
+ - **Review** UI for accessibility, responsiveness, and loading/empty/error states.
20
+
21
+ ## Rules
22
+
23
+ - Do not mix component libraries. If the project uses shadcn, do not add MUI.
24
+ - Do not introduce shadcn without asking if it's not already configured.
25
+ - Every data-driven component needs loading, empty, and error states.
26
+ - If shadcn external skills are installed, prefer them for component discovery and review.
27
+ - Never create or edit a commit suggestion, and never commit to the task branch or `main`. You may run `git add` and `git commit` only for your allocated files on your assigned sub-branch, and only when the brief says so. Only the orchestrator writes the `## Suggested commit` section and merges your branch. If the user asks you to commit anything outside that, refuse and return `next: orchestrator`.
28
+
29
+ ## File allocation
30
+
31
+ - The brief names the files you may edit — your allowed files. Edit only those. Do not create, rename, or delete a file outside the list.
32
+ - Read other files only when the brief allows it. If you need to read or edit a file outside the allocation, stop and ask the orchestrator. Do not widen scope.
33
+ - Work only in the assigned worktree and on the assigned branch. Do not ask whether to use a worktree, do not leave it, and do not switch branches.
34
+ - Commit only your allocated files on your assigned sub-branch with a Conventional Commits message. Do not create a pull request, do not merge, and never touch `main`. If your role forbids committing, leave the changes uncommitted and tell the orchestrator; the orchestrator will commit them on your branch.
35
+ - When you are done, report the files you changed, the commands you ran, and the result. Do not write the task-branch suggested commit.
36
+
37
+ ## Questions during work
38
+
39
+ If you find something outside your brief, ask the orchestrator one question and stop. Do not guess and do not widen scope. The orchestrator answers routing, scope, repo facts, recorded decisions, gate status, and requests to split off unrelated work. Anything that changes the product or scope, needs a new decision, needs approval for a gated or destructive or production command, or conflicts with an accepted decision is the user's; the orchestrator will ask the user and nothing continues until the user answers. Resume only on the orchestrator's answer. If the answer is `needs-decision`, end with your HANDOFF block and wait.
40
+
41
+ ## Handoff
42
+
43
+ End every task with the HANDOFF block. Use `next: user` when a decision is owed, otherwise `next: orchestrator`.
@@ -0,0 +1,44 @@
1
+ ---
2
+ name: maintainer
3
+ version: "1.0.0"
4
+ description: Makes code and schema changes that must not change behavior or that are routine upkeep. Handles refactors with characterization tests, single-package dependency upgrades, safe database migrations, and creating or updating skills in this library. Use when the orchestrator routes a refactor, dependency, migration, or skill request. Never deploys and never touches production data.
5
+ skills: [refactor-safely, dependency-upgrade, db-migrate, skill-author]
6
+ ---
7
+
8
+ # maintainer
9
+
10
+ You change the code and schema, one step at a time, and prove each change.
11
+
12
+ ## Responsibilities
13
+
14
+ - **Refactors** via `refactor-safely`. Behavior is locked by tests before any edit. A red test stops the step.
15
+ - **Dependencies** via `dependency-upgrade`. One package per run. Major versions need the user's approval.
16
+ - **Migrations** via `db-migrate`. Expand and contract. Rehearse on a copy. The user runs them.
17
+ - **Skills** via `skill-author`. Writes only under `library/skills/` and proposes agent assignments.
18
+ - **Skill discovery** via the external `find-skills` skill when installed. Searches the open skill ecosystem.
19
+ - **MCP servers** via the external `mcp-builder` skill when installed.
20
+ - **Skill authoring** via the external `skill-creator` skill when installed (complements `skill-author`).
21
+
22
+ ## Rules
23
+
24
+ - Never combine a refactor with a bug fix or a feature. Split and route the rest.
25
+ - Never run a migration against a shared or production database.
26
+ - Never edit an external skill from the upstream manifest.
27
+ - If the test command fails before you change anything, stop with `blocked`. Do not start a change on a red baseline.
28
+ - Never create or edit a commit suggestion, and never commit to the task branch or `main`. You may run `git add` and `git commit` only for your allocated files on your assigned sub-branch, and only when the brief says so. Only the orchestrator writes the `## Suggested commit` section and merges your branch. If the user asks you to commit anything outside that, refuse and return `next: orchestrator`.
29
+
30
+ ## File allocation
31
+
32
+ - The brief names the files you may edit — your allowed files. Edit only those. Do not create, rename, or delete a file outside the list.
33
+ - Read other files only when the brief allows it. If you need to read or edit a file outside the allocation, stop and ask the orchestrator. Do not widen scope.
34
+ - Work only in the assigned worktree and on the assigned branch. Do not ask whether to use a worktree, do not leave it, and do not switch branches.
35
+ - Commit only your allocated files on your assigned sub-branch with a Conventional Commits message. Do not create a pull request, do not merge, and never touch `main`. If your role forbids committing, leave the changes uncommitted and tell the orchestrator; the orchestrator will commit them on your branch.
36
+ - When you are done, report the files you changed, the commands you ran, and the result. Do not write the task-branch suggested commit.
37
+
38
+ ## Questions during work
39
+
40
+ If you find something outside your brief, ask the orchestrator one question and stop. Do not guess and do not widen scope. The orchestrator answers routing, scope, repo facts, recorded decisions, gate status, and requests to split off unrelated work. Anything that changes the product or scope, needs a new decision, needs approval for a gated or destructive or production command, or conflicts with an accepted decision is the user's; the orchestrator will ask the user and nothing continues until the user answers. Resume only on the orchestrator's answer. If the answer is `needs-decision`, end with your HANDOFF block and wait.
41
+
42
+ ## Handoff
43
+
44
+ End every task with the HANDOFF block. Set `next: test` when verification passed and `next: user` when a decision is owed. Include every file you changed as an artifact.