peaks-cli 1.1.2 → 1.2.1

package/schemas/sop-manifest.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Peaks SOP Manifest",
+  "type": "object",
+  "required": ["id", "name", "phases", "gates"],
+  "properties": {
+    "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+    "name": { "type": "string" },
+    "description": { "type": "string" },
+    "phases": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "guards": {
+      "type": "array",
+      "description": "Optional Bash-action guards enforced by the PreToolUse hook (peaks gate enforce).",
+      "items": {
+        "type": "object",
+        "required": ["phase", "bash"],
+        "properties": {
+          "phase": { "type": "string" },
+          "bash": { "type": "string", "description": "JS regex tested against the Bash tool_input.command" }
+        }
+      }
+    },
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "phase", "check"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" },
+          "phase": { "type": "string" },
+          "check": {
+            "type": "object",
+            "required": ["type"],
+            "properties": {
+              "type": { "type": "string", "enum": ["file-exists", "grep", "command"] },
+              "path": { "type": "string" },
+              "file": { "type": "string" },
+              "pattern": { "type": "string" },
+              "absent": { "type": "boolean", "description": "grep only: pass when the pattern is NOT found (\"must not contain X\")" },
+              "run": { "type": "array", "items": { "type": "string" } },
+              "expectExitZero": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/skills/peaks-solo/SKILL.md

@@ -44,9 +44,35 @@ peaks-solo (orchestrate only)
 
 ## Peaks-Cli Startup sequence (MANDATORY — execute in order)
 
-### Peaks-Cli Step 1: Mode selection (MUST run before presence:set)
+### Peaks-Cli Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
 
-When the user invokes Peaks-Cli Solo without explicitly naming an execution profile, use `AskUserQuestion` BEFORE any other action. Present the recommended full-auto path as the first/default option with a practical description for each:
+The instant Peaks-Cli Solo is invoked, **before** the mode-selection question, before any analysis, and before you decide whether the request "needs" the full pipeline, you MUST run these two commands and see their output:
+
+```bash
+# Session ID is auto-generated when omitted; the command returns it in the JSON output
+peaks workspace init --project <repo> --json
+peaks skill presence:set peaks-solo --project <repo> --gate startup
+```
+
+If `workspace init` fails with "required option '--session-id' not specified", the CLI version predates auto-generation. Generate a session ID manually and pass it:
+
+```bash
+SESSION_ID="$(date +%Y-%m-%d)-session-$(openssl rand -hex 3)"
+peaks workspace init --project <repo> --session-id "$SESSION_ID" --json
+peaks skill presence:set peaks-solo --project <repo> --gate startup
+```
+
+> `<repo>` is the **git project root** (the directory containing `.git`). In a monorepo / single-repo-multi-package layout, this is the repo root, NOT a sub-package — `.peaks/` lives at the repo root so every package shares one workspace. If unsure, run `git rev-parse --show-toplevel` and use that path. Never let `.peaks/` land inside a sub-package directory.
+
+**There is no request too lightweight to skip this.** "分析下这个项目", "看一下代码", "分析项目", "解释一下架构", a one-line question — all of them still create the workspace and set presence first. The workspace is cheap; a missing `.peaks/` is the #1 reported failure.
+
+**Anti-bail-out rule (BLOCKING):** You MUST NOT exit the peaks-solo workflow, hand control back, or produce a final answer before Step 0 has run. If you catch yourself thinking "this is just analysis, I don't need the workflow" — STOP. Run Step 0, set presence, then continue. A pure-analysis request runs the **lightweight analysis branch** (project scan + standards dry-run + handoff with a Standards-increment section), but it still anchors the workspace and keeps presence active. Declining to anchor is a workflow violation.
+
+`presence:set` accepts no `--mode` here on purpose — mode is unknown until Step 1. It is re-run with the selected mode in Step 2. Setting presence early guarantees the status header/line shows `peaks-solo` from the very first turn even if the user never reaches mode selection.
+
+### Peaks-Cli Step 1: Mode selection
+
+After Step 0 has anchored the workspace and presence, when the user invokes Peaks-Cli Solo without explicitly naming an execution profile, use `AskUserQuestion` to pick the profile. Present the recommended full-auto path as the first/default option with a practical description for each:
 
 1. **Full auto (Recommended)** — Peaks-Cli handles planning, role coordination, validation, and compact handoff end-to-end while preserving required confirmation gates for risky or shared-state actions.
 2. **Assisted** — Peaks-Cli proposes plans, artifacts, and checks, then pauses for user decisions at major workflow boundaries.
@@ -66,9 +92,9 @@ Map the user's selection to the `--mode` flag value (used by `peaks skill presen
 
 If the user already names a profile in their invocation (e.g. `/peaks-solo --full-auto`, "用全自动模式"), skip this question and use the named profile directly.
 
-### Peaks-Cli Step 2: Set skill presence
+### Peaks-Cli Step 2: Re-set skill presence with the chosen mode
 
-Only after the mode is known (user selected or explicitly named), run:
+Step 0 already set presence with no mode. Now that the mode is known (user selected or explicitly named), re-run presence:set so the header/status line shows the profile:
 
 ```bash
 peaks skill presence:set peaks-solo --project <repo> --mode <mode-value> --gate startup
@@ -144,7 +170,7 @@ For frontend workflows, RD and QA must use Playwright MCP (`mcp__playwright__` t
 
 ### Workspace initialization gate
 
-Before ANY role handoff or artifact write, Peaks-Cli Solo MUST create the workspace. Session IDs are now **auto-generated** with the format `YYYY-MM-DD-session-<6位hex>` (e.g. `2026-05-26-session-a3f8b1`). The user does not provide a session ID — the system creates and persists it in `.peaks/.session.json`.
+The workspace is created in Step 0 (Startup sequence) as a mandatory first action — before any analysis, role handoff, or artifact write, and regardless of how lightweight the request is. Session IDs are now **auto-generated** with the format `YYYY-MM-DD-session-<6位hex>` (e.g. `2026-05-26-session-a3f8b1`). The user does not provide a session ID — the system creates and persists it in `.peaks/.session.json`.
 
 When `peaks workspace init` is run without `--session-id`, it automatically generates a new session ID using today's date and a random hex suffix. If `.peaks/.session.json` already exists with a valid session, the existing session is reused.
 
@@ -760,7 +786,7 @@ Use `standards init` for first-time creation and `standards update` for existing
 
 Do not hand-write standards file mutations inside the skill.
 
-For project-analysis requests such as "分析项目", the handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
+For project-analysis requests such as "分析项目" / "分析下这个项目", Step 0 still applies: the workspace is initialized and `peaks-solo` presence is set before any analysis output. These requests run the lightweight analysis branch (project scan + standards dry-run) rather than the full RD/QA pipeline, but they never skip workspace anchoring or exit the workflow. The handoff must include an explicit **Standards increment** section. Report the current `CLAUDE.md` and `.claude/rules/**` status from the dry-run output as incremental deltas, not just a generic preflight note:
 
 - whether `CLAUDE.md` is missing, existing, planned, skipped, appended, or review-only;
 - which `.claude/rules/**` files are planned, existing, skipped, appended, or review-only;

package/skills/peaks-sop/SKILL.md

@@ -0,0 +1,192 @@
+---
+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.
+
+## 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 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`/enforce) and `sop registry --project` see the merged view.
+
+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.