peaks-loop 4.1.0 → 4.1.2

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-audit/SKILL.md

@@ -56,7 +56,7 @@ The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, a
 When a workflow surfaces a human need (a sentence, a ticket summary, a voice note, a vague "I want X"), call `peaks-audit` BEFORE any other skill:
 
 ```text
-need expressed  →  peaks audit-goal  →  (user accepts goal)  →  peaks-prd  →  peaks-rd  →  peaks-qa
+need expressed  →  peaks audit goal  →  (user accepts goal)  →  peaks-prd  →  peaks-rd  →  peaks-qa
                        ▲
                        │
               you are here on first contact
@@ -80,14 +80,14 @@ Do NOT invoke peaks-audit when the user is asking for a code review, a test run,
 ### Intended CLI form (L2.4 — not yet registered in `src/cli/commands/audit-commands.ts`)
 
 ```bash
-peaks audit-goal --need "<natural language description of the need>" --json
+peaks audit goal --need "<natural language description of the need>" --json
 ```
 
 > **Deviation note:** at the time of this writing, only `peaks audit red-lines` and `peaks audit static` are registered as `peaks audit` subcommands. The `audit-goal` subcommand is **not yet wired** in `src/cli/commands/audit-commands.ts`. Callers reach the primitive through the TypeScript module below. The CLI registration is tracked separately and must not be conflated with the primitive itself.
 
 ### Service-layer form (authoritative, used today)
 
-`peaks audit-goal` is a thin wrapper around the `auditGoal()` function in `src/services/audit/audit-goal-service.ts`. Two integration paths exist today:
+`peaks audit goal` is a thin wrapper around the `auditGoal()` function in `src/services/audit/audit-goal-service.ts`. Two integration paths exist today:
 
 **1. Direct TypeScript call** (used by `src/services/final-review/final-review-service.ts`, `src/services/slice/llm-arbitrator.ts`, `src/services/slice/multi-pass-orchestrator.ts`):
 

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/codegraph/codegraph-include-reconciler.d.ts

@@ -1,10 +0,0 @@
-export type CodegraphIncludeNormalizePlan = {
-    readonly changed: boolean;
-    readonly include: readonly string[];
-    readonly addedPatterns: readonly string[];
-};
-export declare function normalizeCodegraphInclude(input: {
-    readonly include: readonly string[];
-    readonly candidateExtensions: readonly string[];
-}): CodegraphIncludeNormalizePlan;
-export declare function upstreamUnnamedIncludeExtensions(): readonly string[];

package/dist/services/codegraph/codegraph-include-reconciler.js

@@ -1,160 +0,0 @@
-// src/services/codegraph/codegraph-include-reconciler.ts
-//
-// Slice-002 of `2026-09-16-codegraph-index-integrity` — the INCLUDE axis
-// of the config repair. It answers one question:
-//
-//   "Which extensions does upstream's extractor support but upstream's own
-//    default `include` template never names, and which of those does THIS
-//    project's `include` still not admit?"
-//
-// Why this exists (the real defect, measured): upstream
-// `@colbymchenry/codegraph` decides what to parse from its own
-// `EXTENSION_MAP` (37 extensions in 0.7.10), but `init` writes a 32-entry
-// `DEFAULT_CONFIG.include` template that names only 32 of them. Five
-// supported extensions are therefore absent from every fresh config:
-// `.mjs`, `.cjs`, `.pyw`, `.hxx`, `.rake`. Upstream's `mergeConfig` has no
-// separate override channel — `config.json`'s `include` replaces the
-// defaults wholesale — so a fresh clone indexes none of them while
-// `peaks codegraph status` still prints `[OK] Index is up to date`. On this
-// repo that was 31 tracked files (30 `.mjs` + 1 `.cjs`) absent from a
-// 1220-row index. It is the same class of defect as upstream's default
-// `exclude` template colliding with real source directories, which slice S2
-// of `2026-09-12-codegraph-exclude-integrity` already self-heals at the
-// `init` seam; the include axis was simply never reconciled.
-//
-// Genericity (binding — mirrors the exclude reconciler): no hardcoded
-// extension list, no hardcoded rule names, no project-specific paths. The
-// candidate set is COMPUTED from upstream's own two tables (`EXTENSION_MAP`
-// in `dist/extraction/grammars.js`, `DEFAULT_CONFIG` in `dist/types.js`),
-// and every candidate is confirmed against upstream's own decision pair
-// (`isLanguageSupported(detectLanguage(...))` — the same two functions
-// `extraction/index.js` calls). Upstream can add an extension tomorrow and
-// this module picks it up with no edit here; the "five" above is a
-// measurement, not a constant in the code.
-//
-// Additive, never clobbering: a project's `include` is append-only from
-// here. No user entry is removed, reordered or rewritten, and an extension
-// any existing entry already admits is left alone. Append-only is the same
-// posture `codegraph-exclude-repair.ts` takes toward a third-party config
-// file it edits.
-//
-// Scope: PURE (`normalizeCodegraphInclude`) plus ONE read-only adapter
-// (`upstreamIncludeCandidateExtensions`, which reads the installed upstream
-// package). Nothing in this module writes a file.
-//
-// NOTE FOR FUTURE EDITORS: glob literals contain the two-character
-// sequence that ends a block comment, so every comment in this file uses
-// `//` lines — INCLUDING the exported API documentation, which is why this
-// file has no `/** ... */` blocks. Do not convert them.
-import { createRequire } from 'node:module';
-import { dirname, extname, join } from 'node:path';
-import { compileCodegraphGlobs } from './codegraph-exclude-reconciler.js';
-// ─────────────────────────────────────────────────────────────────────
-// Which extensions does this project's `include` already admit?
-// ─────────────────────────────────────────────────────────────────────
-// The pattern upstream's own template uses for a bare extension: all 32
-// entries of `DEFAULT_CONFIG.include` have exactly this shape, and they are
-// matched with `picomatch(..., { dot: true })` — the same engine, and the
-// same options, that `matchesCodegraphGlob` delegates to. So an appended
-// pattern is indistinguishable in form from an upstream-authored one.
-function includePatternForExtension(extension) {
-    return `**/*${extension}`;
-}
-// A synthetic path used ONLY to ask "does any existing rule admit a file
-// with this extension". A root-level probe answers that question exactly
-// for every pattern shape upstream itself writes, because `picomatch`'s
-// trailing-slash-star-star prefix matches zero path segments (measured:
-// the `.mjs` pattern matches both `probe.mjs` and `a/b/probe.mjs`).
-//
-// KNOWN PROXY LIMIT, stated rather than hidden: a path-narrowed rule such as
-// a `src`-prefixed brace list of js/mjs does NOT match the root-level probe,
-// so an extension admitted only under a subdirectory is treated as
-// uncovered and the bare extension pattern is appended. That errs ADDITIVE —
-// the index admits more tracked files, never fewer — and it is pinned by a
-// test rather than left to be discovered. A false "already covered" cannot
-// occur for any pattern upstream's template can produce, and if it did its
-// only effect would be to leave the gap the inspector already reports.
-function extensionProbePath(extension) {
-    return `codegraph-include-probe${extension}`;
-}
-// Compiled ONCE per rule, never per (candidate x rule) pair — see
-// `compileCodegraphGlobs`. The `matchers` list is the include list the
-// candidate is tested against: the caller's entries first, then the
-// patterns this same pass has already decided to append, so a duplicate
-// candidate cannot append twice without re-parsing the list each time
-// (perf audit S10: the re-parse was 0.25 / 2.15 / 23.4 / 234.4 ms at
-// 32 / 320 / 3,200 / 32,000 rules, plus a spread array per candidate).
-function isExtensionAdmitted(extension, matchers) {
-    const probe = extensionProbePath(extension);
-    return matchers.some((matcher) => matcher.matchesAny(probe));
-}
-// Pure: given the current `include` list and the extensions upstream
-// supports but its own template omits, return the list with the uncovered
-// ones appended. No fs, no clock, no serialization.
-//
-// The result is always a SUPERSET of the input, in the input's order, so a
-// caller can never remove or reorder a user entry. Appending an extension
-// the list already admits is a no-op, which is what makes the whole
-// normalization idempotent: feeding the repaired list back in yields
-// `changed: false`.
-//
-// Candidates are de-duplicated by their EFFECT, not by string equality:
-// each candidate is tested against the input list PLUS the patterns this
-// call has already appended, so a duplicate candidate cannot append twice.
-export function normalizeCodegraphInclude(input) {
-    const addedPatterns = [];
-    // The include list as this pass sees it, compiled once. Appending a
-    // pattern extends the list by ONE compiled rule instead of re-parsing
-    // every entry on the next candidate (see `isExtensionAdmitted`).
-    const matchers = [compileCodegraphGlobs(input.include)];
-    for (const candidate of input.candidateExtensions) {
-        const extension = candidate.startsWith('.') ? candidate : `.${candidate}`;
-        if (isExtensionAdmitted(extension, matchers)) {
-            continue;
-        }
-        const pattern = includePatternForExtension(extension);
-        addedPatterns.push(pattern);
-        matchers.push(compileCodegraphGlobs([pattern]));
-    }
-    if (addedPatterns.length === 0) {
-        return { changed: false, include: input.include, addedPatterns: [] };
-    }
-    return {
-        changed: true,
-        include: [...input.include, ...addedPatterns],
-        addedPatterns
-    };
-}
-let cachedCandidateExtensions = null;
-// The extensions upstream's extractor supports but its own default
-// `include` template never names, as dotted extensions — measured against
-// the installed `@colbymchenry/codegraph` 0.7.10 as `.mjs`, `.cjs`,
-// `.pyw`, `.hxx`, `.rake`, in that order.
-//
-// Derived entirely from upstream's own data:
-//
-//   1. `EXTENSION_MAP` keys are the extension universe the extractor knows.
-//   2. The extensions upstream's template already names are read off
-//      `DEFAULT_CONFIG.include` — the entry's own extension, so the
-//      comparison is extension-to-extension and cannot be confused by a
-//      template that switches glob syntax.
-//   3. A candidate is kept only when upstream's own support decision
-//      accepts it, so a table entry with no grammar behind it is never
-//      repaired into the config.
-//
-// Returns the same array on every call (module-level cache); the two
-// modules only define tables and functions, so the load is cheap and
-// Node's `require` cache makes later calls free.
-export function upstreamUnnamedIncludeExtensions() {
-    if (cachedCandidateExtensions === null) {
-        const require = createRequire(import.meta.url);
-        const packageJsonPath = require.resolve('@colbymchenry/codegraph/package.json');
-        const distDir = join(dirname(packageJsonPath), 'dist');
-        const types = require(join(distDir, 'types.js'));
-        const grammars = require(join(distDir, 'extraction', 'grammars.js'));
-        const namedByTemplate = new Set(types.DEFAULT_CONFIG.include.map((entry) => extname(entry).toLowerCase()));
-        cachedCandidateExtensions = Object.keys(grammars.EXTENSION_MAP).filter((extension) => !namedByTemplate.has(extension.toLowerCase()) &&
-            grammars.isLanguageSupported(grammars.detectLanguage(`probe${extension}`)));
-    }
-    return cachedCandidateExtensions;
-}

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;