peaks-loop 3.0.0

package/scripts/sync-version.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const packageJson = JSON.parse(readFileSync(resolve('package.json'), 'utf8'));
+const version = packageJson.version;
+
+if (typeof version !== 'string' || version.length === 0) {
+  throw new Error('package.json version must be a non-empty string');
+}
+
+writeFileSync(resolve('src/shared/version.ts'), `export const CLI_VERSION = ${JSON.stringify(version)};\n`);

package/scripts/watch.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { watch as nodeWatch } from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { installBundledSkills } from './install-skills.mjs';
+
+export const WATCHED_INPUTS = ['src', 'schemas', 'skills'];
+export const DEFAULT_BUILD_COMMAND = ['pnpm', ['run', 'build']];
+
+function getErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function getErrorCode(error) {
+  return typeof error === 'object' && error !== null && 'code' in error ? error.code : undefined;
+}
+
+function isAbortError(error) {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+function isMissingPathError(error) {
+  return getErrorCode(error) === 'ENOENT';
+}
+
+export function runCommand(command, args, options = {}) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let child;
+
+    try {
+      child = spawn(command, args, { stdio: 'inherit', ...options });
+    } catch (error) {
+      rejectPromise(error);
+      return;
+    }
+
+    let settled = false;
+    const settle = (handler, value) => {
+      if (settled) {
+        return;
+      }
+
+      settled = true;
+      handler(value);
+    };
+
+    child.once('error', (error) => {
+      if (options.signal?.aborted || isAbortError(error)) {
+        const abortError = new Error(`${command} ${args.join(' ')} was aborted`);
+        abortError.name = 'AbortError';
+        settle(rejectPromise, abortError);
+        return;
+      }
+
+      settle(rejectPromise, error);
+    });
+
+    child.once('close', (code, signal) => {
+      if (code === 0) {
+        settle(resolvePromise);
+        return;
+      }
+
+      if (options.signal?.aborted || signal) {
+        const abortError = new Error(`${command} ${args.join(' ')} was aborted`);
+        abortError.name = 'AbortError';
+        settle(rejectPromise, abortError);
+        return;
+      }
+
+      settle(rejectPromise, new Error(`${command} ${args.join(' ')} failed with exit code ${code}`));
+    });
+  });
+}
+
+export async function collectDirectories(root) {
+  const directories = [];
+  const visited = new Set();
+
+  async function visit(directory) {
+    if (visited.has(directory)) {
+      return;
+    }
+
+    visited.add(directory);
+
+    let entries;
+    try {
+      entries = await readdir(directory, { withFileTypes: true });
+    } catch (error) {
+      if (isMissingPathError(error)) {
+        return;
+      }
+
+      throw error;
+    }
+
+    directories.push(directory);
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      await visit(join(directory, entry.name));
+    }
+  }
+
+  await visit(root);
+  return directories;
+}
+
+export function createDirectoryTreeWatcher(root, options = {}) {
+  const watch = options.watch ?? nodeWatch;
+  const collect = options.collectDirectories ?? collectDirectories;
+  const onChange = options.onChange ?? (() => {});
+  const watchers = new Map();
+  let refreshPromise = null;
+  let refreshRequested = false;
+  let isClosed = false;
+
+  const syncWatchers = async () => {
+    const directories = await collect(root);
+    const nextDirectories = new Set(directories);
+
+    for (const [directory, watcher] of watchers) {
+      if (nextDirectories.has(directory)) {
+        continue;
+      }
+
+      watcher.close();
+      watchers.delete(directory);
+    }
+
+    for (const directory of directories) {
+      if (watchers.has(directory)) {
+        continue;
+      }
+
+      const watcher = watch(directory, () => {
+        onChange();
+        void requestRefresh();
+      });
+      watchers.set(directory, watcher);
+    }
+  };
+
+  const requestRefresh = async () => {
+    if (isClosed) {
+      return;
+    }
+
+    refreshRequested = true;
+    if (refreshPromise) {
+      return refreshPromise;
+    }
+
+    refreshPromise = (async () => {
+      do {
+        refreshRequested = false;
+        await syncWatchers();
+      } while (refreshRequested && !isClosed);
+    })();
+
+    try {
+      await refreshPromise;
+    } finally {
+      refreshPromise = null;
+    }
+  };
+
+  return {
+    async start() {
+      await requestRefresh();
+    },
+    async close() {
+      isClosed = true;
+
+      if (refreshPromise) {
+        await refreshPromise.catch(() => undefined);
+      }
+
+      for (const watcher of watchers.values()) {
+        watcher.close();
+      }
+
+      watchers.clear();
+    }
+  };
+}
+
+export async function rebuildOnce(options = {}) {
+  const runner = options.runner ?? runCommand;
+  const installer = options.installer ?? installBundledSkills;
+  const [command, args] = options.command ?? DEFAULT_BUILD_COMMAND;
+
+  await runner(command, args, options.runOptions);
+  return installer(options.installOptions);
+}
+
+export function createWatchMode(options = {}) {
+  const inputs = options.inputs ?? WATCHED_INPUTS;
+  const createTreeWatcher = options.createTreeWatcher ?? createDirectoryTreeWatcher;
+  const runner = options.runner ?? runCommand;
+  const installer = options.installer ?? installBundledSkills;
+  const collectDirectoriesFn = options.collectDirectories ?? collectDirectories;
+  const watch = options.watch ?? nodeWatch;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const debounceMs = options.debounceMs ?? 150;
+  const treeWatchers = [];
+  let debounceTimer;
+  let isBuilding = false;
+  let hasQueuedRebuild = false;
+  let isClosed = false;
+  let currentAbortController = null;
+  let currentBuildPromise = null;
+
+  const writeStatus = (message) => stdout.write(`[peaks watch] ${message}\n`);
+  const writeError = (message) => stderr.write(`[peaks watch] ${message}\n`);
+
+  const rebuild = async (reason) => {
+    if (isClosed) {
+      return;
+    }
+
+    if (isBuilding) {
+      hasQueuedRebuild = true;
+      return currentBuildPromise ?? undefined;
+    }
+
+    isBuilding = true;
+    currentAbortController = new AbortController();
+    writeStatus(`${reason}: rebuilding dist and relinking skills`);
+
+    const buildPromise = (async () => {
+      try {
+        const result = await rebuildOnce({
+          runner,
+          installer,
+          runOptions: { signal: currentAbortController.signal }
+        });
+        const installed = result?.installed?.length ?? 0;
+        const skipped = result?.skipped?.length ?? 0;
+        writeStatus(`ready (${installed} skills linked, ${skipped} skipped)`);
+      } catch (error) {
+        if (isAbortError(error)) {
+          return;
+        }
+
+        writeError(`rebuild failed: ${getErrorMessage(error)}`);
+      } finally {
+        isBuilding = false;
+        currentAbortController = null;
+      }
+    })();
+
+    currentBuildPromise = buildPromise;
+
+    try {
+      await buildPromise;
+    } finally {
+      currentBuildPromise = null;
+      if (!isClosed && hasQueuedRebuild) {
+        hasQueuedRebuild = false;
+        await rebuild('queued change');
+      }
+    }
+  };
+
+  const scheduleRebuild = () => {
+    if (isClosed) {
+      return;
+    }
+
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+
+    debounceTimer = setTimeout(() => {
+      debounceTimer = undefined;
+      void rebuild('change detected');
+    }, debounceMs);
+  };
+
+  const closeTreeWatchers = async () => {
+    for (const treeWatcher of [...treeWatchers].reverse()) {
+      await treeWatcher.close();
+    }
+
+    treeWatchers.length = 0;
+  };
+
+  return {
+    async start() {
+      await rebuild('initial');
+
+      if (isClosed) {
+        return;
+      }
+
+      let startupFailed = false;
+      try {
+        for (const input of inputs) {
+          if (isClosed) {
+            break;
+          }
+
+          const treeWatcher = createTreeWatcher(input, {
+            watch,
+            collectDirectories: collectDirectoriesFn,
+            onChange: scheduleRebuild
+          });
+          treeWatchers.push(treeWatcher);
+          await treeWatcher.start();
+
+          if (isClosed) {
+            break;
+          }
+        }
+      } catch (error) {
+        startupFailed = true;
+        throw error;
+      } finally {
+        if (startupFailed || isClosed) {
+          await closeTreeWatchers();
+        }
+      }
+
+      if (!isClosed) {
+        writeStatus(`watching ${inputs.join(', ')}`);
+      }
+    },
+    async close() {
+      isClosed = true;
+
+      if (debounceTimer) {
+        clearTimeout(debounceTimer);
+        debounceTimer = undefined;
+      }
+
+      if (currentAbortController) {
+        currentAbortController.abort();
+      }
+
+      await closeTreeWatchers();
+
+      if (currentBuildPromise) {
+        await currentBuildPromise.catch(() => undefined);
+      }
+    }
+  };
+}
+
+async function main() {
+  const watchMode = createWatchMode();
+  let shuttingDown = false;
+
+  const shutdown = async () => {
+    if (shuttingDown) {
+      return;
+    }
+
+    shuttingDown = true;
+
+    try {
+      await watchMode.close();
+      process.stdout.write('[peaks watch] stopped\n');
+      process.exit(0);
+    } catch (error) {
+      process.stderr.write(`[peaks watch] ${getErrorMessage(error)}\n`);
+      process.exit(1);
+    }
+  };
+
+  process.once('SIGINT', () => void shutdown());
+  process.once('SIGTERM', () => void shutdown());
+
+  await watchMode.start();
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  main().catch((error) => {
+    process.stderr.write(`[peaks watch] ${getErrorMessage(error)}\n`);
+    process.exitCode = 1;
+  });
+}

package/skills/peaks-audit/SKILL.md

@@ -0,0 +1,151 @@
+---
+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.
+---
+
+## Single-scope-axis naming convention
+
+> **Read once at the top of this file; the rest of the skill is written against it.**
+
+The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, at `.peaks/_runtime/<sessionId>/...`) with a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` placeholders (NEVER bare `<sid>`). The peaks-cli change-id axis was removed in slice `2026-06-29-change-id-root-removal`; reviewable artifacts now live under `.peaks/_runtime/<sessionId>/<role>/...` only. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched. CLI mapping: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. Regression test `tests/unit/skills/skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) every `.peaks/_runtime/<X>/` has an axis label, (c) this callout is present.
+
+# Peaks-Cli Audit
+
+`peaks-audit` is the **first** step in any peaks-* workflow. It turns a human-expressed need into a 6-dimension audit plus a proposed goal, and refuses to let autonomous LLM work proceed on a partial audit. It is invoked IMMEDIATELY after the need is expressed, and BEFORE any PRD, RD, or QA work begins.
+
+## Precondition
+
+**None.** `peaks-audit` is the entry point; no other peaks-* skill runs first. If the user hands you a raw need with no accepted goal, audit it before doing anything else.
+
+## Hard contract — invoke IMMEDIATELY
+
+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
+                       ▲
+                       │
+              you are here on first contact
+```
+
+Do not start PRD, RD, or QA work on an unaudited need. The audit is what makes the downstream skill boundaries verifiable.
+
+## Trigger conditions
+
+Invoke `peaks-audit` when **any** of these are true:
+
+- A human just expressed a software-development need and no accepted `proposedGoal` exists yet.
+- A previous audit was rejected (any dimension missing, malformed JSON, or the user said "redo the audit").
+- A drift detector (peaks-doctor, peaks-solo) flagged that an in-flight slice lost its goal binding.
+- The user typed `/peaks-audit` or said "audit this", "scope this", "what would this take", "is this a good idea".
+
+Do NOT invoke peaks-audit when the user is asking for a code review, a test run, or a deployment — those are downstream skills.
+
+## Invocation
+
+### 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
+```
+
+> **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:
+
+**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`):
+
+```typescript
+import { auditGoal, IncompleteAuditError } from './services/audit/audit-goal-service.js';
+import type { LlmRunner } from './services/audit/audit-goal-service.js';
+
+try {
+  const output = await auditGoal({ need }, llmRunner);
+  // output is a fully validated AuditGoalOutput
+} catch (err) {
+  if (err instanceof IncompleteAuditError) {
+    // code === 'INCOMPLETE_AUDIT'
+    // autonomous work MUST NOT proceed — return to human
+  }
+  throw err;
+}
+```
+
+**2. File-mediated handoff** (used by `final-review-service` to read the human-approved goal):
+
+The approved goal is persisted at:
+
+```text
+.peaks/_runtime/<sessionId>/audit-goal/<rid>.json
+```
+
+`final-review-service` reads this file at the start of every final-review pass. The shape is exactly `AuditGoalOutput` (see Output below). The writer that produces this file is whatever upstream agent (peaks-audit, the slice LLMArbitrator, or a hand-authored call) ran the audit.
+
+## Output: `AuditGoalOutput`
+
+`auditGoal()` returns a frozen object with EXACTLY these top-level fields (per `src/services/audit/audit-goal-types.ts`):
+
+| Field | Type | Meaning |
+|---|---|---|
+| `summary` | `string` | 1–2 sentence restatement of the need. |
+| `audit` | `readonly AuditDimension[]` | EXACTLY 6 entries, one per dimension (see below). |
+| `proposedGoal` | `string` | What success looks like for the work. |
+| `successCriteria` | `readonly string[]` | Acceptance bullets QA can execute against. |
+| `roughEffort` | `'small' \| 'medium' \| 'large' \| 'epic'` | T-shirt size, not hours. |
+| `confidence` | `'high' \| 'medium' \| 'low'` | How certain the audit is of the need. |
+| `rationale` | `string` | One paragraph tying the audit findings to the proposed goal. |
+
+Each `AuditDimension` is:
+
+| Field | Type | Meaning |
+|---|---|---|
+| `dimension` | `AuditDimensionKind` | One of `correctness`, `completeness`, `scope`, `risks`, `alternatives`, `constraints`. |
+| `finding` | `string` | The audit observation for that dimension. |
+| `severity` | `'info' \| 'concern' \| 'blocker'` | Whether the dimension is healthy (`info`), suspicious (`concern`), or fatal (`blocker`). |
+
+→ see `references/6-dimensions.md` for the per-dimension contract + `info` / `concern` / `blocker` definitions.
+
+## One-shot accuracy (HARD contract)
+
+The audit MUST be good enough that a human can accept the `proposedGoal` on the **first** review. The whole point of the primitive is to compress the LLM's understanding of a need into something a human can OK in one read.
+
+That means:
+
+- `proposedGoal` is one sentence, not a paragraph.
+- `successCriteria` are executable, not aspirational ("`peaks audit red-lines` exits 0" is good; "tests pass" is bad).
+- Every dimension has a `severity`. `info` is the default; reserve `concern` for things the human should weigh in on; reserve `blocker` for things that make the work **unsafe to start**.
+- `rationale` ties the findings to the goal in 3–6 sentences, no marketing.
+- `roughEffort` is honest. If you do not know, say `large`. Do not pre-shrink.
+- `confidence` is honest. If the LLM is guessing, say `low`. Do not over-claim.
+
+If the audit comes back vague, the LLM was lazy. Re-prompt the LLM with the original `need` + a reminder to be specific. Do not edit the audit output by hand — the service rejects malformed JSON or missing dimensions, and an in-place patch will be silently rejected downstream.
+
+## Failure mode (BLOCKING — read before declaring a workflow started)
+
+`auditGoal()` is the **unit of validation**. It rejects any LLM response that:
+
+1. Is not valid JSON.
+2. Is missing any of the top-level fields (`summary`, `audit`, `proposedGoal`, `successCriteria`, `roughEffort`, `confidence`, `rationale`).
+3. Has an `audit` array that does not cover all 6 dimensions (`correctness`, `completeness`, `scope`, `risks`, `alternatives`, `constraints`).
+
+When any of these triggers, the service throws `IncompleteAuditError` with `code === 'INCOMPLETE_AUDIT'`. The error is the gate signal. Autonomous work MUST NOT proceed on a partial audit. The contract is:
+
+- **Caller obligation** — if you catch `IncompleteAuditError`, return the error to the human (or the parent skill). Do not retry silently. Do not fill in the missing dimension yourself.
+- **Downstream obligation** — `peaks-prd`, `peaks-rd`, `peaks-qa` MUST check that an accepted `AuditGoalOutput` exists in the artifact workspace before they start. If absent, they refuse to start and route back to `peaks-audit`.
+
+This is the only validation contract the primitive enforces. It is intentionally narrow so the LLM has room to be creative, but the missing-dimension check is non-negotiable.
+
+## When NOT to use peaks-audit
+
+- **The user has already accepted a goal.** Re-auditing is wasteful; route to `peaks-prd` or `peaks-rd` directly.
+- **The need is a refactor with no behavior change.** `peaks-rd` can run its own regression matrix without a full 6-dim audit; route there with a `refactor-only` flag.
+- **The need is operational (deploy, rollback, rotate secret).** Route to `peaks-doctor` or a runbook skill, not the audit primitive.
+- **You are mid-slice and the goal drifted.** Trigger `peaks-audit` again to re-bind the goal, then continue. Do not silently update the goal in place.
+
+## References
+
+| File | Coverage |
+|---|---|
+| `references/6-dimensions.md` | Per-dimension definition, severity rules, examples. |

package/skills/peaks-audit/references/6-dimensions.md

@@ -0,0 +1,141 @@
+# The 6 audit dimensions
+
+The `auditGoal()` primitive (`src/services/audit/audit-goal-service.ts`) rejects any LLM response that does not cover all six dimensions below. Each dimension is one entry in the `audit` array of `AuditGoalOutput`, shaped as `{ dimension, finding, severity }`. Severity is one of `info`, `concern`, `blocker`.
+
+## Severity recap (applies to every dimension)
+
+| Severity | Meaning | Caller action |
+|---|---|---|
+| `info` | Dimension is healthy. The audit is just recording a fact, not flagging risk. | None. Note it and move on. |
+| `concern` | Dimension is suspicious. The human should weigh in before the work starts. | Surface in the rationale; humans accept or amend the proposed goal. |
+| `blocker` | Dimension is fatal. The work MUST NOT proceed in its current shape. | Refuse to start; require the human to re-scope the need. |
+
+`blocker` is the only severity that hard-stops the workflow. `concern` is advisory. `info` is bookkeeping.
+
+---
+
+## 1. correctness
+
+**Definition.** Does the proposed work actually solve the problem the user described, or is it solving a different problem? Checks whether the LLM's restatement matches the human's intent and whether the goal's success criteria measure the right thing.
+
+| Severity | When it applies |
+|---|---|
+| `blocker` | The proposed goal solves a different problem than the need. Audit restates the need incorrectly. |
+| `concern` | Goal is plausible but the success criteria measure a proxy, not the actual outcome. |
+| `info` | Goal aligns with need; criteria measure the right thing. |
+
+**Example.**
+
+```text
+{ dimension: 'correctness',
+  finding: 'Need says "speed up the doctor report"; goal adds a new check that does not affect report latency.',
+  severity: 'blocker' }
+```
+
+---
+
+## 2. completeness
+
+**Definition.** Is anything obviously missing from the proposed goal — implicit requirements, edge cases, or "while you're at it" work the user almost certainly meant? Checks whether the goal captures the full surface of the need or only part of it.
+
+| Severity | When it applies |
+|---|---|
+| `blocker` | Goal ignores a stated part of the need. (e.g. need says "test + ship" and goal only covers test.) |
+| `concern` | Goal covers the literal need but skips an obvious adjacent surface (migration, rollback, telemetry). |
+| `info` | Goal captures the full need. |
+
+**Example.**
+
+```text
+{ dimension: 'completeness',
+  finding: 'Need mentions "migrate the old config"; goal covers the migration but not the rollback path.',
+  severity: 'concern' }
+```
+
+---
+
+## 3. scope
+
+**Definition.** Is the proposed goal sized appropriately for the change? Too big = `epic` masquerading as `medium`; too small = goal that ships nothing useful. Checks whether the LLM respected the implied boundary of the need.
+
+| Severity | When it applies |
+|---|---|
+| `blocker` | Goal swallows a much larger refactor than the need implies. (e.g. user asked for a flag, goal is to rewrite the module.) |
+| `concern` | Goal is a bit larger than the need warrants, or `roughEffort` understates what the success criteria imply. |
+| `info` | Scope matches the need; `roughEffort` is honest. |
+
+**Example.**
+
+```text
+{ dimension: 'scope',
+  finding: 'Need: "add a --json flag". Goal: refactor the entire output layer. roughEffort: small.',
+  severity: 'blocker' }
+```
+
+---
+
+## 4. risks
+
+**Definition.** What can go wrong, both during the work and after it ships? Includes data loss, regression, performance, security, operability, and human-process risks. Checks whether the LLM surfaced the things a senior engineer would have flagged.
+
+| Severity | When it applies |
+|---|---|
+| `blocker` | A known irreversible risk is unaddressed (data loss, security regression, breaking public API). |
+| `concern` | A real risk that the goal does not mitigate (no rollback plan, no migration safety, no perf baseline). |
+| `info` | Risks are surfaced and either mitigated or explicitly accepted. |
+
+**Example.**
+
+```text
+{ dimension: 'risks',
+  finding: 'Goal rewrites the public API without a deprecation window. Consumers break on upgrade.',
+  severity: 'blocker' }
+```
+
+---
+
+## 5. alternatives
+
+**Definition.** Did the LLM consider other ways to solve the need, and is the chosen approach actually the best one? Checks whether the goal is the result of a real choice, not the only path the LLM thought of. A "no alternatives considered" finding is a `concern` because the human has nothing to compare against.
+
+| Severity | When it applies |
+|---|---|
+| `blocker` | The chosen approach has a known fatal flaw that an obvious alternative avoids. (e.g. "writes a custom parser" when a battle-tested library exists.) |
+| `concern` | No alternatives were considered, or the rationale does not explain why the chosen approach beats them. |
+| `info` | One or more alternatives are noted, with a clear reason the chosen approach wins. |
+
+**Example.**
+
+```text
+{ dimension: 'alternatives',
+  finding: 'Goal hand-rolls a JSON schema validator. `zod` is already a project dep.',
+  severity: 'concern' }
+```
+
+---
+
+## 6. constraints
+
+**Definition.** What non-negotiable boundaries does the work have to respect? Includes public APIs that must not change, dependencies that cannot be added, performance budgets, security policies, regulatory constraints, deployment windows, and human-time constraints. Checks whether the goal acknowledges the walls around the work.
+
+| Severity | When it applies |
+|---|---|
+| `blocker` | The goal violates a known constraint (e.g. "add a new dep" when the project is dep-free; "rewrite the auth path" when security review is locked). |
+| `concern` | A real constraint is unaddressed (no migration window, no review gate, no perf budget). |
+| `info` | Constraints are acknowledged and respected. |
+
+**Example.**
+
+```text
+{ dimension: 'constraints',
+  finding: 'Project is pinned to Node 18. Goal uses `node:test` snapshot matchers added in Node 22.',
+  severity: 'blocker' }
+```
+
+---
+
+## Putting it together
+
+A complete audit has all six entries, each with a non-empty `finding` and an honest `severity`. The human reads `summary` first, scans the `blocker` lines (if any), then reads the `concern` lines to decide whether to amend the `proposedGoal`. The `info` lines are the floor — they exist so the human trusts that the dimension was actually checked.
+
+If any dimension is missing, the `auditGoal()` service throws `IncompleteAuditError` (`code: 'INCOMPLETE_AUDIT'`). The error is a hard gate: autonomous work does not proceed. The fix is to re-prompt the LLM with the original need, not to patch the audit by hand.