peaks-loop 3.0.0

package/skills/peaks-solo-status/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: peaks-solo-status
+description: Show the current state of the peaks-solo orchestrator in a compact summary. Use when the user says "what's the current state", "现在到哪了", "where are we", or invokes `/peaks-solo-status` directly. Reads the existing CLI primitives (`peaks skill presence`, `peaks session list`, `peaks project dashboard`, `peaks request show`) and renders a 1-screen status table. Triggers on `/peaks-solo-status`, "现在到哪了", "what is the current state", "show me the dashboard", "where are we".
+---
+
+# Peaks-Cli Solo Status (wrapper)
+
+Peaks-Cli Solo Status is a thin wrapper that renders a compact status table for the current peaks-solo orchestrator state. It is the answer to "I just want to know where we are" — no PRD, no RD, no QA, no full peaks-solo orchestration. Just read the existing CLI state and render a 1-screen summary.
+
+**This is a transparent wrapper.** The user does not stay in this skill — the status table is rendered, and control hands off (back to the user, or to `peaks-solo` if the user wants to act on the status).
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-status --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Read the current state
+
+Use only existing CLI primitives (no new commands). **Important contract note**: `peaks session list` does NOT support `--project` (verified by dogfood 2026-06-04); it returns all sessions globally. To scope to the current project, read `.peaks/.session.json` for the bound `sessionId`, then use `peaks session info <sid>` for the bound session's full state, and filter `peaks session list` output by `projectRoot` to find other sessions in the same project.
+
+```bash
+# 1. Active skill presence
+peaks skill presence --json
+
+# 2. The bound session id (from .peaks/.session.json — local read, no CLI)
+sid=$(cat .peaks/.session.json | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
+
+# 3. The bound session's full state
+peaks session info "$sid" --json
+
+# 4. All sessions globally (then post-filter to current project)
+peaks session list --json
+# Note: this returns all sessions across all projects; the wrapper filters by
+# matching `projectRoot` against the bound session's `projectRoot` to show only
+# the sessions for THIS project. Sessions from other projects are ignored.
+
+# 5. Per-request role state (PRD / RD / QA / TXT for the bound project)
+peaks project dashboard --project <repo> --json
+
+# 6. Per-request detail (if a specific rid is in flight)
+peaks request show <rid> --role rd --project <repo> --json
+peaks request show <rid> --role qa --project <repo> --json
+```
+
+All 6 calls are read-only. Total cost: sub-second. (The original draft said "5 calls"; the corrected count is 6 because the post-filter step is now explicit.)
+
+## Step 2: Render the status table
+
+Compact 1-screen format:
+
+```
+=== peaks-solo status ===
+Session:   2026-06-04-session-b60252
+Active:    peaks-solo (mode: full-auto, gate: qa-validation)
+Workspace: /Users/yuanyuan/.../peaks-cli/.peaks/2026-06-04-session-b60252
+
+| Role | State          | Artifact                |
+|------|----------------|-------------------------|
+| PRD  | handed-off     | prd/requests/003.md     |
+| RD   | qa-handoff     | rd/requests/003.md      |
+| QA   | running        | qa/requests/003.md      |
+| TXT  | (not started)  | -                       |
+
+QA verdict: pending
+Last activity: 2026-06-04T17:00:00.000Z (12 min ago)
+Standards: 5/5 existing (no delta)
+Health: skill-doctor 35/35 pass
+```
+
+If the session is fresh (no in-flight slice), render a different layout:
+
+```
+=== peaks-solo status ===
+Session: 2026-06-04-session-b60252
+Active:  peaks-solo (mode: full-auto, gate: startup)
+Workspace: /Users/yuanyuan/.../peaks-cli/.peaks/2026-06-04-session-b60252
+
+No in-flight slice. Ready for a new request.
+Health: skill-doctor 35/35 pass
+```
+
+## Step 3: Ask the user what to do next
+
+| Option | What it does |
+|---|---|
+| Continue from the current gate | Hand off to `peaks-solo` with the gate already at the current state. Existing artifacts are preserved. |
+| Open a new slice in this session | Keep the workspace, treat the current request as a new slice (new `rid`). |
+| Just summarize and exit | No further action; the user will decide later. |
+
+## Step 4: Hand off (if user picked option 1 or 2)
+
+Re-assert `peaks-solo` presence so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate <matching-gate>
+```
+
+Then yield control.
+
+## Hard rules (do NOT skip)
+
+- **Never write to `.peaks/_runtime/<sid>/`.** This skill is read-only on the workspace; it only reads existing CLI state.
+- **Never add a new `peaks <cmd>`.** Use only the existing read-only CLI primitives: `peaks skill presence`, `peaks session list`, `peaks session info`, `peaks project dashboard`, `peaks request show`. **Note**: `peaks session list` does not support `--project`; filter its output by `projectRoot` post-hoc.
+- **Never auto-progress the workflow.** The status table is informational only. The user chooses what to do via `AskUserQuestion`. Never silent about what comes next — always present the 3 options.
+- **Never expose sensitive data in the table.** Do NOT include full PRD bodies, full tech-doc bodies, or any test code in the table. Just state names, paths, and counts.
+
+## Anti-patterns (do NOT do)
+
+- Do NOT run `peaks workspace init` on the real session. The wrapper is read-only.
+- Do NOT run `peaks request transition` (would change state). The wrapper is informational only.
+- Do NOT write the status to a file (e.g. `.peaks/_runtime/<sid>/status.md`). The user can see it in the chat; persisting it adds noise to the workspace.
+- Do NOT block on slow CLI calls. The 5 read-only calls are sub-second each. If any takes >5s, fail fast and report the slow command.
+
+## Cross-references
+
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent.
+- `peaks-solo-resume` (P2.1) and `peaks-solo-test` (P2.2) are the sibling wrappers. `peaks-solo-resume` focuses on workflow-state introspection + resume decision; `peaks-solo-status` is the broader 5-CLI snapshot. The two are complementary, not redundant.
+- The "read 5 CLI primitives, render 1 table" pattern is intentionally minimal — the wrapper does NOT add a new status-introspection CLI command (would violate the dev-preference.md "default-no on new CLI" rule).

package/skills/peaks-solo-test/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: peaks-solo-test
+description: Run the project's test suite on the current repo and report results. Use when the user says "run the tests", "跑一下 test", "跑测试", or invokes `/peaks-solo-test` directly. Runs `pnpm vitest run` (or the project's equivalent test command), captures pass/fail counts and any failures, and surfaces a compact summary. Triggers on `/peaks-solo-test`, "跑一下 test", "跑测试", "run the tests", "test now".
+---
+
+# Peaks-Cli Solo Test (wrapper)
+
+Peaks-Cli Solo Test is a thin wrapper that runs the project's test suite on the current repo and reports results. It is the answer to "I just want to see if the tests pass" — no PRD, no RD, no QA, no full peaks-solo orchestration. Just `pnpm vitest run` and a compact summary.
+
+**This is a transparent wrapper.** The user does not stay in this skill — the test command runs, the result is summarized, and control hands off (back to the user, or to `peaks-solo` if the user wants to act on the result).
+
+## Skill presence (MANDATORY first action)
+
+```bash
+peaks skill presence:set peaks-solo-test --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json  # load durable memory
+```
+
+## Step 1: Detect the project's test command
+
+The Peaks-Cli project standard is `pnpm vitest run` (per `vitest.config.ts` + `package.json` scripts). For other project types, check the package.json scripts first. If the user explicitly named a different command (e.g. "跑 `pnpm test` not vitest"), use that.
+
+```bash
+# Default for peaks-cli itself + most TS projects with vitest
+pnpm vitest run
+```
+
+For non-vitest projects (jest, mocha, pytest, etc.), the wrapper respects the project's existing test command. If the user says "run jest" or "run pytest", use that. Do NOT silently default to vitest.
+
+## Step 2: Run the test suite
+
+```bash
+# Run with a reasonable timeout (5 min default; override for slow suites)
+timeout 300 pnpm vitest run 2>&1 | tail -100
+```
+
+Capture both stdout and stderr. If the exit code is 0, tests passed. If non-zero, tests failed or the command errored out.
+
+## Step 3: Summarize the result
+
+Render a compact summary:
+
+- **Test files**: `X passed, Y failed, Z skipped` (from the `Test Files  X passed (Y)` line)
+- **Tests**: `A passed, B failed, C skipped` (from the `Tests  A passed | B skipped (C)` line)
+- **Wall-clock**: the `Duration` line
+- **Failures (if any)**: the first 5-10 failing test names + their failure messages, in priority order (the `FAIL` lines in the test output)
+
+Then ask the user what they want to do next via `AskUserQuestion`:
+
+| Option | What it does |
+|---|---|
+| Show the full failure list | Print all failing test names + messages (not just the first 5-10) |
+| Open a slice to fix the failures | Hand off to `peaks-solo` with the failing tests as the slice's "acceptance criteria" |
+| Just summarize and exit | No further action; the user will decide later |
+
+## Step 4: Hand off (if user picked option 2)
+
+Re-assert `peaks-solo` presence so the status header reads correctly for the rest of the run:
+
+```bash
+peaks skill presence:set peaks-solo --project <repo> --mode <mode> --gate qa-validation
+```
+
+Then yield control. The user's next message will land in `peaks-solo` (in QA validation phase, since the failing tests are the validation surface).
+
+## Hard rules (do NOT skip)
+
+- **Never silently fix test failures.** The user must choose what to do via `AskUserQuestion`. Silently "auto-fix"ing a failing test would mask the failure.
+- **Never modify source code in this skill.** This is a wrapper. The actual fix (if the user wants one) is `peaks-solo`'s job.
+- **Never add a new `peaks <cmd>`.** Use only existing primitives: `peaks skill presence:set`, `peaks project memories`, `peaks workspace init` (for the handoff), `peaks request transition` (if going to QA-validation). The actual test command is the project's existing test runner, not a `peaks <cmd>`.
+- **Never trust the test runner's exit code as the only signal.** Some failures print partial success (e.g. 100 passed + 1 failed); the wrapper must show the failures, not just say "exit 0".
+
+## Anti-patterns (do NOT do)
+
+- Do NOT run `peaks workspace init` on the real session. The wrapper is read-only on the workspace; it only reads the test results, not the workflow state.
+- Do NOT write to `.peaks/_runtime/<sid>/`. This skill is read-only on the workspace.
+- Do NOT auto-fail the workflow if the tests fail. The user gets a summary + 3 options; the workflow state is unchanged.
+- Do NOT run `pnpm vitest run --watch` or any interactive mode. The wrapper captures the output as a one-shot run; interactive mode would block the orchestrator.
+
+## Cross-references
+
+- The "drives a CLI on the user's behalf" pattern (mirror of `peaks-sop`) is the closest existing precedent.
+- `peaks-solo-resume` (sibling wrapper, P2.1) is the workflow-state introspection variant; `peaks-solo-test` is the test-execution variant.
+- The "harness a project-native test runner" pattern is intentionally minimal — the wrapper should NOT add a new CLI for running tests (would violate the dev-preference.md "default-no on new CLI" rule + the user's explicit ask for "skill-first, CLI-auxiliary").

package/skills/peaks-sop/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: peaks-sop
+description: Authoring skill for user-defined SOPs (standard operating procedures) in Peaks. Use when a user wants to create, edit, debug, or register their own gated workflow — ordered phases plus gates that block advancement until conditions are met — by describing it in natural language instead of hand-writing JSON or memorizing CLI commands. DOMAIN-AGNOSTIC: not just software/release flows — equally for content publishing, compliance and approval checklists, data pipelines, onboarding, ops runbooks, or any personal repeatable procedure, wherever "don't enter the next stage until X is true" applies and X is checkable via a file, file content, or a command.
+---
+
+# Peaks-Cli SOP Authoring
+
+Peaks-Cli SOP turns a natural-language workflow description into a validated, registered custom SOP, then helps the user debug it until each gate behaves as intended. The user describes the process in plain language; this skill drives the `peaks sop` CLI on their behalf — they never have to hand-write `sop.json` or remember the command sequence.
+
+**This is a general workflow-gating tool, not a developer-only tool.** A SOP is any repeatable process with ordered stages where you must not skip ahead until conditions are met. Software release is just one example; content publishing, compliance/approval checklists, data validation pipelines, employee onboarding, ops runbooks, and personal procedures are all first-class — often the more valuable use. When you interview the user, do not assume code: ask about *their* process in *their* domain.
+
+## What to tell the user BEFORE running any command
+
+This skill helps you create, test, and enforce a repeatable workflow (a "SOP")
+with gates that physically block advancement until conditions are met. It works
+for ANY domain — content publishing, compliance, onboarding, data pipelines,
+software releases, personal procedures.
+
+Before you run `peaks skill presence:set` or any other setup command, tell the
+user (in your own words, one or two sentences):
+
+  "I'll help you turn your process into a Peaks SOP — ordered stages plus gates
+   that make sure you never skip a step. I'll interview you about your workflow,
+   generate the definition, test it, and register it. Ready?"
+
+If the user has never used Peaks before, offer a 30-second demo:
+
+  "Want me to create a quick demo SOP first? It takes 30 seconds — I'll
+   scaffold one, show you how a gate blocks, then we can replace it with your
+   real workflow."
+
+When they accept, use `demo-sop` as the id (NOT `peaks-sop` — the `peaks-` prefix
+is reserved), name it "Demo SOP", make two phases (draft → done), one gate
+(file-exists README.md), then run the full init→lint→check→register→hooks
+install flow so they see the whole thing. Then offer to replace it with their
+real process.
+
+## Skill presence (MANDATORY first action — run AFTER telling the user what you're doing)
+
+If the user invoked this skill directly ("peaks-sop") without mentioning a
+specific project, assume `--project .` (current directory). If they are NOT in
+the middle of a multi-skill peaks-solo/prd/rd/qa pipeline, skip `statusline
+install` — the status bar is for long-running orchestrations; a standalone SOP
+authoring session does not need it.
+
+```bash
+peaks skill presence:set peaks-sop --project <repo> --mode <mode> --gate startup
+peaks project memories --project <repo> --json
+```
+
+Then display: `Peaks-Cli Skill: peaks-sop | Peaks-Cli Gate: startup | Next: <one short action>`. Update gates with `peaks skill presence:set peaks-sop --project <repo> --mode <mode> --gate <gate>` when they change. When the SOP is registered and the user is satisfied, run `peaks skill presence:clear --project <repo>`.
+
+## Responsibilities
+
+- interview the user to turn a natural-language workflow into ordered **phases** and the **gates** that guard entry into each phase;
+- generate a valid SOP manifest (`sop.json`) and the registrable `SKILL.md` via the CLI — never make the user hand-author JSON;
+- run the lint → fix → re-lint debug loop until the manifest is clean;
+- test each gate (pass/fail/blocked) and dry-run advancement so the user sees the SOP behave before committing;
+- register the SOP so it joins skill presence / statusline like a built-in skill;
+- explain the three gate types and the security posture of command gates.
+
+## What a SOP is (explain this to the user)
+
+A SOP is an **ordered list of phases** plus **gates** bound to phases. A gate that does not pass blocks advancement into its phase — this is how "don't drop steps" applies to the user's own workflow. The SOP lives at `.peaks/sops/<sop-id>/` (manifest `sop.json` + a registrable `SKILL.md`). Gate checks come in three types:
+
+| type | fields | passes when |
+|------|--------|-------------|
+| `file-exists` | `path` | the file exists (path pinned inside the project) |
+| `grep` | `file` + `pattern` (+ `absent`) | the regex matches in the file — or, with `absent: true`, does NOT match |
+| `command` | `run` (argv array) + `expectExitZero` | the command exits as expected |
+
+Prefer **`grep` with `absent: true`** for any "must not contain X" gate (no leftover `TODO`, no placeholder, no unresolved marker). It is a pure-text check — no `--allow-commands`, cross-platform, no shell. Reach for a `command` gate only when the check genuinely needs to run a program.
+
+`command` gates run user-defined processes and are **refused by default** — they require explicit `--allow-commands`, run with no shell (argv array, no injection), a timeout, and cwd pinned to the project. Always tell the user when a SOP needs `--allow-commands` and why.
+
+### Where SOP files live (two definition layers, per-project execution)
+
+A SOP *definition* (manifest + SKILL.md) can live in two layers:
+- **Global** `~/.peaks/sops/<sop-id>/` — your personal SOPs, reusable across every project. `init` / `lint` / `register` default here (no `--project`).
+- **Project** `<project>/.peaks/sops/<sop-id>/` — **committed into the repo**, so a teammate who clones it gets the SOP (and, with the hook installed, is enforced). Pass `--project <repo>` to `init` / `lint` / `register` to use this layer.
+
+The **project layer takes precedence** over global for the same id. Execution reads see the merged view (project wins). A SOP's *run-state* (current phase, history) is always **per-project**: `<project>/.peaks/sop-state/<sop-id>/`. `check` / `advance` take `--project` (default: current directory) to say which project the gates evaluate against, whose progress advances, and which definition layer wins.
+
+`advance` also enforces **phase order**: you may re-enter the current phase, step back, or move to the immediately-next phase, but not skip ahead — a forward jump returns `SOP_PHASE_SKIP` (bypassable, like a gate, with `--allow-incomplete --reason`).
+
+### Where SOPs apply (lead with the user's domain, not code)
+
+The three gate primitives are domain-neutral, so the same engine governs very different workflows:
+
+| domain | phases (example) | gate idea |
+|--------|------------------|-----------|
+| content / publishing | draft → edit → publish | `file-exists` the draft; `grep` no `TODO`/`TKTK`; `command` runs a spell/word-count check |
+| compliance / approval | prepare → review → sign-off | `file-exists` `approval.md`; `grep` the doc contains "Approved" |
+| data pipeline | raw → cleaned → validated | `command` runs a validator script that exits 0 |
+| onboarding / ops | request → provision → done | `file-exists` each checklist artifact; `command` verifies a config |
+| personal procedure | any repeatable steps | whatever "don't forget step X" means, expressed as a file/grep/command |
+
+The one boundary to explain: a gate must reduce to **a file existing, text matching in a file, or a command's exit code**. A purely human-judgment gate ("did the editor approve?") is expressed by reifying it into a signal — e.g. require an `approved.md` file, or that a status file contains "approved". The `command` gate is the universal adapter for anything scriptable.
+
+### Literal-word trap and `stripMeta` (added by PRD 006 on 2026-06-02)
+
+A naive `grep` gate for a content-publishing SOP has a self-referential failure mode: the author writing *about* the gate's pattern ("we use a `grep absent: "TODO"` gate to block leftover T-O-D-O") ends up triggering the gate they just described. This is rare in code-review SOPs and very common in content/publishing SOPs.
+
+**Opt-in workaround**: add `stripMeta: true` to the gate's check. The evaluator strips HTML comments (`<!-- … -->`), fenced code blocks (` ``` … ``` `), and C-style block comments (`/* … */`) from the file content *before* applying the regex. The author's discussion of the gate in those areas is no longer counted.
+
+```json
+{
+  "id": "no-todo",
+  "phase": "publish",
+  "check": { "type": "grep", "file": "post.md", "pattern": "TODO", "absent": true, "stripMeta": true }
+}
+```
+
+Default `false` preserves byte-identical behavior for existing SOPs. The stripper is conservative on malformed input (unclosed fences / block comments fall through un-stripped). Not covered by this slice: inline code (`` `TODO` ``) and blockquotes (`> TODO`) — both are content the author explicitly chose to render, so they remain subject to the regex. If a future dogfood surfaces a need to strip those too, open a follow-up PRD.
+
+## Un-bypassable enforcement (optional, opt-in)
+
+By default a SOP gate only blocks the `peaks sop advance` command — nothing forces the agent through it. To make a gate **physically un-bypassable**, a SOP can declare **guards** that bind a concrete irreversible Bash action to a phase, and the user installs a PreToolUse hook:
+
+```jsonc
+// in sop.json
+"guards": [ { "phase": "publish", "bash": "git +push" } ]
+```
+Meaning: running a Bash command matching `git +push` IS entering the publish phase, so publish's gates must pass first. Then:
+
+```bash
+peaks hooks install --project <repo>     # explicit, opt-in; writes one PreToolUse entry
+```
+
+Now when the agent tries `git push` while the publish gate fails, Claude Code receives `permissionDecision: "deny"` and the command is blocked **before any permission check — it holds even under `--dangerously-skip-permissions`**. CI only blocks at merge; CLAUDE.md instructions are advisory; this blocks in-conversation and cannot be skipped.
+
+- `bash` is a **JS regex inside JSON** — escape backslashes (`"git\\s+push"`) or just use `"git +push"`. `peaks sop lint` rejects an invalid regex (`GUARD_INVALID_PATTERN`).
+- Emergency override: `peaks gate bypass --sop <id> --phase <phase> --reason "<why>"` records a **one-shot** token consumed by the next blocked command (capped per project per SOP, reason audited).
+- Trust: enforcement **fails open** — any internal error allows the command (a Peaks bug never bricks Claude Code); only a real gate failure denies. Installing the hook is an explicit user command; this skill never writes `settings.json` itself.
+- `peaks hooks status` / `peaks hooks uninstall` manage the hook.
+
+> Team enforcement: register the SOP into the **project layer** (`peaks sop init/register --project <repo>`) so the definition is committed in the repo. A teammate who clones it — even with an empty global `~/.peaks` — is enforced by the same gates once they install the hook. (A SOP that lives only in your global `~/.peaks` enforces only on your machine.)
+
+## Default runbook
+
+The default sequence this skill executes on the user's behalf. The natural-language → generate → debug loop IS this runbook.
+
+```bash
+# self-check (required by doctor; no user-visible effect)
+peaks skill runbook peaks-sop --json
+
+# 1. interview the user FIRST (before any scaffold): what are the ordered stages?
+#    For each stage, what must be true before entering it? Translate answers into
+#    file-exists / grep / grep-absent / command gates.
+
+# 2. scaffold the SOP based on the interview (preview first, then apply)
+#    definitions are global (~/.peaks/sops) — init/lint/register take no --project
+peaks sop init --id <sop-id> --name "<human name>" --json
+peaks sop init --id <sop-id> --name "<human name>" --apply --json
+
+# 3. write the phases/gates from the interview into ~/.peaks/sops/<sop-id>/sop.json
+#    (edit the manifest directly — the user described it in natural language)
+
+# 4. DEBUG LOOP: lint, fix the reported findings, re-lint until clean
+peaks sop lint --id <sop-id> --json
+peaks sop lint --id <sop-id> --allow-commands --json   # when the SOP uses command gates
+
+# 5. test each gate behaves as intended (pass / fail / blocked) against a project
+peaks sop check --id <sop-id> --gate <gate-id> --project <repo> --json
+
+# 6. dry-run the flow to confirm gates + phase order block/allow the right phases
+peaks sop advance --id <sop-id> --to <phase> --project <repo> --dry-run --json
+
+# 7. register the SOP (preview, then apply) so it joins presence/statusline
+peaks sop register --id <sop-id> --dry-run --json
+peaks sop register --id <sop-id> --json
+peaks sop registry --json
+
+# 8. (optional) make a gate un-bypassable: declare guards in sop.json, then install the hook
+peaks hooks install --project <repo>
+peaks hooks status --project <repo>
+#    emergency one-shot override when a guarded action must proceed despite a failing gate:
+peaks gate bypass --sop <sop-id> --phase <phase> --reason "<why>" --project <repo>
+
+# 9. hand the SOP to the user; clear presence when done
+peaks project memories:extract --session-id <session-id> --project <repo> --json  # extract durable memories
+peaks skill presence:clear --project <repo>
+```
+
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare a SOP ready from memory. Each gate below is a command you **MUST run** and whose output you **MUST see**.
+
+**Peaks-Cli Gate A — the manifest lints clean before register:**
+```bash
+peaks sop lint --id <sop-id> --json
+# Expected: ok:true. If ok:false, fix the findings and re-lint — do NOT register a SOP that does not lint.
+```
+
+**Peaks-Cli Gate B — gates behave as intended before handing off:**
+```bash
+peaks sop check --id <sop-id> --gate <gate-id> --project <repo> --json
+# Confirm each gate returns the verdict the user expects (pass on the good state, fail/blocked otherwise).
+```
+
+## Debugging guidance
+
+When `sop lint` reports findings, fix them in `sop.json` and re-lint — common findings: duplicate gate id, gate bound to an undefined phase, missing check fields, or a command gate without `--allow-commands`. When `sop check` returns `blocked`, the check could not be evaluated (path escaped the project, target file unreadable, command not permitted or failed to spawn) — distinct from `fail` (evaluated, condition not met). Use `sop advance --dry-run` to confirm the blocking behaves before any real advance.
+
+Concrete manifest reference, gate cookbook, and the debug loop: `references/sop-authoring.md`.
+
+## Boundaries
+
+Do not implement the user's business code, run their real release, or modify runtime configuration. This skill authors and validates the SOP definition; the SOP's gates then govern the user's own workflow. `command` gates execute user-defined commands only with explicit `--allow-commands` consent. Do not register a SOP that does not lint clean.

package/skills/peaks-sop/references/sop-authoring.md

@@ -0,0 +1,161 @@
+# SOP Authoring Reference
+
+Concrete reference for the `peaks-sop` skill: manifest shape, gate cookbook, the
+interview → generate → debug loop, and security notes. The skill drives the
+`peaks sop` CLI on the user's behalf — this file is the detail behind that.
+
+## Where files live
+
+SOP **definitions** live in one of two layers:
+- **Global** `~/.peaks/sops/<sop-id>/sop.json` (+ `SKILL.md`) — personal, reusable across every project. `init` / `lint` / `register` default here.
+- **Project** `<project>/.peaks/sops/<sop-id>/sop.json` — committed into the repo and team-shared. Pass `--project <repo>` to `init` / `lint` / `register` to use this layer. The project layer **wins** over global for the same id; execution reads (`check` / `advance` / `gate enforce` / `registry`) default `--project` to the current directory, so they see the merged view without an explicit flag.
+
+A SOP's **run-state** is always per-project: `<project>/.peaks/sop-state/<sop-id>/state.json` (git-ignored — runtime, not shared). `check` / `advance` take `--project` (default: current directory) — that says which project the gate paths resolve against, whose progress advances, and which definition layer wins.
+
+Use the **project layer** when you want a workflow's gates to bind the whole team (commit the SOP, install the hook in the repo's `.claude/settings.json`); use **global** for your own repeatable procedures across many repos.
+
+## Manifest shape (`~/.peaks/sops/<sop-id>/sop.json`)
+
+```json
+{
+  "id": "team-release",
+  "name": "Team Release",
+  "description": "Gates that must pass before we ship a release.",
+  "phases": ["draft", "review", "ship"],
+  "gates": [
+    { "id": "changelog", "phase": "ship", "check": { "type": "file-exists", "path": "CHANGELOG.md" } },
+    { "id": "no-fixme", "phase": "review", "check": { "type": "grep", "file": "src/index.ts", "pattern": "FIXME" } },
+    { "id": "tests", "phase": "ship", "check": { "type": "command", "run": ["npm", "test"] } }
+  ]
+}
+```
+
+Rules the lint enforces (so generate the manifest to satisfy them):
+
+- `id` — lowercase kebab, starts alphanumeric; must NOT collide with the reserved `peaks-` / `peaks` namespace; must match the directory name.
+- `phases` — at least one; no duplicates.
+- each gate `id` — lowercase kebab, unique within the SOP.
+- each gate `phase` — must be one of the declared `phases`.
+- each gate `check` — a known type with its required fields present.
+
+## Gate cookbook
+
+| intent | check |
+|--------|-------|
+| a file must exist before a phase | `{ "type": "file-exists", "path": "CHANGELOG.md" }` |
+| a doc must contain a marker | `{ "type": "grep", "file": "README.md", "pattern": "## Release notes" }` |
+| there must be NO leftover markers | `{ "type": "grep", "file": "post.md", "pattern": "TODO", "absent": true }` — passes only when the pattern is absent. Pure text, no `--allow-commands`, cross-platform. Prefer this over a `! grep` command gate. |
+| tests must pass | `{ "type": "command", "run": ["npm", "test"] }` (requires `--allow-commands`) |
+| a build must succeed | `{ "type": "command", "run": ["npm", "run", "build"] }` (requires `--allow-commands`) |
+| a command must FAIL to pass the gate | add `"expectExitZero": false` to the command check |
+
+Gate verdicts:
+
+- `pass` — the condition is met.
+- `fail` — evaluated, condition not met (e.g. file missing, pattern absent, command exited wrong).
+- `blocked` — could not evaluate: path escaped the project root, target file unreadable, command not permitted (`--allow-commands` missing) or failed to spawn / timed out.
+
+## Cross-domain examples (SOPs are not just for code)
+
+The release example above is one domain. The same engine governs any gated workflow — often the higher-value use. Lead the interview with the user's own domain.
+
+**Content publishing** (`~/.peaks/sops/blog-publish/sop.json`):
+
+```json
+{
+  "id": "blog-publish",
+  "name": "Blog Publish",
+  "phases": ["draft", "edit", "publish"],
+  "gates": [
+    { "id": "draft-exists", "phase": "edit", "check": { "type": "file-exists", "path": "posts/current.md" } },
+    { "id": "no-placeholders", "phase": "publish", "check": { "type": "grep", "file": "posts/current.md", "pattern": "TODO|TKTK", "absent": true } }
+  ]
+}
+```
+
+Note `no-placeholders` uses `grep` with `absent: true` — "must not contain a placeholder" — so it needs no `--allow-commands` and works on any OS. This is the single most common non-engineering gate.
+
+**Compliance / approval** (`~/.peaks/sops/vendor-approval/sop.json`):
+
+```json
+{
+  "id": "vendor-approval",
+  "name": "Vendor Approval",
+  "phases": ["submitted", "reviewed", "approved"],
+  "gates": [
+    { "id": "review-notes", "phase": "reviewed", "check": { "type": "file-exists", "path": "vendors/acme/review.md" } },
+    { "id": "signed-off", "phase": "approved", "check": { "type": "grep", "file": "vendors/acme/review.md", "pattern": "Status:\\s*Approved" } }
+  ]
+}
+```
+
+**Data pipeline** (`~/.peaks/sops/dataset-release/sop.json`):
+
+```json
+{
+  "id": "dataset-release",
+  "name": "Dataset Release",
+  "phases": ["raw", "cleaned", "validated"],
+  "gates": [
+    { "id": "schema-valid", "phase": "validated", "check": { "type": "command", "run": ["python", "scripts/validate.py", "data/cleaned.csv"] } }
+  ]
+}
+```
+
+These reuse the same three gate types — only the phases and the file/command targets differ. A human-judgment step ("the editor approved") is reified into a file/grep signal (an `approval.md` file, or a status line matching "Approved"), as shown above.
+
+## Guards: un-bypassable enforcement (optional)
+
+A gate normally only blocks `peaks sop advance`. To make it physically un-bypassable by the agent, add **guards** that bind an irreversible Bash action to a phase, and have the user install the PreToolUse hook.
+
+```json
+{
+  "id": "team-release",
+  "name": "Team Release",
+  "phases": ["draft", "review", "ship"],
+  "gates": [
+    { "id": "no-fixme", "phase": "ship", "check": { "type": "grep", "file": "src/index.ts", "pattern": "FIXME", "absent": true } }
+  ],
+  "guards": [
+    { "phase": "ship", "bash": "git +push" },
+    { "phase": "ship", "bash": "npm +publish" }
+  ]
+}
+```
+
+Semantics: a Bash command matching a guard's `bash` regex = entering that phase, so the phase's gates must pass first. With the hook installed (`peaks hooks install --project <repo>`), the agent literally cannot run `git push` / `npm publish` while `no-fixme` fails — Claude Code receives `permissionDecision: "deny"` before any permission check (holds even under `--dangerously-skip-permissions`).
+
+`bash` rules:
+- It is a **JS regex written inside JSON**. Escape backslashes: `"git\\s+push"`, or sidestep escaping with `"git +push"` (one-or-more spaces). `peaks sop lint` rejects an uncompilable regex (`GUARD_INVALID_PATTERN`) and a guard on an undeclared phase (`GUARD_PHASE_UNKNOWN`).
+- Keep patterns specific to the irreversible action (`git +push`, `npm +publish`, `gh +release`, a deploy script name) — not broad verbs.
+
+Override once (hotfix): `peaks gate bypass --sop team-release --phase ship --reason "<why>" --project <repo>` — consumed by the next blocked command, capped per project per SOP.
+
+`command`-type gates run during enforcement with commands enabled (installing the hook is the consent); each gate keeps its 30s timeout. Enforcement **fails open** on any internal error — only a real gate failure denies.
+
+## Interview → generate → debug loop
+
+1. **Interview.** Ask: what are the ordered stages of this workflow? For each stage, what must be true before you're allowed to enter it? Translate "must be true" into file-exists / grep / command checks. For "must NOT contain X", reach for `grep` + `absent: true`.
+2. **Scaffold.** `peaks sop init --id <id> --name "<name>" --apply --json`. Writes a starter `sop.json` + `SKILL.md` into the global `~/.peaks/sops/<id>/` (no `--project`).
+3. **Write the real manifest.** Replace the scaffold's example phases/gates with the interviewed ones by editing `sop.json` directly.
+4. **Lint loop.** `peaks sop lint --id <id> --json` → read findings → fix in `sop.json` → re-lint until `ok:true`. Add `--allow-commands` when the SOP uses command gates.
+5. **Gate test.** `peaks sop check --id <id> --gate <gate-id> --project <repo> --json` for each gate, in both the good state (expect `pass`) and a bad state (expect `fail`/`blocked`). `--project` is the project the gate paths resolve against (default: current directory).
+6. **Dry-run the flow.** `peaks sop advance --id <id> --to <phase> --project <repo> --dry-run --json` — confirms a failing gate (or a forward phase skip) truly blocks, without recording anything.
+7. **Register.** `peaks sop register --id <id> --json` (preview with `--dry-run` first). Now the SOP is enumerable in the global registry and can be set as the active skill via presence.
+
+## Security notes (always surface to the user)
+
+- `command` gates run user-defined commands. They are refused unless the user explicitly passes `--allow-commands` to `lint` / `register` / `check` / `advance`. Tell the user a SOP needs `--allow-commands` and what the command does before running it.
+- Commands run with an argv array (no shell, no injection), a timeout cap, and cwd pinned to the project root. The command executable itself is not sandboxed — the trust boundary is whoever authored the SOP, the same as an npm script or Makefile target.
+- `file-exists` / `grep` paths are confined inside the project root; an out-of-bounds path returns `blocked`, never reads outside the project.
+- Side-effecting commands (`init` / `register` / `advance`) support `--dry-run` to preview without writing.
+
+## Bypassing a blocked advance
+
+If the user must move forward despite a failing gate **or a forward phase skip** (e.g. a hotfix that skips review), advancement can be bypassed explicitly:
+
+```bash
+peaks sop advance --id <id> --to <phase> --project <repo> --allow-incomplete --reason "<why>" --json
+```
+
+`--allow-incomplete` bypasses both the gate checks and the phase-order check. In assisted/strict mode this also requires `--confirm`, and each SOP has a per-project bypass cap. Always record a real reason — the bypass is logged in that project's SOP history.