peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/skills/hooks-settings-service.js

@@ -200,6 +200,126 @@ function resolveLegacySentinels(ide) {
     }
     return [HOOK_ENFORCE_SENTINEL, LEGACY_PROGRESS_START_SENTINEL];
 }
+// --- Slice 2026-07-29-worktree-layer3-deny -----------------------------------
+// Layer 3 of the Worktree Governance 3-layer design (see
+// .peaks/memory/2026-07-29-worktree-layer3-deny.md). The gateway is the IDE
+// native `permissions.deny` list — Claude Code refuses to invoke any Skill
+// listed there BEFORE the LLM even sees it. This is the strongest of the three
+// layers because it bypasses the LLM's tool-call decision entirely: the IDE
+// matches the deny entry against the Skill's namespace and returns a
+// permission error, so the LLM observes "skill not available" rather than
+// "skill denied" — true fail-closed.
+//
+// The list is intentionally tiny: only skills that the superpowers chain
+// *forces* downstream from peaks-loop work paths. We do NOT deny every
+// superpowers skill — only the one whose `description` field or SKILL.md body
+// recommends `git worktree add` / native worktree tools as a step. Anything
+// else stays available as a reference (peaks-code's
+// references/external-skill-invocation.md already describes every other
+// superpowers skill as informational).
+//
+// The IDE expects the deny entry in the form `UseSkill(<skill-id>)`. The
+// prefix is fixed; the skill id is the namespace-qualified name. We render
+// the entries at install time and at uninstall time so the sentinel list is
+// the single source of truth.
+/**
+ * The set of Skills whose use is denied at the IDE permissions layer for
+ * every `peaks hooks install` call. Each entry is the namespace-qualified
+ * skill id; the helper `formatSuperpowersDenyEntry` wraps it in the IDE's
+ * `UseSkill(...)` envelope.
+ *
+ * Slice 2026-07-29-worktree-layer3-deny: the list is empty-aware. To deny a
+ * new skill, append its id here and re-run `peaks hooks install`. The list
+ * is also the inverse for uninstall: `removeHookInstall` rebuilds the deny
+ * list by filtering out anything whose wrapped form matches one of these
+ * ids.
+ */
+export const SUPERPOWERS_DENIED_SKILLS = [
+    // superpowers:using-git-worktrees is the chain's "ground zero" — its
+    // SKILL.md (lines 47-99) literally instructs the LLM to run
+    // `git worktree add`. Denying this Skill at the IDE layer prevents the
+    // LLM from ever receiving that prompt.
+    'superpowers:using-git-worktrees'
+];
+function formatSuperpowersDenyEntry(skillId) {
+    return `UseSkill(${skillId})`;
+}
+const SUPERPOWERS_DENY_SENTINELS = new Set(SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry));
+/**
+ * Merge the peaks-managed Skill denylist into the existing settings object.
+ * Preserves every other `permissions.deny` entry the user (or another tool)
+ * has written so the install is additive, not destructive. The output is
+ * always deterministic: the same input always yields the same output,
+ * regardless of insertion order in the source array.
+ *
+ * Defensive behavior:
+ * - `settings.permissions` is missing or non-object → install creates a
+ *   fresh `permissions: { deny: [...our entries] }` object.
+ * - `settings.permissions.deny` is missing or non-array → install replaces
+ *   the field with a fresh array containing only our entries.
+ * - Duplicate entries (any source) are collapsed to one via `new Set`.
+ *
+ * The function is pure: it does not mutate the input. Atomic write happens
+ * at the call site (`applyHookInstall`).
+ */
+export function withSuperpowersSkillDenylist(settings) {
+    const ourEntries = SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry);
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    const existingDeny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    const otherDeny = existingDeny.filter((d) => !SUPERPOWERS_DENY_SENTINELS.has(d));
+    const finalDeny = [...new Set([...otherDeny, ...ourEntries])];
+    return {
+        ...settings,
+        permissions: { ...permissions, deny: finalDeny }
+    };
+}
+/**
+ * Inverse of `withSuperpowersSkillDenylist`. Removes every peaks-managed
+ * `UseSkill(...)` entry from the deny list. If the resulting deny list is
+ * empty, the `deny` field itself is deleted; if the `permissions` object
+ * becomes empty, the `permissions` field itself is deleted. This is the
+ * uninstall path: every field we wrote must be removed exactly, and no
+ * other field may be touched.
+ *
+ * Pure (no mutation).
+ */
+export function withoutSuperpowersSkillDenylist(settings) {
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    if (!Array.isArray(permissions.deny)) {
+        return settings;
+    }
+    const remainingDeny = permissions.deny
+        .filter((d) => typeof d === 'string')
+        .filter((d) => !SUPERPOWERS_DENY_SENTINELS.has(d));
+    const nextPermissions = { ...permissions };
+    if (remainingDeny.length > 0) {
+        nextPermissions.deny = remainingDeny;
+    }
+    else {
+        delete nextPermissions.deny;
+    }
+    if (Object.keys(nextPermissions).length === 0) {
+        // The whole `permissions` object is empty (no deny, no allow, no other
+        // sub-fields). Drop it to avoid leaving an empty object on disk.
+        const { permissions: _omit, ...rest } = settings;
+        return rest;
+    }
+    return { ...settings, permissions: nextPermissions };
+}
+/**
+ * Read-only introspection. Returns the deny entries that `peaks hooks
+ * install` would write today. Useful for `peaks hooks status` and the
+ * dry-run envelope.
+ */
+export function listSuperpowersDenyEntries() {
+    return SUPERPOWERS_DENIED_SKILLS.map(formatSuperpowersDenyEntry);
+}
 /** Default (claude-code) peaks-managed hook entries — kept as a stable export for tests. Slice #014: only the gate-enforce entry. */
 export const PEAKS_HOOK_ENTRIES = (() => {
     const spec = resolveHookSpec('claude-code');
@@ -341,7 +461,21 @@ export function applyHookInstall(scope, projectRoot, options) {
     if (baseResult.alreadyInstalled) {
         return { ...baseResult, applied: false };
     }
-    atomicWriteJson(settingsPath, withHooksInstalledForIde(settings, ide));
+    // Slice 2026-07-29-worktree-layer3-deny: Layer 3 — write the
+    // `permissions.deny` block alongside the gate hook in a single atomic
+    // write so the two halves of the install are always co-located. The
+    // helper is idempotent and additive: any user-written deny entries
+    // are preserved.
+    //
+    // Slice 2026-07-29-worktree-l2-extended Part 29: also apply
+    // withTriggeredDenyList. If the existing settings file has a
+    // superpowers / git-worktree / podman-run entry (any source),
+    // the install appends a defensive `Edit(deny-trigger:<phrase>)`
+    // entry. The chain cannot run raw `git worktree add` (or
+    // `podman run`) without an explicit `peaks hooks uninstall`
+    // first. Both helpers are pure + idempotent.
+    const merged = withTriggeredDenyList(withSuperpowersSkillDenylist(withHooksInstalledForIde(settings, ide)));
+    atomicWriteJson(settingsPath, merged);
     return { ...baseResult, alreadyInstalled: false, applied: true };
 }
 export function removeHookInstall(scope, projectRoot, options) {
@@ -382,7 +516,17 @@ export function removeHookInstall(scope, projectRoot, options) {
     else {
         delete nextSettings.hooks;
     }
-    atomicWriteJson(settingsPath, nextSettings);
+    // Slice 2026-07-29-worktree-layer3-deny: Layer 3 — symmetric uninstall.
+    // Strips the peaks-managed `UseSkill(...)` deny entries alongside the
+    // hook entries; user-written entries are untouched. The helper self-
+    // decomposes an empty `permissions` object.
+    //
+    // Slice 2026-07-29-worktree-l2-extended Part 29: also strip the
+    // trigger-style deny entries via withoutTriggeredDenyList. The
+    // chain of helpers is order-independent (each is idempotent and
+    // additive over the same set of peaks-managed entries).
+    const finalSettings = withoutTriggeredDenyList(withoutSuperpowersSkillDenylist(nextSettings));
+    atomicWriteJson(settingsPath, finalSettings);
     return { scope, settingsPath, removed: removedAny };
 }
 export function readHookStatus(scope, projectRoot, options) {
@@ -394,3 +538,87 @@ export function readHookStatus(scope, projectRoot, options) {
     const settings = exists ? readJsonObjectFile(settingsPath) : {};
     return { scope, settingsPath, exists, installed: isInstalledForIde(settings, ide) };
 }
+/**
+ * Slice 2026-07-29-worktree-l2-extended Part 27 — trigger-style deny.
+ *
+ * In addition to the static SUPERPOWERS_DENIED_SKILLS list, peaks
+ * scans the existing settings file for "trigger phrases" that
+ * indicate the user has configured the superpowers chain (or
+ * any other auto-run worktree-creating tool) and appends a
+ * defensive deny to prevent the chain from running raw
+ * `git worktree add` (or `podman run`) directly.
+ *
+ * Triggers detected (substring match on the existing
+ * permissions.deny / permissions.allow list):
+ *
+ *  - `superpowers:using-git-worktrees` — the chain's ground zero
+ *  - `superpowers:brainstorming` etc. — the upstream skill
+ *  - `Bash(git worktree add` — the user has explicitly
+ *    allowed raw git worktree, which our L2 lease-aware gate
+ *    would also intercept (defense in depth)
+ *
+ * Append-only — never replaces, never re-orders, never removes
+ * existing entries. Idempotent: re-running the install with
+ * the same input yields the same output.
+ */
+export const TRIGGER_PHRASES = Object.freeze([
+    'superpowers:using-git-worktrees',
+    'superpowers:brainstorming',
+    'superpowers:writing-plans',
+    'superpowers:subagent-driven-development',
+    'Bash(git worktree add',
+    'Bash(podman run'
+]);
+/**
+ * Format a trigger-phrase into a stable `Edit` deny entry. We deny
+ * `Edit` (not `Bash`) on the *settings file* itself, so the
+ * user cannot edit the trigger away without an explicit
+ * `peaks hooks uninstall` first. The skill name (when
+ * applicable) is the value after the colon.
+ */
+function formatTriggerDenyEntry(phrase) {
+    return `Edit(deny-trigger:${phrase})`;
+}
+export function withTriggeredDenyList(settings) {
+    const existingDeny = Array.isArray(settings.permissions?.deny)
+        ? (settings.permissions.deny
+            .filter((d) => typeof d === 'string'))
+        : [];
+    // Detect triggers in the existing allow + deny lists.
+    const existingAllow = Array.isArray(settings.permissions?.allow)
+        ? (settings.permissions.allow
+            .filter((d) => typeof d === 'string'))
+        : [];
+    const haystack = [...existingDeny, ...existingAllow].join('|');
+    const triggered = TRIGGER_PHRASES.filter((p) => haystack.includes(p));
+    if (triggered.length === 0)
+        return settings;
+    const triggeredEntries = triggered.map(formatTriggerDenyEntry);
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    const otherDeny = existingDeny.filter((d) => !triggeredEntries.includes(d));
+    return {
+        ...settings,
+        permissions: { ...permissions, deny: [...new Set([...otherDeny, ...triggeredEntries])] }
+    };
+}
+/** Inverse of withTriggeredDenyList: strip every deny-trigger entry. */
+export function withoutTriggeredDenyList(settings) {
+    const permissions = (settings.permissions && typeof settings.permissions === 'object' && !Array.isArray(settings.permissions))
+        ? settings.permissions
+        : {};
+    const existingDeny = Array.isArray(permissions.deny)
+        ? permissions.deny.filter((d) => typeof d === 'string')
+        : [];
+    const kept = existingDeny.filter((d) => !d.startsWith('Edit(deny-trigger:'));
+    const next = { ...permissions, deny: kept };
+    if (kept.length === 0)
+        delete next.deny;
+    if (Object.keys(next).length === 0) {
+        const out = { ...settings };
+        delete out.permissions;
+        return out;
+    }
+    return { ...settings, permissions: next };
+}

package/dist/services/skills/skill-registry.d.ts

@@ -3,6 +3,7 @@ export type SkillMetadata = {
     description: string;
     directory: string;
     skillPath: string;
+    visibility?: string;
 };
 export type SkillLoadFailure = {
     directory: string;

package/dist/services/skills/skill-registry.js

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
-import { listDirectories, pathExists, readText } from '../../shared/fs.js';
+import { listDirectories, pathExists, readText } from 'peaks-loop-shared/fs';
 import { parseFrontmatter } from '../../shared/frontmatter.js';
-import { skillsDir } from '../../shared/paths.js';
+import { skillsDir } from 'peaks-loop-shared/paths';
 function getLoadFailureMessage(error) {
     return error instanceof Error ? error.message : 'Unable to parse skill metadata';
 }
@@ -31,7 +31,8 @@ export async function loadSkillRegistry(baseDir = skillsDir) {
                         name: frontmatter.name,
                         description: frontmatter.description,
                         directory: subDir,
-                        skillPath
+                        skillPath,
+                        ...(frontmatter.visibility !== undefined ? { visibility: frontmatter.visibility } : {})
                     });
                 }
                 catch (error) {
@@ -50,7 +51,8 @@ export async function loadSkillRegistry(baseDir = skillsDir) {
                 name: frontmatter.name,
                 description: frontmatter.description,
                 directory,
-                skillPath
+                skillPath,
+                ...(frontmatter.visibility !== undefined ? { visibility: frontmatter.visibility } : {})
             });
         }
         catch (error) {

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

@@ -1,6 +1,6 @@
 import { dirname, join } from 'node:path';
 import * as path from 'node:path';
-import { readText } from '../../shared/fs.js';
+import { readText } from 'peaks-loop-shared/fs';
 import { loadSkillRegistry } from './skill-registry.js';
 const DESTRUCTIVE_APPLY_PATTERNS = [
     /peaks\s+memory\s+sync[^\n]*--apply/,

package/dist/services/slice/slice-check-service.js

@@ -1,7 +1,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import { isDirectory } from '../../shared/fs.js';
+import { isDirectory } from 'peaks-loop-shared/fs';
 // Slice 2026-06-29-change-id-root-removal: `getCurrentChangeId` was
 // removed with the change-id axis. Slice check resolves the rid from
 // `options.rid` only; the binding file at `.peaks/_runtime/current-change`

package/dist/services/standards/main-session-monitor-ban-hook.d.ts

@@ -0,0 +1,14 @@
+export type MainSessionMonitorBanInput = {
+    readonly tool_name?: string;
+    readonly tool_input?: {
+        readonly file_path?: string;
+        readonly content?: string;
+        readonly new_string?: string;
+    };
+};
+export type MainSessionMonitorBanDecision = {
+    readonly allowed: boolean;
+    readonly reason?: string;
+};
+/** Reject Edit/Write calls that introduce a new import of the legacy monitor. */
+export declare function checkMainSessionMonitorImport(input: MainSessionMonitorBanInput): MainSessionMonitorBanDecision;

package/dist/services/standards/main-session-monitor-ban-hook.js

@@ -0,0 +1,19 @@
+const FORBIDDEN_IMPORT = /import\s*\{[^}]*\b(?:detectIdeFromEnv|IdeKind|IDE_KINDS|isIdeKind)\b[^}]*\}\s*from\s*['"][^'"]*main-session-monitor(?:\.js)?['"]/;
+/** Reject Edit/Write calls that introduce a new import of the legacy monitor. */
+export function checkMainSessionMonitorImport(input) {
+    if (input.tool_name !== 'Edit' && input.tool_name !== 'Write') {
+        return { allowed: true };
+    }
+    const filePath = input.tool_input?.file_path;
+    if (!filePath || /(?:^|[\\/])main-session-monitor\.ts$/.test(filePath)) {
+        return { allowed: true };
+    }
+    const candidate = input.tool_input?.new_string ?? input.tool_input?.content ?? '';
+    if (!FORBIDDEN_IMPORT.test(candidate)) {
+        return { allowed: true };
+    }
+    return {
+        allowed: false,
+        reason: 'Import IDE detection from services/context/ide-detect.ts; main-session-monitor.ts is legacy-only.'
+    };
+}

package/dist/services/standards/missing-standards-detector.d.ts

@@ -42,6 +42,31 @@ export type MissingProjectStandardsDiagnostic = {
     readonly remediation: string;
     readonly language: StandardsLanguage;
 };
+/**
+ * List which standards tree components are missing vs populated.
+ *
+ * Returns one of three stable shapes:
+ *   - { kind: 'complete' }                    — both common + language overlay populated
+ *   - { kind: 'common-missing' }              — common dir absent/empty (universal)
+ *   - { kind: 'language-missing', language }  — common ok, language overlay absent/empty
+ *
+ * The detector previously returned a single boolean that flipped to
+ * "missing: true" the moment the language overlay was empty, but printed
+ * the remediation as if BOTH common AND language were missing — a UX bug
+ * that surfaced in ice-cola (common=4 .md files; typescript=1 .md file;
+ * javascript overlay absent → label said "no project-local standards found"
+ * even though common was clearly populated). This split lets the CLI emit
+ * a precise remediation string per kind.
+ */
+export type StandardsTreeDiagnostic = {
+    readonly kind: 'complete';
+} | {
+    readonly kind: 'common-missing';
+} | {
+    readonly kind: 'language-missing';
+    readonly language: StandardsLanguage;
+};
+export declare function diagnoseStandardsTree(projectRoot: string, language: StandardsLanguage): StandardsTreeDiagnostic;
 /**
  * Detect whether a consumer project's `.peaks/standards/` tree (2.0
  * canonical) is missing or empty.

package/dist/services/standards/missing-standards-detector.js

@@ -62,6 +62,26 @@ function hasPopulatedMarkdown(dir) {
     const entries = readdirSync(dir);
     return entries.some((entry) => entry.toLowerCase().endsWith('.md'));
 }
+export function diagnoseStandardsTree(projectRoot, language) {
+    if (!SUPPORTED_LANGUAGES.has(language)) {
+        throw new Error(`Unsupported standards language: ${String(language)}`);
+    }
+    const normalizedRoot = normalizeProjectRoot(projectRoot);
+    const commonDir = join(normalizedRoot, '.peaks', 'standards', 'common');
+    const languageDir = language === 'generic'
+        ? null
+        : join(normalizedRoot, '.peaks', 'standards', language);
+    const commonOk = hasPopulatedMarkdown(commonDir);
+    const languageOk = languageDir === null ? true : hasPopulatedMarkdown(languageDir);
+    if (commonOk && languageOk) {
+        return { kind: 'complete' };
+    }
+    if (!commonOk) {
+        return { kind: 'common-missing' };
+    }
+    // common ok, language overlay empty/missing
+    return { kind: 'language-missing', language };
+}
 /**
  * Detect whether a consumer project's `.peaks/standards/` tree (2.0
  * canonical) is missing or empty.
@@ -84,18 +104,29 @@ export function detectMissingProjectStandards(projectRoot, language) {
     }
     const normalizedRoot = normalizeProjectRoot(projectRoot);
     const renderedPath = renderForPlatform(normalizedRoot);
-    const commonDir = join(normalizedRoot, '.peaks', 'standards', 'common');
-    const languageDir = language === 'generic'
-        ? null
-        : join(normalizedRoot, '.peaks', 'standards', language);
-    const commonOk = hasPopulatedMarkdown(commonDir);
-    const languageOk = languageDir === null ? true : hasPopulatedMarkdown(languageDir);
-    const missing = !(commonOk && languageOk);
-    // Remediation message: copy-pasteable, mentions language, references the
-    // resolved project path, and hints at the `--init-standards` opt-in flag.
-    const remediation = missing
-        ? `⚠ no project-local standards found at ${renderedPath} — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold, or pass --init-standards to peaks workspace init for one-shot auto-apply (language: ${language}).`
-        : `Project-local standards already present at ${renderedPath}. Re-run \`peaks standards init --project ${normalizedRoot} --apply\` to refresh from the curated baseline.`;
+    const diagnostic = diagnoseStandardsTree(projectRoot, language);
+    // Bug-01 fix (ice-cola surface check 2026-07-22): the previous
+    // remediation said "no project-local standards found" whenever EITHER
+    // common or the language overlay was empty, which misrepresented
+    // projects that have common populated but a missing language overlay
+    // (e.g. ice-cola has common/*.md + typescript/coding-style.md but no
+    // javascript/coding-style.md). The remediation now distinguishes the
+    // three kinds so the operator gets a precise hint.
+    let missing;
+    let remediation;
+    if (diagnostic.kind === 'complete') {
+        missing = false;
+        remediation = `Project-local standards already present at ${renderedPath}. Re-run \`peaks standards init --project ${normalizedRoot} --apply\` to refresh from the curated baseline.`;
+    }
+    else if (diagnostic.kind === 'common-missing') {
+        missing = true;
+        remediation = `⚠ no project-local common standards at ${renderedPath} — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold (language: ${language}), or pass --init-standards to peaks workspace init for one-shot auto-apply.`;
+    }
+    else {
+        missing = true;
+        const overlayName = diagnostic.language;
+        remediation = `⚠ common standards present at ${renderedPath}\\common but ${overlayName} language overlay is missing — run \`peaks standards init --project ${normalizedRoot} --apply\` to scaffold the ${overlayName} overlay (or pass --init-standards to peaks workspace init for one-shot auto-apply).`;
+    }
     return {
         missing,
         path: renderedPath,

package/dist/services/tech/tech-change-id-service.d.ts

@@ -0,0 +1,82 @@
+/**
+ * tech-change-id-service — change-id-axis slice of the tech planner (rid-012).
+ *
+ * Purpose:
+ *   The original `peaks tech plan` / `peaks tech status` (in `tech-service.ts`)
+ *   is keyed by an active session id (the change-id axis was removed in
+ *   v2.19.0). This module provides the *consumer-side wiring* that lets the
+ *   same CLI surface be re-keyed by an explicit `--change-id <id>` for the
+ *   OpenSpec / change-driven workflow. The path math, change-id validation,
+ *   and workspace-unavailable response are all delegated to the rid-009
+ *   helpers in `src/services/openspec/artifact-boundary.ts`.
+ *
+ * Style:
+ *   - Named function exports (matches `artifact-boundary.ts`).
+ *   - Hand-rolled `Result<T, E>` unions — no `neverthrow` dep.
+ *   - Pure path math; never reads the filesystem.
+ *
+ * Hard ban:
+ *   - This file MUST NOT import from `peaks-loop-shared` (stays inside
+ *     peaks-loop per §9 of the rid-012 plan).
+ *   - This file MUST NOT touch `src/services/openspec/artifact-boundary.ts`
+ *     (rid-009 helpers are frozen; we only consume via import).
+ */
+import type { WorkspaceConfig } from '../config/config-types.js';
+import { type BoundaryError, type ChangeIdError, type PlanArtifactPathOutput, type WorkspaceUnavailableResponse, type Result } from '../openspec/artifact-boundary.js';
+export type TechArtifactPathResult = PlanArtifactPathOutput;
+export type TechChangeArtifacts = {
+    taskGraph: TechArtifactPathResult;
+    waveManifests: TechArtifactPathResult[];
+    reviewChecklist: TechArtifactPathResult;
+    approvalTemplate: TechArtifactPathResult;
+};
+export type TechChangeStatusValue = 'unavailable' | 'missing' | 'blocked' | 'approved';
+export type TechChangeStatus = {
+    changeId: string;
+    status: TechChangeStatusValue;
+    artifactRoot: string;
+    requiredArtifacts: string[];
+    missingArtifacts: string[];
+    approvalRecord: string | null;
+    blockedReasons: string[];
+    nextActions: string[];
+};
+/**
+ * Validate a change-id string. This is a thin consumer-side wrapper that
+ * delegates to `validateChangeId` (rid-009). The wrapper exists so the
+ * change-id-axis service has a single named export point (`validateTechChangeId`)
+ * and so the test file can import it without reaching across to openspec.
+ */
+export declare function validateTechChangeId(id: string): Result<{
+    changeId: string;
+}, ChangeIdError>;
+/**
+ * Plan the 5 artifact-relative paths the tech-change-id planner needs to
+ * expose:
+ *   - `taskGraph`           → `<id>/architecture/tech-task-graph.json`
+ *   - `waveManifests`       → `<id>/architecture/waves/wave-<n>-<wave>.json` (4)
+ *   - `reviewChecklist`     → `<id>/architecture/tech-review-checklist.md`
+ *   - `approvalTemplate`    → `<id>/architecture/tech-approval-record.template.md`
+ *
+ * Delegates to `planArtifactPath` (rid-009) for each one. Returns the FIRST
+ * failure (so callers get a single, deterministic BoundaryError).
+ *
+ * Pure path math — does not touch the filesystem.
+ */
+export declare function planTechArtifactPath(input: {
+    changeId: string;
+    workspaceRoot: string;
+    requestId: string;
+}): Result<TechChangeArtifacts, BoundaryError>;
+/**
+ * Build the workspace-unavailable response for the change-id-axis tech
+ * planner. Thin wrapper around `buildWorkspaceUnavailable` (rid-009) so
+ * the same single source of truth (nextActions constant) is reused.
+ *
+ * The `mode` discriminator matches the existing artifact-boundary shape
+ * (`'preview-only' | 'blocked'`).
+ */
+export declare function buildTechWorkspaceUnavailable(input: {
+    mode: WorkspaceUnavailableResponse['mode'];
+}): WorkspaceUnavailableResponse;
+export type { WorkspaceConfig };

package/dist/services/tech/tech-change-id-service.js

@@ -0,0 +1,117 @@
+/**
+ * tech-change-id-service — change-id-axis slice of the tech planner (rid-012).
+ *
+ * Purpose:
+ *   The original `peaks tech plan` / `peaks tech status` (in `tech-service.ts`)
+ *   is keyed by an active session id (the change-id axis was removed in
+ *   v2.19.0). This module provides the *consumer-side wiring* that lets the
+ *   same CLI surface be re-keyed by an explicit `--change-id <id>` for the
+ *   OpenSpec / change-driven workflow. The path math, change-id validation,
+ *   and workspace-unavailable response are all delegated to the rid-009
+ *   helpers in `src/services/openspec/artifact-boundary.ts`.
+ *
+ * Style:
+ *   - Named function exports (matches `artifact-boundary.ts`).
+ *   - Hand-rolled `Result<T, E>` unions — no `neverthrow` dep.
+ *   - Pure path math; never reads the filesystem.
+ *
+ * Hard ban:
+ *   - This file MUST NOT import from `peaks-loop-shared` (stays inside
+ *     peaks-loop per §9 of the rid-012 plan).
+ *   - This file MUST NOT touch `src/services/openspec/artifact-boundary.ts`
+ *     (rid-009 helpers are frozen; we only consume via import).
+ */
+import { buildWorkspaceUnavailable, planArtifactPath, validateChangeId, } from '../openspec/artifact-boundary.js';
+/**
+ * Wave template names — must match the 4 waves the existing
+ * `tech-service.ts#createTechGraph` produces (scan / document / review /
+ * reducer). The relative path layout follows `design.md §Artifact Layout`
+ * verbatim: `<change-id>/architecture/waves/wave-<index>-<wave>.json`.
+ */
+const TECH_CHANGE_ID_WAVES = ['scan', 'document', 'review', 'reducer'];
+const TECH_ARCHITECTURE_ROOT = '<changeId>/architecture';
+/**
+ * Validate a change-id string. This is a thin consumer-side wrapper that
+ * delegates to `validateChangeId` (rid-009). The wrapper exists so the
+ * change-id-axis service has a single named export point (`validateTechChangeId`)
+ * and so the test file can import it without reaching across to openspec.
+ */
+export function validateTechChangeId(id) {
+    return validateChangeId(id);
+}
+/**
+ * Plan the 5 artifact-relative paths the tech-change-id planner needs to
+ * expose:
+ *   - `taskGraph`           → `<id>/architecture/tech-task-graph.json`
+ *   - `waveManifests`       → `<id>/architecture/waves/wave-<n>-<wave>.json` (4)
+ *   - `reviewChecklist`     → `<id>/architecture/tech-review-checklist.md`
+ *   - `approvalTemplate`    → `<id>/architecture/tech-approval-record.template.md`
+ *
+ * Delegates to `planArtifactPath` (rid-009) for each one. Returns the FIRST
+ * failure (so callers get a single, deterministic BoundaryError).
+ *
+ * Pure path math — does not touch the filesystem.
+ */
+export function planTechArtifactPath(input) {
+    const taskGraphResult = planArtifactPath({
+        changeId: input.changeId,
+        workspaceRoot: input.workspaceRoot,
+        role: 'architecture',
+        requestId: input.requestId,
+        template: `${TECH_ARCHITECTURE_ROOT}/tech-task-graph.json`,
+    });
+    if (!taskGraphResult.ok)
+        return taskGraphResult;
+    const waveManifestResults = [];
+    for (let index = 0; index < TECH_CHANGE_ID_WAVES.length; index += 1) {
+        const wave = TECH_CHANGE_ID_WAVES[index];
+        const waveResult = planArtifactPath({
+            changeId: input.changeId,
+            workspaceRoot: input.workspaceRoot,
+            role: 'architecture',
+            requestId: input.requestId,
+            template: `${TECH_ARCHITECTURE_ROOT}/waves/wave-${index + 1}-${wave}.json`,
+        });
+        if (!waveResult.ok)
+            return waveResult;
+        waveManifestResults.push(waveResult.value);
+    }
+    const reviewChecklistResult = planArtifactPath({
+        changeId: input.changeId,
+        workspaceRoot: input.workspaceRoot,
+        role: 'architecture',
+        requestId: input.requestId,
+        template: `${TECH_ARCHITECTURE_ROOT}/tech-review-checklist.md`,
+    });
+    if (!reviewChecklistResult.ok)
+        return reviewChecklistResult;
+    const approvalTemplateResult = planArtifactPath({
+        changeId: input.changeId,
+        workspaceRoot: input.workspaceRoot,
+        role: 'architecture',
+        requestId: input.requestId,
+        template: `${TECH_ARCHITECTURE_ROOT}/tech-approval-record.template.md`,
+    });
+    if (!approvalTemplateResult.ok)
+        return approvalTemplateResult;
+    return {
+        ok: true,
+        value: {
+            taskGraph: taskGraphResult.value,
+            waveManifests: waveManifestResults,
+            reviewChecklist: reviewChecklistResult.value,
+            approvalTemplate: approvalTemplateResult.value,
+        },
+    };
+}
+/**
+ * Build the workspace-unavailable response for the change-id-axis tech
+ * planner. Thin wrapper around `buildWorkspaceUnavailable` (rid-009) so
+ * the same single source of truth (nextActions constant) is reused.
+ *
+ * The `mode` discriminator matches the existing artifact-boundary shape
+ * (`'preview-only' | 'blocked'`).
+ */
+export function buildTechWorkspaceUnavailable(input) {
+    return buildWorkspaceUnavailable(input);
+}

package/dist/services/understand/understand-hybrid-service.js

@@ -1,6 +1,6 @@
 import { createCodegraphInvocation, executeCodegraphInvocation } from '../codegraph/codegraph-service.js';
 import { scanUnderstandAnything, summarizeKnowledgeGraph } from './understand-scan-service.js';
-import { getErrorMessage } from '../../shared/result.js';
+import { getErrorMessage } from 'peaks-loop-shared/result';
 const DEFAULT_FILES = ['src/index.ts', 'package.json', 'README.md'];
 function resolveFiles(files) {
     if (files !== undefined && files.length > 0) {