peaks-loop 4.0.41 → 4.0.43

package/dist/services/session/caller-binding-service.js

@@ -96,6 +96,15 @@ export function getCallerBinding(projectRoot, callerId) {
         return null;
     }
 }
+export function resolveCallerBinding(projectRoot, callerId) {
+    const binding = getCallerBinding(projectRoot, callerId);
+    if (binding === null)
+        return { status: 'absent' };
+    if (!existsSync(getSessionDir(projectRoot, binding.peakSessionId))) {
+        return { status: 'stale', binding };
+    }
+    return { status: 'bound', binding };
+}
 /**
  * Write or update a per-caller binding file. The caller is responsible
  * for the binding object (callerId must match the file stem, peakSessionId
@@ -149,8 +158,7 @@ export function updateCallerBindingSessionId(projectRoot, callerId, peakSessionI
         return false;
     setCallerBinding(projectRoot, callerId, {
         ...existing,
-        peakSessionId,
-        lastActivityAt: new Date().toISOString()
+        peakSessionId
     });
     return true;
 }

package/dist/services/session/caller-id-types.d.ts

@@ -58,6 +58,18 @@ export interface CallerProjection {
 /**
  * On-disk shape of `.peaks/_runtime/callers/<callerId>.json`. One file
  * per caller; two callers may point to the same `peakSessionId` (D6).
+ *
+ * Slice 2026-09-12 (rid=caller-binding-staleness): the former
+ * `lastActivityAt` field is REMOVED. It promised "bumped on every
+ * `peaks <cmd>` that touches the binding" but was written only at first
+ * bind and at an explicit rebind — never on reuse — so no freshness
+ * decision could rest on it without first fixing the write side, and a
+ * TTL built on a timestamp that ages on a live binding would un-bind
+ * exactly the live sessions the caller-first resolution exists to keep
+ * apart. Freshness is decided by the bound session directory (see
+ * `resolveCallerBinding`) plus rotation clearing the binding, not by a
+ * clock. A legacy file that still carries the key is read fine — the
+ * extra property is ignored.
  */
 export interface CallerBinding {
     /** Echo of the filename stem; matches D1 regex. */
@@ -68,8 +80,6 @@ export interface CallerBinding {
     projectRoot: string;
     /** ISO 8601 timestamp; stamped at first write. */
     createdAt: string;
-    /** ISO 8601 timestamp; bumped on every `peaks <cmd>` that touches the binding. */
-    lastActivityAt: string;
     /** Last skill that touched this binding, e.g. "peaks-code". */
     skill: string;
     /** Last mode, e.g. "full-auto". */

package/dist/services/session/index.d.ts

@@ -1,7 +1,7 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';
+export { ensureSession, getSessionId, resolveCallerBoundSession, type CallerBoundSession, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding, type SessionInfo, type SessionMeta } from './session-manager.js';
 export { getSessionDir } from './getSessionDir.js';
 export { resolveCallerId, } from './resolve-caller-id.js';
-export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
+export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, resolveCallerBinding, type CallerBindingResolution, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
 export { PLATFORM_FALLBACKS, type PlatformFallback } from './platform-fallbacks.js';
 export { resolveCallerProjection, type ResolveCallerIdOptions } from './resolve-caller-id.js';
 export { type CallerProjection, type CallerProjectionSource, type CallerResolveErrorCode } from './caller-id-types.js';

package/dist/services/session/index.js

@@ -1,8 +1,8 @@
-export { ensureSession, getSessionId, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding } from './session-manager.js';
+export { ensureSession, getSessionId, resolveCallerBoundSession, getCurrentSessionDir, listSessions, getSessionMeta, setSessionMeta, setSessionTitle, listSessionMetas, getProjectScanPath, hasProjectScan, setCurrentSessionBinding, rotateSessionBinding } from './session-manager.js';
 export { getSessionDir } from './getSessionDir.js';
 // Slice 020 — caller-keyed session binding. The new canonical path.
 export { resolveCallerId, } from './resolve-caller-id.js';
-export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
+export { getCallerBindingFile, getActiveSkillFileForCaller, synthesiseLegacyCallerId, getCallerBinding, resolveCallerBinding, setCallerBinding, listCallerBindings } from './caller-binding-service.js';
 // Slice 4.0.8 (C1): PLATFORM_FALLBACKS is deleted. Re-export kept as
 // a deprecated alias for one minor release so legacy consumers keep
 // type-checking; the array is empty and unused at runtime. New code

package/dist/services/session/session-binding-bridge.js

@@ -23,7 +23,7 @@ import { dirname, join } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { initWorkspace } from '../workspace/workspace-service.js';
 import { projectRootsMatch, stableRealPath } from '../../shared/path-utils.js';
-import { getCallerBinding, setCallerBinding, } from './caller-binding-service.js';
+import { resolveCallerBinding, setCallerBinding, } from './caller-binding-service.js';
 import { resolveCallerProjection } from './resolve-caller-id.js';
 import { getSessionId, getSessionIdCanonical, getSessionMeta, rotateSessionBinding, setSessionMeta } from './session-manager.js';
 // --- Lower-level helpers the bridge needs (moved verbatim) ---
@@ -205,6 +205,12 @@ export function _resetLastResolvedOuterForTest() {
  * `ensureSession` consults it BEFORE `readSessionFile` so a binding
  * written by a previous call from the same caller is preferred over
  * a stale `session.json` (the legacy single-file binding).
+ *
+ * Slice 2026-09-12 (rid=caller-binding-staleness): the binding is only
+ * usable when its bound session directory still exists
+ * (`resolveCallerBinding`). A binding pointing at a deleted session
+ * directory is treated as absent, so `ensureSession` falls through and
+ * rolls a fresh session instead of returning an id whose tree is gone.
  */
 function resolveCallerBindingForEnsure(projectRoot) {
     let projection;
@@ -215,12 +221,12 @@ function resolveCallerBindingForEnsure(projectRoot) {
         return null;
     }
     try {
-        const binding = getCallerBinding(projectRoot, projection.callerId);
-        if (binding === null)
+        const resolution = resolveCallerBinding(projectRoot, projection.callerId);
+        if (resolution.status !== 'bound')
             return null;
         return {
-            sessionId: binding.peakSessionId,
-            createdAt: binding.createdAt,
+            sessionId: resolution.binding.peakSessionId,
+            createdAt: resolution.binding.createdAt,
             callerId: projection.callerId
         };
     }
@@ -324,7 +330,6 @@ export async function ensureSession(projectRoot) {
             peakSessionId: sessionId,
             projectRoot,
             createdAt: now,
-            lastActivityAt: now,
             skill: 'peaks-code',
             mode: 'unknown',
             gate: 'startup'

package/dist/services/session/session-manager.d.ts

@@ -39,7 +39,10 @@ export type SessionMeta = {
  * is left intact — rotating does NOT delete the user's data, it
  * just unbinds the project from that session. Also drops the legacy
  * `.peaks/.session.json` if present so a stale read from another
- * tool cannot re-bind the project after rotation.
+ * tool cannot re-bind the project after rotation. Also drops the
+ * ROTATING caller's per-caller binding when it points at the rotated-out
+ * session (slice 2026-09-12, rid=caller-binding-staleness) — see
+ * `clearRotatedCallerBinding`.
  *
  * Returns the id of the session that was unbound, or `null` if
  * no binding was present. The caller is expected to do something
@@ -126,6 +129,35 @@ export declare function getSessionId(projectRoot: string): string | null;
  * so this variant is opt-in.
  */
 export declare function getSessionIdCanonical(projectRoot: string): string | null;
+/**
+ * Outcome of the caller-binding half of session resolution.
+ *
+ * `staleSessionId` is the id of a per-caller binding that was SKIPPED
+ * because its session directory no longer exists — `null` for the
+ * ordinary "no binding" case. It exists so the fall-through is
+ * observable: a caller can tell "this caller has no binding" apart from
+ * "this caller's binding pointed at a session tree that is gone", and
+ * report it instead of silently resolving a different session.
+ */
+export type CallerBoundSession = {
+    sessionId: string | null;
+    staleSessionId: string | null;
+};
+/**
+ * Resolve the caller-binding primary source (slice 2026-09-12,
+ * rid=caller-binding-staleness).
+ *
+ * The caller-first precedence is unchanged: this caller's binding still
+ * outranks the project-global `session.json`. What changed is what counts
+ * as a USABLE binding — a binding whose bound session directory is gone
+ * is stale, is not trusted, and is reported through `staleSessionId`
+ * instead of being returned as if it were live.
+ *
+ * Returns `{ sessionId: null, staleSessionId: null }` when caller-id
+ * resolution fails (`PEAKS_CALLER_NOT_RESOLVED`), when no per-caller file
+ * exists, or when the file is malformed.
+ */
+export declare function resolveCallerBoundSession(projectRoot: string): CallerBoundSession;
 /**
  * Get the absolute path to the current session directory.
  * Creates the session if it doesn't exist.

package/dist/services/session/session-manager.js

@@ -11,7 +11,7 @@ import { dirname, join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { projectRootsMatch, stableRealPath } from '../../shared/path-utils.js';
 import { ensureSession } from './session-binding-bridge.js';
-import { getCallerBinding } from './caller-binding-service.js';
+import { getCallerBinding, getCallerBindingFile, resolveCallerBinding } from './caller-binding-service.js';
 import { resolveCallerProjection } from './resolve-caller-id.js';
 // As of slice 2026-06-05-peaks-runtime-layer the project-level session
 // binding lives under `.peaks/_runtime/session.json`. The legacy
@@ -199,7 +199,10 @@ function writeSessionFile(projectRoot, info) {
  * is left intact — rotating does NOT delete the user's data, it
  * just unbinds the project from that session. Also drops the legacy
  * `.peaks/.session.json` if present so a stale read from another
- * tool cannot re-bind the project after rotation.
+ * tool cannot re-bind the project after rotation. Also drops the
+ * ROTATING caller's per-caller binding when it points at the rotated-out
+ * session (slice 2026-09-12, rid=caller-binding-staleness) — see
+ * `clearRotatedCallerBinding`.
  *
  * Returns the id of the session that was unbound, or `null` if
  * no binding was present. The caller is expected to do something
@@ -231,8 +234,49 @@ export function rotateSessionBinding(projectRoot) {
             // best-effort: a stale legacy binding is not blocking
         }
     }
+    // Slice 2026-09-12 (rid=caller-binding-staleness): the per-caller
+    // binding is the FIRST thing `getSessionId` reads, so unlinking only
+    // the project-global files left the rotating caller still resolving
+    // the session it just rotated out of — `peaks job init` re-created
+    // `.peaks/_runtime/<old-sid>/job/...` instead of reporting
+    // NO_ACTIVE_SESSION, and `ensureSession` returned the old id instead
+    // of rolling a fresh session. The rotation is only complete once THIS
+    // caller's binding is gone too (the next resolution then either
+    // falls through to the global file or starts a fresh session).
+    clearRotatedCallerBinding(projectRoot, previous.sessionId);
     return previous.sessionId;
 }
+/**
+ * Drop the ROTATING caller's per-caller binding when it points at the
+ * session being rotated out.
+ *
+ * Only that caller is affected: every other caller holds its own session
+ * on purpose (D6 multi-caller isolation — a second IDE window must not
+ * lose its binding because a sibling window rotated). When no caller id
+ * is resolvable (CI / plain shell), there is no per-caller binding to
+ * clear and this is a no-op.
+ */
+function clearRotatedCallerBinding(projectRoot, rotatedOutSessionId) {
+    let callerId;
+    try {
+        callerId = resolveCallerProjection({ projectRoot, env: process.env }).callerId;
+    }
+    catch { // PEAKS_CALLER_NOT_RESOLVED → no per-caller binding exists
+        return;
+    }
+    const binding = getCallerBinding(projectRoot, callerId);
+    if (binding === null || binding.peakSessionId !== rotatedOutSessionId) {
+        return;
+    }
+    try {
+        unlinkSync(getCallerBindingFile(projectRoot, callerId));
+    }
+    catch { // TODO(g2): best-effort unlink — rotation must not fail on a cleanup
+        // error (Windows EPERM). On failure the binding survives; it is stale
+        // for as long as its session directory is gone, and the next rotation
+        // or rebind retries the clear.
+    }
+}
 /**
  * Bind the project's current session to the given session id by writing
  * `.peaks/.session.json`. The single-session binding is the source of truth
@@ -401,17 +445,19 @@ export { ensureSession, ensureSessionWithRotation } from './session-binding-brid
  */
 export function getSessionId(projectRoot) {
     // Slice 2026-08-06-session-cacde8-A.5a: caller-binding becomes
-    // primary source. Read order is (1) `getCallerBinding` if
-    // `resolveCallerProjection` succeeds, (2) `readSessionFile`
-    // (the legacy session.json), (3) null (no binding). The legacy
-    // session.json is preserved as a fallback so a project without
-    // a caller-id resolution still resolves its binding (e.g. CLI
-    // run from a stock shell with no IDE adapter). `PEAKS_CALLER_NOT_RESOLVED`
-    // falls through to the session.json path; no caller-facing exit
-    // change.
-    const fromCallerBinding = getSessionIdFromCallerBinding(projectRoot);
-    if (fromCallerBinding !== null)
-        return fromCallerBinding;
+    // primary source. Read order is (1) the per-caller binding if
+    // `resolveCallerProjection` succeeds — and only when that binding is
+    // still usable (`resolveCallerBoundSession` drops one whose session
+    // directory is gone, slice 2026-09-12 rid=caller-binding-staleness),
+    // (2) `readSessionFile` (the legacy session.json), (3) null (no
+    // binding). The legacy session.json is preserved as a fallback so a
+    // project without a caller-id resolution still resolves its binding
+    // (e.g. CLI run from a stock shell with no IDE adapter).
+    // `PEAKS_CALLER_NOT_RESOLVED` falls through to the session.json path;
+    // no caller-facing exit change.
+    const { sessionId } = resolveCallerBoundSession(projectRoot);
+    if (sessionId !== null)
+        return sessionId;
     const info = readSessionFile(projectRoot);
     return info?.sessionId ?? null;
 }
@@ -446,27 +492,40 @@ export function getSessionIdCanonical(projectRoot) {
     // Slice 2026-08-06-session-cacde8-A.5a: same caller-binding primary
     // lookup as `getSessionId`; fall back to the canonical-fallback
     // `readSessionFileCanonical` if caller-binding is absent / unresolved.
-    const fromCallerBinding = getSessionIdFromCallerBinding(projectRoot);
-    if (fromCallerBinding !== null)
-        return fromCallerBinding;
+    const { sessionId } = resolveCallerBoundSession(projectRoot);
+    if (sessionId !== null)
+        return sessionId;
     const info = readSessionFileCanonical(projectRoot);
     return info?.sessionId ?? null;
 }
 /**
- * Internal helper: read the caller-binding primary source.
- * Returns `null` when caller-id resolution fails
- * (`PEAKS_CALLER_NOT_RESOLVED`), when no per-caller file exists,
- * or when the file is malformed. NOT exported; the public surface
- * is still `getSessionId` / `getSessionIdCanonical`.
+ * Resolve the caller-binding primary source (slice 2026-09-12,
+ * rid=caller-binding-staleness).
+ *
+ * The caller-first precedence is unchanged: this caller's binding still
+ * outranks the project-global `session.json`. What changed is what counts
+ * as a USABLE binding — a binding whose bound session directory is gone
+ * is stale, is not trusted, and is reported through `staleSessionId`
+ * instead of being returned as if it were live.
+ *
+ * Returns `{ sessionId: null, staleSessionId: null }` when caller-id
+ * resolution fails (`PEAKS_CALLER_NOT_RESOLVED`), when no per-caller file
+ * exists, or when the file is malformed.
  */
-function getSessionIdFromCallerBinding(projectRoot) {
+export function resolveCallerBoundSession(projectRoot) {
     try {
         const projection = resolveCallerProjection({ projectRoot, env: process.env });
-        const binding = getCallerBinding(projectRoot, projection.callerId);
-        return binding?.peakSessionId ?? null;
+        const resolution = resolveCallerBinding(projectRoot, projection.callerId);
+        if (resolution.status === 'bound') {
+            return { sessionId: resolution.binding.peakSessionId, staleSessionId: null };
+        }
+        if (resolution.status === 'stale') {
+            return { sessionId: null, staleSessionId: resolution.binding.peakSessionId };
+        }
+        return { sessionId: null, staleSessionId: null };
     }
     catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-        return null;
+        return { sessionId: null, staleSessionId: null };
     }
 }
 /**

package/dist/services/skills/skill-presence-service.d.ts

@@ -52,9 +52,23 @@ export type SkillPresence = {
     lastHeartbeat?: string;
 };
 /**
- * Resolve the active peaks session id from
- * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
- * Returns `null` when no session is bound.
+ * Resolve the active peaks session id.
+ *
+ * Resolution order (slice caller-first-session-resolution):
+ *   1. The per-caller binding (via `getSessionId`) — the SAME source
+ *      `peaks session info --active` resolves through.
+ *   2. The project-global `.peaks/_runtime/session.json` (legacy:
+ *      `.peaks/.session.json`) — unchanged back-compat fallback.
+ *   3. `null` when neither is present.
+ *
+ * The caller-first step is what keeps two IDE windows on one project
+ * apart. The project-global file is last-writer-wins, so the window
+ * that initialised most recently owned it for every reader; commands
+ * that resolved through this helper (job / dispatch / worktree /
+ * share / ...) then wrote into THAT window's session tree, silently
+ * cross-contaminating the two sessions.
+ *
+ * Returns `null` when no session is bound. Never throws.
  *
  * Public export: callers like `peaks sub-agent dispatch` use this
  * to auto-resolve `--session-id` when the LLM driver forgets to

package/dist/services/skills/skill-presence-service.js

@@ -81,9 +81,23 @@ function resolveProjectRoot(override) {
     return findProjectRoot(process.cwd()) ?? process.cwd();
 }
 /**
- * Resolve the active peaks session id from
- * `.peaks/_runtime/session.json` (legacy: `.peaks/.session.json`).
- * Returns `null` when no session is bound.
+ * Resolve the active peaks session id.
+ *
+ * Resolution order (slice caller-first-session-resolution):
+ *   1. The per-caller binding (via `getSessionId`) — the SAME source
+ *      `peaks session info --active` resolves through.
+ *   2. The project-global `.peaks/_runtime/session.json` (legacy:
+ *      `.peaks/.session.json`) — unchanged back-compat fallback.
+ *   3. `null` when neither is present.
+ *
+ * The caller-first step is what keeps two IDE windows on one project
+ * apart. The project-global file is last-writer-wins, so the window
+ * that initialised most recently owned it for every reader; commands
+ * that resolved through this helper (job / dispatch / worktree /
+ * share / ...) then wrote into THAT window's session tree, silently
+ * cross-contaminating the two sessions.
+ *
+ * Returns `null` when no session is bound. Never throws.
  *
  * Public export: callers like `peaks sub-agent dispatch` use this
  * to auto-resolve `--session-id` when the LLM driver forgets to
@@ -93,6 +107,12 @@ function resolveProjectRoot(override) {
  */
 export function getCurrentSessionId(projectRootOverride) {
     const projectRoot = resolveProjectRoot(projectRootOverride);
+    // Caller-first: a binding for THIS caller outranks the project-global
+    // file. Delegated to `getSessionId` rather than re-implemented, so the
+    // two answers to "which session is current?" cannot drift again.
+    const callerBound = getSessionId(projectRoot);
+    if (callerBound !== null)
+        return callerBound;
     const sessionPath = resolve(projectRoot, SESSION_FILE);
     const legacyPath = resolve(projectRoot, SESSION_FILE_LEGACY);
     // Back-compat window: prefer the new canonical path; fall back to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.41",
+  "version": "4.0.43",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "keywords": [
@@ -101,10 +101,10 @@
     "fzf": "^0.5.2",
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
-    "peaks-loop-internal-runtime": "0.0.26",
-    "peaks-loop-shared-channel": "0.0.43",
-    "peaks-loop-mut": "0.1.39",
-    "peaks-loop-shared": "0.0.75"
+    "peaks-loop-mut": "0.1.41",
+    "peaks-loop-shared": "0.0.77",
+    "peaks-loop-internal-runtime": "0.0.28",
+    "peaks-loop-shared-channel": "0.0.45"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

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

@@ -223,11 +223,19 @@ When RD work creates a frontend application and the user has not specified a tec
 
 → see `references/frontend-project-generation.md` for the scaffold protocol.
 
-## Frontend anti-corruption layer (ACL)
+## Frontend anti-corruption layer (ACL) — route by integration mode first
 
-When RD work touches the frontend (pure frontend or full-stack), enforce the ACL discipline: the frontend's internal model is never polluted by external / API shapes. DTO ↔ ViewModel mapping converts external fields to internal fields at the boundary, and all conversion logic lives in one mapper file per domain (e.g. `mappers/user.mapper.ts`) — never scattered across pages. Hard constraint, verified by QA / code-review.
+When RD work touches the frontend, read `.integrationMode` from `## Project mode` in `.peaks/project-scan/project-scan.md` (written from `peaks scan archetype --json`) and run that mode's procedure. Do **not** route on the `frontendOnly` boolean: it is back-compat only and merges two modes that need different first commands (`frontendOnly=false` covers both `full-stack` and `prd-plus-interface-doc`; `frontendOnly=true` covers `prd-only`).
 
-→ see `references/frontend-acl-mapper.md` for the three rules + reference shape + verification.
+| `.integrationMode` | RD runs first | Contract source | Artifact that proves it ran |
+|---|---|---|---|
+| `full-stack` | read `## API` in `.peaks/project-scan/project-scan.md` (a real wrapper + endpoint inventory exist here) | the backend's own response type in this repo | the per-domain mapper at the path in `## API → DTO ↔ ViewModel boundary`, plus `peaks scan diff-vs-scope --rid <rid> --project <repo>` |
+| `prd-plus-interface-doc` | `peaks scan api-diff <doc> --project <repo>`, **before writing any type** | the OpenAPI document | the doc-derived `src/services/types/<feature>-api.types.ts` + the `Exact` section recorded in `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md` |
+| `prd-only` | write `.peaks/_runtime/<sessionId>/rd/mock-plan.md` before any mock file | an authored guess | `mock-plan.md` + `mock/<feature>-mock.ts` |
+
+Whichever the mode, the mapping rule is unchanged: the frontend's internal model is never polluted by external / API shapes, DTO ↔ ViewModel conversion happens at the boundary, and all conversion logic for a domain lives in exactly one mapper file (e.g. `mappers/user.mapper.ts`) — never scattered across pages. Hard constraint, verified by QA / code-review.
+
+→ see `references/frontend-acl-mapper.md` for the three rules + reference shape + verification, and `skills/peaks-code/references/frontend-only-mode.md` §"Integration-mode routing (RD)" for the numbered procedure per mode — including the two checks each mode **cannot** perform (doc↔server drift; and, for `prd-only`, that no mechanism detects a real document appearing, since the §2.6 staleness artifact is not built).
 
 ## Artifact and standards output
 

package/skills/peaks-code/references/existing-system-extraction.md

@@ -20,7 +20,8 @@ The CLI emits stable JSON containing:
   - `componentNaming`: `PascalCase | kebab-case | mixed | unknown` (decided from real file names under the component directory)
   - `componentDir`, `serviceDir`, `hookDir` — first matching path found
   - `samples[]` — up to 5 most-recently-modified files per kind
-- `inconsistencies[]` — token names that have different values across sources
+  - `hookConvention` — the hook directories' file CONTENTS read (not just paths): `{ directories[], inconsistencies[] }`. Each directory carries `namingPattern`, `dominantReturnShape` (null when no class is strictly dominant) + `dominantReturnSignature`, `offShapeHooks[]` (hooks whose shape CLASS differs — key drift is reported separately) plus the file-level `hookFileCount` and `mapperFiles[]`; each hook carries `{ file, name, usePrefix, returnShape, returnSignature }`. These are OBSERVED from the text, never type-checked: an import specifier matching /mapper/i is recorded against the FILE that contains it, and a file absent from `mapperFiles[]` is the absence of an observation, NOT evidence that its hooks map data inline
+- `inconsistencies[]` — token names that have different values across sources, followed by the hook return-shape / hook-naming / mapper-delegation inconsistencies (all prefixed by the directory they belong to)
 
 Copy these fields VERBATIM into `existing-system.md`. Do not re-classify tokens; do not invent additional samples.
 
@@ -59,6 +60,9 @@ Use the template below. Every value must come from the CLI JSON; leave a section
 ## Hooks convention
 - Directory: <conventions.hookDir>
 - Sample files: <conventions.samples filtered by kind=hook>
+- Observed return shape: <per directory: namingPattern + dominantReturnShape + dominantReturnSignature from conventions.hookConvention.directories[*]; "- (none)" when the directory holds no exported function>
+- Hooks deviating from it: <offShapeHooks; "- (none)" when empty>
+- Mapper delegation: <mapperFiles.length of hookFileCount per directory — observed from import paths only, at FILE granularity; do not read a missing import as inlined mapping>
 
 ## Detected inconsistencies
 <paste inconsistencies[*] verbatim; if empty, write "- (none)">

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

@@ -1,23 +1,65 @@
 # Peaks-Loop Frontend-only development mode
 
 > Extracted from `skills/peaks-code/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 Frontend-only development mode section that was previously inline; nothing was paraphrased, just relocated.
+>
+> **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`.
 
-When the project has no live backend (no swagger.json, no API server), Code must activate frontend-only mode.
+`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.
 
 ### Mode determination (deterministic — CLI is the source of truth)
 
-The CLI decision is authoritative. Read `frontendOnly` and `frontendOnlyReason` directly from the `peaks scan archetype --json` output and copy both into `project-scan.md` under `## Project mode`. Do NOT re-derive the decision from user phrasing.
+Read `.integrationMode` and `.integrationModeReason` from the `peaks scan archetype --json` output and copy both into `.peaks/project-scan/project-scan.md` under `## Project mode`. Copy `frontendOnly` / `frontendOnlyReason` alongside them under `## Project mode`, labelled back-compat. Do NOT re-derive the decision from user phrasing — the three values are already deterministic:
+
+| `.integrationMode` | `.integrationModeReason` | What is physically present |
+|---|---|---|
+| `full-stack` | `backend-detected` | a backend framework, Next API routes, or a backend dir in this repo |
+| `prd-plus-interface-doc` | `interface-doc-present` | an OpenAPI / proto document, and no backend here |
+| `prd-only` | `no-backend-no-interface-doc` | neither |
+
+A 0-1 bootstrap stub writes `unknown`; treat that as "not yet scanned", not as a fourth mode.
+
+Back-compat mapping: `frontendOnly=false` covers `full-stack` **and** `prd-plus-interface-doc`; `frontendOnly=true` covers `prd-only`. That is why the boolean cannot route work — it merges two modes that need different procedures.
 
 User-stated intent is **only** consulted when it conflicts with the CLI result. The two conflict cases:
 
-- **CLI says `frontendOnly=false` but the user says "前端项目 / 没有后端 / 先 mock 数据"**: STOP and `AskUserQuestion` to confirm whether to override the scan (the repo probably contains a backend folder the user wants to ignore). Record the override decision and reason in `project-scan.md`.
-- **CLI says `frontendOnly=true` but the user says "需要做后端 / 加 API"**: STOP and `AskUserQuestion` to confirm whether the request actually targets the missing backend (the user may be confused about repo scope, or there is a separate backend repo Code should switch to).
+- **CLI says `full-stack` but the user says "前端项目 / 没有后端 / 先 mock 数据"**: STOP and `AskUserQuestion` to confirm whether to override the scan (the repo probably contains a backend folder the user wants to ignore). Record the override decision and reason in `.peaks/project-scan/project-scan.md` under `## Project mode`.
+- **CLI says `prd-only` but the user says "需要做后端 / 加 API"**: STOP and `AskUserQuestion` to confirm whether the request actually targets the missing backend (the user may be confused about repo scope, or there is a separate backend repo Code should switch to).
 
 When there is no conflict, do not ask — the CLI value wins and the workflow proceeds.
 
+### Integration-mode routing (RD) — three procedures
+
+RD reads `.integrationMode` from `## Project mode` in `.peaks/project-scan/project-scan.md` and follows exactly one of the procedures below. Each mode has a different first command, a different contract source, and a different artifact; running one mode's steps under another mode is the collapse this routing exists to prevent.
+
+#### `full-stack` — the backend is in this repo
+
+1. **First:** read `## API` in `.peaks/project-scan/project-scan.md`. A real request wrapper, error shape, and endpoint inventory exist here — take them from the scan instead of re-deriving them by reading every service file.
+2. If `.detected.swaggerPaths` from `peaks scan archetype --json` is non-empty, run `peaks scan api-diff <that path> --project <repo>` **before** editing any `*-api.types.ts`, and start from its `Exact` section.
+3. **Boundary:** the DTO is the backend's own response type, imported at exactly one site per domain — the mapper path recorded under `## API → DTO ↔ ViewModel boundary` (`frontend-acl-mapper.md` rule 3: one mapper file per domain, reference shape `src/mappers/user.mapper.ts`). The internal ViewModel file it targets is the one recorded in that same `## API` row (reference shape `src/models/<domain>.ts`).
+4. **Produces:** that mapper file, and the `## Red-line scope` section of `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md` naming the in-scope endpoints. Close with `peaks scan diff-vs-scope --rid <rid> --project <repo>` (Gate B8).
+5. **MUST NOT** mock. There is no missing contract to guess, so no `mock-plan.md` entry and no `mock/*.ts` file is written. This is not honour-system: an inline mock literal in a changed file under `src/` fails `rl-mock-placement-001` (`src/services/audit/enforcers/mock-placement.ts`).
+
+#### `prd-plus-interface-doc` — a document exists, no backend here
+
+1. **First:** `peaks scan api-diff <doc> --project <repo>`, where `<doc>` is a path from `.detected.swaggerPaths`. Run it **before any type is written** — the whole point of this mode is that the recorded interfaces start from the document rather than from a guess. The `Exact` section is the change list; it is exact because both sides are parsed.
+2. Write or refresh `src/services/types/<feature>-api.types.ts` — one interface per endpoint the `Exact` section names. Every field must trace to a line of the document.
+3. **Boundary:** the mapper imports its DTO from the doc-derived `*-api.types.ts` and its ViewModel from the internal model file recorded under `## API → DTO ↔ ViewModel boundary`. The mapper is what absorbs a doc revision: after the document changes, re-run step 1 and the mapper file appears in the `Candidate mentions` section as the place to edit.
+4. **Produces:** the doc-derived `*-api.types.ts`, the mapper, and the `api-diff` `Exact` output pasted into `.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`.
+5. **MUST NOT** author a DTO from memory — that is `prd-only`'s guess, and here it would silently shadow the document. **MUST NOT** treat the `Candidate mentions` section as exact: it is a name-grep over the consumer's source, so it over-reports test fixtures and under-reports i18n keys, AntD `columns` arrays, `data-field` attributes, and monorepo barrels.
+6. **Not checkable in this repo:** nothing detects doc↔server drift. `api-diff` compares the document against what the project recorded; if the document itself is stale, the interfaces compile clean and the UI renders `undefined`. `api-diff` prints this limitation in its own output footer — do not restate it as covered.
+
+#### `prd-only` — no backend, no document
+
+1. **First:** pick a row of the mock-strategy table below from the project's data-fetching pattern in `## API`, then write `.peaks/_runtime/<sessionId>/rd/mock-plan.md` **before producing any mock file** — chosen strategy, planned file paths, one-line rationale per file (`mock-plan.md` is the source of truth for mock locations across runs; RD reads it before writing code and QA reads it before writing test cases). If the table's last row applies ("cannot decide from scan alone"), STOP and `AskUserQuestion`.
+2. Define the response interfaces first: `src/services/types/<feature>-api.types.ts`, per the placeholder layout below. These interfaces are an **authored guess** — mark them as such in the file header.
+3. **Boundary:** write the mapper against the *interface*, never against the mock module. That is what keeps the guess cheap: when the real document lands, the mock file is deleted and the mapper's import target changes — no component, hook, or store is touched.
+4. **Produces:** `mock-plan.md`, the `*-api.types.ts` interfaces, `mock/<feature>-mock.ts`, and the mapper.
+5. **MUST NOT** write mock data inline in a component file — mock files live in the mock directory, and an inline mock literal in a changed file under `src/` fails `rl-mock-placement-001`. Every mock file carries the `// MOCK: Replace with real API call when swagger.json is available` header (mock rule 4 below).
+6. **Exit path:** when a document appears, run `peaks scan api-diff <doc> --project <repo>` and follow §"Mock-to-real migration path" below. **Not checkable in this repo:** nothing detects "a real document now exists for this domain" automatically, and the conditional contract artifact (`.peaks/api-contract.json` with staleness detection, design spec §2.6 / S3) is **not built**. Until it is, step 1 of the migration is a run RD schedules manually.
+
 ### Mock data strategy selection
 
-Code records the chosen mock strategy in `.peaks/_runtime/<sessionId>/rd/tech-doc.md` under a `## Mock Data Strategy` section. The choice depends on the project scan results:
+This table belongs to `prd-only`. Under `full-stack` and `prd-plus-interface-doc` a real contract source exists (the backend type, or the document), so no mock is written. Under `prd-only`, Code records the chosen strategy in `.peaks/_runtime/<sessionId>/rd/mock-plan.md` under a `## Mock Data Strategy` section — the same file mock rule 5 below requires before any mock file is produced. The choice depends on the project scan results:
 
 | Project data-fetching pattern | Recommended mock approach | Rationale |
 |---|---|---|
@@ -81,7 +123,7 @@ Never silently fall back to unauthenticated `fetch` or `WebFetch` for authentica
 1. Read `.peaks/_runtime/<sessionId>/prd/requests/<rid>.md` body.
 2. Lowercase + strip markdown; check regex `\b(页面|组件|表单|弹窗|表格|样式|布局|交互|UI|UX|page|component|form|modal|table|styling|layout|interaction|frontend|前端)\b`.
 3. If match count ≥ 1 → `frontendKeywordHit=true`.
-4. If `frontendOnly` (from project-scan) is `true` and no keyword hit → UI joins anyway (frontend-only project, even non-visual changes may need visual sanity for regressions).
+4. If `frontendOnly` (back-compat boolean from `## Project mode` in project-scan — the UI-inclusion signal only; it is not the integration-mode router) is `true` and no keyword hit → UI joins anyway (frontend-only project, even non-visual changes may need visual sanity for regressions).
 5. If `frontendOnly` is `false` and no keyword hit → UI skipped.
 
 Code records the pre-flight result in `sc/swarm-plan.json` so the audit trail shows why UI was or was not included.

package/skills/peaks-code/references/project-scan-checklist.md

@@ -18,8 +18,10 @@ The command emits a stable JSON envelope with these fields you copy verbatim int
 
 - `archetype`: `greenfield | legacy-frontend | legacy-fullstack | frontend-monorepo | unknown`
 - `confidence`: `high | medium | low`
-- `frontendOnly`: `true | false`
+- `frontendOnly`: `true | false` (back-compat boolean — keep it recorded)
 - `frontendOnlyReason`: short string explaining the decision
+- `integrationMode`: `full-stack | prd-plus-interface-doc | prd-only` — which of the three frontend integration scenarios the project is in (`full-stack` = backend in this repo, contract is a shared interface; `prd-plus-interface-doc` = no backend here but an interface doc exists, derive the ACL from it; `prd-only` = no backend and no doc yet, mock and keep the boundary cheap to change)
+- `integrationModeReason`: short string explaining the decision (`backend-detected | interface-doc-present | no-backend-no-interface-doc`)
 - `signals[]`: each signal's name, matched flag, and detail (paste under `## Archetype → Signals matched`)
 - `detected`: raw filesystem facts (package.json presence, backend frameworks, swagger paths, monorepo configs, src file count, lockfile age)
 
@@ -106,9 +108,16 @@ Grep `src/` for outdated patterns and list them as constraints in `project-scan.
 - Signals matched: <bullet list of signals that drove the decision>
 
 ## Project mode
+- Integration mode: <full-stack | prd-plus-interface-doc | prd-only> (from `peaks scan archetype --json` → `.integrationMode`)
+- Integration mode reason: <backend-detected | interface-doc-present | no-backend-no-interface-doc>
 - Frontend-only: <true | false>
 - Reason: <archetype-derived | user-stated | backend-detected>
 
+The integration mode is one of exactly three values, all derived by `peaks scan archetype`
+from signals it already detects — never judged by hand. The 0-1 bootstrap stub writes
+`unknown` instead, because on that path no archetype report has been produced yet; treat
+`unknown` as "not yet scanned", not as a fourth mode.
+
 ## Build tool
 - Framework: <name> <version>
 - Config file: <path>
@@ -128,6 +137,16 @@ Grep `src/` for outdated patterns and list them as constraints in `project-scan.
 - Routing: <name>
 - Data fetching: <name>
 
+## API
+- Record file paths, not summaries — a later slice diffs against them, and a path that has moved is a finding.
+- Base URL / env configuration: <env-var name(s) and the file that reads them, e.g. `VITE_API_BASE` in `src/config/env.ts` | none>
+- Request wrapper + interceptors: <path of the single HTTP entry point, e.g. `src/services/http/client.ts`, and the mechanism used for cross-cutting concerns — axios interceptors, a `fetch` wrapper, ofetch hooks — with the auth/retry/header logic named | none>
+- Error-handling shape: <what the wrapper hands callers on failure — thrown `Error` subclass, `{ ok, data, error }` result, HTTP-status branch — and the file where it is normalised>
+- Hook convention: <naming pattern and directory, e.g. `use<Domain>` under `src/hooks/`, the return shape (`{ data, loading, error }` | `[data, actions]` | query object), and whether the hook does its own mapping or delegates>
+- Endpoint inventory: <one bullet per endpoint the frontend actually calls — `METHOD /path` → calling file; when an interface doc exists, cross-check with `peaks scan api-diff <path-to-doc>`>
+- Existing mock strategy: <mechanism in use today (module mock | MSW | static fixture module | inline) and where mock files live. Per `frontend-only-mode.md` mocks MUST NOT be inline in component files — an inline mock here is a finding, record it>
+- DTO ↔ ViewModel boundary: <path of the per-domain mapper file, e.g. `src/mappers/user.mapper.ts`, and the internal ViewModel file it targets, per `skills/bee/peaks-rd/references/frontend-acl-mapper.md`. Record `none` explicitly when there is no mapper — that is a finding, not a blank>
+
 ## Library versions
 - Source: output of `peaks scan libraries --project <repo> --json` (see Gate A; cross-check diff imports against `schemas/library-breaking-changes.data.json` in `peaks-rd` preflight)
 - Total: <count from scan.libraries.totalCount>

package/skills/peaks-doctor/references/doctor-check-catalog.md

@@ -21,6 +21,7 @@ Slice L3.2 ships 69 doctor checks. The most user-relevant ones:
 ## Integration (third-party hooks)
 
 - **`integration:gateguard-peaks-conflict`** — warns when `gateguard-fact-force` is installed without a `.peaks/**` skip pattern (the 3rd-party hook would block all peaks-qa .peaks/ artifact writes)
+- **`integration:ecc-hooks-schema-drift`** — warns (cosmetic, never fails the run) when the 3rd-party ECC plugin's `hooks/hooks.json` carries keys Claude Code ignores (`$schema` at the root; `description` + `id` per matcher group), which is what prints `ecc: hooks.json: unknown keys ... ignored` at startup
 
 ## Skills