@devenius/junamis-skills 0.0.0-stage → 1.1.0

package/junamis-skills.yml

@@ -0,0 +1,328 @@
+# junamis-skills — complete project reference
+# This file is the single source of truth for the project's structure, features,
+# setup, runtime functionality, decisions, and validation. Keep it in sync with
+# bin/, src/**/*.ts, dist/ (build output), scripts/, library/, skills-lock.json,
+# and SECURITY.md.
+Name: junamis-skills
+CLI: junamis-skills
+Bins: [junamis-skills, junamis-orchestrator, junamis-design-registry, junamis-reconcile]
+License: MIT
+Status: 1.1.x (Node 26+; ESM; external installs also need the system git CLI)
+
+Description: >
+  Install and manage Agent Skills (SKILL.md workflows) for AI coding agents. The
+  package ships the installer, a pinned external-skill manifest, and the owned
+  library (orchestrator plus specialist agents and their skills). It never
+  vendors third-party SKILL.md content: external skills are fetched at locked
+  commits, verified against the recorded scan, and installed non-interactively.
+
+Architecture:
+  PackageContent:
+    - "bin/junamis-skills.js is the only executable entry point for the installer."
+    - "src/**/*.ts holds all runtime code as TypeScript: the CLI, the external installer, the pinned-source checkout, the library installer, and the guide writer."
+    - "src/orchestrator/ holds the journal-first resume state engine."
+    - "src/**/*.ts is the source of truth; the published package ships only the built dist/ output and its declarations."
+    - "dist/ is generated by pnpm build (JavaScript, .d.ts declarations, source maps) and is never committed."
+    - "bin/junamis-skills.js and scripts/*.mjs are thin launchers that import their implementation from dist/."
+    - "scripts/orchestrator-state.mjs is the thin launcher over dist/orchestrator/cli.js for the junamis-orchestrator bin."
+    - "src/targets/ is the only place that knows agent-specific paths and agent-definition formats."
+    - "library/ holds owned skills, agents, and shared docs; it is published with the package."
+    - "library/RESUME.md is the normative persistence and resume contract."
+    - "docs/RECONCILE.md is the work-queue contract and installs as a shared doc next to RESUME.md."
+    - "skills-lock.json is the single source of truth for external skills."
+    - "SECURITY.md is the scan record for every internal and external skill."
+  WorkIsolation:
+    - "Every orchestrator prompt starts with git branch --show-current. On main or a detached HEAD it runs git fetch origin and git switch -c task/<task-slug> origin/main (or git switch -c task/<task-slug> main with no remote) and continues on that branch; on a task branch it continues; it never works on main."
+    - "The orchestrator works in the project checkout on task/<task-slug> and commits there; the state root (<project>/.orchestrator/) and the design registry (<project>/docs/design/) live in that checkout."
+    - "The Delegation plan in <state-root>/delegation.md assigns every file to exactly one task and records owner, depends on, worktree, branch, allowed files, and done proof; dependency order decides dispatch."
+    - "Each delegated task runs in <project>/.worktrees/<task-slug>-<subtask> on task/<task-slug>-<subtask>, cut from the task branch, and may edit only the allowed files; any other file asks the orchestrator, and the sub-agent never creates a pull request."
+    - "When a sub-agent finishes, the orchestrator verifies the diff is a subset of the allowed files, runs the task checks, merges with git merge --no-ff, removes the worktree with git worktree remove, and deletes the merged sub-branch with git branch -d; on conflict it runs git merge --abort, stops, and asks the user."
+    - "Worktree limit is 8: before creating one, count git worktree list entries under .worktrees/ and prune only a worktree merged into the task branch and clean with git worktree remove, never rm -rf; ask the user when none qualifies."
+    - "After every task is merged and the full gate passes, the orchestrator asks the user for approval, pushes task/<task-slug> with git push -u origin task/<task-slug>, opens one pull request with gh pr create, reports the URL, and stops. Creating the pull request is the end of its authority: it never merges, never uses --admin, never pushes main, never force-pushes, never tags, and never rebases or resets main. The user reviews and merges."
+    - "Approvals are single-use: an approval covers one command in one prompt exactly once, ends when that command finishes or fails, and never carries to a retry, a second command, a later step, another task, another pull request, or another session; a general go-ahead is not approval and every gated command must be asked for again. Commands allowed by opencode.json (read-only git, build, test, task-branch pushes, gh pr create, and gh pr reads) are not gated."
+  Persistence:
+    - "State root: <project>/.orchestrator/ by default; ORCH_STATE_ROOT overrides it."
+    - "journal.ndjson is the append-only source of truth with a hash chain; state.json, plan.json, and tasks/<task_id>/task.json are derived snapshots."
+    - "boot runs before route, acquires the lease, verifies the journal and fingerprints, reconciles in-flight work, and writes resume-report.md and STATE.md."
+    - "A live lease halts a second session; a stale lease is taken over. Idempotent interruptions retry; non-idempotent interruptions escalate."
+    - "The engine uses only Node 26 built-in modules and adds no runtime dependency."
+  InstallLayout:
+    - "Config root: ~/.config/junamis/skills/ (the project segment for junamis-skills is skills)."
+    - "OpenCode internal skills: ~/.config/junamis/skills/skills/<name>/SKILL.md."
+    - "Canonical agents: ~/.config/junamis/skills/agents/<name>.md."
+    - "OpenCode agent links: ~/.config/opencode/agents/<name>.md -> the canonical file."
+    - "OpenCode shared docs: ~/.config/junamis/skills/{HANDOFF,SAFETY,EXTERNAL,SECURITY,RESUME}.md."
+    - "Installed skill manifest for the state engine: ~/.config/junamis/skills/skills-lock.json."
+    - "OpenCode install manifest: ~/.config/junamis/skills/installed/library-opencode.json."
+    - "OpenCode external skills: ~/.agents/skills/<name>/SKILL.md."
+    - "Execution state: <project>/.orchestrator/ (gitignored; never inside the OS temp directory)."
+    - "Claude Code uses one skills directory (~/.claude/skills) for internal and external skills; canonical agents are still linked into ~/.claude/agents."
+    - "Project scope mirrors the config root under <project>/.config/junamis/skills/{skills,agents,*.md,installed}; external skills stay at <project>/.agents/skills and project agent links at <project>/.opencode/agents (OpenCode)."
+    - "No automatic migration: init writes only the nested layout, and status reports old flat files as legacy without deleting them."
+  SupplyChain:
+    - "skills-lock.json pins a 40-character upstream commit and a 40-character skill tree SHA for every external skill."
+    - "The checkout is a Git tree at the locked commit (HEAD === ref). In-tree symlinks are allowed; absolute and escaping symlinks and gitlinks are rejected."
+    - "The scanner is skillsio@1.1.3 from the public npm registry, with a pinned tarball URL and SHA-512 integrity."
+    - "Auto-install passes --skip-scan: -y cannot bypass the high/critical scan prompt, so the recorded scan is the gate."
+    - "After each successful group every expected <name>/SKILL.md is verified on disk; only verified skills count as installed."
+    - "No branch heads, raw-file downloads, or unscanned installers are used."
+  Targets:
+    - "claude, opencode, cursor, windsurf, cline. External auto-install supports OpenCode and Claude Code only."
+
+Features:
+
+  Init:
+    Description: >
+      One non-interactive command performs the whole install in order: guide,
+      OpenCode config, library, then every pinned external skill.
+    Order:
+      - "writeGuide writes junamis-skills-guide.md and .junamis/junamis-skills.json once."
+      - "writeOpencodeConfig writes opencode.json only when missing, or with --force; no prompt."
+      - "planLibraryInstall/applyLibraryInstall copy skills and shared docs, write canonical agents, and link them into the target agents directory."
+      - "installExternal installs every lock entry through the pinned scanner."
+    DryRun: "init --dry-run reports all four steps and writes nothing, with no network."
+
+  Status:
+    Description: >
+      Reports guide and marker state, per-target internal/external skill counts,
+      canonical agents and their link state, legacy leftovers (informational),
+      library manifest validity, opencode.json validity, external coverage
+      (every lock skill present under ~/.agents/skills), and the SECURITY.md
+      scan record and last external scan month.
+    Exit: "1 when a required piece is missing for the selected scope; 0 otherwise. Legacy leftovers never fail status."
+
+  Persistence:
+    Description: >
+      Journal-first execution state under <project>/.orchestrator/. Every session
+      boots before route, rehydrates the cursor, checks the lease and
+      fingerprints, reconciles in-flight work, and writes resume-report.md and
+      STATE.md.
+    Commands: "boot, plan set, plan show, start, end, resolve, status, checkpoint, lease acquire|heartbeat|release|status, finish"
+    Journal: "journal.ndjson is append-only with a hash chain; state.json, plan.json, and tasks/<task_id>/task.json are derived snapshots."
+    Lease: "Single-writer lease with a 60s base TTL; start raises it to 900s. A live lease halts a second session; a stale lease is taken over."
+    Drift: "skills-lock.json, library override, and design registry fingerprints gate boot, plan set, and start; a mismatch is BLOCKED_DRIFT with exit 3."
+    Reports: "resume-report.md is regenerated on every boot; STATE.md is a generated view regenerated on boot and checkpoint and never read as input."
+    Reconcile: "B7.5 runs the MVP reconcile pass and writes work-queue.json plus reconcile-report.md before B8 hands the queue to route."
+    CrashSafety: "Interrupted idempotent tasks retry; interrupted non-idempotent tasks escalate to needs_review."
+    Tests: "T1 crash, T2 replay, T3 manifest drift, T4 override drift, T5 lease safety, T6 escalation, T7 torn-write recovery, and SIM-T1/SIM-T2 end-to-end simulation of the built CLIs from design bootstrap to no_work; D-T1 to D-T8 cover the design registry contract."
+
+  DesignRegistry:
+    Description: >
+      A durable design surface registry under <project>/docs/design/ that the
+      orchestrator fingerprints, loads by code path before dispatch, and skills
+      update only through design deltas.
+    Commands: "junamis-design-registry validate, load --surface|--code-path, apply, index, drift, bootstrap, fingerprint"
+    Bootstrap: "Always writes the project-wide map docs/design/other/project.md, plus one draft overview per project, or per app/package in a monorepo; copies the package schema, creates _registry.json with bootstrap_complete false, regenerates INDEX.md, and never promotes a draft."
+    Schemas: "web, api, data, infra, cli, and other; common Intent, Current state, Known gaps, and Change log sections plus kind sections."
+    Checksum: "sha256 over the canonicalized body in fixed section order; frontmatter excluded."
+    Deltas: "replace, append, prepend, remove_line with a base_checksum guard, version bump, change log, atomic write, and design_update or design_delta_rejected journal event."
+    Drift: "CODE_DRIFT, DEPENDENCY_DRIFT, and COVERAGE_GAP; coverage failure is gated by docs/design/_registry.json bootstrap_complete."
+    Tests: "D-T1 schema, D-T2 INDEX determinism, D-T3 delta idempotency, D-T4 checksum guard, D-T5 code drift, D-T6 coverage, D-T7 deprecated guard, D-T8 resume drift; project/monorepo bootstrap and load --code-path tests."
+    PackageRegistry: "This repository's own registry holds 4 surfaces: cli/overview (the single-project bootstrap overview, detected as cli from package.json bin), other/project (the project-wide map), plus the canonical web/homepage and api/get-user examples; D-T1 asserts those canonical surfaces."
+
+  Reconcile:
+    Description: >
+      A deterministic work queue that turns durable state and the design
+      registry into the next dispatchable candidate. It reads state, journal,
+      plan, design, and the detector manifest; it never executes a skill.
+    Commands: "junamis-reconcile pass --trigger <name>"
+    Detectors: "plan_pending, code_drift, failed_step, coverage_gap, dependency_drift, needs_review, stale_surface, and shadow_conflict; the extended detectors are present and disabled by default."
+    Scoring: "Full severity base plus reason weight with plan_position_frac for plan_pending; p0..p3 buckets; unknown reasons use weight 100 and journal unknown_reason."
+    Queue: "work-queue.json is derived and deterministic for one input snapshot; reconcile-report.md is its human companion; queue_stale reports a changed input fingerprint."
+    Escalation: "Blocked heads journal queue_blocked; shadowed heads journal escalation shadow_conflict; empty all-done queues journal run_complete; stalled queues keep status no_work with a stalled flag and blocking set."
+    Overrides: "Journal priority_override events apply after scoring; an override without a rationale is journaled priority_override_rejected."
+    Tick: "A periodic tick runs after N step_end events (default 10, from detectors.yaml tick_every) and records tick on reconcile_pass."
+    Tests: "R-T1 through R-T12: determinism, stable ids, scoring, drift guard, shadow safety, dependency closure, dedup, triggers, empty queue, stalled queue, crash recovery, and override audit."
+
+  Library:
+    OwnedSkills: 20
+    OwnedAgents: 9
+    SharedDocs: [HANDOFF.md, SAFETY.md, EXTERNAL.md, SECURITY.md, RESUME.md, RECONCILE.md]
+    CanonicalAgents: "Written once to <configRoot>/agents; linked into the target agents directory."
+    LinkRules: "A correct link is unchanged; a missing link is created; an identical regular file is adopted; a differing file or wrong link is a conflict unless --force; a failed symlink falls back to a copy with a warning."
+    ConflictRule: "Never overwrite a file the user edited unless --force."
+    Manifest: "Records every written file and its SHA-256; stale unmodified files are removed."
+
+  External:
+    Count: 24
+    ExistingSkills: "Skipped, not overwritten and not counted as failures."
+    Return: "{ groups, installed, skipped, failed }"
+    Verification: "After a successful group, installed counts only skills whose <name>/SKILL.md exists on disk; a missing skill is a logged failure."
+    Scan: "Always runs with --skip-scan because -y cannot bypass the high/critical prompt; SECURITY.md plus library/SAFETY.md is the vetting record."
+    FailureRule: "init exits 1 only when failed > 0; a declined or missing install is a failure and is not retried."
+
+  Security:
+    Record: "SECURITY.md lists kind, source, license, scan status, and last review month for all 44 skill rows (20 internal + 24 external; document has one row of each kind)."
+    Scanner: "skillsio 1.1.3 (Trust Hub, Socket, Snyk)"
+    Gate: "Install-time scanning is skipped by design (--skip-scan); SECURITY.md and library/SAFETY.md define the gate, and flagged findings are reviewed there."
+    PinCheck: "pnpm run check:pins fetches each locked source/ref and compares the actual tree SHA; network check, not in CI/release."
+
+  Publishing:
+    Description: >
+      npmjs is the primary public registry for @devenius/junamis-skills;
+      GitHub Packages is the mirror. The package is scoped, publishConfig sets
+      access public and no registry, and CI publishes through a trusted
+      publisher.
+    Workflow: ".github/workflows/publish.yml (name Publish) runs publish-github (GITHUB_TOKEN, packages write) then publish-npm (needs publish-github, id-token write, environment npm-publish, OIDC, npm stage publish to registry.npmjs.org)."
+    Checklist: "pnpm publish:npm runs scripts/publish-npm.mjs over src/scripts/publish-npm.ts; it validates the name, publishConfig.access, and the absence of publishConfig.registry, then prints the exact npm stage publish command and never runs it."
+    Command: "npm stage publish --access public --tag <tag> --registry=https://registry.npmjs.org; the user approves the staged version on npmjs.com with 2FA."
+    Release: "The first usable npm release is 1.1.0: package.json is 1.1.0, CHANGELOG.md has ## [1.1.0] - 2026-11-13, and docs/releases/1.1.0.md is the release note. Tag v1.1.0 to run publish.yml (publish-github mirrors to GitHub Packages, publish-npm stages 1.1.0 to npmjs with OIDC and the npm-publish environment); the user approves the staged 1.1.0 on npmjs.com with 2FA, then deprecates 1.0.0-placeholder.0."
+    Gate: "The agent never runs npm publish, npm stage publish, npm deprecate, npm unpublish, npm dist-tag, npm owner, or npm access; library/SAFETY.md gates each one on a single-use approval."
+
+Setup:
+  Install:
+    - "pnpm install"
+    - "pnpm build"
+    - "node bin/junamis-skills.js help"
+  Prerequisites:
+    - "Node.js 26 or newer"
+    - "pnpm 12.15.0 for development"
+    - "git CLI for external checkouts"
+    - "skillsio is never installed globally; it runs through pnpm dlx at the pinned version"
+  Run:
+    - "npx github:devenius/junamis-skills init"
+    - "npx @devenius/junamis-skills init"
+  Validate:
+    - "pnpm test"
+    - "pnpm lint"
+    - "pnpm run check:config"
+    - "pnpm run check:skills-lock"
+    - "pnpm run check:security"
+    - "pnpm run check:pins"
+    - "pnpm run check:pack"
+    - "pnpm run check:yaml"
+  Scripts:
+    - "test: node --test test/*.test.js"
+    - "check:config: validates the shipped opencode.json invariants."
+    - "check:skills-lock: validates every lock pin and license."
+    - "check:security: requires every internal and external skill in SECURITY.md plus a Last external scan line."
+    - "check:pins: fetches every locked source/ref and compares the actual folder tree SHA with skills-lock.json (network; not in CI)."
+    - "check:pack: asserts the published file set and no nested upstream clones."
+    - "release:check: runs the full gate, including tests and SECURITY.md coverage."
+
+Functionality:
+
+  InitFlow:
+    - "Resolve scope: global (default) or project; reject any agent other than opencode or claude."
+    - "Guide: write once, keep a user-authored file, rewrite only with --force."
+    - "Config: for OpenCode only; identical file is unchanged, a different file is left unchanged with a --force hint, --force replaces it."
+    - "Library: plan, then apply; conflicts are listed and set exit 1; --dry-run never writes."
+    - "External: install every source group through the scanner; existing skill directories are skipped."
+    - "Summary: prints guide, config, library, external counts, and the exit state."
+
+  StatusChecks:
+    - "Guide and marker are required when the project scope is selected."
+    - "At least one target must have a valid library manifest per selected scope."
+    - "An existing opencode.json must use V2 permissions, policies, mcp.servers, and plugins; a malformed or V1-only file fails."
+    - "External coverage is required when the global scope is selected."
+    - "SECURITY.md and its Last external scan line are always required."
+
+  ExternalInstall:
+    - "Group lock entries by source and commit; one scanner call per group."
+    - "Partition existing skills before checkout and again after checkout; both are skipped."
+    - "Verify every skill tree SHA (in-tree symlinks allowed, escapes rejected), then verify the scanner integrity once per run."
+    - "Run with --skip-scan so the high/critical prompt cannot silently skip skills; install-time scanning is skipped by design."
+    - "After a successful group, count only skills whose <name>/SKILL.md exists; log and fail a missing one."
+    - "Run with a sanitized environment, neutral cwd, inherited stdin, no shell, and a timeout that kills the process group."
+    - "Convert scanner cancellation output to exit 125 and never retry it."
+
+  LibraryInstall:
+    - "Plan every owned skill file, canonical agent definition, shared doc, and the agent links."
+    - "Reject symlinked managed roots and destinations before any write or delete; link destinations check their parent only so a wrong target is a conflict, not an escape."
+    - "Write atomically, back up changes, apply links (adopt identical files, relink with --force), and roll back on failure."
+    - "Fall back to copying a canonical agent when symlink creation fails with EPERM or EACCES, and report a warning."
+
+CLIOptions:
+  - "init [--agent opencode|claude] [--scope global|project] [--dir <path>] [--force] [--dry-run] : install guide, config, library, and every pinned external skill"
+  - "status [--dir <path>] [--scope global|project|all] : report install and security state; exits 1 when a required piece is missing"
+  - "help, --help, -h : usage"
+  - "--force : overwrite the guide, opencode.json, or edited library files"
+  - "--dry-run : print the plan; no writes and no network"
+  - "--dir : project directory (default: current directory)"
+  - "--scope : global or project for init; global, project, or all for status"
+  - "removed commands : install-library, install-external, sync, doctor, init-config; each fails with a pointer to init/status"
+
+InstalledPaths:
+  "~/.config/junamis/skills/skills": "internal (library) skills, OpenCode"
+  "~/.config/junamis/skills/agents": "canonical agent definitions"
+  "~/.config/junamis/skills/*.md": "shared docs: HANDOFF.md, SAFETY.md, EXTERNAL.md, SECURITY.md, RESUME.md, RECONCILE.md"
+  "~/.config/junamis/skills/skills-lock.json": "installed external-skill manifest used by the state engine fingerprint"
+  "~/.config/junamis/skills/installed/library-<agent>.json": "library install manifest"
+  "~/.config/opencode/agents": "OpenCode agent links to the canonical files"
+  "~/.agents/skills": "external skills, OpenCode"
+  "~/.claude/skills": "internal and external skills, Claude Code"
+  "~/.claude/agents": "Claude Code agent links"
+  "<project>/.config/junamis/skills/...": "project-scope internal skills, canonical agents, docs, and manifest"
+  "<project>/.agents/skills": "project-scope external skills, OpenCode"
+  "<project>/.opencode/agents": "project-scope OpenCode agent links"
+  "<project>/.orchestrator/": "execution state root: journal, snapshots, checkpoints, leases, resume report, and STATE.md (gitignored)"
+  "<project>/.junamis/junamis-skills.json": "guide marker"
+  "<project>/junamis-skills-guide.md": "setup guide (project file, not a skill)"
+
+Utilities:
+  - "bin/junamis-skills.js : executable entry point, imports dist/cli.js"
+  - "src/cli.ts : parseArgs, runInit, writeOpencodeConfig, status, run"
+  - "src/external.ts : lock grouping, scanner command, integrity check, sandboxed runner, installExternal"
+  - "src/pinned-source.ts : pinned Git checkout and skill tree SHA verification"
+  - "src/library-install.ts : plan/apply, manifest validation, containment, canonical agents, links, rollback"
+  - "src/paths.ts : single source of truth for the nested config root and install paths"
+  - "src/guide.ts : guide rendering, the shared PACKAGE_ROOT, and the atomic writer"
+  - "src/orchestrator/ : journal-first resume engine (journal, state, plan, lease, drift, compaction, report, boot, handoff, commands, CLI)"
+  - "src/design/ : design registry schema, delta applier, index generator, drift detectors, bootstrap, and fingerprint"
+  - "src/reconcile/ : MVP work queue detectors, scoring, manifest, and pass runner"
+  - "dist/ : build output (JavaScript, declarations, source maps); never committed, always built before a check runs"
+  - "scripts/orchestrator-state.mjs : thin launcher over dist/orchestrator/cli.js for the junamis-orchestrator bin"
+  - "scripts/design-registry.mjs : thin launcher over dist/design/cli.js for the design registry"
+  - "scripts/reconcile.mjs : thin launcher over dist/reconcile/cli.js for the junamis-reconcile bin"
+  - "src/targets/ : one adapter per agent"
+  - "scripts/check-*.mjs : config, lock, security, pack, and YAML checks, each a launcher over dist/scripts/*.js"
+  - "scripts/release-check.mjs : release gate, a launcher over dist/scripts/release-check.js"
+  - "src/color.ts : dependency-free ANSI palette, stripAnsi, and colorsEnabled (NO_COLOR, TERM=dumb, TTY)"
+  - "scripts/publish-npm.mjs : thin launcher over dist/scripts/publish-npm.js for the read-only publish checklist (pnpm publish:npm)"
+  - "test/orchestrator-simulation.test.js : end-to-end simulation of design bootstrap, boot, plan set, reconcile, start, end, and no_work"
+
+Decisions:
+  - "0001: External skills are auto-installed by init and are never vendored."
+  - "0002: The scanner is pinned and integrity-checked; -y is required for non-interactive init."
+  - "0003: A declined security scan is a failure, not a prompt to skip."
+  - "0004: Existing external skills are skipped, not failures."
+  - "0005: SECURITY.md is the scan record; SAFETY.md keeps the approval gate."
+  - "0006: Only init, status, and help remain as commands."
+  - "0007: OpenCode splits internal skills, shared docs, and external skills; other targets share one skills directory."
+  - "0008: Project scope mirrors the internal side and keeps external skills at the target's project paths."
+  - "0009: Library files edited by the user are conflicts unless --force."
+  - "0010: Install-time scanning is skipped with --skip-scan; SECURITY.md plus SAFETY.md is the vetting record, and every install is verified on disk."
+  - "0011: An in-tree symlink inside a verified skill folder is allowed; absolute and escaping symlinks are rejected."
+  - "0012: check:pins is a manual network check, not part of CI or release."
+  - "0013: The config root is ~/.config/junamis/skills; skills, canonical agents, docs, and the manifest are nested under it."
+  - "0014: Agent definitions are written once to the canonical agents directory and symlinked into each target; a failed symlink falls back to a copy with a warning."
+  - "0015: No automatic migration; status reports legacy flat files and never deletes them."
+  - "0016: The orchestrator is resumable through a journal-first state engine under src/orchestrator/; boot runs before route, skills declare idempotent, and the state root is <project>/.orchestrator/ with no new runtime dependency."
+  - "0017: Every writing task runs in <project-root>/.worktrees/<task-slug> on task/<task-slug>, that worktree is the project root for setup, state, design, and routing, the limit is 8 worktrees pruned only when merged and clean, and opencode.json allows /tmp, /var/tmp, and .worktrees while keeping main, force, and --no-verify pushes denied. Superseded by 0019 for the branch-per-prompt and per-subtask worktree model; the 8-worktree limit and path allows still apply."
+  - "0018: The orchestrator's authority ends at gh pr create; it never merges, uses --admin, pushes main, force-pushes, tags, or rebases/resets main, and the user reviews and merges. Every approval is single-use: one command in one prompt, consumed when that command runs or fails, never standing, never reused. gh pr merge, main pushes, HEAD:main, and --force-with-lease are hard-denied in opencode.json and mirrored in HARD_DENY_POLICIES."
+  - "0019: The orchestrator checks git branch --show-current at the start of every prompt and creates task/<task-slug> from the latest default branch when on main or a detached HEAD. It works and commits in the project checkout on that branch, plans the delegation with one owner per file, gives each delegated task its own .worktrees/<task-slug>-<subtask> worktree and allowed-file list, merges each sub-branch back with git merge --no-ff, removes the worktree, and opens one pull request per approved batch. Sub-agents commit only their allocated files on their sub-branch, never merge, and never create a pull request. git switch/checkout main and git branch -d/-D main are hard-denied."
+  - "0020: npmjs is the primary public registry for @devenius/junamis-skills and GitHub Packages is the mirror. The package name is already scoped, publishConfig sets access public and no registry, CI stages to npmjs through a GitHub Actions trusted publisher (publish.yml, environment npm-publish, OIDC with id-token write, npm stage publish) and a maintainer approves with 2FA. The agent never runs a registry mutation; pnpm publish:npm is a read-only checklist that prints the exact command."
+
+Limitations:
+  - "No third-party skill content is shipped; init needs network access to fetch and scan external skills."
+  - "Scanned external auto-install supports only OpenCode and Claude Code; other targets receive the library only."
+  - "Scanner trust is pinned to skillsio@1.1.3 and its recorded scan results; new upstream content needs a fresh scan."
+  - "Auto-install skips scanning (--skip-scan) because -y cannot bypass the high/critical prompt; on-disk verification is the runtime backstop."
+  - "Global installs are shared: a second agent with the same skills directory can see files from another target."
+  - "The legacy .agents/, .opencode/ agent layer and nested upstream clones (skills/, nestjs-agent-skills/) are not part of the package."
+  - "Execution state is host-local: resume does not work across machines, and the lease does not coordinate across hosts."
+  - "The journal grows until compaction; checkpoint truncation is the one place an append-only journal is rewritten."
+  - "A crash in a non-idempotent step waits for a human review by design; the engine never guesses."
+  - "The handoff parser is a strict subset because a runtime YAML dependency is not allowed."
+
+Validation:
+  - "pnpm test (292 tests)"
+  - "pnpm lint"
+  - "pnpm audit"
+  - "pnpm run check:config"
+  - "pnpm run check:skills-lock"
+  - "pnpm run check:security"
+  - "pnpm run check:pins"
+  - "pnpm run check:pack"
+  - "pnpm run check:yaml"
+  - "pnpm run release:check"

package/library/EXTERNAL.md

@@ -0,0 +1,35 @@
+# External skills referenced by the library
+
+These skills are installed from `skills-lock.json` into the global skills directory (`~/.agents/skills/` for OpenCode, as `skillsio -g` writes it). Each lock entry pins a Git commit and the skill folder's Git tree SHA; the installer verifies both before scanning and installation. They are not owned by this project. The library refers to them by name only. Each reference must resolve to a lock entry, which `test/library.test.js` checks.
+
+The orchestrator runs `route-external` before dispatching any external skill, so the run ends with a HANDOFF block. The adapter lives in `.junamis/adapters/<skill>.md`; upstream content is never edited.
+
+| Name | Lock source | License | Referenced by | Used for |
+|---|---|---|---|---|
+| debug | JavaScript-Mastery-Pro/skills | MIT | route, orchestrator | bug path: reproduce, root cause, minimal fix |
+| architect | JavaScript-Mastery-Pro/skills | MIT | route, orchestrator | feature path: decision and build spec |
+| develop | JavaScript-Mastery-Pro/skills | MIT | route, orchestrator | feature path: build from spec |
+| test | JavaScript-Mastery-Pro/skills | MIT | route, orchestrator | tests written after a change |
+| tdd | mattpocock/skills | MIT | route, orchestrator | build a behavior test-first (red-green) |
+| check | JavaScript-Mastery-Pro/skills | MIT | release-prep | `check review` on the release diff before tagging |
+
+Routing between `test` and `tdd` is in `library/skills/route/SKILL.md`. Both are installed; the route decides which runs.
+
+External skills assigned to library agents (by reference, not ownership):
+
+- `scope`, `document` → orchestrator (workflow planning and release documentation)
+- `find-skills` → maintainer agent (skill discovery and installation)
+- `mcp-builder`, `skill-creator` → maintainer agent (MCP servers, skill authoring)
+- `shadcn`, `shadcn-component-discovery`, `shadcn-component-review` → frontend agent (UI components)
+- `frontend-design`, `theme-factory` → frontend agent (design guidance)
+- `webapp-testing` → frontend agent (browser-based UI testing)
+- `nestjs-best-practices` → nestjs agent (deep NestJS patterns)
+- `agent-browser` → reviewer agent (browser-based verification)
+- `driftlock` → context-keeper agent (documentation governance)
+- `agent-rules` → context-keeper agent (AGENTS.md generation and maintenance)
+- `grill-me`, `grill-with-docs` → architect agent (stress-testing plans and designs)
+- `doc-coauthoring` → orchestrator (structured documentation workflow)
+
+Their licenses and safety status are in `skills-lock.json` and `~/.config/junamis/skills/SAFETY.md`.
+
+If an external name is not installed, the orchestrator stops and tells the user which one is missing. It does not perform that skill's work itself.

package/library/HANDOFF.md

@@ -0,0 +1,93 @@
+This file defines the step output block. Execution state and resume behavior are in RESUME.md.
+
+# Handoff contract
+
+Every skill and agent in `library/` ends its work with exactly one YAML block. The orchestrator reads only this block to decide what happens next. Nothing else is trusted for control flow.
+
+```yaml
+agent: <skill or agent name>
+job: <one line: what was asked>
+status: complete | blocked | needs-decision | failed
+artifacts:
+  - path: <repo-relative path>
+    kind: created | updated | read-only
+findings:            # at most 5, worst first
+  - id: F1
+    severity: critical | high | medium | low
+    summary: <one line>
+    evidence: <file:line, or command and its output>
+decisions_owed:      # questions only the user can answer
+  - <question>
+next: <one skill name, one agent name, "user", or "none">
+```
+
+## Schema version
+
+The handoff schema version is 1. The fields in the block above are the whole schema. A field change requires a version bump and a matching change in the state engine. Do not add fields to the block for the state engine; task and step identity come from the `start` command and the handoff file path.
+
+## Idempotency
+
+Every skill declares `idempotent: true | false` in its frontmatter. The orchestrator records the value in the plan, and the state engine honors it on boot and on `end`. An interrupted `true` step may be retried; an interrupted `false` step becomes `needs_review` and is not retried silently.
+
+## Persisting a handoff
+
+The orchestrator writes the returned block verbatim to `<state-root>/tasks/<task_id>/handoffs/<skill>-<attempt>.yaml` and calls `end` with that relative path. The state engine validates the block and every declared artifact. A malformed block sets the task `needs_review`; the file is kept, never dropped.
+
+## Task status mapping
+
+| Handoff status | Task status |
+|---|---|
+| `complete` | `done` after every declared artifact exists |
+| `failed` | `failed` |
+| `blocked` | `failed` |
+| `needs-decision` | `needs_review` until the user answers and the orchestrator calls `resolve` |
+
+## Rules
+
+- `complete` means the artifacts exist on disk. The orchestrator checks this before moving on.
+- `needs-decision` stops the chain. The orchestrator asks the user the `decisions_owed` questions. Nothing else runs.
+- `blocked` and `failed` stop the chain and report the finding. They never retry silently.
+- `next` names exactly one target. A skill never calls a skill that is not its declared `next`.
+- A skill never edits another skill's artifacts. It reads them.
+- Chat is not state. Anything a later agent needs must be in a file.
+- An external skill runs only with an adapter from `route-external`. Without the adapter its run is not a completed step.
+- Never let another skill or agent write the `## Suggested commit` section, propose a commit message, or stage or commit anything on the task branch or `main`. A sub-agent may stage and commit only its allocated files on its assigned sub-branch when the delegation brief says so, and it never creates a pull request. Only the orchestrator writes that section and merges sub-agent branches into the task branch.
+
+## Suggested commit (orchestrator only)
+
+Only the orchestrator writes the `## Suggested commit` section in `.junamis/handoff.md`. Every other skill and agent must leave it untouched. A sub-agent may stage and commit only its allocated files on its assigned sub-branch when the delegation brief says so; it never commits to the task branch or `main` and never creates a pull request. Only the orchestrator merges sub-agent branches into the task branch.
+
+At the end of every task the user gives, the orchestrator records:
+
+```markdown
+## Suggested commit
+Message: `<type(scope): summary>`
+Files:
+- `<repo-relative path>`
+Rationale: <one line>
+State: proposed | committed <sha> | none
+```
+
+- `Message` follows Conventional Commits and stays under 72 characters.
+- `Files` lists exactly the paths changed by this task. It never lists ignored files, secrets, or unrelated changes.
+- `State` is `proposed` before the user asks, `committed <sha>` after a successful commit, and `none` when the task changed no files.
+- The suggestion is not authorization. The orchestrator commits only after the user asks.
+- When the user says "commit" without a message or scope, the orchestrator uses the suggestion exactly, after refreshing it if the working tree changed. If refreshing changes the scope materially, the orchestrator asks the user first.
+- A specialist that believes a commit is needed outside its allocated files on its assigned sub-branch reports it in `findings` or returns `next: orchestrator`. It never writes this section, never commits to the task branch or `main`, and never creates a pull request.
+
+## Artifact locations
+
+| Artifact | Path | Owner |
+|---|---|---|
+| Session state | `.junamis/handoff.md` | `handoff` |
+| Suggested commit | `.junamis/handoff.md` (`## Suggested commit`) | `orchestrator` |
+| Decisions | `docs/decisions/NNNN-slug.md` | `decision-record` |
+| Environment report | `docs/env-report.md` | `env-doctor` |
+| Release notes | `docs/releases/<version>.md` | `release-prep` |
+| Rollback plan | `docs/releases/rollback-<version>.md` | `rollback` |
+| Incident record | `docs/incidents/<YYYY-MM-DD>-<slug>.md` | `incident-response` |
+| Review findings | `docs/reviews/<kind>-<YYYY-MM-DD>.md` | `security-audit`, `perf-budget` |
+| Perf budgets | `docs/perf/budgets.md` | `perf-budget` (created on first run) |
+| External skill adapter | `.junamis/adapters/<skill>.md` | `route-external` |
+
+Execution state lives under `<project>/.orchestrator/` (gitignored) and follows `RESUME.md`.