peaks-cli 1.0.15 → 1.0.17

package/skills/peaks-sc/SKILL.md

@@ -25,6 +25,17 @@ Then display: `Peaks Skill: peaks-sc | Gate: startup | Next: <one short action>`
 - 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/<id>/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).
+
+Solo reads this record before declaring the workflow complete.
+
 ## Refactor role
 
 Each refactor slice must leave a traceable local artifact boundary in `.peaks/<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.
@@ -41,14 +52,20 @@ Use gstack as a concrete source-control and release workflow reference for the `
 
 Project `.claude/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.
 
-## OpenSpec-derived commit boundaries
+## Commit boundary derivation
 
-When `openspec/changes/<id>/tasks.md` exists, derive commit boundaries from it through the Peaks CLI instead of redesigning them:
+**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
@@ -57,29 +74,45 @@ Use this sequence when SC owns the change-control pass for a refactor or release
 
 ```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               # show persistent skill presence every turn
 
-# 1. Derive commit boundaries from OpenSpec when openspec/ exists
+# 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 / coverage / review artifacts
+# 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 only when the user or active profile authorizes durable writes
+# 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                      # SC complete, remove presence indicator
@@ -87,6 +120,24 @@ peaks skill presence:clear                      # SC complete, remove presence i
 
 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/<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.
+
+**Gate A — After impact + retention + validate + boundary:**
+```bash
+ls .peaks/<id>/sc/change-control/<rid>.md
+# Expected output: .peaks/<id>/sc/change-control/<rid>.md
+# "No such file" → STOP, write the change-control record first.
+```
+
+**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 CLI artifact commands.