peaks-loop 4.0.38 → 4.0.40

package/dist/services/workflow/provision-dispatch-node.d.ts

@@ -0,0 +1,42 @@
+export interface ProvisionedDispatchNode {
+    readonly nodeId: string;
+    readonly workflowId: string;
+    readonly graphRef: string;
+    /** True when this call created the graph; false when it appended to one. */
+    readonly graphCreated: boolean;
+}
+/**
+ * Bind a dispatch to a graph node, creating the graph and the node when
+ * they do not exist yet.
+ *
+ * Why this exists. `--graph-node` was a `.requiredOption`, and the failure
+ * message told the caller to "Prepare a graph node via
+ * `peaks workflow node prepare` and re-run dispatch". That instruction was
+ * unwalkable:
+ *
+ *   - `workflow node prepare` never calls `writeGraph`, so the node it
+ *     reports is never persisted — it is printed into the envelope's
+ *     `graph` field (which is a single NODE, not a graph) and dropped;
+ *   - the graph that command reads must already exist, and no CLI verb
+ *     creates one.
+ *
+ * So the documented three-step ritual had no viable first step anywhere
+ * outside peaks-loop's own tree, while the flag itself guaranteed nothing:
+ * `dispatch-record-writer` treats the graph transition as best-effort and
+ * silently returns when the node is absent, and `PEAKS_GRAPH_NODE_NOT_PREPARED`
+ * is imported but never thrown on this path. A required parameter that is
+ * never validated, blocking every consumer project, is pure friction.
+ *
+ * Provisioning makes the binding cheap and real instead: the node exists
+ * from the first dispatch, so the transition in the record writer has
+ * something to find.
+ */
+export declare function provisionDispatchNode(input: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly role: string;
+    readonly workflowId?: string | undefined;
+    readonly graphRef?: string | undefined;
+    /** Injectable for tests; defaults to `Date.now()`. */
+    readonly now?: (() => number) | undefined;
+}): ProvisionedDispatchNode;

package/dist/services/workflow/provision-dispatch-node.js

@@ -0,0 +1,66 @@
+import { emptyGraph, readGraph, writeGraph, PEAKS_GRAPH_NOT_FOUND } from './workflow-graph-store.js';
+import { WORKFLOW_ID_REGEX } from './workflow-graph-types.js';
+/**
+ * Bind a dispatch to a graph node, creating the graph and the node when
+ * they do not exist yet.
+ *
+ * Why this exists. `--graph-node` was a `.requiredOption`, and the failure
+ * message told the caller to "Prepare a graph node via
+ * `peaks workflow node prepare` and re-run dispatch". That instruction was
+ * unwalkable:
+ *
+ *   - `workflow node prepare` never calls `writeGraph`, so the node it
+ *     reports is never persisted — it is printed into the envelope's
+ *     `graph` field (which is a single NODE, not a graph) and dropped;
+ *   - the graph that command reads must already exist, and no CLI verb
+ *     creates one.
+ *
+ * So the documented three-step ritual had no viable first step anywhere
+ * outside peaks-loop's own tree, while the flag itself guaranteed nothing:
+ * `dispatch-record-writer` treats the graph transition as best-effort and
+ * silently returns when the node is absent, and `PEAKS_GRAPH_NODE_NOT_PREPARED`
+ * is imported but never thrown on this path. A required parameter that is
+ * never validated, blocking every consumer project, is pure friction.
+ *
+ * Provisioning makes the binding cheap and real instead: the node exists
+ * from the first dispatch, so the transition in the record writer has
+ * something to find.
+ */
+export function provisionDispatchNode(input) {
+    // A caller-supplied workflowId is honoured only when it is well-formed;
+    // the option was previously ignored outright, so falling back is strictly
+    // additive, and the effective id is returned so the choice is visible.
+    const workflowId = typeof input.workflowId === 'string' && WORKFLOW_ID_REGEX.test(input.workflowId)
+        ? input.workflowId
+        : `dispatch-${input.sessionId}`;
+    const graphRef = input.graphRef ?? `graphs/${workflowId}.json`;
+    let graph;
+    let graphCreated = false;
+    try {
+        graph = readGraph({ projectRoot: input.projectRoot, sessionId: input.sessionId, graphRef, workflowId });
+    }
+    catch (err) {
+        if (err.code !== PEAKS_GRAPH_NOT_FOUND)
+            throw err;
+        // `emptyGraph` supplies the one terminal node `validateGraph` requires.
+        graph = emptyGraph({ workflowId, rootSkill: 'peaks-code' });
+        graphCreated = true;
+    }
+    const stamp = (input.now ?? Date.now)().toString(36);
+    const nodeId = `dispatch-${input.role}-${stamp}`;
+    const node = {
+        id: nodeId,
+        kind: 'dispatch',
+        label: `${input.role} dispatch`,
+        status: 'prepared',
+        dependsOn: [],
+    };
+    writeGraph({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        graphRef,
+        workflowId,
+        graph: { ...graph, nodes: [...graph.nodes, node] },
+    });
+    return { nodeId, workflowId, graphRef, graphCreated };
+}

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

@@ -10,7 +10,7 @@
  * and behaviour are unchanged (verbatim move).
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { mkdir, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { withExternalGateExemptions } from '../skills/hooks-codegate-superpowers.js';
 import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
@@ -59,6 +59,8 @@ const PEAKS_GITIGNORE_SNIPPET = [
     '# Gitignored so the init flow\'s drift-driven refresh does not show up as',
     '# "modified" in `git status` on every release bump. Recovery path: re-run',
     '# `peaks workspace init` to regenerate; or copy from peaks-loop source.',
+    '# Both patterns below are PROJECT-ROOT-relative, so this snippet must land',
+    '# in the root .gitignore — see `upsertPeaksGitignoreSnippet`.',
     '.peaks/.claude-settings-template.json',
     PEAKS_GITIGNORE_FOOTER,
     ''
@@ -194,13 +196,70 @@ async function writeOfflineTemplateCopy(projectRoot, serialized) {
     return action;
 }
 /**
- * Append the peaks-managed `.claude/settings.local.json` snippet to
- * the consumer project's `.peaks/.gitignore`. Preserves any user-
- * managed entries above the snippet. Idempotent: re-running on a
- * project that already has the snippet is a no-op.
+ * Append the peaks-managed snippet to the consumer project's ROOT
+ * `.gitignore`. Preserves any user-managed entries above the snippet.
+ * Idempotent: re-running on a project that already has the snippet is a
+ * no-op.
+ *
+ * Root, not `.peaks/.gitignore`. A gitignore pattern containing a slash is
+ * anchored to the directory of the .gitignore that holds it, and both
+ * patterns here are project-root-relative. Written into `.peaks/.gitignore`
+ * they resolved to `.peaks/.claude/settings.local.json` and
+ * `.peaks/.peaks/.claude-settings-template.json` — matching nothing, in
+ * every project. The root-level `settings.local.json` entry could not be
+ * expressed from inside `.peaks/` at all, since gitignore has no `..`.
+ */
+/**
+ * The snippet's former home. Projects initialized before the move carry a
+ * managed block there that now matches nothing and is maintained by nobody —
+ * yet still announces itself as "do not edit by hand", which is worse than
+ * absent: a reader takes it for live configuration.
  */
+const LEGACY_PEAKS_GITIGNORE_PATH = ['.peaks', '.gitignore'];
+/**
+ * Strip the managed block from its legacy home, preserving every line the
+ * user wrote. Idempotent; a no-op on projects that never had one.
+ *
+ * The file is deleted only when nothing remains. An empty `.peaks/.gitignore`
+ * left behind reads as "peaks put something here and stopped", which invites
+ * the next reader to guess.
+ *
+ * A malformed block (header without footer) is left untouched rather than
+ * guessed at — deleting a user's file to tidy our own mess is not a trade
+ * worth making.
+ */
+async function stripLegacyPeaksGitignoreSnippet(projectRoot) {
+    const legacyPath = join(projectRoot, ...LEGACY_PEAKS_GITIGNORE_PATH);
+    if (!existsSync(legacyPath))
+        return;
+    let existing;
+    try {
+        existing = await readFile(legacyPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    const start = existing.indexOf(PEAKS_GITIGNORE_HEADER);
+    if (start === -1)
+        return;
+    const footerAt = existing.indexOf(PEAKS_GITIGNORE_FOOTER, start);
+    if (footerAt === -1)
+        return;
+    const remainder = (existing.slice(0, start) + existing.slice(footerAt + PEAKS_GITIGNORE_FOOTER.length))
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+    if (remainder.length === 0) {
+        await rm(legacyPath, { force: true });
+        return;
+    }
+    await writeFile(legacyPath, `${remainder}\n`, 'utf8');
+}
 async function upsertPeaksGitignoreSnippet(projectRoot) {
-    const gitignorePath = join(projectRoot, '.peaks', '.gitignore');
+    // Migration first: the snippet used to live in `.peaks/.gitignore`, where
+    // its patterns silently matched nothing. Strip that copy before writing the
+    // one that works.
+    await stripLegacyPeaksGitignoreSnippet(projectRoot);
+    const gitignorePath = join(projectRoot, '.gitignore');
     await mkdir(join(projectRoot, '.peaks'), { recursive: true });
     let existing = '';
     if (existsSync(gitignorePath)) {

package/dist/shared/npm-cache.d.ts

@@ -0,0 +1,2 @@
+/** `<npm cache>/_npx` candidates: the per-user defaults, and nothing else. */
+export declare function npmExecCacheRoots(): string[];

package/dist/shared/npm-cache.js

@@ -0,0 +1,31 @@
+/**
+ * Where npm puts its per-user exec (`npx`) cache.
+ *
+ * This list lives in exactly ONE place on purpose: whoever resolves a package
+ * out of that cache (the Playwright loader `import()`s what it finds, the OCR
+ * probe reports it as installed) is answering the same question — "is this
+ * package already here?" — and a second copy of the roots is a second answer
+ * that would drift from this one.
+ *
+ * `npm_config_cache` / `NPM_CONFIG_CACHE` are deliberately NOT honoured: under
+ * `npm run`, npm exports the value a repo's own `.npmrc` chose, so trusting
+ * them lets a committed `.npmrc` select the tree that gets executed. The
+ * default roots below are where npm actually puts an `npx` cache.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** `<npm cache>/_npx` candidates: the per-user defaults, and nothing else. */
+export function npmExecCacheRoots() {
+    // Resolved per call, never at module load: callers that relocate the home
+    // (tests, and any future sandboxed run) must see the relocation.
+    const roots = [join(homedir(), '.npm', '_npx')];
+    if (process.platform === 'win32') {
+        for (const key of ['LOCALAPPDATA', 'APPDATA']) {
+            const base = process.env[key];
+            if (base !== undefined && base.length > 0) {
+                roots.push(join(base, 'npm-cache', '_npx'));
+            }
+        }
+    }
+    return roots;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "4.0.38",
+  "version": "4.0.40",
   "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.23",
-    "peaks-loop-shared": "0.0.72",
-    "peaks-loop-mut": "0.1.36",
-    "peaks-loop-shared-channel": "0.0.40"
+    "peaks-loop-internal-runtime": "0.0.25",
+    "peaks-loop-shared": "0.0.74",
+    "peaks-loop-shared-channel": "0.0.42",
+    "peaks-loop-mut": "0.1.38"
   },
   "devDependencies": {
     "@changesets/cli": "2.31.1",

package/skills/bee/peaks-perf-audit/SKILL.md

@@ -6,12 +6,40 @@ metadata:
   appliesTo: peaks-loop v2.12.0+
   replaces: peaks-rd 5-way fan-out perf-baseline-reviewer slot (per AC-3.x)
   sources:
-    - handoff: .peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)
-    - template: .peaks/project-scan/perf-template.md (git-tracked, schemaVersion: 1)
-    - output: .peaks/_runtime/<sessionId>/audit/perf-<rid>.md (frontmatter schemaVersion: 1)
+    - handoff: ".peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)"
+    - template: ".peaks/project-scan/perf-template.md (git-tracked, schemaVersion: 1)"
+    - output: ".peaks/_runtime/<sessionId>/audit/perf-<rid>.md (frontmatter schemaVersion: 1)"
     - schema: .peaks/project-scan/audit-output-schema.md
 ---
 
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
+
 # peaks-perf-audit
 
 > **Independent performance audit skill** — separate from `peaks-rd`'s

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

@@ -7,6 +7,34 @@ description: |
   acceptance criteria, product change proposals, or user-confirmable product artifacts.
 visibility: internal
 ---
+
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
 ---
 
 # Peaks-Loop PRD

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

@@ -7,6 +7,34 @@ description: |
   baseline reports, validation reports, acceptance checks, or refactor verification gates.
 visibility: internal
 ---
+
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
 ---
 
 ## Single-scope-axis naming convention

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

@@ -8,6 +8,34 @@ description: |
   Always use this for Peaks-Loop refactor workflows.
 visibility: internal
 ---
+
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
 ---
 
 ## Single-scope-axis naming convention

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

@@ -4,6 +4,34 @@ visibility: internal
 description: Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.
 ---
 
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
+
 ## Single-scope-axis naming convention
 
 > **Read once at the top of this file; the rest of the skill is written against it.**

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

@@ -7,6 +7,34 @@ description: |
   GitHub artifact repository pointers, sync state, or rollback evidence.
 visibility: internal
 ---
+
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
 ---
 
 # Peaks-Loop SC

package/skills/bee/peaks-security-audit/SKILL.md

@@ -6,12 +6,40 @@ metadata:
   appliesTo: peaks-loop v2.12.0+
   replaces: peaks-rd 5-way fan-out security-reviewer slot (per AC-2.x)
   sources:
-    - handoff: .peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)
-    - template: .peaks/project-scan/security-template.md (git-tracked, schemaVersion: 1)
-    - output: .peaks/_runtime/<sessionId>/audit/security-<rid>.md (frontmatter schemaVersion: 1)
+    - handoff: ".peaks/_runtime/<sessionId>/prd/handoff.md (sha256-locked, schemaVersion: 2)"
+    - template: ".peaks/project-scan/security-template.md (git-tracked, schemaVersion: 1)"
+    - output: ".peaks/_runtime/<sessionId>/audit/security-<rid>.md (frontmatter schemaVersion: 1)"
     - schema: .peaks/project-scan/audit-output-schema.md
 ---
 
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
+
 # peaks-security-audit
 
 > **Independent security audit skill** — separate from `peaks-rd`'s

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

@@ -7,6 +7,34 @@ description: |
   assumptions, discarded options, staleness checks, lessons, or reusable project memory.
 visibility: internal
 ---
+
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
 ---
 
 # Peaks-Loop TXT

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

@@ -7,6 +7,34 @@ description: |
   frontend page behavior, high-fidelity HTML prototypes, or UI regression seeds.
 visibility: internal
 ---
+
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
 ---
 
 # Peaks-Loop UI

package/skills/peaks-audit/SKILL.md

@@ -3,6 +3,34 @@ name: peaks-audit
 description: Gate autonomous LLM work on a 6-dimension audit + user-accepted goal. Use IMMEDIATELY after a need is expressed, BEFORE any PRD/RD/QA work starts.
 ---
 
+<!-- peaks:loop-hygiene — generated block; keep byte-identical in every SKILL.md -->
+
+## Loop hygiene (every turn — MANDATORY)
+
+**Skill header.** While this skill is active, open every turn with
+`Peaks-Loop Skill: <skill> | Peaks-Loop Gate: <gate> | Next: <one short action>`.
+Every turn, not only the first — it is how the user knows which skill is driving.
+
+**Context is this skill's own business.** Run `peaks skill presence --json` every turn and
+read its `context` block. When `action` is `auto-fire`, `pre-compact`, or `red-line`,
+run `peaks code auto-compact --project .` **yourself**, then continue. Tell the user the
+ratio in one line if it helps, but never hand them the compaction step: asking the user to
+run `/compact` is the regression the zero-pause contract forbids. This holds in **every
+mode** — standard *and* 24h. The mode moves the threshold, never the obligation.
+
+**Read before you edit.** Read a file before your first `Edit` / `Write` / `MultiEdit` on
+it — the normal way to work here — for every path outside `.peaks/**` (source, tests, docs,
+config); `.peaks/**` writes are exempt.
+
+**Expect one denial per file regardless.** A `PreToolUse` gate (ECC's "Fact-Forcing Gate")
+denies the FIRST edit a session makes to any given path, once, by design. Reading does NOT
+prevent it — the gate keys on the path's first touch, not on whether you read it. **A denial
+is not a failure and the tool is not broken — your edit was NOT applied.** State the facts it
+asks for (importers, affected API, data schemas if any, the user's verbatim instruction) and
+retry the SAME operation; the retry is allowed. Do not switch tools, do not give up, do not
+retry blindly.
+<!-- /peaks:loop-hygiene -->
+
 ## Single-scope-axis naming convention
 
 > **Read once at the top of this file; the rest of the skill is written against it.**