@momentiq/dark-factory-cli 2.17.0 → 3.0.0

package/dist/mode/critic-registration.js

@@ -0,0 +1,279 @@
+// Cycle 27 Phase C — register the deterministic ModeScope critic into a
+// consumer's `.agent-review/config.json`.
+//
+// `df mode init` calls this after seeding the `modes` catalog so the scope
+// critic RUNS in local `df review` / `df gate-push` AND in CI `agent-critic`
+// (inside the existing required check — no consumer ruleset/workflow
+// changes). The mirror of static-schema-lint's posture: the adapter ships
+// available-but-off in `ADAPTER_LOADERS`; a config reference is what turns
+// it on for a repo.
+//
+// QUORUM SAFETY (the subtle part). The scope critic is a deterministic,
+// veto-only critic that ALWAYS completes. Under `min-complete-quorum`, the
+// gate needs `quorum` critics to COMPLETE. Naively appending an
+// always-completing critic to the fleet WITHOUT touching quorum would let
+// it substitute for an LLM completion — silently LOWERING the number of LLM
+// chief-engineers that must complete. `df critic` aggregates on TWO paths
+// and the scope critic (added to `critics[]`) runs on BOTH, so BOTH quorums
+// are bumped by exactly 1:
+//   - the root `aggregation.quorum`, which governs the PROFILE-LESS run the
+//     reusable workflow's CONSUMER path uses (`df critic` with no
+//     `AGENT_REVIEW_PROFILE` → `resolveCriticProfile` → undefined → whole
+//     `critics[]` fleet under the root aggregation); AND
+//   - every `profile.quorum`, for EXPLICIT-profile runs like dark-factory's
+//     own `AGENT_REVIEW_PROFILE=cloud` CI (filters to `profile.criticIds`).
+// The bumps are independent — a single run uses exactly one aggregation
+// config (root OR one profile) — so they never double-count. The engineer
+// reviewing the init PR sees each bump reported in `df mode init`'s output.
+//
+// Operates on the RAW parsed JSON (not the normalized AgentReviewConfig) so
+// consumer customizations are preserved byte-for-byte except the fields we
+// touch. The caller re-validates the mutated object through
+// `parseAgentReviewConfig` (fail-closed) before writing.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseAgentReviewConfig } from "@momentiq/dark-factory-schemas";
+import { MODE_SCOPE_ADAPTER_ID } from "../adapters/mode-scope.js";
+/** The critic id used for the ModeScope critic in `.agent-review/config.json`. */
+export const MODE_SCOPE_CRITIC_ID = "mode-scope-critic";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * The critic entry appended to `critics[]`. Deterministic critic: no auth,
+ * no vendor SDK. `required: true` — the scope critic is a HARD GATE, so its
+ * blockers must block under EVERY aggregation policy. Under `block-if-any`
+ * the gate demotes `required: false` critics' findings to warnings (report.ts
+ * / gate.ts key on `config.critics.filter(c => c.required)`), so a
+ * `required: false` scope critic would NOT block an out-of-scope `Mode:` PR
+ * there. `required: true` is also safe under `min-complete-quorum`: that path
+ * (`quorumAggregateVerdict`) never consults the `required` flag, and because
+ * the adapter ALWAYS completes it never trips the "required critic errored →
+ * block" rule — so it only ever adds the veto its blocker already carries, and
+ * the per-path quorum bumps below stay exact. `runtime: "local"` is metadata —
+ * the same deterministic entry is referenced by both the local and cloud
+ * profiles (mirrors how `cursor-*` is shared across profiles).
+ */
+export function buildModeScopeCriticEntry() {
+    return {
+        id: MODE_SCOPE_CRITIC_ID,
+        name: "Mode Scope Critic — deterministic operator-mode scope enforcement",
+        adapter: MODE_SCOPE_ADAPTER_ID,
+        required: true,
+        runtime: "local",
+        model: { id: "deterministic", params: [] },
+    };
+}
+/**
+ * Bump the ROOT `aggregation.quorum` by 1 (min-complete-quorum only). Governs
+ * the PROFILE-LESS run: the reusable workflow's consumer path invokes
+ * `df critic` with no `AGENT_REVIEW_PROFILE`, so the whole `critics[]` fleet —
+ * now including the always-completing scope critic — is aggregated under the
+ * root policy, and its LLM completion floor must be preserved. Under
+ * block-if-any there is no quorum to preserve (a blocker vetoes directly), so
+ * nothing is bumped.
+ *
+ * Called EXACTLY ONCE, at the moment the scope critic is first ADDED to
+ * `critics[]` (a fresh registration) — never on a converge re-run. Quorum is a
+ * bare integer, so "already bumped to N" is indistinguishable from "should be
+ * N+1 but wasn't"; a converge that re-bumped would inflate the floor without
+ * bound. Presence of the entry in `critics[]` means the root fleet already
+ * accounts for it. (This is the exact-once transition key.)
+ */
+function bumpRootQuorum(raw, changes) {
+    const aggregation = raw["aggregation"];
+    if (isRecord(aggregation) &&
+        aggregation["policy"] === "min-complete-quorum" &&
+        typeof aggregation["quorum"] === "number") {
+        const prev = aggregation["quorum"];
+        aggregation["quorum"] = prev + 1;
+        changes.push(`aggregation.quorum bumped ${prev}→${prev + 1} (governs profile-less runs incl. the reusable workflow's consumer path; preserves the LLM completion floor)`);
+    }
+}
+/**
+ * Ensure `criticId` is listed in EVERY profile's `criticIds`, bumping the
+ * quorum by 1 ONLY for each profile it was newly ADDED to. The add and the
+ * bump are coupled and keyed on the absent→present transition: a profile that
+ * already lists the critic is left untouched (no double-bump). This is what
+ * makes both fresh registration and the converge path idempotent — re-running
+ * `df mode init` never inflates a profile that already accounts for the scope
+ * critic, and it repairs a profile that a partial migration left it out of.
+ */
+function ensureCriticInEveryProfile(raw, criticId, changes) {
+    const profiles = raw["profiles"];
+    if (!isRecord(profiles))
+        return;
+    for (const [name, profileRaw] of Object.entries(profiles)) {
+        if (!isRecord(profileRaw))
+            continue;
+        const ids = Array.isArray(profileRaw["criticIds"])
+            ? profileRaw["criticIds"]
+            : [];
+        if (ids.includes(criticId))
+            continue; // already accounted for — no re-bump.
+        ids.push(criticId);
+        profileRaw["criticIds"] = ids;
+        if (typeof profileRaw["quorum"] === "number") {
+            const prev = profileRaw["quorum"];
+            profileRaw["quorum"] = prev + 1;
+            changes.push(`profile "${name}": added scope critic + bumped quorum ${prev}→${prev + 1} (preserves the LLM completion floor)`);
+        }
+        else {
+            changes.push(`profile "${name}": added scope critic`);
+        }
+    }
+}
+/**
+ * Register the ModeScope critic into a raw parsed `.agent-review/config.json`
+ * object. Mutates `raw` in place AND returns a change report. The caller
+ * validates the mutated object through `parseAgentReviewConfig` before
+ * persisting it.
+ *
+ * "Present" is NOT "safe". A pre-existing mode-scope entry can itself be
+ * UNSAFE — an older CLI (or a hand edit) may have added it `required: false`
+ * (its blockers are demoted to warnings under block-if-any) or left it out of a
+ * profile (it does not run at all under profile-filtered runs). So rather than
+ * no-op the instant an entry is present, we CONVERGE it to the required shape:
+ * promote `required: true`, repair a missing id, and ensure the id is in every
+ * profile. Only a FULLY compliant entry is a true no-op (`changed: false`).
+ *
+ * Quorum is preserved EXACTLY ONCE per scope, keyed on the absent→present
+ * transition (`bumpRootQuorum` for the root fleet, `ensureCriticInEveryProfile`
+ * per profile), so a converge re-run never double-counts.
+ */
+export function registerModeScopeCritic(raw) {
+    if (!isRecord(raw)) {
+        throw new Error("`.agent-review/config.json` is not a JSON object");
+    }
+    const critics = Array.isArray(raw["critics"])
+        ? raw["critics"]
+        : [];
+    raw["critics"] = critics;
+    const existing = critics.filter((c) => isRecord(c) && c["adapter"] === MODE_SCOPE_ADAPTER_ID);
+    if (existing.length > 1) {
+        // Ambiguous / corrupt: two always-completing scope critics double-count the
+        // quorum floor and there is no single canonical entry to converge. Fail
+        // CLOSED — the caller surfaces this as `error` and `df mode init` fails loud
+        // (never a silent "already-registered"). Judgment call: we throw rather than
+        // auto-dedup, because choosing which duplicate to keep and reconciling their
+        // differing required/id/profile state is not safely inferable.
+        throw new Error(`\`.agent-review/config.json\` has ${existing.length} critics with adapter ` +
+            `"${MODE_SCOPE_ADAPTER_ID}"; expected at most one. Remove the duplicate ` +
+            `entries and re-run \`df mode init\`.`);
+    }
+    const changes = [];
+    if (existing.length === 0) {
+        // FRESH registration: add the entry, then preserve the floor once on each
+        // scope it newly enters (the root fleet + every profile).
+        critics.push(buildModeScopeCriticEntry());
+        changes.push(`added critic "${MODE_SCOPE_CRITIC_ID}" (adapter: ${MODE_SCOPE_ADAPTER_ID}, required: true, deterministic hard gate)`);
+        bumpRootQuorum(raw, changes);
+        ensureCriticInEveryProfile(raw, MODE_SCOPE_CRITIC_ID, changes);
+        return { changed: true, changes };
+    }
+    // CONVERGE the single pre-existing entry to the required shape.
+    const entry = existing[0];
+    // 1. Canonical id. Profiles reference critics BY id, so keep an existing
+    //    non-empty string id (forcing a new one would orphan those references)
+    //    and only repair a missing / non-string one. Judgment call: we do NOT
+    //    rename a differing existing id — it is the consumer's chosen id and
+    //    renaming is not safely reversible; we converge profiles to whatever id
+    //    the entry actually uses.
+    let criticId;
+    if (typeof entry["id"] === "string" && entry["id"].length > 0) {
+        criticId = entry["id"];
+    }
+    else {
+        entry["id"] = MODE_SCOPE_CRITIC_ID;
+        criticId = MODE_SCOPE_CRITIC_ID;
+        changes.push(`set the missing id on the existing mode-scope critic to "${MODE_SCOPE_CRITIC_ID}"`);
+    }
+    // 2. Promote to required: true — the hard-gate invariant. A required: false
+    //    scope critic's blockers are demoted to warnings under block-if-any.
+    if (entry["required"] !== true) {
+        const was = entry["required"];
+        entry["required"] = true;
+        changes.push(`promoted the existing mode-scope critic "${criticId}" to required: true ` +
+            `(hard-gate invariant; was ${JSON.stringify(was)})`);
+    }
+    // 3. Ensure the id is in every profile (adds + bumps only the profiles that
+    //    were missing it). Already-listing profiles are left alone — their
+    //    presence means they already account for the critic.
+    //
+    //    WONTFIX (documented, #311): the ROOT `aggregation.quorum` is likewise
+    //    NOT re-bumped on converge. A hand-corrupted config where `mode-scope` is
+    //    in `critics[]` but the root quorum was never bumped is OUTSIDE this
+    //    converge contract's repair scope, for two reasons: (1) the CLI never
+    //    produces that state — the fresh path bumps root atomically with the add
+    //    (the caller writes the fully-mutated object or nothing), and no released
+    //    CLI registers `mode-scope` at all, so it is reachable only by hand-edit;
+    //    (2) root-bump status is UNOBSERVABLE from a bare integer — `N` cannot be
+    //    told apart from `(N+1) minus one` — so any in-registration "repair" is a
+    //    blind guess that either over-inflates the already-correct case or runs
+    //    away on re-runs (breaking idempotency). Detection of this hand-edit-only
+    //    drift is deferred to a read-only `df doctor` check (#333); registration
+    //    stays idempotent.
+    ensureCriticInEveryProfile(raw, criticId, changes);
+    return { changed: changes.length > 0, changes };
+}
+/**
+ * Register the ModeScope critic into `<repoRoot>/.agent-review/config.json`.
+ *
+ *  - `absent`: no config.json — the consumer hasn't run `df onboard`. Skipped
+ *    (not an error): the catalog seed still stands and re-running init after
+ *    onboarding completes registration.
+ *  - `already-registered`: the critic is already present — idempotent no-op.
+ *  - `registered`: patched + written.
+ *  - `error`: the config is malformed OR the patched config fails canonical
+ *    validation. The on-disk file is left UNTOUCHED (fail-closed); the error
+ *    is reported, not thrown, so `df mode init` degrades gracefully.
+ */
+export function applyModeScopeCriticRegistration(repoRoot) {
+    const configPath = join(repoRoot, ".agent-review", "config.json");
+    if (!existsSync(configPath)) {
+        return { configPath, status: "absent", changes: [] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, "utf8"));
+    }
+    catch (e) {
+        return {
+            configPath,
+            status: "error",
+            changes: [],
+            error: `not valid JSON: ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    let result;
+    try {
+        result = registerModeScopeCritic(raw); // mutates `raw` in place
+    }
+    catch (e) {
+        return {
+            configPath,
+            status: "error",
+            changes: [],
+            error: e instanceof Error ? e.message : String(e),
+        };
+    }
+    if (!result.changed) {
+        return { configPath, status: "already-registered", changes: [] };
+    }
+    // Fail closed: the mutated object MUST parse canonically before we persist
+    // it. On failure the on-disk file is never rewritten.
+    try {
+        parseAgentReviewConfig(raw);
+    }
+    catch (e) {
+        return {
+            configPath,
+            status: "error",
+            changes: [],
+            error: `patched config failed validation (not written): ${e instanceof Error ? e.message : String(e)}`,
+        };
+    }
+    writeFileSync(configPath, `${JSON.stringify(raw, null, 2)}\n`);
+    return { configPath, status: "registered", changes: result.changes };
+}
+//# sourceMappingURL=critic-registration.js.map

package/dist/mode/critic-registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"critic-registration.js","sourceRoot":"","sources":["../../src/mode/critic-registration.ts"],"names":[],"mappings":"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"}

package/dist/mode/guard.d.ts

@@ -0,0 +1,15 @@
+import type { ModeConfig } from "@momentiq/dark-factory-schemas";
+export { globMatch } from "./scope-policy.js";
+export interface ResolvedModeLike {
+    modeName: string;
+    mode: ModeConfig;
+}
+export type GuardDecision = {
+    decision: "allow";
+} | {
+    decision: "deny";
+    plain: string;
+    hint: string;
+};
+export declare function decideGuard(input: unknown, resolved: ResolvedModeLike | undefined): GuardDecision;
+//# sourceMappingURL=guard.d.ts.map

package/dist/mode/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../../src/mode/guard.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gCAAgC,CAAC;AAQjE,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAE9C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,GACrB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAuItD,wBAAgB,WAAW,CACzB,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,gBAAgB,GAAG,SAAS,GACrC,aAAa,CAwCf"}

package/dist/mode/guard.js

@@ -0,0 +1,160 @@
+// Cycle 27 Phase B — `df mode guard --hook` pure decision core.
+//
+// The Designer Mode tool guard, bound to Claude Code's PreToolUse hook by
+// commands/mode.ts (stdin JSON → decideGuard → hook decision JSON). Layer 2
+// of the enforcement stack (spec §4.4): soft relative to the pre-push gate
+// and CI ModeScope critic (layers 3–4), but the layer that turns a wrong
+// turn into instant, plain-language feedback inside the session.
+//
+// Posture:
+//  - No active mode → allow everything: the guard must be invisible to
+//    normal engineer sessions.
+//  - Active mode → file-writing tools are scope-checked (protectedPaths
+//    WINS over writeScopes on overlap); `dependencyPolicy: "none"` denies
+//    manifest/lockfile edits and dependency-adding Bash; destructive git
+//    is denied; read-only tools pass.
+//  - Active mode + input we cannot understand → fail CLOSED. A guard that
+//    fails open under confusion is not a guard.
+//
+// Denials are dual-register: `plain` speaks to a non-technical operator
+// (no jargon, no file-path vocabulary beyond the path itself); `hint`
+// speaks to the agent (which config knob fired, what to do instead —
+// usually: offer a handoff, never retry the same write).
+import { relative, resolve, sep } from "node:path";
+import { classifyModePath } from "./scope-policy.js";
+// `globMatch` historically lived in this file and is imported from here by
+// tests + external callers. Its canonical home is now scope-policy.ts
+// (shared with the CI scope critic so layers 2 and 4 enforce one policy —
+// spec §4.4); re-export keeps the old import path working.
+export { globMatch } from "./scope-policy.js";
+const ALLOW = { decision: "allow" };
+const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
+const DESTRUCTIVE_BASH = [
+    { re: /\bgit\s+push\b[^\n;|&]*\s(--force\b|-f\b|--force-with-lease\b)/, what: "force-push" },
+    { re: /\bgit\s+reset\s+--hard\b/, what: "hard reset" },
+    { re: /\bgit\s+clean\s+-[a-zA-Z]*f/, what: "git clean" },
+    { re: /\brm\s+-[a-zA-Z]*r[a-zA-Z]*f|\brm\s+-[a-zA-Z]*f[a-zA-Z]*r/, what: "recursive delete" },
+];
+const DEPENDENCY_BASH = /\b(npm\s+(install|i|add)\s+\S|yarn\s+add\b|pnpm\s+(add|install)\s+\S|bun\s+add\b)/;
+// Bash is DEFAULT-DENY while a mode is active: shell writes (`> file`,
+// `sed -i`, `cp`, arbitrary interpreters) would bypass writeScopes entirely,
+// and no denylist can enumerate a shell. Only read-only inspection and the
+// repo's own dev/test scripts are allowed — and only as single, unchained
+// commands (metacharacters disqualify even safe-list prefixes).
+const BASH_METACHARS = /[;&|<>`$\\\n\r]/;
+const BASH_ALLOWLIST = [
+    /^git (status|log|diff|show|branch)(\s|$)/,
+    // NOTE: no `find` — its -delete/-exec/-ok forms mutate; the agent has
+    // dedicated read-only search tools instead.
+    /^(ls|pwd|cat|head|tail|grep|rg|echo|which)(\s|$)/,
+    /^npm (test|start)$/,
+    // `npm run <script>` (+ optional `--workspace=<name>`): RATIFIED trusted, same
+    // basis as `mode.devServer.command` below — package scripts are repo-author-
+    // committed. Contingent on package.json being operator-non-editable in these
+    // modes: `checkPath` denies manifest edits under `dependencyPolicy: "none"` and
+    // package.json sits in the seeded `protectedPaths`, so an operator cannot add a
+    // script — the reachable set is exactly what engineers vetted at commit time.
+    // No per-mode `allowedScripts` allowlist: it would duplicate those author-
+    // controls and desync from real scripts without narrowing an already author-
+    // bounded surface. The script-name charset admits no args and BASH_METACHARS is
+    // rejected first (checkBash), so there is no `-- <shell>` passthrough or
+    // chaining. Revisit only if a mode ever leaves package.json operator-editable.
+    /^npm run [A-Za-z0-9:_./-]+(\s--workspace=[A-Za-z0-9@/._-]+)?$/,
+    /^(node|npm|npx|git) --version$/,
+];
+function deny(plain, hint) {
+    return { decision: "deny", plain, hint };
+}
+function failClosed(modeName) {
+    return deny(`To be safe, ${modeName} mode blocked an action it couldn't understand.`, `guard received unparseable PreToolUse input while mode "${modeName}" is active — fail-closed; re-issue the tool call with well-formed input or hand off`);
+}
+/**
+ * Repo-relative, forward-slash, `..`-free path — or null when it escapes the
+ * repo. BOTH absolute and relative inputs are canonicalized through
+ * `resolve(cwd, filePath)` first: a relative path with `..` segments
+ * ("src/components/../../server/db.ts") must be scope-checked against what
+ * it RESOLVES to, never against its raw text.
+ */
+function relativize(filePath, cwd) {
+    const rel = relative(cwd, resolve(cwd, filePath));
+    const normalized = rel.split(sep).join("/");
+    if (normalized === "" || normalized === "." || normalized.startsWith("../") || normalized === "..") {
+        return null;
+    }
+    return normalized;
+}
+function checkPath(path, resolved) {
+    const { modeName, mode } = resolved;
+    // Precedence (protected > dependency > out-of-scope) lives in the shared
+    // classifier so this hook (layer 2) and the CI scope critic (layer 4)
+    // cannot drift — spec §4.4. This function maps the classification to the
+    // guard's dual-register deny messages.
+    const classification = classifyModePath(path, mode);
+    switch (classification.kind) {
+        case "protected":
+            return deny(`"${path}" is a protected area that needs an engineer — ${modeName} mode can't change it.`, `path matches mode "${modeName}" protectedPaths (protected wins over writeScopes) — do not retry; offer a handoff (df handoff) describing the intended change`);
+        case "dependency":
+            return deny(`Adding or changing installed packages isn't something ${modeName} mode can do.`, `dependencyPolicy is "none" for mode "${modeName}" — dependency changes escalate to an engineer via handoff`);
+        case "out-of-scope":
+            return deny(`"${path}" is outside the design areas set up for you, so ${modeName} mode left it unchanged.`, `path matches no writeScopes entry for mode "${modeName}" — if the task genuinely needs this file, stop and offer a handoff instead of retrying`);
+        case "allow":
+            return ALLOW;
+    }
+}
+function checkBash(command, resolved) {
+    const { modeName, mode } = resolved;
+    const trimmed = command.trim();
+    // Specific denials first — they carry sharper reasons than the default.
+    for (const { re, what } of DESTRUCTIVE_BASH) {
+        if (re.test(trimmed)) {
+            return deny(`That command could destroy work (${what}), so ${modeName} mode blocked it.`, `destructive command class "${what}" is always denied in operator modes — never needed for design work`);
+        }
+    }
+    if (mode.dependencyPolicy === "none" && DEPENDENCY_BASH.test(trimmed)) {
+        return deny(`Installing new packages isn't something ${modeName} mode can do.`, `dependencyPolicy is "none" for mode "${modeName}" — dependency additions escalate via handoff`);
+    }
+    // The catalog's own dev-server command is repo-author-committed — trusted
+    // verbatim (exact match only).
+    if (mode.devServer?.command && trimmed === mode.devServer.command.trim()) {
+        return ALLOW;
+    }
+    // Default-deny with a curated allowlist: single unchained commands only.
+    if (!BASH_METACHARS.test(trimmed) && BASH_ALLOWLIST.some((re) => re.test(trimmed))) {
+        return ALLOW;
+    }
+    return deny(`That command isn't on ${modeName} mode's safe list, so it wasn't run.`, `bash is default-deny in mode "${modeName}" (shell writes would bypass writeScopes) — use the file tools for edits inside writeScopes, the configured devServer command for previews, or offer a handoff`);
+}
+export function decideGuard(input, resolved) {
+    // Layer-2 invisibility: no active mode, no opinions.
+    if (!resolved)
+        return ALLOW;
+    if (typeof input !== "object" || input === null)
+        return failClosed(resolved.modeName);
+    const hook = input;
+    if (typeof hook.tool_name !== "string")
+        return failClosed(resolved.modeName);
+    const toolInput = typeof hook.tool_input === "object" && hook.tool_input !== null
+        ? hook.tool_input
+        : {};
+    if (FILE_TOOLS.has(hook.tool_name)) {
+        const rawPath = toolInput["file_path"] ?? toolInput["notebook_path"];
+        if (typeof rawPath !== "string" || rawPath.length === 0) {
+            return failClosed(resolved.modeName);
+        }
+        const cwd = typeof hook.cwd === "string" && hook.cwd.length > 0 ? hook.cwd : process.cwd();
+        const rel = relativize(rawPath, cwd);
+        if (rel === null) {
+            return deny(`That file is outside this project, so ${resolved.modeName} mode left it alone.`, `path resolves outside the repo root — always denied in operator modes`);
+        }
+        return checkPath(rel, resolved);
+    }
+    if (hook.tool_name === "Bash") {
+        const command = toolInput["command"];
+        if (typeof command !== "string")
+            return failClosed(resolved.modeName);
+        return checkBash(command, resolved);
+    }
+    // Read-only / non-mutating tools pass through untouched.
+    return ALLOW;
+}
+//# sourceMappingURL=guard.js.map

package/dist/mode/guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.js","sourceRoot":"","sources":["../../src/mode/guard.ts"],"names":[],"mappings":"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"}

package/dist/mode/init.d.ts

@@ -0,0 +1,17 @@
+import { type ModeConfig } from "@momentiq/dark-factory-schemas";
+export interface InitModeResult {
+    status: "created" | "exists";
+    modeName: string;
+    configPath: string;
+    writeScopes: string[];
+}
+/**
+ * Propose write scopes from directories that exist. Monorepo `apps/<name>`
+ * workspaces are scanned one level deep. Styling files are always in scope —
+ * a designer mode with no reachable surface still gets `**\/*.css` so the
+ * engineer sees an editable (if minimal) seed to correct in the init PR.
+ */
+export declare function detectWriteScopes(repoRoot: string): string[];
+export declare function buildDefaultModeEntry(repoRoot: string, modeName: string): ModeConfig;
+export declare function initMode(repoRoot: string, modeName: string): InitModeResult;
+//# sourceMappingURL=init.d.ts.map

package/dist/mode/init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/mode/init.ts"],"names":[],"mappings":"AAgBA,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,gCAAgC,CAAC;AAIxC,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAkCD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAiB5D;AAkBD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAcpF;AAED,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,CAwD3E"}

package/dist/mode/init.js

@@ -0,0 +1,147 @@
+// Cycle 27 Phase A — `df mode init <name>`: seed a `modes.<name>` catalog
+// entry into the consumer's darkfactory.yaml.
+//
+// Design constraints:
+//  - APPEND, never re-serialize the consumer's file: hand-maintained comments
+//    and formatting survive. The appended block is generated YAML.
+//  - Deterministic scope proposal: only directories that actually exist are
+//    proposed (the engineer reviews the init PR — this is a seed, not policy).
+//  - Idempotent: an existing `modes.<name>` entry short-circuits to "exists".
+//  - Fail closed: the candidate file content must round-trip through the
+//    canonical parser (@momentiq/dark-factory-schemas) before it is written.
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { MODE_NAME_RE, parseDarkFactoryConfig, } from "@momentiq/dark-factory-schemas";
+import { loadModeConfig } from "./loadConfig.js";
+const DEFAULT_PROTECTED_PATHS = [
+    "**/auth/**",
+    "**/api/**",
+    "**/migrations/**",
+    ".github/**",
+    "**/*.config.*",
+    "package.json",
+    "package-lock.json",
+];
+const ROOT_SCOPE_DIR_CANDIDATES = [
+    "src/components",
+    "src/app",
+    "src/pages",
+    "src/styles",
+    "app",
+    "components",
+    "pages",
+    "styles",
+    "public",
+];
+const APP_SCOPE_SUBDIR_CANDIDATES = ["src/components", "src/app", "src/pages", "public"];
+function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Propose write scopes from directories that exist. Monorepo `apps/<name>`
+ * workspaces are scanned one level deep. Styling files are always in scope —
+ * a designer mode with no reachable surface still gets `**\/*.css` so the
+ * engineer sees an editable (if minimal) seed to correct in the init PR.
+ */
+export function detectWriteScopes(repoRoot) {
+    const scopes = [];
+    for (const candidate of ROOT_SCOPE_DIR_CANDIDATES) {
+        if (isDir(join(repoRoot, candidate)))
+            scopes.push(`${candidate}/**`);
+    }
+    const appsRoot = join(repoRoot, "apps");
+    if (isDir(appsRoot)) {
+        for (const entry of readdirSync(appsRoot).sort()) {
+            for (const sub of APP_SCOPE_SUBDIR_CANDIDATES) {
+                if (isDir(join(appsRoot, entry, sub))) {
+                    scopes.push(`apps/${entry}/${sub}/**`);
+                }
+            }
+        }
+    }
+    scopes.push("**/*.css");
+    return scopes;
+}
+function detectDevServer(repoRoot) {
+    const pkgPath = join(repoRoot, "package.json");
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (pkg.scripts?.["dev"]) {
+            return { command: "npm run dev", url: "http://localhost:3000" };
+        }
+    }
+    catch {
+        // Malformed package.json → no dev-server proposal; init still succeeds.
+    }
+    return undefined;
+}
+export function buildDefaultModeEntry(repoRoot, modeName) {
+    const writeScopes = detectWriteScopes(repoRoot);
+    const devServer = detectDevServer(repoRoot);
+    const entry = {
+        writeScopes,
+        protectedPaths: [...DEFAULT_PROTECTED_PATHS],
+        dependencyPolicy: "none",
+        diffBudget: { maxFiles: 15, maxLines: 600 },
+        designSystem: { designMd: "DESIGN.md" },
+        evidence: { visual: "required" },
+    };
+    if (devServer)
+        entry.devServer = devServer;
+    void modeName; // reserved: future per-mode-name defaults (e.g. "pm")
+    return entry;
+}
+export function initMode(repoRoot, modeName) {
+    if (!MODE_NAME_RE.test(modeName)) {
+        // Validated BEFORE any file work: the name is interpolated into
+        // generated YAML (comment lines + map key) — newlines or comment
+        // breakouts are injection, not typos. Same rule the canonical parser
+        // enforces, applied early for a better error.
+        throw new Error(`df mode init: invalid mode name ${JSON.stringify(modeName)} — mode names must be ` +
+            `lowercase slugs matching ${MODE_NAME_RE.source} (e.g. "designer").`);
+    }
+    // Shared read → parseYaml → parseDarkFactoryConfig ritual (with the raw
+    // `text` init appends to) lives in loadModeConfig — one interpretation of
+    // darkfactory.yaml across the `df mode …` surface.
+    const { configPath, text: existingText, config: existingConfig } = loadModeConfig(repoRoot);
+    const entry = buildDefaultModeEntry(repoRoot, modeName);
+    if (existingConfig.modes?.[modeName]) {
+        return {
+            status: "exists",
+            modeName,
+            configPath,
+            writeScopes: existingConfig.modes[modeName]?.writeScopes ?? [],
+        };
+    }
+    if (existingConfig.modes) {
+        // Appending a second top-level `modes:` block would produce a duplicate
+        // YAML key. Rare (multi-mode repos) — fail with a precise manual step
+        // rather than re-serializing the consumer's file and destroying comments.
+        throw new Error(`df mode init: darkfactory.yaml already has a \`modes\` catalog ` +
+            `(without "${modeName}"). Add the entry under the existing \`modes:\` ` +
+            `key manually — df will not rewrite your file.`);
+    }
+    const block = `\n# Operator-mode catalog (cycle 27) — seeded by \`df mode init ${modeName}\`.\n` +
+        `# Review the proposed scopes: protectedPaths always wins over writeScopes.\n` +
+        stringifyYaml({ modes: { [modeName]: entry } });
+    const separator = existingText.length === 0 || existingText.endsWith("\n") ? "" : "\n";
+    const candidate = existingText + separator + block;
+    // Fail closed: the file we are about to write must parse canonically.
+    parseDarkFactoryConfig(parseYaml(candidate));
+    writeFileSync(configPath, candidate);
+    return {
+        status: "created",
+        modeName,
+        configPath,
+        writeScopes: entry.writeScopes ?? [],
+    };
+}
+//# sourceMappingURL=init.js.map