peaks-loop 3.1.2 → 4.0.0-beta.10

package/skills/bee/peaks-rd/references/rd-transition-gates.md

@@ -0,0 +1,148 @@
+# Peaks-Loop RD transition verification gates
+
+> Extracted from `skills/peaks-rd/SKILL.md` on 2026-06-09 (slice 019 — slim skill files to references) to keep SKILL.md under the 800-line cap from `common/coding-style.md`. The content below is the verbatim "Transition verification gates" section that was previously inline; nothing was paraphrased, just relocated.
+
+## Transition verification gates (MANDATORY — full per-gate contract)
+
+You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file" or any command returns empty, the phase is incomplete.
+
+> **CLI enforcement (NEW)**: the gates below are now ALSO enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. The exact required files depend on the request type chosen at `peaks request init --type <feature|bugfix|refactor|docs|config|chore>` (default `feature`):
+>
+> | Type | rd:implemented requires | rd:qa-handoff also requires |
+> |---|---|---|
+> | feature / refactor | `rd/tech-doc.md` | `rd/code-review.md` + `rd/security-review.md` + `rd/perf-baseline.md` (filled Results table, or `N/A — no perf surface` in Notes) + **`qa/test-cases/<rid>.md`** (added in slice 004; pre-drafted by the 4th sub-agent in the parallel fan-out) |
+> | bugfix | `rd/bug-analysis.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review.md` + `rd/security-review.md` + **`qa/test-cases/<rid>.md`**; `rd/perf-baseline.md` only when the bug is performance-shaped (matches the L449-452 "When this applies" criteria) |
+> | config | (none) | `rd/security-review.md` only |
+> | docs / chore | (none) | (none) |
+>
+> The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions; the bypass is recorded in the artifact transition note.
+
+**Peaks-Loop Gate A — After project-scan read (before any implementation):**
+```bash
+ls .peaks/project-scan/project-scan.md
+# Expected output: .peaks/project-scan/project-scan.md
+# "No such file" → STOP, create the project-scan first. Do not write code.
+```
+
+**Peaks-Loop Gate A2 — Before tech-doc write: project structure verified (PATH CORRECTNESS — CRITICAL):**
+```bash
+# Verify EVERY file path and directory in the tech-doc exists in the actual project.
+# Do not assume paths. Do not guess directory structures. Open the files and verify.
+# Example verification (adapt paths to the actual tech-doc):
+ls <every-single-directory-path-in-tech-doc> 2>&1 | grep -c "No such file"
+# Expected: 0 (zero "No such file" errors)
+# Any "No such file" → WRONG PATH. Fix the tech-doc BEFORE writing another word.
+# This gate exists because a tech-doc with wrong paths wastes QA time,
+# breaks the implementation, and forces the user to correct the engineer.
+```
+
+**Peaks-Loop Gate A3 — Before implementation: project standards files exist (CLAUDE.md + .claude/rules/):**
+```bash
+ls CLAUDE.md .claude/rules/common/coding-style.md .claude/rules/common/code-review.md .claude/rules/common/security.md 2>&1 | grep -c "No such file"
+# Expected: 0 (all four files exist)
+# Any missing → BLOCKED. Run `peaks standards init --project .` to generate them FIRST.
+# Do not write a single line of implementation code without standards files in place.
+# Without CLAUDE.md and .claude/rules/, code review and security review triggers won't fire.
+```
+
+**Peaks-Loop Gate B — Before QA handoff:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md \
+   .peaks/_runtime/<sessionId>/rd/tech-doc.md
+# Both must exist. Missing either → BLOCKED, do not hand off to QA
+```
+
+**Peaks-Loop Gate B2 — Before QA handoff: unit tests exist and pass for the changed surface:**
+```bash
+# Run the project's test command against changed files. Record the output.
+# Example (adapt to project test runner):
+npx vitest run --changed --reporter=verbose 2>&1 | tail -20
+# Expected: exit code 0, all changed-surface tests passing, coverage for new/changed code recorded
+# Any failing test or zero tests for new code → BLOCKED. Write tests, then re-run.
+#
+# To run the FULL suite (slower; not the default for `peaks slice check`),
+# drop `--changed` or use `npx vitest run --reporter=verbose`. The peaks-code-test
+# skill is the user-facing wrapper for the full suite; the slice check's
+# `--run-tests` flag is the CLI opt-in.
+```
+
+**Peaks-Loop Gate B3 — Before QA handoff: code review evidence exists:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/code-review.md 2>&1
+# Expected: .peaks/_runtime/<sessionId>/rd/code-review.md
+# "No such file" → BLOCKED. Run code review (use code-reviewer agent or equivalent),
+# record findings, fix CRITICAL/HIGH issues, then re-check.
+```
+
+**Peaks-Loop Gate B4 — Before QA handoff: security review evidence exists:**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/security-review.md 2>&1
+# Expected: .peaks/_runtime/<sessionId>/rd/security-review.md
+# "No such file" → BLOCKED. Run security review (use security-reviewer agent or equivalent),
+# fix CRITICAL/HIGH issues, record findings, then re-check.
+```
+
+**Peaks-Loop Gate B5 — RD artifact body has no unfilled placeholders:**
+```bash
+peaks request lint <rid> --role rd --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# ok=false → BLOCKED. The lint output lists every <placeholder>, "- ..." stub,
+# and TBD/TODO marker with line numbers. Fill them in before attempting handoff.
+```
+
+**Peaks-Loop Gate B6 — Declared --type matches the actual diff:**
+```bash
+peaks scan request-type-sanity --project <repo> --type <type> --json
+# Expected: consistent=true. exit 0.
+# consistent=false → BLOCKED. Either the implementation scope-creeped beyond what
+# the declared type covers, or the type was mis-classified at PRD time. Re-classify
+# (`peaks request init` with the corrected --type) or trim the scope.
+```
+
+**Peaks-Loop Gate B7 — Repair cycle cap (only relevant during RD↔QA repair loop):**
+```bash
+peaks request repair-status <rid> --project <repo> --session-id <session-id> --json
+# Expected: atCap=false. exit 0.
+# atCap=true → BLOCKED. Three repair cycles already attempted; emit a blocked TXT
+# handoff via Code rather than entering a fourth cycle.
+```
+
+**Peaks-Loop Gate B8 — Diff stays inside the declared red-line scope:**
+```bash
+peaks scan diff-vs-scope --rid <rid> --project <repo> --session-id <session-id> --json
+# Expected: ok=true. exit 0.
+# violations[] non-empty → BLOCKED. A changed file matches an explicit out-of-scope
+#   pattern. Revert it, or — only with PRD approval — expand the RD red-line scope.
+# unclassified[] non-empty → BLOCKED. A changed file does not match any declared
+#   in-scope pattern. Either add it to the in-scope list (intentional widening, requires
+#   PRD approval) or revert the change.
+# patternsDeclared=false → BLOCKED. The RD artifact's `## Red-line scope` section has
+#   no concrete path or glob patterns. Fill it in with paths like `src/services/login/**`
+#   before re-running. Auto-allowed paths (test files, .peaks/, __mocks__/) never need a pattern.
+```
+
+**Peaks-Loop Gate B9 — RD-side perf-baseline output present (when slice has a user-perceivable perf surface):**
+```bash
+ls .peaks/_runtime/<sessionId>/rd/perf-baseline.md 2>&1
+# Expected: .peaks/_runtime/<sessionId>/rd/perf-baseline.md
+# "No such file" + slice is feature / refactor / bugfix-when-perf → BLOCKED.
+#   Run the perf-baseline sub-agent from "Parallel review fan-out" below (or
+#   `peaks perf baseline --apply` inline), then fill in the Results table
+#   with measurements (lighthouse / k6 / autocannon / project-local bench —
+#   the CLI does not run these; that is the RD's job), then re-verify.
+# "No such file" + slice is docs / chore / pure-bugfix-no-perf → OK to proceed;
+#   this gate does not apply to those slice types.
+# File exists but Results table is empty (only the header row, no data rows) →
+#   BLOCKED. The sub-agent scaffolds the file; the main RD loop must fill in
+#   the Path / route | Workload | Tool | Metric | Baseline | Threshold table
+#   with actual numbers before handoff.
+# File contains the marker `N/A — no perf surface` in its Notes section →
+#   OK to proceed. This is the explicit opt-out the sub-agent writes when
+#   the slice has no user-perceivable perf surface (e.g. a feature that only
+#   adds an internal flag with no runtime cost, or a refactor that does not
+#   alter any hot path).
+#
+# The CLI enforcement table below the section header also gates this at the
+# `peaks request transition rd:qa-handoff` call, so a missing or empty file
+# is rejected by the CLI with `code: PREREQUISITES_MISSING`.
+```

package/skills/bee/peaks-rd/references/skill-presence-and-title.md

@@ -0,0 +1,22 @@
+# Skill presence (RD)
+
+> Body of `## Skill presence (MANDATORY first action — main-loop context only)`. When this skill is running in the main Claude session (not as a sub-agent — i.e. user invoked `peaks-rd` directly, or `peaks-code` is executing the role inline in assisted/strict mode), before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Read persistent project memory via CLI (durable, LLM-authored memories):
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Loop Skill: peaks-rd | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-rd --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.

package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md

@@ -0,0 +1,68 @@
+# Writing handoff frontmatter (peaks-rd → peaks-qa)
+
+Every RD handoff artifact carries a **YAML frontmatter block** so peaks-qa (and downstream roles) can mechanically cross-check decisions, risks, and gate evidence. The body below the frontmatter is free-form prose (markdown).
+
+## Path
+
+`.peaks/_runtime/<sessionId>/prd/handoff.md` — the canonical immutable PRD handoff path (v2.11.0+). The handoff is written by peaks-prd, sha256-hashed in frontmatter, and verified by every downstream sub-agent against the dispatched hash before reading.
+
+> **v2.11.0 change (Group A):** the per-session `rd/tech-doc.md` is removed; the immutable peaks-prd handoff replaces it as the slice's source-of-truth architecture document.
+
+## Required frontmatter fields
+
+```yaml
+---
+requestId: 2026-06-25-slice-topology-multipass
+scope:
+  - src/services/slice/schema-router.ts
+  - src/services/audit/audit-goal-service.ts
+files:
+  - src/services/slice/schema-router.ts
+  - src/services/audit/audit-goal-service.ts
+handoffPath: .peaks/_runtime/<sessionId>/prd/handoff.md
+handoffHash: sha256:<64 hex chars>
+decisions:
+  - id: D1
+    summary: "Route v1/v2 envelopes via SchemaRouter instead of branching in prompts"
+    rationale: "Single source of truth; SchemaRouter already lives in src/services/slice/"
+risks:
+  - id: R1
+    description: "v1 fallback path untested when sliceIds collide with v2 parentSliceIds"
+    mitigation: "Added 3 collision cases to v1-fallback.test.ts"
+nextActions:
+  - "peaks-qa reads this handoff and runs the regression matrix"
+  - "If Gate C passes, transition to txt handoff"
+gateEvidence:
+  projectScan: .peaks/project-scan/project-scan.md
+  prdHandoff: .peaks/_runtime/<sessionId>/prd/handoff.md
+  codeReview: .peaks/_runtime/<sessionId>/rd/code-review.md
+  securityReview: .peaks/_runtime/<sessionId>/rd/security-review.md
+  perfBaseline: .peaks/_runtime/<sessionId>/rd/perf-baseline.md
+schemaVersion: '2.0'
+---
+```
+
+## Field rules
+
+- `requestId` — kebab-case; matches the PRD `requestId`.
+- `scope` / `files` — absolute repo-relative paths (`src/...`). Sorted alphabetically.
+- `handoffPath` + `handoffHash` — the immutable PRD handoff location and its sha256 hash. Sub-agents MUST verify `handoffHash` matches the file's actual sha256 before reading; mismatch → return `blocked`.
+- `decisions[]` — every decision an LLM made that an implementer could question. `id` is local; `summary` is one line; `rationale` is ≤ 2 sentences.
+- `risks[]` — same shape; `mitigation` is required. A risk without a mitigation is a red line (gate blocked).
+- `nextActions[]` — verb-first; what peaks-qa should do next, in order.
+- `gateEvidence` — paths to the gate files peaks-qa will validate. Missing keys → Gate C failure.
+- `schemaVersion: '2.0'` — pinned (bumped from `'1.0'` in v2.11.0); bump only when the field set changes.
+
+> **v2.11.0 Group A change:** the validation tests at `tests/unit/artifacts/handoff-frontmatter-shape.test.ts` now assert `schemaVersion === '2.0'`. Files still carrying `'1.0'` will fail validation until upgraded.
+
+## Validation
+
+The frontmatter MUST parse as valid YAML. The regression test `tests/unit/artifacts/handoff-frontmatter-shape.test.ts` (≥ 4 cases) enforces (a) required fields present, (b) `gateEvidence` keys match the per-request-type matrix in `peaks-rd/SKILL.md` Gate C table, (c) `schemaVersion: '1.0'`. Run before commit:
+
+```bash
+./node_modules/.bin/vitest run tests/unit/artifacts/handoff-frontmatter-shape.test.ts
+```
+
+## Body (prose, free-form)
+
+Markdown below the frontmatter is the implementation narrative: what changed, why this slice, what the next role should know. Do NOT restate frontmatter fields in prose.

package/skills/bee/peaks-reviewer/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: peaks-reviewer
+description: Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.
+---
+
+## Single-scope-axis naming convention
+
+> **Read once at the top of this file; the rest of the skill is written against it.**
+
+The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, at `.peaks/_runtime/<sessionId>/...`) with a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` placeholders (NEVER bare `<sid>`). The peaks-loop change-id axis was removed in slice `2026-06-29-change-id-root-removal`; reviewable artifacts now live under `.peaks/_runtime/<sessionId>/<role>/...` only. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. CLI mapping: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Regression test `tests/unit/skills/skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) every `.peaks/_runtime/<X>/` has an axis label, (c) this callout is present.
+
+## peaks-context auto-build (v3.0)
+
+The peaks-reviewer workflow automatically runs `peaks context build --audience peaks-reviewer` before the LLM is invoked. No manual setup needed.
+
+# Peaks-Loop Third-Party Reviewer (v2.14.0 G4)
+
+`peaks-reviewer` is a **parallel** reviewer to `karpathy-reviewer`. It is intentionally **not** a replacement: karpathy-reviewer keeps enforcing the 4 guidelines; peaks-reviewer adds an out-of-band perspective from a different model family to mitigate single-LLM self-dogfood blind spots.
+
+## Why a separate reviewer (R6 from the PRD)
+
+In v2.13.x, two real cases slipped through 49/49 unit-test-pass + tsc-clean + single-LLM dogfood:
+- v2.13.1: aggregateVerdict cross-source dedup BLOCKER
+- v2.13.2: parseSecurity/Perf v2.12.0 markdown envelope parse failure
+
+`peaks-reviewer` does NOT promise to eliminate such cases (A4.5 prohibits the claim). It is a structural mitigation that adds a second opinion with a guaranteed-distinct model family.
+
+## Hard contract — modelFamily distinctness (BLOCKING)
+
+The peaks-reviewer modelFamily MUST differ from the karpathy-reviewer modelFamily. Configuration enforces this:
+- `~/.peaks/config.json` `reviewer.providers[]` lists at least 2 distinct providers
+- `reviewer.requireDistinctModelFamily: true` (default)
+- The CLI/agent stamps `modelFamily` from the actual `modelId` we called — the LLM cannot self-report a different family
+
+If the distinctness check fails, the CI gate fails. See `references/reviewer-schema.md` for the envelope shape and `references/reviewer-prompt.md` for the prompt the provider receives.
+
+## CLI surface
+
+```
+peaks reviewer run --rid <rid> [--json]
+peaks reviewer status [--json]
+```
+
+`run` produces `rd/third-party-review.json` (and a human-readable `rd/third-party-review.md`) under `.peaks/_runtime/<sessionId>/`. `status` shows whether the reviewer is configured and which selection mode is active.
+
+## Configuration (`~/.peaks/config.json`)
+
+```jsonc
+{
+  "reviewer": {
+    "providers": [
+      { "name": "ollama",    "model": "llama3.2:8b", "endpoint": "http://localhost:11434" },
+      { "name": "anthropic", "model": "claude-haiku-4-5" },
+      { "name": "openai",    "model": "gpt-4o-mini" }
+    ],
+    "selection": "round-robin",
+    "rdProviderName": null,
+    "requireDistinctModelFamily": true,
+    "fallbackOnError": "skip",
+    "schemaPath": "schemas/reviewer-envelope.schema.json"
+  }
+}
+```
+
+Missing section: reviewer is skipped (transition still passes; envelope records `skipped: no-reviewer-config`). Per A4.1, the CLI flag `--reviewer-model` is REMOVED — users edit the config file.
+
+## Hard prohibitions
+
+- DO NOT modify karpathy-reviewer (NG4). peaks-reviewer is a parallel addition.
+- DO NOT introduce new heavy dependencies (no langchain / openai-sdk). Use `fetch` + manual schema validation.
+- DO NOT silently prompt users for API keys. Missing env vars surface as `providerUnavailable` and the `fallbackOnError` policy decides skip vs throw.
+- DO NOT change the schema for the 5 existing envelope parsers (v2.13.3 territory). The ReviewerEnvelope schema is additive.
+
+## Sub-agent dispatch (when launched by peaks-code swarm)
+
+When this skill runs as a sub-agent dispatched by peaks-code, the sub-agent receives the parent session id and change-id via envelope. It MUST write its output to `.peaks/_runtime/<sessionId>/rd/third-party-review.json` + `.md` and return a compact JSON envelope.

package/skills/bee/peaks-sc/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: peaks-sc
+description: |
+  Source control, sync, and change-control role for Peaks-Loop (LLM-only internal role;
+  not user-invocable. Triggered by peaks-code via `peaks sub-agent dispatch --role sc`.)
+  Use when a workflow needs change impact, artifact retention, commit boundaries,
+  GitHub artifact repository pointers, sync state, or rollback evidence.
+visibility: internal
+---
+---
+
+# Peaks-Loop SC
+
+Peaks-Loop SC records how product, RD, QA, code, and artifacts move together.
+
+## Slice planning first step
+
+The first step in slice planning (before commit-boundary derivation below) is to invoke `peaks-slice-decompose` to produce a v2 topology. The decomposition envelope is the input to every later SC step (impact, retention, boundary). See [peaks-slice-decompose/SKILL.md](../peaks-slice-decompose/SKILL.md).
+
+## Scope directory (slice 10 — read scopeDir from envelope)
+
+The canonical scope dir for this request is provided as `envelope.data.scopeDir` (absolute path). Write all change-id-scoped files under that path. **NEVER** construct paths like `.peaks/_runtime/<sessionId>/...` from frontmatter — the path has already been resolved by the CLI.
+
+## Skill presence (MANDATORY first action)
+
+Before any analysis or tool call, immediately run:
+
+```bash
+peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate startup
+```
+
+On the first presence:set in a project, ensure the out-of-band status bar is installed so the user can see at a glance that Peaks is orchestrating — it renders the active skill in Claude Code's terminal status line, independent of model output:
+
+```bash
+peaks statusline install --project <repo>   # idempotent; skips if already installed
+```
+
+Read persistent project memory via CLI (durable, LLM-authored memories):
+
+```bash
+peaks project memories --project <repo> --json
+```
+
+This returns durable memories from `.peaks/memory` — decisions, conventions, modules, and rules captured in past sessions. Filter with `--kind <decision|convention|module|rule|reference|project>`. (`.peaks/PROJECT.md` is a human-readable session timeline only.)
+Then display: `Peaks-Loop Skill: peaks-sc | Peaks-Loop Gate: startup | Next: <one short action>`. Update with `peaks skill presence:set peaks-sc --project <repo> --mode <mode> --gate <gate>` when gates change. When the role's work ends, run `peaks skill presence:clear --project <repo>`.
+
+## Responsibilities
+
+- produce change-impact artifacts;
+- record commit boundaries;
+- ensure intermediate artifacts are retained locally first;
+- track artifact repository pointers when external sync or git retention is explicitly authorized;
+- record sync state and rollback points.
+
+## Mandatory per-request artifact
+
+Every SC invocation must write a change-control record at `.peaks/_runtime/<sessionId>/sc/change-control/<rid>.md` linking:
+
+- impact evidence (`peaks sc impact` output);
+- retention evidence (`peaks sc retention` output);
+- validation result (`peaks sc validate` output);
+- boundary record (`peaks sc boundary` output).
+
+Code reads this record before declaring the workflow complete.
+
+## Refactor role
+
+Each refactor slice must leave a traceable local artifact boundary in `.peaks/_runtime/<session-id>/` by default. A git commit boundary containing code changes and PRD/RD/QA/TXT intermediate artifacts is required only when the user or active profile explicitly authorizes committing artifacts.
+
+## GStack integration
+
+Use gstack as a concrete source-control and release workflow reference for the `Ship → Reflect` stages:
+
+- map `/ship` and `/land-and-deploy` concepts to Peaks-Loop commit boundaries, sync state, rollback points, and artifact retention;
+- map checkpoint discipline to traceable code-plus-artifact slices;
+- do not create PRs, merge, deploy, or mutate shared state unless the active Peaks-Loop workflow and user confirmation explicitly allow it.
+
+## Project memory backup
+
+Project `.peaks/memory` is the primary source for durable project memory. At approved checkpoints, use `peaks memory sync --project <path> --workspace <artifact-workspace> --apply` to back up the full project memory directory into the artifact repository workspace; do not treat the artifact backup as a second writable memory source.
+
+## Commit boundary derivation
+
+**Primary path — OpenSpec available:** When `openspec/changes/<id>/tasks.md` exists, derive commit boundaries from it:
+
+- `peaks openspec to-rd <id> --project <repo> --json` returns `commitBoundaries[]`, one entry per tasks.md heading.
+- Default to one commit per heading. Each commit message references the change-id and the section heading.
+- If implementation produces diffs outside any todo, surface that as out-of-scope before closing SC.
+
+**Fallback — OpenSpec missing:** When `openspec/` does not exist or `peaks openspec to-rd` fails:
+
+- derive commit boundaries from the RD request artifact's slice spec and the current `git diff --stat`;
+- group changed files by module or feature area, one commit per group;
+- record in the change-control artifact that boundaries were derived from git diff, not OpenSpec, so downstream reviewers know the source.
+
+Concrete rules: `references/openspec-commit-boundaries.md`.
+
+## Default runbook
+
+Use this sequence when SC owns the change-control pass for a refactor or release slice. SC never edits code or tests; it only records boundary evidence through the Peaks-Loop CLI.
+
+```bash
+# 0. Confirm SC's own runbook integrity before recording boundary evidence
+# in:  none
+# out: runbook version, presence set
+peaks skill runbook peaks-sc --json
+peaks skill presence:set peaks-sc --project <repo>  # show persistent skill presence every turn
+
+# 1. Derive commit boundaries (OpenSpec preferred, git diff fallback)
+# in:  change-id, repo path
+# out: commitBoundaries[] or fallback git diff grouping
+peaks openspec to-rd <change-id> --project <repo> --json
+
+# 2. Inventory artifacts already produced by other roles for this session
+# in:  repo path, session-id
+# out: artifact list with paths and statuses
+peaks artifacts status --project <repo> --json
+peaks artifacts workspace --workspace <session-id> --json
+
+# 3. Record change impact for the slice
+# in:  change-id, module, file path
+# out: impact record (JSON)
+peaks sc impact --change-id <change-id> --module <module> --file <path> --json
+
+# 4. Record retention evidence linking PRD / RD / QA artifacts
+# in:  slice-id, artifact paths from other roles
+# out: retention record (JSON)
+peaks sc retention --slice-id <slice-id> --prd <prd-path> --rd <rd-path> --qa <qa-path> --json
+
+# 5. Validate retention completeness
+# in:  slice-id
+# out: validation result (pass/fail + missing items)
+peaks sc validate --slice-id <slice-id> --json
+
+# 6. Record the commit boundary for the slice
+# in:  slice-id, artifact path, code file path
+# out: boundary record (JSON)
+peaks sc boundary --slice-id <slice-id> --artifact <artifact-path> --code <code-file> --json
+
+# 7. Sync memory and artifacts (requires explicit authorization)
+# in:  repo path, workspace
+# out: sync result or dry-run preview
+peaks memory sync --project <repo> --workspace <workspace> --apply --json
+peaks artifacts sync --workspace <workspace> --apply --json
+peaks skill presence:clear --project <repo>                      # SC complete, remove presence indicator
+```
+
+The final two `--apply` calls require explicit authorization. Without it, default to `--dry-run` or omit the sync calls entirely and keep the boundary evidence local under `.peaks/_runtime/<session-id>/`.
+
+### Transition verification gates (MANDATORY — run the command, see the output)
+
+You cannot declare SC complete from memory. Each gate below is a `ls` command you **MUST run** and whose output you **MUST see** before proceeding.
+
+**Peaks-Loop Gate A — After impact + retention + validate + boundary:**
+```bash
+ls .peaks/_runtime/<sessionId>/sc/change-control/<rid>.md
+# Expected output: .peaks/_runtime/<sessionId>/sc/change-control/<rid>.md
+# "No such file" → STOP, write the change-control record first.
+```
+
+**Peaks-Loop Gate B — Before declaring SC complete (verify commit boundary is recorded):**
+```bash
+git log --oneline -5
+# Expected: at least one recent commit whose message references the change-id or slice-id.
+# No matching commit → STOP, the boundary was not recorded. Re-run steps 3-6.
+```
+
+## Boundaries
+
+Do not implement code or test logic. Do not create GitHub repositories directly from the skill body. Use the Peaks-Loop CLI artifact commands.
+
+Reference: `references/artifact-retention.md`.