peaks-loop 4.0.54 → 4.1.1

package/scripts/sync-version.mjs

@@ -9,13 +9,27 @@ if (typeof version !== 'string' || version.length === 0) {
   throw new Error('package.json version must be a non-empty string');
 }
 
+// Emitted SINGLE-quoted, not via `JSON.stringify`. `JSON.stringify` quotes with
+// `"`, and the repo's own prettier config (`package.json#prettier`,
+// `singleQuote: true`) is what the husky gate runs over this tracked file — so a
+// double-quoted emit made `prettier --check` fail on version.ts after every run.
+// This script runs in `build` / `prepack` / `prepublish` / `pretest`, so every
+// build dirtied a tracked file against a `prettierUnformatted` ceiling of 0
+// (reproduced + fixed in slice S5a, 2026-09-19). A version that cannot be
+// written as a single-quoted TS literal throws instead of being escaped: the
+// alternative is silently emitting broken source, which is the same failure the
+// RUNTIME_VERSION writer below refuses with a throw.
+if (/['\\\r\n]/.test(version)) {
+  throw new Error(`package.json version cannot be emitted as a single-quoted literal: ${version}`);
+}
+
 // Slice 3a — version.ts lives in the peaks-loop-shared workspace package.
 // The shared package is `private: true` and is consumed via workspace:*,
 // so its own package.json `version` field is irrelevant for downstream
 // consumers; we always emit the main peaks-loop version.
 writeFileSync(
   resolve('packages/peaks-loop-shared/src/version.ts'),
-  `export const CLI_VERSION = ${JSON.stringify(version)};\n`,
+  `export const CLI_VERSION = '${version}';\n`
 );
 
 // Slice 2026-09-11 (runtime-version-lockstep) — sync RUNTIME_VERSION.
@@ -23,17 +37,21 @@ writeFileSync(
 // `RUNTIME_VERSION` under a comment stating it tracks the peaks-loop root
 // version, but nothing wrote it: v4.0.37 was tagged with the constant still
 // at 4.0.36 and publish.yml's gate-cli-version step aborted before npm
-// publish. The literal is replaced in place, single-quoted — the exact
-// shape the gate greps — because the file also holds the package's public
-// exports and must never be regenerated wholesale. A literal we cannot
+// publish. The literal is replaced in place, preserving whichever quote the
+// declaration currently uses — the file also holds the package's public
+// exports and must never be regenerated wholesale, and since the gate reads
+// the VALUE (rid 2026-10-03-release-gate-quote-brittle) the writer must not
+// re-assert one quote style either. A literal we cannot
 // find throws instead of no-op'ing: that silence is how the drift reached CI.
 const runtimeIndexPath = resolve('packages/peaks-loop-internal-runtime/src/index.ts');
 const runtimeIndex = readFileSync(runtimeIndexPath, 'utf8');
-const runtimeDecl = /(export const RUNTIME_VERSION = ')[^']*(';)/;
+const runtimeDecl = /(export const RUNTIME_VERSION = (['"]))[^'"]*\2(;)/;
 if (!runtimeDecl.test(runtimeIndex)) {
-  throw new Error(`${runtimeIndexPath}: could not find "export const RUNTIME_VERSION = '...';"`);
+  throw new Error(
+    `${runtimeIndexPath}: could not find export const RUNTIME_VERSION = '<version>'; (single- or double-quoted)`
+  );
 }
-const syncedRuntimeIndex = runtimeIndex.replace(runtimeDecl, `$1${version}$2`);
+const syncedRuntimeIndex = runtimeIndex.replace(runtimeDecl, `$1${version}$2$3`);
 if (syncedRuntimeIndex !== runtimeIndex) {
   writeFileSync(runtimeIndexPath, syncedRuntimeIndex);
 }
@@ -102,4 +120,3 @@ for (const ext of ['js', 'd.ts', 'd.ts.map']) {
 // that a stale packages/peaks-loop-shared/dist/version.js is
 // actually removed. If you need the unlink pinned, that test has
 // to be written — the one named here no longer exists.
-

package/scripts/watch.mjs

@@ -72,7 +72,10 @@ export function runCommand(command, args, options = {}) {
         return;
       }
 
-      settle(rejectPromise, new Error(`${command} ${args.join(' ')} failed with exit code ${code}`));
+      settle(
+        rejectPromise,
+        new Error(`${command} ${args.join(' ')} failed with exit code ${code}`)
+      );
     });
   });
 }
@@ -383,7 +386,10 @@ async function main() {
   await watchMode.start();
 }
 
-if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+if (
+  process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(resolve(process.argv[1])).href
+) {
   main().catch((error) => {
     process.stderr.write(`[peaks watch] ${getErrorMessage(error)}\n`);
     process.exitCode = 1;

package/skills/bee/peaks-qa/references/reading-handoff-frontmatter.md

@@ -4,10 +4,12 @@ QA reads the RD handoff's YAML frontmatter **before** reading the body prose. Th
 
 ## Required frontmatter fields (mirror RD writer)
 
-`requestId`, `scope`, `files`, `decisions[]`, `risks[]`, `nextActions[]`, `gateEvidence`, `schemaVersion: '1.0'`. Field schema: `../../peaks-rd/references/writing-handoff-frontmatter.md`.
+`requestId`, `scope`, `files`, `decisions[]`, `risks[]`, `nextActions[]`, `gateEvidence`, `schemaVersion: 2` (written plain; `'2.0'` is not a valid value). Field schema: `../../peaks-rd/references/writing-handoff-frontmatter.md`.
 
 ## Mechanical cross-checks (run before body read)
 
+Checks 1–3 and 5 are conditional on the capsule DECLARING the field: `scope`, `files`, `decisions[]`, `risks[]` and `nextActions[]` are authored by the writer, not derived, and the serializer writes no line for a field nobody filled in. An absent field is therefore NOT a pass — it means the writer made no claim to check, which is recorded as `not declared` rather than green. Only check 4 has a machine producer (`peaks prd handoff init` derives it from the request type).
+
 1. **Decisions ↔ tests** — every `decisions[].id` (e.g. `D1`) implies a test under `tests/unit/`. Grep `tests/unit/` for the decision id (or its summary keywords). Missing test → Gate B2 partial.
 2. **Risks ↔ security tests** — every `risks[].id` with `description` mentioning auth / input / boundary / path / external / crypto / payment MUST have a matching case under `tests/unit/security/`. Missing → Gate A3 partial.
 3. **Files ↔ diff** — `files[]` must equal `git diff --name-only` against the parent commit. Any file in the diff not in `files[]` (or vice versa) → Gate B8 fail (out-of-scope or missing scope).

package/skills/bee/peaks-rd/references/parallel-review-fanout.md

@@ -50,7 +50,7 @@ Note: sub-agent 1 (code-reviewer) and sub-agent 3 (karpathy-reviewer) write to `
 - Required for Gate B3.
 - **v2.11.0 Tier 7 (Group D) + 2026-09-09-ecc-dynamic:** the code-reviewer dispatch goes through the **ECC bridge** (`src/services/code-review/ecc-bridge.ts`). Fallback order is **native plugin → cache-backed generic agent → inline**:
   1. **Native plugin** (`detectEcc` state `ready`): invoke the Agent tool with `subagent_type: "ecc:code-reviewer"` (plugin `ecc` + agent `code-reviewer`; see `DEFAULT_NATIVE_ECC_AGENT_ID`); it returns the structured envelope `{ passed, violations[], gateAction }`.
-  2. **Cache-backed generic agent** (`detectEcc` state `ready-via-cache` — plugin or its review agent absent, but a materialized ECC agent exists under `~/.peaks/agents/ecc/`): resolve the agent's REAL name first — `resolveMaterializedAgentName(['code-reviewer', 'code-review'])` from `peaks-loop-mut` (upstream ships `code-reviewer.md`; a hardcoded `code-review.md` never resolves). Read `~/.peaks/agents/ecc/<resolved>.md`, pass the name through as `detectEcc({ ..., cacheAgentName: resolved })`, build the prompt with `buildCacheBackedEccPrompt({ rid, instructions, diff })` (agent body + diff + `ECC_OUTPUT_CONTRACT`), dispatch a **generic** sub-agent, and validate its reply with `isEccEnvelope`. No ECC plugin required. If the cache is empty, run `peaks ecc install` first (dynamic acquisition); if that fails offline, degrade to inline.
+  2. **Cache-backed generic agent** (`detectEcc` state `ready-via-cache` — plugin or its review agent absent, but a materialized ECC agent exists under `~/.peaks/agents/ecc/`): resolve the agent's REAL name first — `resolveMaterializedAgentName(['code-reviewer', 'code-review'])` from `peaks-loop-mut` (upstream ships `code-reviewer.md`; a hardcoded `code-review.md` never resolves). Read `~/.peaks/agents/ecc/<resolved>.md`, pass the name through as `detectEcc({ ..., cacheAgentName: resolved })`, build the prompt with `buildCacheBackedEccPrompt({ rid, instructions, diff })` (agent body + diff + `ECC_OUTPUT_CONTRACT`), dispatch a **generic** sub-agent, and validate its reply with `isEccEnvelope`. No ECC plugin required. If no agent is materialized, run `peaks ecc install` first — it copies the agents out of the bundled `ecc-universal` dependency (local, no network); if that refuses with `ECC_PACKAGE_MISSING`, the dependency tree is broken and the only remedy is reinstalling peaks-loop, so degrade to inline review rather than retrying.
   3. **Inline** (`detectEcc` states `plugin-missing` / `agent-missing` / `dispatch-failed` / `envelope-malformed`): fall back to inline review — TXT note `code-review-ecc-degraded-to-inline`.
 
   In all dispatchable cases the envelope is rendered by the SAME bridge adapter (`adaptEccEnvelopeToRdCodeReview`) into the canonical `rd/code-review-<rid>.md` markdown shape that Gate B3 reads (`mustContain: ['## Findings', 'CRITICAL']`). The materialized copy lives under `~/.peaks/agents/ecc/` — peaks-loop NEVER writes into `~/.claude/`.

package/skills/bee/peaks-rd/references/rd-fanout-contracts.md

@@ -45,8 +45,9 @@ end of implementation, RD fires 3 sub-agents in parallel via
     `detectEcc({ ..., cacheAgentName: resolved })`, compose the prompt with
     `buildCacheBackedEccPrompt({ rid, instructions, diff })`,
     dispatch a **generic** sub-agent, and validate the reply with `isEccEnvelope`.
-    If the cache is empty, run `peaks ecc install` first (dynamic acquisition);
-    offline → inline.
+    If nothing is materialized, run `peaks ecc install` first — it copies the
+    agents from the bundled `ecc-universal` dependency (local, no network);
+    `ECC_PACKAGE_MISSING` → reinstall peaks-loop, and degrade to inline.
   - Any other state (plugin-missing / agent-missing / dispatch-failed /
     envelope-malformed) → inline review; the `code-review-ecc-degraded-to-inline`
     TXT note records the fallback.

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

@@ -13,6 +13,18 @@ Every RD handoff artifact carries a **YAML frontmatter block** so peaks-qa (and
 ```yaml
 ---
 requestId: 2026-06-25-slice-topology-multipass
+sessionId: 2026-06-25-session-ee2aba
+schemaVersion: 2
+sha256: <64 lowercase hex of the body>
+handoffHash: <the same 64 hex, no prefix>
+writtenAt: 2026-06-25T03:05:30.000Z
+goals:
+  - G1
+  - G2
+acceptanceCriteria:
+  - AC-1
+preservedBehavior:
+  - P1
 scope:
   - src/services/slice/schema-router.ts
   - src/services/audit/audit-goal-service.ts
@@ -20,7 +32,6 @@ files:
   - src/services/slice/schema-router.ts
   - src/services/audit/audit-goal-service.ts
 handoffPath: .peaks/_runtime/<sessionId>/prd/handoff-<rid>.md
-handoffHash: sha256:<64 hex chars>
 decisions:
   - id: D1
     summary: "Route v1/v2 envelopes via SchemaRouter instead of branching in prompts"
@@ -38,7 +49,6 @@ gateEvidence:
   codeReview: .peaks/_runtime/<sessionId>/rd/code-review-<rid>.md
   securityReview: .peaks/_runtime/<sessionId>/audit/security-<rid>.md
   perfBaseline: .peaks/_runtime/<sessionId>/audit/perf-<rid>.md
-schemaVersion: '2.0'
 ---
 ```
 
@@ -46,7 +56,11 @@ schemaVersion: '2.0'
 ## Field rules
 
 - `requestId` — kebab-case; matches the PRD `requestId`.
-- `scope` / `files` — absolute repo-relative paths (`src/...`). Sorted alphabetically.
+- `sessionId` — the session the capsule belongs to. **Required by `readHandoff`.**
+- `writtenAt` — ISO 8601 at write time. **Required by `readHandoff`.**
+- `goals` / `acceptanceCriteria` / `preservedBehavior` — the PRD IDs this slice binds to (`['G1','G2']`, `['AC-1']`, `['P1']`). Arrays, empty allowed, and **required by `readHandoff`** — omitting the line is a shape failure, not a declaration of nothing.
+- `sha256` and `handoffHash` — the same 64 hex digits, twice, on purpose: `sha256` is the PLAIN field the gate and both independent audit loaders match at line start, `handoffHash` is the quoted field `readHandoff` reads. A capsule whose two values differ verifies as tampering.
+- `scope` / `files` — repo-relative paths (`src/...`), sorted. Authored by the writer; the serializer writes them only when present (`handoff-frontmatter.ts`), so an absent field is no line rather than an empty claim.
 - `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).
@@ -56,16 +70,24 @@ schemaVersion: '2.0'
   - `config` → **2 keys**: `projectScan`, `securityReview`. `CONFIG_TABLE['rd:qa-handoff']` is the security review alone, so a config slice has **no** `prdHandoff`; and its security evidence is the genuinely ridless `rd/security-review.md`, not `audit/security-<rid>.md`.
   - `docs` / `chore` → **no `gateEvidence` block at all**. Those types have no `rd:qa-handoff` row: there is no evidence to declare and nothing for Gate C to check, so the block is omitted rather than filled with an unverified statement. Such a capsule is byte-identical to a pre-B2 one.
   **The Gate C failure rule is scoped to the types above** — where that gate runs: a declared path that does not exist fails `peaks request transition --state qa-handoff` (`PREREQUISITES_MISSING`), naming the key. Two shapes are deliberately NOT failures: a capsule for a type with no `rd:qa-handoff` row (the check does not run), and an **empty** declaration (`gateEvidence: {}`) — a weak claim, not a false one, since the type's artifacts remain enforced by the table itself, so an empty map cannot open the gate. When the request type cannot be resolved at all, the block is omitted rather than half-declared.
-- `schemaVersion: '2.0'` — pinned (bumped from `'1.0'` in v2.11.0); bump only when the field set changes.
+- `schemaVersion: 2` — pinned, and written PLAIN (no quotes). The constant is `HANDOFF_SCHEMA_VERSION` in `src/services/prd/handoff-frontmatter-shape.ts` and its value is the string `'2'`; the serializer emits it unquoted, because `AUDIT_REQUIRES_HANDOFF` matches the substring `schemaVersion: 2` and a quoted `'2'` would not contain it. `readHandoff` accepts `'2'` or the bare number `2` and nothing else — **`'2.0'` is not a valid value here**, and this document said it was until it was measured against the serializer. Bump only when the field set changes.
 
-> **v2.11.0 Group A change:** `schemaVersion` was bumped to `'2.0'`. The consumers listed under §Validation anchor on that value, so a file still carrying `'1.0'` is rejected at read time.
+> **v2.11.0 Group A change:** `schemaVersion` moved to version 2 (the shape that added `sha256` and AC/goal IDs). The consumers listed under §Validation anchor on it, so a file carrying anything else is rejected at read time.
 
 ## Validation
 
-The frontmatter MUST parse as valid YAML. Two automated consumers read it, and both anchor on `schemaVersion` + `sha256`: the `AUDIT_REQUIRES_HANDOFF` prereq in `src/services/artifacts/artifact-prerequisites.ts` and the independent audit services under `src/services/audit-independent/`. The serializer that writes it is `src/services/prd/handoff-frontmatter.ts`. No unit test pins the field set — the "regression test" this section used to name never existed in this repository — so required-field and `gateEvidence` completeness are conventions the publisher must honour.
+The frontmatter MUST parse as valid YAML. Two automated consumers read it, and both anchor on `schemaVersion` + `sha256`: the `AUDIT_REQUIRES_HANDOFF` prereq in `src/services/artifacts/artifact-prerequisites.ts` and the independent audit services under `src/services/audit-independent/`. The serializer that writes it is `src/services/prd/handoff-frontmatter.ts`.
+
+What is pinned now, and what is not:
+
+- **Pinned** by `tests/unit/prd/handoff-frontmatter-doc-contract.test.ts`: the `gateEvidence` key set in the example above against `GATE_EVIDENCE_KEYS`, each request type's declared keys against `deriveGateEvidence`, and `schemaVersion` against what the serializer actually emits. If this document drifts from the code it describes, that test goes red.
+- **NOT pinned — a recorded divergence**: `scope`, `files`, `decisions[]`, `risks[]` and `nextActions[]` are listed as required fields by this file and by `peaks-qa`'s reader doc, and the serializer emits none of them (it never has). `readHandoff` additionally REQUIRES `sessionId`, `writtenAt`, `goals`, `acceptanceCriteria` and `preservedBehavior`, which neither document lists. So a capsule hand-authored from this example is rejected, and four of peaks-qa's five mechanical cross-checks read fields that are not on disk. The contract test pins the gap in both directions so it cannot be quietly re-forgotten; closing it is an open decision (give the frontmatter those fields, or re-base the checks on inputs that exist).
 
 ```bash
-# No command validates the frontmatter today; review the consumers above by hand.
+# `peaks prd handoff init` prints the derived gateEvidence map (dry-run and
+# applied), so the key set for a given slice is readable without opening the
+# serializer. It does not validate an arbitrary handoff; that is
+# `peaks prd handoff verify`.
 ```
 
 ## Body (prose, free-form)

package/skills/peaks-code/SKILL.md

@@ -207,7 +207,7 @@ Before the first planning action, run `peaks fresh-context preflight --prompt "<
 | `0.85 ≤ ratio < 0.95` | **pre-compact zone** | `peaks code auto-compact` fires **automatically** (deferred only when in-flight sub-agent batch is running; fires the moment the batch lands). The LLM does not prompt the user. In practice peaks-loop already fired at the 0.80 tier above, so this band is today the "already fired" zone; `peaks code context-now` reports `action: 'auto-compact-now'` from 0.85 up. |
 | `ratio ≥ 0.95` | **red-line (Karpathy §4)** | `peaks code auto-compact` invoked immediately; `peaks code context-now` returns `action: 'red-line'`. **Since 4.0.47 the red line REQUESTS the compaction and says it is waiting — it does NOT block sub-agent dispatch, and it does not refuse to advance.** Keep working and re-probe with `peaks code context-now`; the harness performs the compaction, and nothing peaks-loop can do lowers the ratio on its own, so blocking here was a deadlock rather than a gate. If the ratio keeps climbing and no compaction lands, report that and hand control back — do not stall. `--bypass-red-line` is a no-op. |
 
-**Probe primitive (single source of truth):** `peaks code context-now --json`. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks code auto-compact` on `auto-compact-now` or `red-line` without user confirmation.
+**Probe primitive:** `peaks code context-now --json` — authoritative for `ratio` and for the `action` tier **from 0.85 up**. Do NOT use `peaks context check --prompt-size` (deprecated, will silently under-report ratio). Returns `{ ratio, action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' }` — Code reads `action` and dispatches `peaks code auto-compact` on `auto-compact-now` or `red-line` without user confirmation. **It has no 0.80 tier** (see the tier table above): the `0.80 ≤ ratio < 0.85` band belongs to `peaks skill presence`'s `auto-fire`, and that probe runs every turn. **Read both probes and act on whichever fires first — the earlier of the two governs, so 0.80, not 0.85.**
 
 **Enforcement layers (defense in depth):**
 1. `src/services/code/auto-compact-orchestrator.ts` — `evaluateAutoCompactDecision` default-returns `shouldCompact: true` for both `pre-compact` and `red-line`. Only deferral is `inFlightBatch.hasInFlightBatch` (D6.e); no LLM/human approval branch.

package/skills/peaks-code/references/frontend-only-mode.md

@@ -4,7 +4,7 @@
 >
 > **2026-09-12 (`rd-routing-by-integration-mode`):** this file is now the routing home for all three integration modes, not just `prd-only`. `### Integration-mode routing (RD)` was added and the boolean-era text in `### Mode determination` was retargeted onto `.integrationMode`; the mock table and placeholder layout below belong to `prd-only`.
 
-`peaks scan archetype --json` classifies every project into exactly one of three integration modes (`.integrationMode`). Code and RD both branch on that value — the `frontendOnly` boolean is retained for back-compat only (the swarm plan still reads it) and is no longer a routing decision.
+`peaks scan archetype --json` classifies every project into exactly one of three integration modes (`.integrationMode`). Code and RD both branch on that value — the `frontendOnly` boolean is retained for back-compat only (the swarm plan still reads it) and is no longer a routing decision. Both answers, and the `archetype`, come out of ONE backend predicate (`hasBackendEvidence` in `src/services/scan/archetype-service.ts`); before it was one predicate the three decision functions each re-spelled the same check inline, and a signal added for one of them left the others reading a different project.
 
 ### Mode determination (deterministic — CLI is the source of truth)
 
@@ -12,7 +12,7 @@ Read `.integrationMode` and `.integrationModeReason` from the `peaks scan archet
 
 | `.integrationMode` | `.integrationModeReason` | What is physically present |
 |---|---|---|
-| `full-stack` | `backend-detected` | a backend framework, Next API routes, or a backend dir in this repo |
+| `full-stack` | `backend-detected` | a backend anywhere in this repo: a root framework, Next API routes **or server actions**, a backend dir, a workspace package's own manifest (`apps/gateway: express`), or a non-Node service (`go.mod`, `pom.xml`, `services/x/requirements.txt` naming a web framework) |
 | `prd-plus-interface-doc` | `interface-doc-present` | an OpenAPI / proto document, and no backend here |
 | `prd-only` | `no-backend-no-interface-doc` | neither |
 

package/skills/peaks-code/references/startup-sequence.md

@@ -49,10 +49,6 @@ Run `peaks workspace init` + `peaks skill presence:set peaks-code` BEFORE any an
 
 After Step 0, run the resume-detection probe; surface via `AskUserQuestion` if a slice is in flight. **v3.1.2 resume rule:** if `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` exists, read FIRST and surface `Next: slice #N of M`. **v2.11.0 D7 override:** if user just `/compact`ed, run `peaks code post-compact-detect --project <repo> --json` FIRST; `shouldAutoResume: true` skips AskUserQuestion. → `resume-detection.md`.
 
-### Peaks-Loop Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
-
-After Step 0.7 returns "fresh", run `peaks upgrade --detect-1x --project <root> --json`. If `isOneX: true`, surface `AskUserQuestion`. → `step-0-55-1x-detection.md`.
-
 ### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch + v3.1.2 mechanical gates)
 
 > **CLI reality check (D-001 sediment, 2026-07-09):** The CLI surface has changed since this section was last verified. The actual command is **`peaks job init --job-id <jid> --slice-list <list> --main-loop-strategy <single|rotating> [--parallelism-hint <serial|llm-decides>] [--exit-policy <strict|best-effort>] [--project <repo>]`**. The legacy `peaks code detect-job --is-job/--suggested-job-id/--confidence` form described below is **no longer present** in 4.0.0-beta.6. If you find `--is-job` rejected, fall back to `peaks job init`.

package/dist/cli/commands/upgrade-commands.d.ts

@@ -1,25 +0,0 @@
-/**
- * peaks upgrade * CLI surface — Slice: 1.x → 2.0 umbrella +
- * Slice 3: --detect-1x flag.
- * Fix-4: reject dangerous probe names passed positionally and expose
- * --gitignore-migrate as a read-only probe.
- *
- * Per the "one-key completion" + "minimal-user-operation" tenets
- * (2026-06-11), the user's typical upgrade path is
- * `npm i -g peaks-loop@2.0` (the postinstall does the upgrade).
- *
- * The `peaks upgrade --to 2.0` CLI is the manual fallback for
- * when the postinstall is skipped (e.g. CI uses
- * `--ignore-scripts`). The umbrella orchestrates 7 sub-commands:
- * config-migrate / standards-migrate / memory-extract /
- * hooks-install / skill-sync / audit-verify + write-upgrade-record.
- *
- * The `--detect-1x` flag (added in slice 3) is a read-only
- * probe that the peaks-code skill calls to gate the
- * AskUserQuestion that prompts the 1.x → 2.0 upgrade. The
- * probe returns the JSON envelope from the
- * 1x-detector-service; it does NOT modify any files.
- */
-import { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-export declare function registerUpgradeCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/upgrade-commands.js

@@ -1,154 +0,0 @@
-import { runUpgrade } from '../../services/upgrade/upgrade-service.js';
-import { detect1xProjectState } from '../../services/upgrade/1x-detector-service.js';
-import { migrateGitignoreFile } from '../../services/upgrade/gitignore-migrate-service.js';
-import { initWorkspace } from '../../services/workspace/workspace-service.js';
-import { ensureSessionWithRotation } from '../../services/session/session-manager.js';
-import { resolveCanonicalProjectRoot } from '../../services/config/config-service.js';
-import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
-import { fail, ok } from 'peaks-loop-shared/result';
-const REJECTED_POSITIONALS = {
-    '1x-detector': '--detect-1x',
-    'gitignore-migrate': '--gitignore-migrate'
-};
-function isRejectedPositional(value) {
-    return value === '1x-detector' || value === 'gitignore-migrate';
-}
-export function registerUpgradeCommands(program, io) {
-    addJsonOption(program
-        .command('upgrade', { hidden: true })
-        .description('Upgrade a peaks-loop 1.x project to 2.0. Umbrella that orquestrates 7 sub-commands: config-migrate / standards-migrate / memory-extract / hooks-install / skill-sync / audit-verify + write-upgrade-record. Per the "one-key completion" tenet, prefer letting `npm i -g peaks-loop@2.0` postinstall run this for you. Use `--detect-1x` for a read-only probe (no file writes) that the peaks-code skill uses to gate the 1.x → 2.0 AskUserQuestion.')
-        .option('--to <version>', 'target version (only "2.0" supported)', '2.0')
-        .option('--project <path>', 'project root to upgrade (default: cwd)')
-        .option('--auto', 'non-interactive: accept soft-fail on any sub-step (used by the postinstall hook)')
-        .option('--detect-1x', 'read-only probe: returns the 1.x state as JSON (no file writes); consumed by peaks-code Step 0.55 to gate the AskUserQuestion')
-        .option('--gitignore-migrate', 'read-only probe: reports whether .gitignore needs the 1.x to 2.0 migration (no file writes)')
-        .option('--apply-init', 'slice 4 (slice 2026-06-13-selfheal-claude-settings-template): run initWorkspace so the drift-driven self-heal fires on the consumer-project .claude/settings.local.json and the offline .peaks/.claude-settings-template.json. Idempotent. Use after a peaks-loop version bump if you do not otherwise re-run init. Mutually exclusive with --detect-1x.')).action(async (options, command) => {
-        const projectRoot = options.project ?? process.cwd();
-        const positional = command.args[0];
-        if (isRejectedPositional(positional)) {
-            const replacementFlag = REJECTED_POSITIONALS[positional];
-            const message = `Positional \`${positional}\` is not supported because it could trigger the destructive upgrade umbrella. The documented read-only probe is \`${replacementFlag}\`.`;
-            printResult(io, fail('upgrade', 'UPGRADE_POSITIONAL_REJECTED', message, {}, [
-                `The LLM can coordinate the documented ${replacementFlag} read-only probe instead.`
-            ]), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        // Branch 1: --detect-1x (read-only probe)
-        if (options.detect1x === true) {
-            try {
-                const state = detect1xProjectState(projectRoot);
-                const nextActions = [];
-                if (state.isOneX) {
-                    nextActions.push(`Detected 1.x state. peaks-code Step 0.55 should present an AskUserQuestion to invoke \`peaks upgrade --to 2.0 --auto --project ${state.projectRoot ?? projectRoot}\`.`);
-                }
-                else {
-                    nextActions.push('No 1.x state detected. Proceed with the standing 2.0 layout.');
-                }
-                const envelope = ok('upgrade.detect-1x', state, [], nextActions);
-                printResult(io, envelope, options.json);
-            }
-            catch (error) {
-                const message = getErrorMessage(error);
-                printResult(io, fail('upgrade.detect-1x', 'DETECT_1X_FAILED', message, { isOneX: false, signals: [], projectRoot: null, configPath: null }, [message]), options.json);
-                process.exitCode = 1;
-            }
-            return;
-        }
-        // Branch 2: --gitignore-migrate (read-only probe)
-        if (options.gitignoreMigrate === true) {
-            try {
-                const result = migrateGitignoreFile({ projectRoot, apply: false });
-                const envelope = ok('upgrade.gitignore-migrate', result, [], result.changed
-                    ? ['The upgrade umbrella can coordinate the required .gitignore migration.']
-                    : ['No .gitignore migration is required.']);
-                printResult(io, envelope, options.json);
-            }
-            catch (error) {
-                const message = getErrorMessage(error);
-                printResult(io, fail('upgrade.gitignore-migrate', 'GITIGNORE_MIGRATE_FAILED', message, { appliedWrite: false }, [message]), options.json);
-                process.exitCode = 1;
-            }
-            return;
-        }
-        // Branch 3: --apply-init (slice 4 — slice 2026-06-13-selfheal-claude-settings-template).
-        //
-        // The drift-driven self-heal inside initWorkspace only fires when
-        // the user invokes init. After a peaks-loop version bump, users who
-        // never re-run init are stuck with stale templates until they do.
-        // This flag is the post-bump escape hatch: it triggers init for them.
-        //
-        // We do NOT pass --session-id (the CLI auto-generates / reuses an
-        // existing binding). We do NOT pass --no-claude-hooks (the goal is to
-        // bring the project to the current peaks-loop baseline, including the
-        // consumer-project hook).
-        if (options.applyInit === true) {
-            try {
-                const canonicalRoot = resolveCanonicalProjectRoot(projectRoot);
-                // Match the workspace-init CLI's pattern: resolve the session id
-                // (auto-generate / reuse binding / rotate on outer-mismatch)
-                // BEFORE calling initWorkspace. initWorkspace itself validates
-                // the session id and does NOT auto-generate, so we have to do
-                // the rotation-aware resolution here.
-                const sessionResolution = await ensureSessionWithRotation(canonicalRoot, {
-                    skipRotateOnOuterMismatch: false
-                });
-                const result = await initWorkspace({
-                    projectRoot: canonicalRoot,
-                    sessionId: sessionResolution.sessionId,
-                    allowSessionRebind: false
-                });
-                const nextActions = [];
-                // Surface the same self-heal messaging that workspace-init uses.
-                if (result.claudeSettings.offlineTemplate.action === 'refreshed') {
-                    nextActions.push(`Self-healed .peaks/.claude-settings-template.json (action: refreshed) — ` +
-                        'the offline recovery anchor now matches the current peaks-loop template.');
-                    nextActions.push('⚠️  If you had manually edited .peaks/.claude-settings-template.json, ' +
-                        'those edits have been overwritten by the self-heal.');
-                }
-                else if (result.claudeSettings.offlineTemplate.action === 'written') {
-                    nextActions.push('Wrote .peaks/.claude-settings-template.json (action: written) — ' +
-                        'the offline recovery anchor is now in place.');
-                }
-                if (result.claudeSettings.action === 'refreshed') {
-                    nextActions.push(`Refreshed .claude/settings.local.json (action: refreshed) — ` +
-                        'the consumer-project hook now matches the current peaks-loop template. ' +
-                        'Restart Claude Code so the hooks take effect.');
-                }
-                else if (result.claudeSettings.action === 'written') {
-                    nextActions.push('Wrote .claude/settings.local.json (action: written) — ' +
-                        'the [Fact-Forcing Gate] bypass is now in effect. Restart Claude Code so the hooks take effect.');
-                }
-                const envelope = ok('upgrade.apply-init', result, [], nextActions);
-                printResult(io, envelope, options.json);
-            }
-            catch (error) {
-                const message = getErrorMessage(error);
-                printResult(io, fail('upgrade.apply-init', 'APPLY_INIT_FAILED', message, { applied: false }, [message]), options.json);
-                process.exitCode = 1;
-            }
-            return;
-        }
-        // Branch 4: the umbrella (existing behavior)
-        try {
-            const result = runUpgrade({ projectRoot, auto: options.auto === true });
-            const nextActions = [...result.nextActions];
-            if (result.failedCount > 0) {
-                nextActions.unshift(`${result.failedCount} sub-step(s) failed. Re-run \`peaks upgrade --to 2.0\` to retry.`);
-            }
-            if (result.upgradeRecordPath !== null) {
-                nextActions.push(`Upgrade record written: ${result.upgradeRecordPath}`);
-            }
-            const envelope = ok('upgrade', result, [...result.warnings], nextActions);
-            printResult(io, envelope, options.json);
-            if (result.failedCount > 0) {
-                process.exitCode = 1;
-            }
-        }
-        catch (error) {
-            const message = getErrorMessage(error);
-            printResult(io, fail('upgrade', 'UPGRADE_FAILED', message, { applied: false }, [message]), options.json);
-            process.exitCode = 1;
-        }
-    });
-}

package/dist/services/upgrade/1x-detector-service.d.ts

@@ -1,7 +0,0 @@
-export interface OneXState {
-    readonly isOneX: boolean;
-    readonly signals: readonly string[];
-    readonly projectRoot: string | null;
-    readonly configPath: string | null;
-}
-export declare function detect1xProjectState(cwd?: string): OneXState;

package/dist/services/upgrade/1x-detector-service.js

@@ -1,94 +0,0 @@
-/**
- * 1.x → 2.0 detection service — TypeScript mirror of
- * `scripts/install-skills.mjs:detect1xProjectState`.
- *
- * Slice: 2026-06-12-code-step-0-55-1x-detection.
- *
- * The canonical implementation lives in the .mjs postinstall
- * (because the postinstall runs before any TS compile step).
- * This TS mirror exists so the peaks-code skill can call
- * `peaks upgrade --detect-1x --project <root> --json` and
- * read a structured JSON envelope to gate the
- * AskUserQuestion that prompts the 1.x → 2.0 upgrade.
- *
- * The two implementations MUST stay in parity. The
- * `tests/integration/upgrade/1x-detector-parity.test.ts`
- * test exercises both on the same fixture and asserts
- * their outputs match.
- */
-import { existsSync, readFileSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-const MAX_WALK_UP = 8;
-export function detect1xProjectState(cwd = process.cwd()) {
-    const home = homedir();
-    const signals = [];
-    let projectRoot = null;
-    let configPath = null;
-    // Walk up from cwd looking for .peaks/_runtime (signals
-    // we're inside a peaks project).
-    let dir = cwd;
-    for (let i = 0; i < MAX_WALK_UP; i += 1) {
-        const peaksRuntime = join(dir, '.peaks', '_runtime');
-        if (existsSync(peaksRuntime)) {
-            projectRoot = dir;
-            break;
-        }
-        const parent = dirname(dir);
-        if (parent === dir)
-            break;
-        dir = parent;
-    }
-    // Signal 1: ~/.peaks/config.json with 1.x version
-    const globalConfig = join(home, '.peaks', 'config.json');
-    if (existsSync(globalConfig)) {
-        try {
-            const raw = JSON.parse(readFileSync(globalConfig, 'utf8'));
-            if (typeof raw['version'] === 'string' && /^1\./.test(raw['version'])) {
-                signals.push(`global config at ${globalConfig} is 1.x (${raw['version']})`);
-                if (configPath === null)
-                    configPath = globalConfig;
-            }
-        }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-            // ignore parse error — the 1.x detection is best-effort
-        }
-    }
-    // Signal 2: .claude/rules/common/dev-preference.md with peaks progress
-    if (projectRoot !== null) {
-        const devPref = join(projectRoot, '.claude', 'rules', 'common', 'dev-preference.md');
-        if (existsSync(devPref)) {
-            try {
-                const body = readFileSync(devPref, 'utf8');
-                if (/peaks progress/i.test(body)) {
-                    signals.push(`${devPref} references "peaks progress" (1.x CLI surface, removed in slice #014)`);
-                }
-            }
-            catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-                // ignore
-            }
-        }
-        // Signal 3: project preferences.json missing or 1.x
-        const prefs = join(projectRoot, '.peaks', 'preferences.json');
-        if (!existsSync(prefs)) {
-            signals.push(`${prefs} does not exist (1.x project never migrated)`);
-        }
-        else {
-            try {
-                const raw = JSON.parse(readFileSync(prefs, 'utf8'));
-                if (raw['schema_version'] !== '2.0.0') {
-                    signals.push(`${prefs} has schema_version ${JSON.stringify(raw['schema_version'])}, expected '2.0.0'`);
-                }
-            }
-            catch {
-                signals.push(`${prefs} exists but is not valid JSON`);
-            }
-        }
-    }
-    return {
-        isOneX: signals.length > 0,
-        signals,
-        projectRoot,
-        configPath,
-    };
-}

package/dist/services/upgrade/gitignore-migrate-service.d.ts

@@ -1,56 +0,0 @@
-/**
- * The 2.0 canonical ignore block. Mirrors the same paths
- * peaks-loop's own .gitignore uses; kept in lockstep manually
- * (the peaks-loop root .gitignore is the source of truth).
- *
- * Sentinel: every emitted line carries the marker comment so
- * the migration can detect "already-migrated" and stay
- * idempotent.
- */
-export declare const PEAKS_2_0_BLOCK_SENTINEL = "# peaks-loop 2.0 canonical ignore block \u2014 managed by `peaks upgrade --to 2.0`";
-export declare const CANONICAL_2_0_PEAKS_BLOCK: string;
-/**
- * Returns true when `line` is a wholesale ignore of the entire
- * `.peaks/` tree (the 1.x pattern that breaks 2.0 tracking).
- *
- * Examples that match:    `.peaks`  `.peaks/`  `/.peaks`  `/.peaks/`  `  .peaks/  `
- * Examples that DON'T:    `.peaks/_runtime/`  `# .peaks/ comment`  `.peaks_other`
- */
-export declare function isStaleWholesalePeaksRule(line: string): boolean;
-export interface MigrateGitignoreContentResult {
-    /** True if at least one stale wholesale .peaks rule was removed OR the canonical block was appended. */
-    readonly changed: boolean;
-    /** The exact lines that were removed (verbatim, with original whitespace). */
-    readonly removedRules: readonly string[];
-    /** The migrated content (always ends with a newline). */
-    readonly content: string;
-}
-/**
- * Pure function: takes the .gitignore content, returns the
- * migrated content + diff summary. No I/O.
- */
-export declare function migrateGitignoreContent(input: string): MigrateGitignoreContentResult;
-export interface MigrateGitignoreFileInput {
-    readonly projectRoot: string;
-    readonly apply?: boolean;
-}
-export interface MigrateGitignoreFileResult {
-    /** True if .gitignore is absent (nothing to migrate). */
-    readonly missing: boolean;
-    /** True if the migration would change the file. */
-    readonly changed: boolean;
-    /** True only if `apply: true` AND `changed: true`. */
-    readonly appliedWrite: boolean;
-    /** Absolute path to the timestamped backup file, or null. */
-    readonly backupPath: string | null;
-    /** Removed lines (verbatim). */
-    readonly removedRules: readonly string[];
-}
-/**
- * FS variant: reads .gitignore, runs migration, optionally
- * writes the result + a timestamped backup of the original.
- *
- * Date.now() is used for the backup suffix; in test environments
- * where determinism matters, the caller can stub Date via vi.
- */
-export declare function migrateGitignoreFile(input: MigrateGitignoreFileInput): MigrateGitignoreFileResult;