@litfamily/litcodex 1.0.0

package/node_modules/@litcodex/lit-loop/dist/markers.d.ts

@@ -0,0 +1,33 @@
+export declare const LIT_LOOP_DIRECTIVE_MARKER: "<lit-loop-mode>";
+export declare const LIT_LOOP_DIRECTIVE_CLOSE: "</lit-loop-mode>";
+export declare const LITWORK_DIRECTIVE_MARKER: "<litwork-mode>";
+export declare const LITWORK_DIRECTIVE_CLOSE: "</litwork-mode>";
+export declare const LIT_PLAN_DIRECTIVE_MARKER: "<lit-plan-mode>";
+export declare const LIT_PLAN_DIRECTIVE_CLOSE: "</lit-plan-mode>";
+export declare const LITGOAL_DIRECTIVE_MARKER: "<litgoal-mode>";
+export declare const LITGOAL_DIRECTIVE_CLOSE: "</litgoal-mode>";
+export declare const REVIEW_WORK_DIRECTIVE_MARKER: "<review-work-mode>";
+export declare const REVIEW_WORK_DIRECTIVE_CLOSE: "</review-work-mode>";
+export declare const LITRESEARCH_DIRECTIVE_MARKER: "<litresearch-mode>";
+export declare const LITRESEARCH_DIRECTIVE_CLOSE: "</litresearch-mode>";
+export declare const START_WORK_DIRECTIVE_MARKER: "<start-work-mode>";
+export declare const START_WORK_DIRECTIVE_CLOSE: "</start-work-mode>";
+export declare const LIT_RECAP_DIRECTIVE_MARKER: "<lit-recap-mode>";
+export declare const LIT_RECAP_DIRECTIVE_CLOSE: "</lit-recap-mode>";
+export declare const LIT_CRUCIBLE_DIRECTIVE_MARKER: "<lit-crucible-mode>";
+export declare const LIT_CRUCIBLE_DIRECTIVE_CLOSE: "</lit-crucible-mode>";
+export declare const LIT_INIT_DIRECTIVE_MARKER: "<lit-init-mode>";
+export declare const LIT_INIT_DIRECTIVE_CLOSE: "</lit-init-mode>";
+export declare const DEEP_INTERVIEW_DIRECTIVE_MARKER: "<deep-interview-mode>";
+export declare const DEEP_INTERVIEW_DIRECTIVE_CLOSE: "</deep-interview-mode>";
+export declare const HANDOFF_DIRECTIVE_MARKER: "<lit-handoff-mode>";
+export declare const HANDOFF_DIRECTIVE_CLOSE: "</lit-handoff-mode>";
+export declare const SCIENTIFIC_VISUALIZATION_DIRECTIVE_MARKER: "<lit-scientific-visualization-mode>";
+export declare const SCIENTIFIC_VISUALIZATION_DIRECTIVE_CLOSE: "</lit-scientific-visualization-mode>";
+export declare const BROWSER_DRIVE_DIRECTIVE_MARKER: "<browser-drive-mode>";
+export declare const BROWSER_DRIVE_DIRECTIVE_CLOSE: "</browser-drive-mode>";
+export declare const SKILL_OBSERVER_DIRECTIVE_MARKER: "<skill-observer-mode>";
+export declare const SKILL_OBSERVER_DIRECTIVE_CLOSE: "</skill-observer-mode>";
+export declare const LIT_COMPREHEND_DIRECTIVE_MARKER: "<lit-comprehend-mode>";
+export declare const LIT_COMPREHEND_DIRECTIVE_CLOSE: "</lit-comprehend-mode>";
+export type LitLoopDirectiveMarker = typeof LIT_LOOP_DIRECTIVE_MARKER;

package/node_modules/@litcodex/lit-loop/dist/markers.js

@@ -0,0 +1,38 @@
+// Single source of the lit-family directive markers (A3 C1).
+// Zero-dependency on purpose: guards.ts, directive.ts, and modes.ts import (and
+// re-export) from here so the dedupe markers can never drift between them
+// while preserving the no-cycle invariant (guards never imports directive).
+export const LIT_LOOP_DIRECTIVE_MARKER = "<lit-loop-mode>";
+export const LIT_LOOP_DIRECTIVE_CLOSE = "</lit-loop-mode>";
+// lit-family modes (multi-mode hook router): each mode owns its open/close marker pair so the
+// per-mode idempotency guard (RC1) scans the transcript for the MATCHED mode's marker only.
+export const LITWORK_DIRECTIVE_MARKER = "<litwork-mode>";
+export const LITWORK_DIRECTIVE_CLOSE = "</litwork-mode>";
+export const LIT_PLAN_DIRECTIVE_MARKER = "<lit-plan-mode>";
+export const LIT_PLAN_DIRECTIVE_CLOSE = "</lit-plan-mode>";
+export const LITGOAL_DIRECTIVE_MARKER = "<litgoal-mode>";
+export const LITGOAL_DIRECTIVE_CLOSE = "</litgoal-mode>";
+export const REVIEW_WORK_DIRECTIVE_MARKER = "<review-work-mode>";
+export const REVIEW_WORK_DIRECTIVE_CLOSE = "</review-work-mode>";
+export const LITRESEARCH_DIRECTIVE_MARKER = "<litresearch-mode>";
+export const LITRESEARCH_DIRECTIVE_CLOSE = "</litresearch-mode>";
+export const START_WORK_DIRECTIVE_MARKER = "<start-work-mode>";
+export const START_WORK_DIRECTIVE_CLOSE = "</start-work-mode>";
+export const LIT_RECAP_DIRECTIVE_MARKER = "<lit-recap-mode>";
+export const LIT_RECAP_DIRECTIVE_CLOSE = "</lit-recap-mode>";
+export const LIT_CRUCIBLE_DIRECTIVE_MARKER = "<lit-crucible-mode>";
+export const LIT_CRUCIBLE_DIRECTIVE_CLOSE = "</lit-crucible-mode>";
+export const LIT_INIT_DIRECTIVE_MARKER = "<lit-init-mode>";
+export const LIT_INIT_DIRECTIVE_CLOSE = "</lit-init-mode>";
+export const DEEP_INTERVIEW_DIRECTIVE_MARKER = "<deep-interview-mode>";
+export const DEEP_INTERVIEW_DIRECTIVE_CLOSE = "</deep-interview-mode>";
+export const HANDOFF_DIRECTIVE_MARKER = "<lit-handoff-mode>";
+export const HANDOFF_DIRECTIVE_CLOSE = "</lit-handoff-mode>";
+export const SCIENTIFIC_VISUALIZATION_DIRECTIVE_MARKER = "<lit-scientific-visualization-mode>";
+export const SCIENTIFIC_VISUALIZATION_DIRECTIVE_CLOSE = "</lit-scientific-visualization-mode>";
+export const BROWSER_DRIVE_DIRECTIVE_MARKER = "<browser-drive-mode>";
+export const BROWSER_DRIVE_DIRECTIVE_CLOSE = "</browser-drive-mode>";
+export const SKILL_OBSERVER_DIRECTIVE_MARKER = "<skill-observer-mode>";
+export const SKILL_OBSERVER_DIRECTIVE_CLOSE = "</skill-observer-mode>";
+export const LIT_COMPREHEND_DIRECTIVE_MARKER = "<lit-comprehend-mode>";
+export const LIT_COMPREHEND_DIRECTIVE_CLOSE = "</lit-comprehend-mode>";

package/node_modules/@litcodex/lit-loop/dist/modes.d.ts

@@ -0,0 +1,29 @@
+import type { RenamedSkillId } from "./skill-renames.js";
+import type { LitTriggerToken } from "./trigger.js";
+/** Lit-family modes. Multiple tokens may map to one mode (lit/litcodex/lit-loop → lit-loop). */
+export type LitMode = RenamedSkillId | "browser-drive" | "skill-observer" | "lit-handoff" | "lit-scientific-visualization" | "deep-interview" | "lit-crucible" | "lit-init" | "lit-loop" | "litwork" | "lit-plan" | "litgoal" | "review-work" | "litresearch" | "start-work" | "lit-recap" | "lit-comprehend";
+/** Per-mode routing spec: its marker pair (guard) + resolved directive path (loader). */
+export interface LitModeSpec {
+    readonly mode: LitMode;
+    readonly openMarker: string;
+    readonly closeMarker: string;
+    /** Absolute path to the mode's directive.md, resolved from this module. */
+    readonly directivePath: string;
+    /** The bundled skill whose full SKILL.md body must be injected for this mode. */
+    readonly skillName: string;
+    /** Absolute path to the bundled skill body. */
+    readonly skillPath: string;
+}
+export declare function resolveSkillPath(name: string): string;
+/** Exact bare `handoff` has a dedicated route outside the bounded lit-family token grammar. */
+export declare const HANDOFF_MODE_SPEC: LitModeSpec;
+/** Exact bare `lit-scientific-visualization` is a standalone route outside the token grammar. */
+export declare const SCIENTIFIC_VISUALIZATION_MODE_SPEC: LitModeSpec;
+/** Exact browser-drive and `$litcodex:browser-drive` are standalone routes outside token matching. */
+export declare const BROWSER_DRIVE_MODE_SPEC: LitModeSpec;
+/** Exact skill-observer and `$litcodex:skill-observer` are standalone routes. */
+export declare const SKILL_OBSERVER_MODE_SPEC: LitModeSpec;
+/** Token → mode spec. Frozen; the single source the hook router branches on. */
+export declare const MODE_BY_TOKEN: Readonly<Record<LitTriggerToken, LitModeSpec>>;
+/** The mode spec for a matched token. Total over the token union (every token has a spec). */
+export declare function modeForToken(token: LitTriggerToken): LitModeSpec;

package/node_modules/@litcodex/lit-loop/dist/modes.js

@@ -0,0 +1,176 @@
+// src/modes.ts — multi-mode hook router table (RC1/RC2).
+//
+// Maps each bounded trigger token (trigger.ts) to its mode spec: the open/close directive markers
+// (for the per-mode idempotency guard, RC1) and the absolute directive path (for the generic loader,
+// RC2). The lit-loop-family tokens (lit-loop / litcodex / lit) share the single lit-loop mode;
+// sibling tokens and natural lit phrases route to their own mode directives.
+//
+// Layout decision (SDD RC4): lit-loop keeps the authored `directive.md` at the COMPONENT ROOT (zero
+// churn to its lockstep points); sibling directives live under `directives/<mode>.md`. Paths
+// resolve relative to THIS module so they land correctly from both layouts (src/modes.ts →
+// <component>/… in dev/vitest; dist/modes.js → <pkg>/… in the published tarball, where files[] ships
+// `directive.md` and the `directives/` dir beside dist/). Path resolution never reads the file; the
+// loader reads lazily + fail-silent, so a not-yet-authored directive simply degrades to a noop.
+//
+// Imports markers + the trigger token type only (no cycle: hook → modes → {markers, trigger}).
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { BROWSER_DRIVE_DIRECTIVE_CLOSE, BROWSER_DRIVE_DIRECTIVE_MARKER, DEEP_INTERVIEW_DIRECTIVE_CLOSE, DEEP_INTERVIEW_DIRECTIVE_MARKER, HANDOFF_DIRECTIVE_CLOSE, HANDOFF_DIRECTIVE_MARKER, LIT_COMPREHEND_DIRECTIVE_CLOSE, LIT_COMPREHEND_DIRECTIVE_MARKER, LIT_CRUCIBLE_DIRECTIVE_CLOSE, LIT_CRUCIBLE_DIRECTIVE_MARKER, LIT_INIT_DIRECTIVE_CLOSE, LIT_INIT_DIRECTIVE_MARKER, LIT_LOOP_DIRECTIVE_CLOSE, LIT_LOOP_DIRECTIVE_MARKER, LIT_PLAN_DIRECTIVE_CLOSE, LIT_PLAN_DIRECTIVE_MARKER, LIT_RECAP_DIRECTIVE_CLOSE, LIT_RECAP_DIRECTIVE_MARKER, LITGOAL_DIRECTIVE_CLOSE, LITGOAL_DIRECTIVE_MARKER, LITRESEARCH_DIRECTIVE_CLOSE, LITRESEARCH_DIRECTIVE_MARKER, LITWORK_DIRECTIVE_CLOSE, LITWORK_DIRECTIVE_MARKER, REVIEW_WORK_DIRECTIVE_CLOSE, REVIEW_WORK_DIRECTIVE_MARKER, SCIENTIFIC_VISUALIZATION_DIRECTIVE_CLOSE, SCIENTIFIC_VISUALIZATION_DIRECTIVE_MARKER, SKILL_OBSERVER_DIRECTIVE_CLOSE, SKILL_OBSERVER_DIRECTIVE_MARKER, START_WORK_DIRECTIVE_CLOSE, START_WORK_DIRECTIVE_MARKER, } from "./markers.js";
+/** Resolve a path relative to this module (percent-decoding, space/#/Hangul-safe). */
+function resolveFromHere(rel) {
+    return fileURLToPath(new URL(rel, import.meta.url));
+}
+export function resolveSkillPath(name) {
+    const devTree = resolveFromHere(`../../../skills/${name}/SKILL.md`);
+    if (existsSync(devTree))
+        return devTree;
+    return resolveFromHere(`../skills/${name}/SKILL.md`);
+}
+function resolveAuthoredHandoffPath() {
+    const relative = "vendor/handoff/SKILL.md";
+    const devTree = resolveFromHere(`../../../${relative}`);
+    return existsSync(devTree) ? devTree : resolveFromHere(`../${relative}`);
+}
+// lit-loop keeps the component-root directive.md (A3 G6); shared by lit / litcodex / lit-loop tokens.
+const LIT_LOOP_SPEC = Object.freeze({
+    mode: "lit-loop",
+    openMarker: LIT_LOOP_DIRECTIVE_MARKER,
+    closeMarker: LIT_LOOP_DIRECTIVE_CLOSE,
+    directivePath: resolveFromHere("../directive.md"),
+    skillName: "lit-loop",
+    skillPath: resolveSkillPath("lit-loop"),
+});
+/** Exact bare `handoff` has a dedicated route outside the bounded lit-family token grammar. */
+export const HANDOFF_MODE_SPEC = Object.freeze({
+    mode: "lit-handoff",
+    openMarker: HANDOFF_DIRECTIVE_MARKER,
+    closeMarker: HANDOFF_DIRECTIVE_CLOSE,
+    directivePath: resolveFromHere("../directives/lit-handoff.md"),
+    skillName: "lit-handoff",
+    skillPath: resolveAuthoredHandoffPath(),
+});
+/** Exact bare `lit-scientific-visualization` is a standalone route outside the token grammar. */
+export const SCIENTIFIC_VISUALIZATION_MODE_SPEC = Object.freeze({
+    mode: "lit-scientific-visualization",
+    openMarker: SCIENTIFIC_VISUALIZATION_DIRECTIVE_MARKER,
+    closeMarker: SCIENTIFIC_VISUALIZATION_DIRECTIVE_CLOSE,
+    directivePath: resolveFromHere("../directives/lit-scientific-visualization.md"),
+    skillName: "lit-scientific-visualization",
+    skillPath: resolveSkillPath("lit-scientific-visualization"),
+});
+/** Exact browser-drive and `$litcodex:browser-drive` are standalone routes outside token matching. */
+export const BROWSER_DRIVE_MODE_SPEC = Object.freeze({
+    mode: "browser-drive",
+    openMarker: BROWSER_DRIVE_DIRECTIVE_MARKER,
+    closeMarker: BROWSER_DRIVE_DIRECTIVE_CLOSE,
+    directivePath: resolveFromHere("../directives/browser-drive.md"),
+    skillName: "browser-drive",
+    skillPath: resolveSkillPath("browser-drive"),
+});
+/** Exact skill-observer and `$litcodex:skill-observer` are standalone routes. */
+export const SKILL_OBSERVER_MODE_SPEC = Object.freeze({
+    mode: "skill-observer",
+    openMarker: SKILL_OBSERVER_DIRECTIVE_MARKER,
+    closeMarker: SKILL_OBSERVER_DIRECTIVE_CLOSE,
+    directivePath: resolveFromHere("../directives/skill-observer.md"),
+    skillName: "skill-observer",
+    skillPath: resolveSkillPath("skill-observer"),
+});
+/** Token → mode spec. Frozen; the single source the hook router branches on. */
+export const MODE_BY_TOKEN = Object.freeze({
+    "lit-crucible": Object.freeze({
+        mode: "lit-crucible",
+        openMarker: LIT_CRUCIBLE_DIRECTIVE_MARKER,
+        closeMarker: LIT_CRUCIBLE_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/lit-crucible.md"),
+        skillName: "lit-crucible",
+        skillPath: resolveSkillPath("lit-crucible"),
+    }),
+    "lit-init": Object.freeze({
+        mode: "lit-init",
+        openMarker: LIT_INIT_DIRECTIVE_MARKER,
+        closeMarker: LIT_INIT_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/lit-init.md"),
+        skillName: "lit-init",
+        skillPath: resolveSkillPath("lit-init"),
+    }),
+    "deep-interview": Object.freeze({
+        mode: "deep-interview",
+        openMarker: DEEP_INTERVIEW_DIRECTIVE_MARKER,
+        closeMarker: DEEP_INTERVIEW_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/deep-interview.md"),
+        skillName: "deep-interview",
+        skillPath: resolveSkillPath("deep-interview"),
+    }),
+    "lit-loop": LIT_LOOP_SPEC,
+    litcodex: LIT_LOOP_SPEC,
+    lit: LIT_LOOP_SPEC,
+    litwork: Object.freeze({
+        mode: "litwork",
+        openMarker: LITWORK_DIRECTIVE_MARKER,
+        closeMarker: LITWORK_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/litwork.md"),
+        skillName: "litwork",
+        skillPath: resolveSkillPath("litwork"),
+    }),
+    "lit-plan": Object.freeze({
+        mode: "lit-plan",
+        openMarker: LIT_PLAN_DIRECTIVE_MARKER,
+        closeMarker: LIT_PLAN_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/lit-plan.md"),
+        skillName: "lit-plan",
+        skillPath: resolveSkillPath("lit-plan"),
+    }),
+    litgoal: Object.freeze({
+        mode: "litgoal",
+        openMarker: LITGOAL_DIRECTIVE_MARKER,
+        closeMarker: LITGOAL_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/litgoal.md"),
+        skillName: "litgoal",
+        skillPath: resolveSkillPath("litgoal"),
+    }),
+    "review-work": Object.freeze({
+        mode: "review-work",
+        openMarker: REVIEW_WORK_DIRECTIVE_MARKER,
+        closeMarker: REVIEW_WORK_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/review-work.md"),
+        skillName: "review-work",
+        skillPath: resolveSkillPath("review-work"),
+    }),
+    litresearch: Object.freeze({
+        mode: "litresearch",
+        openMarker: LITRESEARCH_DIRECTIVE_MARKER,
+        closeMarker: LITRESEARCH_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/litresearch.md"),
+        skillName: "litresearch",
+        skillPath: resolveSkillPath("litresearch"),
+    }),
+    "start-work": Object.freeze({
+        mode: "start-work",
+        openMarker: START_WORK_DIRECTIVE_MARKER,
+        closeMarker: START_WORK_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/start-work.md"),
+        skillName: "start-work",
+        skillPath: resolveSkillPath("start-work"),
+    }),
+    "lit-recap": Object.freeze({
+        mode: "lit-recap",
+        openMarker: LIT_RECAP_DIRECTIVE_MARKER,
+        closeMarker: LIT_RECAP_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/lit-recap.md"),
+        skillName: "lit-recap",
+        skillPath: resolveSkillPath("lit-recap"),
+    }),
+    "lit-comprehend": Object.freeze({
+        mode: "lit-comprehend",
+        openMarker: LIT_COMPREHEND_DIRECTIVE_MARKER,
+        closeMarker: LIT_COMPREHEND_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/lit-comprehend.md"),
+        skillName: "lit-comprehend",
+        skillPath: resolveSkillPath("lit-comprehend"),
+    }),
+});
+/** The mode spec for a matched token. Total over the token union (every token has a spec). */
+export function modeForToken(token) {
+    return MODE_BY_TOKEN[token];
+}

package/node_modules/@litcodex/lit-loop/dist/plan-persistence.d.ts

@@ -0,0 +1,20 @@
+export declare const PLAN_PERSISTENCE_DIR = ".litcodex/lit-plan";
+export declare const PLAN_PERSISTENCE_PLANS_DIR = ".litcodex/plans";
+export declare const PLAN_PERSISTENCE_MAX_BLOCKS = 2;
+export declare const PLAN_PUBLISHER_COMMAND = "node <plugin-root>/components/start-work-continuation/dist/cli.js publish-plan --cwd <path> --slug <slug>";
+export type PlanPersistenceDecision = {
+    readonly decision: "pass";
+} | {
+    readonly decision: "block";
+    readonly reason: string;
+};
+/** Record (or re-record) a lit-plan activation for `sessionId`. Fail-open: never throws. */
+export declare function recordLitPlanActivation(repoRoot: string, sessionId: string, now?: number): void;
+/**
+ * Decide whether the Stop for `sessionId` may end. Pass when no activation exists, when the guard is
+ * already satisfied, or when the block cap is spent; otherwise block until a checkbox plan newer than
+ * the activation exists. Fail-open on any fs error.
+ */
+export declare function evaluatePlanPersistence(repoRoot: string, sessionId: string): PlanPersistenceDecision;
+/** Codex Stop hook output for a block decision (single line + newline). */
+export declare function formatStopBlockOutput(reason: string): string;

package/node_modules/@litcodex/lit-loop/dist/plan-persistence.js

@@ -0,0 +1,147 @@
+// src/plan-persistence.ts — lit-plan plan-file persistence guard for the Stop hook.
+//
+// A lit-plan turn must leave a durable `.litcodex/plans/<slug>.md` behind (written through the
+// compiled start-work-continuation publisher), otherwise `lit start work` later fails with a missing
+// plan. The UserPromptSubmit hook records the activation timestamp per session when the lit-plan
+// directive is injected; the Stop hook then blocks the turn end until a plan file newer than that
+// activation with at least one top-level `- [ ] N.` task row exists. At most
+// PLAN_PERSISTENCE_MAX_BLOCKS blocks are issued per session so a model that keeps interviewing (or a
+// user who abandons the plan) can never be trapped in a Stop loop. Every fs failure is FAIL-OPEN.
+import { mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { normalizeSessionId } from "./state-paths.js";
+export const PLAN_PERSISTENCE_DIR = ".litcodex/lit-plan";
+export const PLAN_PERSISTENCE_PLANS_DIR = ".litcodex/plans";
+export const PLAN_PERSISTENCE_MAX_BLOCKS = 2;
+export const PLAN_PUBLISHER_COMMAND = "node <plugin-root>/components/start-work-continuation/dist/cli.js publish-plan --cwd <path> --slug <slug>";
+const STATE_VERSION = 1;
+const MAX_PLAN_BYTES = 1_000_000;
+const TASK_ROW = /^- \[ \] \d+\./m;
+const PASS = Object.freeze({ decision: "pass" });
+function statePath(repoRoot, sessionId) {
+    const id = normalizeSessionId(sessionId);
+    if (id === null || !isAbsolute(repoRoot))
+        return null;
+    return join(repoRoot, PLAN_PERSISTENCE_DIR, `${id}.json`);
+}
+function readState(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+            return null;
+        const record = parsed;
+        if (record["version"] !== STATE_VERSION ||
+            typeof record["sessionId"] !== "string" ||
+            typeof record["activatedAt"] !== "number" ||
+            typeof record["blocks"] !== "number" ||
+            typeof record["satisfied"] !== "boolean") {
+            return null;
+        }
+        return {
+            version: STATE_VERSION,
+            sessionId: record["sessionId"],
+            activatedAt: record["activatedAt"],
+            blocks: record["blocks"],
+            satisfied: record["satisfied"],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeState(path, state) {
+    mkdirSync(join(path, ".."), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    renameSync(tmp, path);
+}
+/** Record (or re-record) a lit-plan activation for `sessionId`. Fail-open: never throws. */
+export function recordLitPlanActivation(repoRoot, sessionId, now = Date.now()) {
+    const path = statePath(repoRoot, sessionId);
+    if (path === null)
+        return;
+    try {
+        writeState(path, { version: STATE_VERSION, sessionId, activatedAt: now, blocks: 0, satisfied: false });
+    }
+    catch {
+        // A state write failure only disables the guard for this session.
+    }
+}
+/** Newest `.litcodex/plans/*.md` modified at or after `since`, or null when none exists. */
+function newestPlanSince(repoRoot, since) {
+    const dir = join(repoRoot, PLAN_PERSISTENCE_PLANS_DIR);
+    let entries;
+    try {
+        entries = readdirSync(dir).filter((name) => name.endsWith(".md") && !name.startsWith("."));
+    }
+    catch {
+        return null;
+    }
+    let newest = null;
+    for (const file of entries) {
+        try {
+            const stat = statSync(join(dir, file));
+            if (!stat.isFile() || stat.mtimeMs < since || stat.size > MAX_PLAN_BYTES)
+                continue;
+            if (newest === null || stat.mtimeMs > newest.mtimeMs)
+                newest = { file, mtimeMs: stat.mtimeMs };
+        }
+        catch {
+            // unreadable entry: skip
+        }
+    }
+    if (newest === null)
+        return null;
+    try {
+        const body = readFileSync(join(dir, newest.file), "utf8");
+        return { file: newest.file, taskRows: body.split(/\r?\n/).filter((line) => TASK_ROW.test(line)).length };
+    }
+    catch {
+        return null;
+    }
+}
+function blockReason(detail) {
+    return (`lit-plan must persist the plan before finishing: ${detail}. ` +
+        `If the user approved the plan, publish it now through the compiled publisher: ${PLAN_PUBLISHER_COMMAND} ` +
+        "(plan Markdown on stdin; `## Todos` rows as `- [ ] N. <title>` at column zero). " +
+        `If approval is still pending, ask for it explicitly and end the turn; this guard blocks at most ${PLAN_PERSISTENCE_MAX_BLOCKS} turns per session.`);
+}
+/**
+ * Decide whether the Stop for `sessionId` may end. Pass when no activation exists, when the guard is
+ * already satisfied, or when the block cap is spent; otherwise block until a checkbox plan newer than
+ * the activation exists. Fail-open on any fs error.
+ */
+export function evaluatePlanPersistence(repoRoot, sessionId) {
+    const path = statePath(repoRoot, sessionId);
+    if (path === null)
+        return PASS;
+    const state = readState(path);
+    if (state === null || state.satisfied)
+        return PASS;
+    const newest = newestPlanSince(repoRoot, state.activatedAt);
+    if (newest !== null && newest.taskRows > 0) {
+        try {
+            writeState(path, { ...state, satisfied: true });
+        }
+        catch {
+            // Losing the satisfied mark only means the next Stop re-checks the (already valid) plan.
+        }
+        return PASS;
+    }
+    if (state.blocks >= PLAN_PERSISTENCE_MAX_BLOCKS)
+        return PASS;
+    try {
+        writeState(path, { ...state, blocks: state.blocks + 1 });
+    }
+    catch {
+        return PASS;
+    }
+    const detail = newest === null
+        ? `no ${PLAN_PERSISTENCE_PLANS_DIR}/<slug>.md was written after this lit-plan prompt`
+        : `the newest plan ${PLAN_PERSISTENCE_PLANS_DIR}/${newest.file} has zero top-level \`- [ ] N.\` checkbox task rows`;
+    return { decision: "block", reason: blockReason(detail) };
+}
+/** Codex Stop hook output for a block decision (single line + newline). */
+export function formatStopBlockOutput(reason) {
+    return `${JSON.stringify({ decision: "block", reason })}\n`;
+}

package/node_modules/@litcodex/lit-loop/dist/redaction.d.ts

@@ -0,0 +1,3 @@
+export declare const REDACTED_SECRET: "[REDACTED_SECRET]";
+export declare function redactSecrets(text: string): string;
+export declare function redactSecretsInValue<T>(value: T): T;

package/node_modules/@litcodex/lit-loop/dist/redaction.js

@@ -0,0 +1,177 @@
+// src/redaction.ts — prompt/evidence secret redaction helpers.
+// Pure, deterministic, and intentionally conservative: user text may be persisted into brief.md,
+// goals.json, ledger.jsonl, and Codex goal handoff output, so known secret shapes are replaced before
+// state writes or model-facing payload rendering.
+export const REDACTED_SECRET = "[REDACTED_SECRET]";
+const DIRECT_SECRET_PATTERNS = Object.freeze([
+    /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+    /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g,
+    /\bgithub_pat_[A-Za-z0-9_]{16,}\b/g,
+    /\b(?:glpat|gloas|gldt|glrt|glcbt)-[A-Za-z0-9_-]{8,}\b/g,
+    /\b(?:xox[baprs]|xapp)-[A-Za-z0-9-]{8,}\b/g,
+    /\bnpm_[A-Za-z0-9_-]{8,}\b/g,
+    /\b(?:sk|rk)_(?:live|test)_[A-Za-z0-9_-]{10,}\b/g,
+    /\bwhsec_[A-Za-z0-9_-]{10,}\b/g,
+    /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/giu,
+    /\bAIza[A-Za-z0-9_-]{20,}\b/g,
+    /\bhf_[A-Za-z0-9_-]{20,}\b/g,
+    /\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/g,
+    /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+]);
+// A value that is nothing but a short lowercase word is ordinary English, not a credential: real
+// bearer/basic payloads and generated secrets are base64, hex, JWT, or otherwise mixed-case. This
+// guard is applied only where the surrounding key is itself an English word, so `password=correct`
+// still redacts while `Secret: the plan is simple` survives byte-identical. The cost is that a
+// credential deliberately written as a bare lowercase word after an ambiguous key is not caught.
+const PROSE_VALUE = /(?![a-z]{1,19}(?:[\s"'`]|$))/.source;
+// Keys that are never ordinary prose: redact whatever value follows, including a plain word.
+const HIGH_SIGNAL_KEY_VALUE_SECRET = /\b((?:(?:[A-Za-z][A-Za-z0-9]*[_-]+)*(?:api[_-]?key|access[_-]?token|auth[_-]?token|client[_-]?secret|credential|passphrase|password|private[_-]?key|refresh[_-]?token|_auth(?:token)?)(?:[_-]+[A-Za-z0-9]+)*)\s*[=:]\s*)([^\s"'`]+)/giu;
+// `auth`, `secret`, and `token` are also everyday English, so they require a credential-shaped value.
+const COMPACT_AMBIGUOUS_KEY_VALUE_SECRET = /\b((?:(?:[A-Za-z][A-Za-z0-9]*[_-]+)*(?:auth|secret|token)(?:[_-]+[A-Za-z0-9]+)*)(?:\s*=\s*|:))([^\s"'`]+)/giu;
+const AMBIGUOUS_KEY_VALUE_SECRET = new RegExp(`\\b((?:(?:[A-Za-z][A-Za-z0-9]*[_-]+)*(?:auth|secret|token)(?:[_-]+[A-Za-z0-9]+)*)\\s*[=:]\\s*)(${PROSE_VALUE}[^\\s"'\`]+)`, "giu");
+const AUTH_HEADER_SECRET = /\b((?:(?:Proxy-Authorization|Authorization)[ \t]*:[ \t]*)[^\s"'`:]+[ \t]+)([^\s"'`]+)/giu;
+// A bare `Bearer`/`Basic` scheme carries far less signal than an Authorization header, and "a basic
+// dashboard" is ordinary prose, so the payload must look like a credential.
+const BARE_AUTH_SCHEME_SECRET = new RegExp(`\\b((?:Bearer|Basic)[ \t]+)(${PROSE_VALUE}[^\\s"'\`]+)`, "giu");
+const GENERIC_AUTH_HEADER_SECRET = /\b((?:Proxy-Authorization|Authorization)[ \t]*:[ \t]*)([^\r\n]*\S[^\r\n]*)(?=\r?$)/gimu;
+const URI_USERINFO = /((?:[a-z][a-z0-9+.-]*:\/\/|\/\/))[^/?#\s]*@/giu;
+const PRIVATE_KEY_SECRET = /-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----[\s\S]*?-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----/giu;
+const PRIVATE_KEY_MARKER_SECRET = /-----(?:BEGIN|END) [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----/giu;
+const REDACTION_RULES = Object.freeze([
+    { pattern: URI_USERINFO, replacement: (match) => match[1] ?? "" },
+    { pattern: PRIVATE_KEY_SECRET, replacement: () => REDACTED_SECRET },
+    { pattern: PRIVATE_KEY_MARKER_SECRET, replacement: () => REDACTED_SECRET },
+    {
+        pattern: GENERIC_AUTH_HEADER_SECRET,
+        replacement: (match) => `${match[1] ?? ""}${REDACTED_SECRET}`,
+    },
+    {
+        pattern: AUTH_HEADER_SECRET,
+        replacement: (match) => `${match[1] ?? ""}${REDACTED_SECRET}`,
+    },
+    {
+        pattern: BARE_AUTH_SCHEME_SECRET,
+        replacement: (match) => `${match[1] ?? ""}${REDACTED_SECRET}`,
+    },
+    // High-signal keys are matched before the ambiguous set so `auth_token: none` still redacts.
+    {
+        pattern: HIGH_SIGNAL_KEY_VALUE_SECRET,
+        replacement: (match) => `${match[1] ?? ""}${REDACTED_SECRET}`,
+    },
+    {
+        pattern: COMPACT_AMBIGUOUS_KEY_VALUE_SECRET,
+        replacement: (match) => `${match[1] ?? ""}${REDACTED_SECRET}`,
+    },
+    {
+        pattern: AMBIGUOUS_KEY_VALUE_SECRET,
+        replacement: (match) => `${match[1] ?? ""}${REDACTED_SECRET}`,
+    },
+    ...DIRECT_SECRET_PATTERNS.map((pattern) => ({
+        pattern,
+        replacement: () => REDACTED_SECRET,
+    })),
+]);
+const C1_CSI = /^\u009b[0-?]*[ -/]*[@-~]/u;
+const OBFUSCATION_CONTROL = /[\p{Cc}\p{Cf}]/u;
+function normalizedView(text, preserveControlBoundaries) {
+    let normalized = "";
+    const sourceStarts = [];
+    const sourceEnds = [];
+    const append = (value, start, end) => {
+        normalized += value;
+        for (let index = 0; index < value.length; index += 1) {
+            sourceStarts.push(start);
+            sourceEnds.push(end);
+        }
+    };
+    for (let offset = 0; offset < text.length;) {
+        if (text[offset] === "\u009b") {
+            const sequence = text.slice(offset).match(C1_CSI);
+            if (sequence !== null) {
+                if (preserveControlBoundaries) {
+                    append(" ", offset, offset + sequence[0].length);
+                }
+                offset += sequence[0].length;
+                continue;
+            }
+        }
+        const codePoint = text.codePointAt(offset);
+        if (codePoint === undefined)
+            break;
+        const character = String.fromCodePoint(codePoint);
+        const end = offset + character.length;
+        if (OBFUSCATION_CONTROL.test(character)) {
+            if (character === "\t" || character === "\n" || character === "\r") {
+                append(character, offset, end);
+            }
+            else if (preserveControlBoundaries) {
+                append(" ", offset, end);
+            }
+        }
+        else {
+            append(character, offset, end);
+        }
+        offset = end;
+    }
+    return { text: normalized, sourceStarts, sourceEnds };
+}
+function collectRedactionEdits(view) {
+    const edits = [];
+    for (const [order, rule] of REDACTION_RULES.entries()) {
+        const matcher = new RegExp(rule.pattern.source, rule.pattern.flags);
+        for (const match of view.text.matchAll(matcher)) {
+            const matched = match[0];
+            if (match.index === undefined || matched.length === 0)
+                continue;
+            const lastIndex = match.index + matched.length - 1;
+            const start = view.sourceStarts[match.index];
+            const end = view.sourceEnds[lastIndex];
+            if (start === undefined || end === undefined)
+                continue;
+            edits.push({ start, end, replacement: rule.replacement(match), order });
+        }
+    }
+    return edits;
+}
+function applyRedactionEdits(text, edits) {
+    const selected = [];
+    for (const edit of edits.sort((first, second) => first.start - second.start ||
+        second.end - second.start - (first.end - first.start) ||
+        first.order - second.order)) {
+        const previous = selected.at(-1);
+        if (previous !== undefined && edit.start < previous.end)
+            continue;
+        selected.push(edit);
+    }
+    for (let index = selected.length - 1; index >= 0; index -= 1) {
+        const edit = selected[index];
+        if (edit === undefined)
+            continue;
+        text = `${text.slice(0, edit.start)}${edit.replacement}${text.slice(edit.end)}`;
+    }
+    return text;
+}
+export function redactSecrets(text) {
+    if (typeof text !== "string" || text.length === 0) {
+        return text;
+    }
+    const stripped = normalizedView(text, false);
+    const spaced = normalizedView(text, true);
+    return applyRedactionEdits(text, [...collectRedactionEdits(stripped), ...collectRedactionEdits(spaced)]);
+}
+export function redactSecretsInValue(value) {
+    if (typeof value === "string") {
+        return redactSecrets(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactSecretsInValue(item));
+    }
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            out[key] = redactSecretsInValue(item);
+        }
+        return out;
+    }
+    return value;
+}

package/node_modules/@litcodex/lit-loop/dist/scientific-visualization-route.d.ts

@@ -0,0 +1,7 @@
+import { type GuardTranscriptInput } from "./guards.js";
+/** True only for the complete case-insensitive bare invocation with optional edge whitespace. */
+export declare function isExactBareScientificVisualizationPrompt(prompt: string): boolean;
+/** Reserve the whitespace near miss so it cannot fall through to the generic bare-lit route. */
+export declare function isScientificVisualizationWhitespaceNearMiss(prompt: string): boolean;
+/** Apply transcript idempotency and context-pressure guards to the standalone science route. */
+export declare function shouldSuppressScientificVisualizationInjection(transcriptPath: GuardTranscriptInput): boolean;

package/node_modules/@litcodex/lit-loop/dist/scientific-visualization-route.js

@@ -0,0 +1,15 @@
+import { transcriptHasContextPressureMarker, transcriptHasDirectiveMarker, } from "./guards.js";
+import { SCIENTIFIC_VISUALIZATION_DIRECTIVE_MARKER } from "./markers.js";
+/** True only for the complete case-insensitive bare invocation with optional edge whitespace. */
+export function isExactBareScientificVisualizationPrompt(prompt) {
+    return /^\s*lit-scientific-visualization\s*$/iu.test(prompt);
+}
+/** Reserve the whitespace near miss so it cannot fall through to the generic bare-lit route. */
+export function isScientificVisualizationWhitespaceNearMiss(prompt) {
+    return /^\s*lit\s+scientific\s+visualization\s*$/iu.test(prompt);
+}
+/** Apply transcript idempotency and context-pressure guards to the standalone science route. */
+export function shouldSuppressScientificVisualizationInjection(transcriptPath) {
+    return (transcriptHasDirectiveMarker(transcriptPath, SCIENTIFIC_VISUALIZATION_DIRECTIVE_MARKER) ||
+        transcriptHasContextPressureMarker(transcriptPath));
+}