peaks-loop 4.0.48 → 4.0.50

package/dist/services/workspace/claude-settings-template.d.ts

@@ -2,24 +2,31 @@
  * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
  * consumer-project `.claude/settings.local.json` file.
  *
- * The template is a PreToolUse hook allow-list that bypasses the
- * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
- * the peaks-managed `.peaks/` workspace. Without this bypass,
- * `peaks workspace init` (Step 0 of every peaks-code session) is
- * unrunnable in a consumer project because the gate blocks the very
- * first Write.
+ * The template exempts the peaks-managed `.peaks/` workspace from the
+ * Claude Code [Fact-Forcing Gate], so `peaks workspace init` (Step 0 of
+ * every peaks-code session) is runnable in a consumer project — without
+ * the exemption the gate blocks the very first Write.
+ *
+ * The exemption is declared in the `env` block
+ * (`EXTERNAL_GATE_EXEMPT_ENV`), which is what the gate actually reads.
+ * TEMPLATE_VERSION 1.7.0 moved it there; before that it was declared by a
+ * `Write|Edit|MultiEdit` handler that exited non-zero for non-`.peaks/`
+ * paths and was documented as "fall through to the gate". That concept does
+ * not exist in the Claude Code hook protocol (only exit 2 blocks; any other
+ * non-zero exit is a NON-BLOCKING ERROR reported once per edit), so the
+ * handler was corrected to abstain on every path — and an abstaining handler
+ * that is still INSTALLED is a no-op carrying a machine-specific absolute
+ * script path. TEMPLATE_VERSION 1.8.0 removed it rather than re-point it:
+ * it decided nothing, and the exemption it was written for lives in `env`.
  *
  * The template is a pure-data function (no filesystem, no clock) so
  * it can be unit-tested in isolation and so the on-disk file matches
  * the in-memory template byte-for-byte.
  *
- * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
- *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
- *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
- *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
- *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
- *      bash-specific and therefore could not take a platform `shell` pin.
+ * Two `Bash` matchers are emitted (the Step 0.8 mechanical gate and the
+ * SOP gate-enforce handler). No `Write|Edit|MultiEdit` entry is emitted:
+ * that matcher's gate is `peaks code-gate --json`, installed into the
+ * committed `.claude/settings.json` by `peaks hooks install`.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -80,8 +87,20 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
  *           on-disk file to declare those exemptions too, so a project
  *           installed by an earlier release refreshes once and converges.
+ *   1.8.0 — REMOVED the `Write|Edit|MultiEdit` handler and the shipped
+ *           script it invoked (`src/services/hooks/write-gate.js`, also
+ *           deleted). The handler abstained on every path by design (see
+ *           that file's header for the rationale — it is the reason this
+ *           is a deletion and not a repair), so the only things it still
+ *           contributed were a `node "<abs path>"` command pinned to the
+ *           Node version directory that happened to be on `$PATH` at
+ *           install time, and a `shell: powershell` pin. The exemption it
+ *           was written to provide is declared by the `env` block above.
+ *           `mergeTemplateOwnedHooks` drops the retired entry from
+ *           existing on-disk files, so an earlier install converges
+ *           instead of keeping a no-op with a stale absolute path.
  */
-export declare const TEMPLATE_VERSION = "1.7.0";
+export declare const TEMPLATE_VERSION = "1.8.0";
 /**
  * Compare two serialized template strings: does the on-disk file already
  * declare every entry the generated tree declares?
@@ -108,10 +127,11 @@ export declare const TEMPLATE_VERSION = "1.7.0";
  * detail).
  *
  * Returns `true` iff both strings parse to objects whose `hooks.PreToolUse`
- * arrays satisfy that containment AND the on-disk `env` already carries every
- * exemption the template declares (extra on-disk keys and extra globs are
- * allowed — a user may exempt other trees, and a requirement the file already
- * exceeds must not re-trigger a write).
+ * arrays satisfy that containment, the on-disk file carries NO entry this
+ * template has retired (`isRetiredTemplateEntry`), AND the on-disk `env`
+ * already carries every exemption the template declares (extra on-disk keys
+ * and extra globs are allowed — a user may exempt other trees, and a
+ * requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -147,23 +167,18 @@ export declare function templateContentMatches(generated: string, onDisk: string
  * Non-conforming entries (no string `matcher`, no `hooks` array) are preserved
  * rather than dropped: guessing at their shape is how a user's entry gets
  * deleted.
+ *
+ * ONE exception to "preserve what I do not declare": an entry this template
+ * used to declare and RETIRED (TEMPLATE_VERSION 1.8.0's `Write|Edit|MultiEdit`
+ * gate — see `isRetiredTemplateEntry`) is dropped rather than preserved.
+ * Declaring less cannot retire an entry on its own, because preserving
+ * undeclared entries is exactly what this function does; without the drop, a
+ * pre-1.8.0 install would keep the no-op handler and its version-pinned script
+ * path forever. The predicate is narrow enough that only the exact command
+ * this template emitted matches.
  */
 export declare function mergeTemplateOwnedHooks(onDisk: ReadonlyArray<unknown>, template: ReadonlyArray<unknown>): unknown[];
-/**
- * Absolute path of the shipped Write|Edit|MultiEdit gate script.
- *
- * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
- * single relative filename resolves in BOTH trees: `src/services/hooks/` for
- * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
- * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
- * `package.json#files` already ships it).
- *
- * Separators are normalized to `/` so the emitted command contains no
- * backslash at all. That is what makes the handler shell-agnostic: bash
- * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
- * backslash in the string is one dialect's problem waiting to happen.
- */
-export declare function writeGateScriptPath(): string;
+export declare function isRetiredTemplateEntry(entry: unknown): boolean;
 type ClaudeHookCommand = {
     type: 'command';
     command: string;
@@ -192,10 +207,11 @@ type ClaudeSettingsLocal = {
  * forcing gate is a core feature that PreToolUse hooks can short-
  * circuit but that the `permissions` block cannot.
  *
- * As of TEMPLATE_VERSION 1.2.0, only the `Write|Edit|MultiEdit`
- * matcher is emitted. Bash command enforcement is the responsibility
- * of `peaks gate enforce`, which `peaks hooks install` injects into
- * `.claude/settings.json` (not `.claude/settings.local.json`).
+ * As of TEMPLATE_VERSION 1.8.0 the template emits the two `Bash` matchers
+ * only. The `Write|Edit|MultiEdit` fact-forcing bypass is no longer a hook:
+ * it is the `env` exemption above, and that matcher's gate
+ * (`peaks code-gate --json`) is installed into the committed
+ * `.claude/settings.json` by `peaks hooks install`.
  */
 export declare function buildClaudeSettingsLocalJson(): ClaudeSettingsLocal;
 export {};

package/dist/services/workspace/claude-settings-template.js

@@ -2,24 +2,31 @@
  * Slice 2.0.1-bug3-fact-forcing-bypass — pure-data template for the
  * consumer-project `.claude/settings.local.json` file.
  *
- * The template is a PreToolUse hook allow-list that bypasses the
- * Claude Code [Fact-Forcing Gate] for tool calls whose paths target
- * the peaks-managed `.peaks/` workspace. Without this bypass,
- * `peaks workspace init` (Step 0 of every peaks-code session) is
- * unrunnable in a consumer project because the gate blocks the very
- * first Write.
+ * The template exempts the peaks-managed `.peaks/` workspace from the
+ * Claude Code [Fact-Forcing Gate], so `peaks workspace init` (Step 0 of
+ * every peaks-code session) is runnable in a consumer project — without
+ * the exemption the gate blocks the very first Write.
+ *
+ * The exemption is declared in the `env` block
+ * (`EXTERNAL_GATE_EXEMPT_ENV`), which is what the gate actually reads.
+ * TEMPLATE_VERSION 1.7.0 moved it there; before that it was declared by a
+ * `Write|Edit|MultiEdit` handler that exited non-zero for non-`.peaks/`
+ * paths and was documented as "fall through to the gate". That concept does
+ * not exist in the Claude Code hook protocol (only exit 2 blocks; any other
+ * non-zero exit is a NON-BLOCKING ERROR reported once per edit), so the
+ * handler was corrected to abstain on every path — and an abstaining handler
+ * that is still INSTALLED is a no-op carrying a machine-specific absolute
+ * script path. TEMPLATE_VERSION 1.8.0 removed it rather than re-point it:
+ * it decided nothing, and the exemption it was written for lives in `env`.
  *
  * The template is a pure-data function (no filesystem, no clock) so
  * it can be unit-tested in isolation and so the on-disk file matches
  * the in-memory template byte-for-byte.
  *
- * One matcher is emitted:
- *   1. `Write|Edit|MultiEdit` — a `node <script>` handler that runs the
- *      path gate shipped at `src/services/hooks/write-gate.js`. Exits 0
- *      (allow) for the paths the gate skips, exit 1 (deny → fall through to
- *      gate) for everything else. TEMPLATE_VERSION 1.6.0 moved the decision
- *      out of an inlined `node -e "<js>"` one-liner, whose escaping was
- *      bash-specific and therefore could not take a platform `shell` pin.
+ * Two `Bash` matchers are emitted (the Step 0.8 mechanical gate and the
+ * SOP gate-enforce handler). No `Write|Edit|MultiEdit` entry is emitted:
+ * that matcher's gate is `peaks code-gate --json`, installed into the
+ * committed `.claude/settings.json` by `peaks hooks install`.
  *
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -33,8 +40,6 @@
  * consumer project's `.claude/settings.json` and which exits 0
  * silently for any command not guarded by a registered SOP gate.
  */
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { EXTERNAL_GATE_EXEMPT_ENV, hasExternalGateExemptions, resolveHookShell, resolveHookSpec } from '../skills/hooks-codegate-superpowers.js';
 export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
 /**
@@ -83,8 +88,20 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *           (`EXTERNAL_GATE_EXEMPT_ENV`). The comparator now requires the
  *           on-disk file to declare those exemptions too, so a project
  *           installed by an earlier release refreshes once and converges.
+ *   1.8.0 — REMOVED the `Write|Edit|MultiEdit` handler and the shipped
+ *           script it invoked (`src/services/hooks/write-gate.js`, also
+ *           deleted). The handler abstained on every path by design (see
+ *           that file's header for the rationale — it is the reason this
+ *           is a deletion and not a repair), so the only things it still
+ *           contributed were a `node "<abs path>"` command pinned to the
+ *           Node version directory that happened to be on `$PATH` at
+ *           install time, and a `shell: powershell` pin. The exemption it
+ *           was written to provide is declared by the `env` block above.
+ *           `mergeTemplateOwnedHooks` drops the retired entry from
+ *           existing on-disk files, so an earlier install converges
+ *           instead of keeping a no-op with a stale absolute path.
  */
-export const TEMPLATE_VERSION = '1.7.0';
+export const TEMPLATE_VERSION = '1.8.0';
 /**
  * Compare two serialized template strings: does the on-disk file already
  * declare every entry the generated tree declares?
@@ -111,10 +128,11 @@ export const TEMPLATE_VERSION = '1.7.0';
  * detail).
  *
  * Returns `true` iff both strings parse to objects whose `hooks.PreToolUse`
- * arrays satisfy that containment AND the on-disk `env` already carries every
- * exemption the template declares (extra on-disk keys and extra globs are
- * allowed — a user may exempt other trees, and a requirement the file already
- * exceeds must not re-trigger a write).
+ * arrays satisfy that containment, the on-disk file carries NO entry this
+ * template has retired (`isRetiredTemplateEntry`), AND the on-disk `env`
+ * already carries every exemption the template declares (extra on-disk keys
+ * and extra globs are allowed — a user may exempt other trees, and a
+ * requirement the file already exceeds must not re-trigger a write).
  *
  * Returns `false` on any `JSON.parse` error, shape mismatch, or
  * missing `hooks.PreToolUse`. Whitespace and key order do NOT affect
@@ -151,6 +169,23 @@ export function templateContentMatches(generated, onDisk) {
         }
         unmatched.splice(at, 1);
     }
+    // A RETIRED entry on disk is drift, and this clause is what makes the
+    // retirement in `mergeTemplateOwnedHooks` reach an installed file at all.
+    //
+    // Containment alone cannot express it: a file still carrying
+    // `Write|Edit|MultiEdit` declares every entry the template declares, so
+    // `templateContentMatches` answered "current", no rewrite ran, and the merge
+    // never got the chance to drop it. Measured on a throwaway project root
+    // before this clause existed — init against the rebuilt CLI reported
+    // `already-current` and the retired entry survived verbatim. Declaring less
+    // is not a retirement; the comparator has to say so.
+    //
+    // One extra rewrite per affected install, then the fixed point holds: the
+    // merge emits no retired entry, so the next comparison finds none and
+    // answers `current`.
+    if (parsedOnDisk.hooks.PreToolUse.some((entry) => isRetiredTemplateEntry(entry))) {
+        return false;
+    }
     // A project installed by a release that predates a template-declared
     // exemption still needs the refresh this comparator gates — otherwise the
     // entry would only ever appear on a machine that re-ran `peaks hooks
@@ -184,6 +219,15 @@ export function templateContentMatches(generated, onDisk) {
  * Non-conforming entries (no string `matcher`, no `hooks` array) are preserved
  * rather than dropped: guessing at their shape is how a user's entry gets
  * deleted.
+ *
+ * ONE exception to "preserve what I do not declare": an entry this template
+ * used to declare and RETIRED (TEMPLATE_VERSION 1.8.0's `Write|Edit|MultiEdit`
+ * gate — see `isRetiredTemplateEntry`) is dropped rather than preserved.
+ * Declaring less cannot retire an entry on its own, because preserving
+ * undeclared entries is exactly what this function does; without the drop, a
+ * pre-1.8.0 install would keep the no-op handler and its version-pinned script
+ * path forever. The predicate is narrow enough that only the exact command
+ * this template emitted matches.
  */
 export function mergeTemplateOwnedHooks(onDisk, template) {
     const slots = new Map();
@@ -195,6 +239,10 @@ export function mergeTemplateOwnedHooks(onDisk, template) {
     const taken = new Map();
     const preserved = [];
     for (const entry of onDisk) {
+        // Retired by this template — dropped, not carried across.
+        if (isRetiredTemplateEntry(entry)) {
+            continue;
+        }
         // Unowned by construction: not a shape the template could have declared.
         if (!isPreToolUseEntry(entry)) {
             preserved.push(entry);
@@ -249,44 +297,36 @@ function sameHooksArray(a, b) {
     return true;
 }
 /**
- * This module's own directory — `<root>/src/services/workspace` in the
- * source tree, `<root>/dist/services/workspace` in a build.
- *
- * Anchored on the running module rather than on `process.argv[1]`: the
- * same reason `daemon-supervisor.ts` documents — `argv[1]` is a different
- * file in each way the CLI is entered (`bin/peaks.js`, `src/cli/index.ts`
- * under tsx, `dist/cli/index.js` when invoked directly), whereas the
- * module's own location is the one fact that is always true.
- */
-const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
-/**
- * Absolute path of the shipped Write|Edit|MultiEdit gate script.
- *
- * `write-gate.js` is a plain `.js` (not a compiled `.ts`) precisely so this
- * single relative filename resolves in BOTH trees: `src/services/hooks/` for
- * `tsx` / vitest, `dist/services/hooks/` for an installed consumer (copied by
- * `scripts/copy-templates.mjs`; the `dist/**` `*.js` glob in
- * `package.json#files` already ships it).
+ * The retired `Write|Edit|MultiEdit` gate entry, as an on-disk file written by
+ * a pre-1.8.0 release holds it.
  *
- * Separators are normalized to `/` so the emitted command contains no
- * backslash at all. That is what makes the handler shell-agnostic: bash
- * reduces `\X` inside `"..."` and PowerShell escapes with a backtick, so any
- * backslash in the string is one dialect's problem waiting to happen.
- */
-export function writeGateScriptPath() {
-    return resolve(MODULE_DIR, '..', 'hooks', 'write-gate.js').replaceAll('\\', '/');
-}
-/**
- * Build the Write|Edit|MultiEdit matcher command.
+ * TEMPLATE_VERSION 1.8.0 stopped emitting this entry. Declaring less is not
+ * enough on its own: `mergeTemplateOwnedHooks` preserves every on-disk entry
+ * the template does not declare — that is the whole point of the entry-level
+ * ownership rule (it is what keeps `installAutoCompactHook`'s `Bash|Task`
+ * entry alive) — so a project installed by an earlier release would keep the
+ * no-op handler, and its `node "C:/…/nvm/v24.14.0/…"` path, forever. This
+ * predicate is the retirement: `mergeTemplateOwnedHooks` drops a match.
  *
- * TEMPLATE_VERSION 1.6.0: `node "<script>"` with NO inline payload. The
- * decision lives in `src/services/hooks/write-gate.js` and was relocated
- * there verbatim. Because there is nothing left to escape, this handler is
- * shell-dialect-independent and can carry the same platform `shell` pin as
- * its Bash siblings (see `resolveHookShell`).
+ * Deliberately narrow. It matches the exact command shape this template used
+ * to emit — one handler, `node "<…>/services/hooks/write-gate.js"` — under the
+ * exact legacy matcher spelling, so a user's OWN `Write|Edit|MultiEdit` entry
+ * (a different command, or more than one handler) is preserved like any other
+ * entry the template does not declare. A looser "drop anything on this
+ * matcher" rule would delete a user's hook, which is the failure the ownership
+ * rule exists to prevent.
  */
-function buildWriteHookCommand() {
-    return `node "${writeGateScriptPath()}"`;
+const RETIRED_WRITE_GATE_MATCHER = 'Write|Edit|MultiEdit';
+const RETIRED_WRITE_GATE_COMMAND = /^node "[^"]*\/services\/hooks\/write-gate\.js"$/;
+export function isRetiredTemplateEntry(entry) {
+    if (!isPreToolUseEntry(entry))
+        return false;
+    if (entry.matcher !== RETIRED_WRITE_GATE_MATCHER)
+        return false;
+    if (entry.hooks.length !== 1)
+        return false;
+    const handler = entry.hooks[0];
+    return handler.type === 'command' && RETIRED_WRITE_GATE_COMMAND.test(handler.command);
 }
 /**
  * TEMPLATE_VERSION 1.4.0 — the SOP gate-enforce handler, read from the same
@@ -311,39 +351,22 @@ function buildGateEnforceHandler() {
  * forcing gate is a core feature that PreToolUse hooks can short-
  * circuit but that the `permissions` block cannot.
  *
- * As of TEMPLATE_VERSION 1.2.0, only the `Write|Edit|MultiEdit`
- * matcher is emitted. Bash command enforcement is the responsibility
- * of `peaks gate enforce`, which `peaks hooks install` injects into
- * `.claude/settings.json` (not `.claude/settings.local.json`).
+ * As of TEMPLATE_VERSION 1.8.0 the template emits the two `Bash` matchers
+ * only. The `Write|Edit|MultiEdit` fact-forcing bypass is no longer a hook:
+ * it is the `env` exemption above, and that matcher's gate
+ * (`peaks code-gate --json`) is installed into the committed
+ * `.claude/settings.json` by `peaks hooks install`.
  */
 export function buildClaudeSettingsLocalJson() {
-    // TEMPLATE_VERSION 1.6.0 — the write handler can now be shell-pinned for the
-    // same Windows reason as the two Bash handlers below: a shell-form command is
-    // executed by Git Bash / MSYS2, which force-allocates a console window on
-    // every matching tool call. It could NOT take the pin while its payload was
-    // inlined JavaScript, because PowerShell does not perform bash's backslash
-    // reduction and would have corrupted the payload. `undefined` on POSIX omits
-    // the key entirely.
-    const writeShell = resolveHookShell();
     return {
-        // Slice emit-gateguard-exemption — the third-party gate exemption. Peaks
-        // already bypasses its OWN fact-forcing gate for `.peaks/**` (the
-        // Write|Edit|MultiEdit handler below); this is the same intent declared in
-        // the currency an external PreToolUse gate reads. `peaks hooks install`
-        // merges the same row into this file, so the two writers agree.
+        // Slice emit-gateguard-exemption — the third-party gate exemption. This is
+        // now the ONLY mechanism carrying the `.peaks/**` bypass (TEMPLATE_VERSION
+        // 1.8.0 removed the abstaining `Write|Edit|MultiEdit` handler that used to
+        // be described here). `peaks hooks install` merges the same row into this
+        // file, so the two writers agree.
         env: { ...EXTERNAL_GATE_EXEMPT_ENV },
         hooks: {
             PreToolUse: [
-                {
-                    matcher: 'Write|Edit|MultiEdit',
-                    hooks: [
-                        {
-                            type: 'command',
-                            command: buildWriteHookCommand(),
-                            ...(writeShell !== undefined ? { shell: writeShell } : {})
-                        }
-                    ]
-                },
                 {
                     // v3.1.2 Step 0.8 — Mechanical PreToolUse gate. Runs
                     // `peaks code gate-step-08 --project .` before every Bash
@@ -351,7 +374,6 @@ export function buildClaudeSettingsLocalJson() {
                     // describing the decision + optional `Next: slice #N+1 of
                     // M (<currentSlice>)` line when progress.json exists). Exit
                     // 2 = block (stderr contains the BLOCKED: ... reason).
-                    // The existing Write|Edit|MultiEdit matcher is preserved.
                     matcher: 'Bash',
                     hooks: [buildBashGateStep08Handler()]
                 },

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

@@ -0,0 +1,119 @@
+/**
+ * Version stamp for the artifacts `peaks workspace init` generates into a
+ * consumer project (G4, 2026-09-15).
+ *
+ * WHY THIS EXISTS. `initWorkspace` is the only writer of a consumer project's
+ * generated config: `.claude/settings.local.json`, the offline
+ * `.peaks/.claude-settings-template.json` copy, and the managed `.gitignore`
+ * snippet. `ensureSession` early-returns as soon as a session is bound —
+ * deliberately, see its own comment — so after the FIRST init nothing ever
+ * re-runs the generator. `npm i -g peaks-loop@<newer>` therefore upgrades the
+ * CLI and leaves the project's generated config exactly as the OLD release
+ * wrote it.
+ *
+ * `.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
+ * 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
+ * peaks-loop is 4.0.49".
+ *
+ * WHY A SEPARATE FILE AND NOT A KEY INSIDE THE ARTIFACTS.
+ * `.claude/settings.local.json` is read by Claude Code, which owns its schema;
+ * a version key peaks invented has no contract there and could be rejected or
+ * silently ignored — a stamp nobody reads is worse than none. `.peaks/_runtime/`
+ * is peaks' own gitignored tree and already holds exactly this kind of
+ * machine-local bookkeeping (`session.json`, `.outer-session-cache.json`), so
+ * the stamp lives beside them and needs no new `.gitignore` line.
+ *
+ * WHAT IS COMPARED. Two versions, because they move independently and a
+ * mismatch of either means the same thing to the user (regenerate):
+ *   - `packageVersion`  — the installed peaks-loop release. Moves on `npm i -g`.
+ *   - `templateVersion` — `TEMPLATE_VERSION`, the shape of the hooks tree this
+ *     release emits. Can move without a release the user would notice.
+ *
+ * The stamp records what the generator LAST WROTE. It is not a promise that
+ * the on-disk artifacts still match it — a user may have hand-edited
+ * `.claude/settings.local.json` since. That question is the existing
+ * `templateContentMatches` comparator's, and it is asked on the next init,
+ * which is what this detector tells the user to trigger.
+ */
+/**
+ * Where the stamp lives, relative to the project root.
+ *
+ * `.peaks/_runtime/` is gitignored by every peaks-loop project already (see
+ * the root `.gitignore` snippet), so this file never shows up in
+ * `git status` — which matters, because the whole point is that its content
+ * changes on the user's machine and not in their repository.
+ */
+export declare const GENERATED_ARTIFACTS_STAMP_RELATIVE_PATH: string;
+/**
+ * The artifacts whose generation the stamp describes. Used to answer "is
+ * there anything on disk that could be stale?" — a project that has never run
+ * `peaks workspace init` has nothing to refresh and must not be nagged.
+ */
+export declare const GENERATED_ARTIFACT_RELATIVE_PATHS: ReadonlyArray<string>;
+export type GeneratedArtifactsStamp = {
+    readonly stampVersion: 1;
+    readonly packageVersion: string;
+    readonly templateVersion: string;
+    readonly writtenAt: string;
+};
+export type GeneratedArtifactsStaleness = {
+    /** `true` only when a generated artifact exists AND its stamp is behind. */
+    readonly stale: boolean;
+    /**
+     * Machine-readable reason codes, empty when `stale` is false:
+     *   - `package-upgraded`   — on-disk stamp names an older peaks-loop release
+     *   - `template-changed`   — on-disk stamp names an older template shape
+     *   - `unstamped`          — artifacts exist but predate this stamp
+     *   - `stamp-unreadable`   — a stamp file exists but is not parseable
+     */
+    readonly reasons: ReadonlyArray<string>;
+    readonly onDisk: GeneratedArtifactsStamp | null;
+    readonly expected: {
+        readonly packageVersion: string;
+        readonly templateVersion: string;
+    };
+};
+export declare function generatedArtifactsStampPath(projectRoot: string): string;
+/**
+ * Read the stamp, or `null` when there is none / it is not the shape this
+ * module writes. Tolerant on purpose: a malformed stamp must degrade to
+ * "unstamped", never to a crash on the per-turn read path.
+ *
+ * The catch still NAMES what it tolerates rather than swallowing everything —
+ * the same correction the two P1 sites in this slice got (see
+ * `isExpectedFsMiss`). A missing file (raced away between `existsSync` and the
+ * read) and a stamp we cannot parse both mean "no usable stamp"; a
+ * `TypeError` from a broken dependency does not.
+ */
+export declare function readGeneratedArtifactsStamp(projectRoot: string): GeneratedArtifactsStamp | null;
+/**
+ * Record what the generator just wrote. Called by `initWorkspace` on every
+ * successful materialization — including the one that changes nothing —
+ * because the stamp's job is "when did a release last regenerate this
+ * project", not "when did the bytes change".
+ *
+ * `packageVersion` / `now` are injectable so a test can write a deliberately
+ * old stamp without touching the clock or the package.
+ */
+export declare function writeGeneratedArtifactsStamp(projectRoot: string, options?: {
+    readonly packageVersion?: string;
+    readonly now?: Date;
+}): GeneratedArtifactsStamp;
+/**
+ * Is this project's generated config behind the installed peaks-loop?
+ *
+ * Returns `stale: false` — with no reasons — for the two cases that are NOT
+ * staleness:
+ *   - the project has no generated artifact at all (never initialized), and
+ *   - the stamp matches both expected versions.
+ *
+ * `unstamped` is reported only when an artifact EXISTS and no stamp does:
+ * those are projects initialized by a release that predates this module, and
+ * they are exactly the population the defect was reported against.
+ */
+export declare function detectStaleGeneratedArtifacts(projectRoot: string): GeneratedArtifactsStaleness;