peaks-loop 4.1.0 → 4.1.1

package/dist/services/workspace/generated-artifacts-stamp.d.ts

@@ -13,8 +13,8 @@
  *
  * `.claude/settings.local.json` IS drift-checked against the current template
  * — but only when something calls `initWorkspace`, which is precisely the
- * event that stopped happening. The escape hatch (`peaks upgrade
- * --apply-init`) is real and idempotent. What was missing is anything that
+ * event that stopped happening. The escape hatch (`peaks workspace init`) is
+ * real and idempotent. What was missing is anything that
  * tells the user — or the LLM driving them — that they need it. That is the
  * gap this module closes: a stamp the generator writes, and a detector that
  * can answer "the file on disk was produced by 4.0.40 while the installed

package/dist/services/workspace/generated-artifacts-stamp.js

@@ -13,8 +13,8 @@
  *
  * `.claude/settings.local.json` IS drift-checked against the current template
  * — but only when something calls `initWorkspace`, which is precisely the
- * event that stopped happening. The escape hatch (`peaks upgrade
- * --apply-init`) is real and idempotent. What was missing is anything that
+ * event that stopped happening. The escape hatch (`peaks workspace init`) is
+ * real and idempotent. What was missing is anything that
  * tells the user — or the LLM driving them — that they need it. That is the
  * gap this module closes: a stamp the generator writes, and a detector that
  * can answer "the file on disk was produced by 4.0.40 while the installed

package/dist/services/workspace/workspace-service.js

@@ -194,7 +194,7 @@ export async function initWorkspace(options) {
     // is `$HOME`) resolved to `$HOME` and did exactly that — `.peaks/`,
     // `.gitignore`, `.claude/settings.local.json` and a codegraph index, all in
     // the user's home. Enforced here as well as at the CLI so a non-CLI caller
-    // (`peaks upgrade`) cannot reach the same write by another door.
+    // cannot reach the same write by another door.
     assertWritableProjectRoot(options.projectRoot);
     // Phase 6 refactor (slice 2026-06-05-change-id-as-unit-of-work) +
     // slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs) +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -117,10 +117,10 @@
     "picomatch": "4.0.4",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.40",
-    "peaks-loop-mut": "0.1.53",
-    "peaks-loop-shared": "0.0.89",
-    "peaks-loop-shared-channel": "0.0.57"
+    "peaks-loop-internal-runtime": "0.0.41",
+    "peaks-loop-mut": "0.1.55",
+    "peaks-loop-shared": "0.0.90",
+    "peaks-loop-shared-channel": "0.0.58"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/scripts/install-skills.mjs

@@ -17,7 +17,6 @@ import {
   unlinkSync,
   writeFileSync
 } from 'node:fs';
-import { spawnSync } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
@@ -1409,162 +1408,6 @@ export function installBundledSkillsForAllPlatforms(options = {}) {
   return perPlatform;
 }
 
-/**
- * 1.x → 2.0 detection — sniff for legacy 1.x project state
- * in `cwd`. Returns a 1.x detection envelope with the
- * detected signals (so the postinstall can decide whether
- * to auto-upgrade).
- *
- * 1.x signals (any one fires the detection):
- *   - `~/.peaks/config.json` exists with `version: '1.4.2'` (or
- *     any '1.x' version that predates the 2.0 schema)
- *   - `.claude/rules/common/dev-preference.md` exists and
- *     references "peaks progress" (the 1.x CLI surface
- *     removed in slice #014)
- *   - `<cwd>/.peaks/preferences.json` missing OR has no
- *     `schema_version: '2.0.0'` field
- *
- * Returns:
- *   { isOneX: boolean, signals: string[], projectRoot: string|null,
- *     configPath: string|null }
- */
-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 < 8; 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 {
-      // 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 {
-        // 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
-  };
-}
-
-/**
- * Postinstall auto-upgrade — when the user just ran
- * `npm i -g peaks-loop@2.0` and `cwd` is a 1.x peaks-loop
- * project, this shells out to the installed `peaks`
- * binary to run the umbrella `peaks upgrade --to 2.0 --auto`.
- *
- * Per the "minimal-user-operation" tenet, the user should
- * never have to run a second command after `npm i -g`. The
- * upgrade CLI (if installed) is at the resolved `peaks`
- * binary path; if not, the user gets a hint to run it
- * manually.
- *
- * The auto-upgrade is opt-out via:
- *   PEAKS_SKIP_AUTO_UPGRADE=1
- * (so a CI box that installs 2.0 but never wants the
- * project-level migration can suppress the auto-step).
- */
-export async function autoUpgrade1xProjectIfPresent(options = {}) {
-  if (process.env.PEAKS_SKIP_AUTO_UPGRADE === '1') {
-    return { ran: false, reason: 'PEAKS_SKIP_AUTO_UPGRADE=1' };
-  }
-  const state = detect1xProjectState(options.cwd ?? process.cwd());
-  if (!state.isOneX) {
-    return { ran: false, reason: 'no 1.x project state detected' };
-  }
-  if (state.projectRoot === null) {
-    return { ran: false, reason: 'cwd is not a peaks project (no .peaks/_runtime/)' };
-  }
-  // The peaks binary should be on PATH after `npm i -g`.
-  // We shell out via spawnSync (synchronous; the postinstall
-  // is already synchronous and the umbrella is fast).
-  try {
-    const result = spawnSync(
-      'peaks',
-      ['upgrade', '--to', '2.0', '--auto', '--project', state.projectRoot],
-      {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: 120_000,
-        windowsHide: true
-      }
-    );
-    return {
-      ran: true,
-      reason: 'auto-upgrade dispatched',
-      signals: state.signals,
-      projectRoot: state.projectRoot,
-      exitCode: result.status,
-      stdout: result.stdout ?? '',
-      stderr: result.stderr ?? ''
-    };
-  } catch (err) {
-    return {
-      ran: true,
-      reason: 'auto-upgrade dispatched but failed',
-      signals: state.signals,
-      projectRoot: state.projectRoot,
-      error: err instanceof Error ? err.message : String(err)
-    };
-  }
-}
-
 if (
   process.argv[1] !== undefined &&
   import.meta.url === pathToFileURL(resolve(process.argv[1])).href
@@ -1661,26 +1504,6 @@ if (
     if (userConfigResult.created) {
       process.stdout.write('Peaks user config created: ~/.peaks/config.json\n');
     }
-
-    // 2.0 postinstall: auto-detect 1.x project state in cwd
-    // and dispatch the upgrade umbrella. This makes the
-    // user's `npm i -g peaks-loop@2.0` truly one-key.
-    if (process.env.PEAKS_SKIP_AUTO_UPGRADE !== '1') {
-      // Fire-and-forget; the upgrade is async by design so
-      // the npm install output isn't blocked. We print a
-      // one-line hint so the user knows the auto-step
-      // happened.
-      autoUpgrade1xProjectIfPresent().then((result) => {
-        if (result.ran) {
-          process.stdout.write(
-            `\n✓ Detected 1.x peaks-loop project at ${result.projectRoot}\n` +
-              `  → auto-upgraded to 2.0 (${result.signals?.length ?? 0} signals resolved)\n` +
-              `  Run \`peaks audit red-lines --project .\` to verify.\n`
-          );
-        }
-        // When !result.ran we say nothing — silent on success.
-      });
-    }
     if (userConfigResult.updated) {
       process.stdout.write('Peaks user config updated: ~/.peaks/config.json\n');
     }

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/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 type { 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;