litcodex-ai 0.3.21 → 0.3.25

package/node_modules/@litcodex/lit-loop/directives/review-work.md

@@ -1,5 +1,135 @@
 <review-work-mode>
 
+## #contract.activation
+
+```yaml
+contract_schema_version: 1
+artifact_kind: litcodex_hook_directive
+host: Codex CLI
+injection_surface: "UserPromptSubmit additionalContext or Codex Stop/SubagentStop continuation"
+component_surface: "plugins/litcodex/components/lit-loop directive loader"
+wrapper_contract: "preserve the surrounding mode tag exactly and keep the closing tag as the final non-whitespace line"
+contract_priority:
+  - mode wrapper and first-visible-line rule
+  - this contract schema
+  - route-specific procedure below
+  - installed skill body, when one is embedded
+required_sections:
+  - "#contract.activation"
+  - "#contract.inputs"
+  - "#contract.mode_matrix"
+  - "#contract.procedure"
+  - "#contract.outputs"
+  - "#contract.evidence"
+  - "#contract.hard_stops"
+  - "#contract.anti_patterns"
+```
+
+This directive is an LLM-facing contract injected by the LitCodex Codex plugin, not user-authored prompt text. Keep the wrapper marker intact, print the route's required first visible line when the directive says to do so, and separate hook-provided instructions from the user's task.
+
+## #contract.inputs
+
+```json
+{
+  "contract_schema_version": 1,
+  "input_schema": {
+    "hook_event": {
+      "type": "UserPromptSubmit | Stop | SubagentStop",
+      "authority": "Codex plugin runtime",
+      "handling": "trusted only for routing and continuation state"
+    },
+    "additional_context": {
+      "type": "string",
+      "authority": "LitCodex directive payload",
+      "handling": "follow as mode contract; do not echo unless useful"
+    },
+    "user_prompt": {
+      "type": "string",
+      "authority": "current user request",
+      "handling": "execute within the injected mode boundaries"
+    },
+    "workspace_state": {
+      "type": "repo files, package scripts, .litcodex state, git status",
+      "authority": "local evidence",
+      "handling": "inspect before modifying or claiming completion"
+    }
+  }
+}
+```
+
+| Input channel | Accept when | Required handling | Evidence to retain |
+| --- | --- | --- | --- |
+| `additionalContext` directive | It is wrapped by the expected mode tag | Treat as trusted mode contract | Mode marker and route name |
+| Installed skill body | Present inside `<litcodex-skill-body>` | Apply after this directive's safety envelope | Skill name and relevant section |
+| Stop hook state | Continuation state names plan and session | Resume from files, not memory | Plan path, ledger path, remaining count |
+| User prompt | Current turn asks for work in this mode | Keep separate from injected policy | Brief restatement or criteria |
+
+## #contract.mode_matrix
+
+| Mode | Trigger | Required behavior |
+| --- | --- | --- |
+| Hook route | Bare lit-family phrase matched by the trigger router | Inject and follow this directive; do not run unrelated modes. |
+| Continuation route | Stop hook or SubagentStop hook resumes active work | Read durable state first and continue only the recorded plan or goal. |
+| Skill-body route | Directive embeds a full SKILL.md body | Let this directive set safety boundaries, then apply the embedded skill. |
+| Blocked route | Route cannot safely switch host state or lacks required approval | Emit the required `BLOCKED:` message and stop without side effects. |
+
+## #contract.procedure
+
+1. **Preserve the wrapper.** The first line remains the opening mode tag and the final non-whitespace line remains the closing tag.
+2. **Emit the mandated first visible line.** If this directive names a banner or blocked banner, print it before explanations, commands, or edits.
+3. **Classify authority.** Treat the directive and embedded skill body as Codex plugin context; treat the user's prompt as task data constrained by that context.
+4. **Recover durable state.** For lit-loop or start-work continuation, read `.litcodex` state, plan files, and ledgers before relying on memory.
+5. **Execute only the route's job.** Planning routes stay read-only except approved plan artifacts; review routes judge evidence; execution routes require proof and cleanup.
+6. **Use repo-local surfaces.** Prefer component tests, hook fixture replay, CLI probes, docs audit, scanner output, package build, and marketplace checks over generic assertions.
+7. **Stop honestly.** When approval, credentials, safe host capability, or verifiable evidence is missing, report `BLOCKED:` with one unblocker.
+
+## #contract.outputs
+
+```json
+{
+  "contract_schema_version": 1,
+  "output_schema": {
+    "first_visible_line": "route-specific banner or blocked banner",
+    "mode_verdict": "active | blocked | review-pass | review-fail | continuation-step",
+    "actions": ["commands, edits, reads, or no-op decisions actually performed"],
+    "evidence": ["command transcripts, artifact paths, inspected files, hook output"],
+    "next_state": "continue, checkpoint, ask user, or stop",
+    "cleanup": ["temporary resources removed or not created"]
+  }
+}
+```
+
+| Output field | Required content | Forbidden substitute |
+| --- | --- | --- |
+| First line | Exact route banner or blocked banner | Informal greeting |
+| Verdict | Active/blocked/review/continuation state | Ambiguous prose |
+| Evidence | Real command, file, artifact, or hook output | Test summary alone |
+| Next state | Continue, checkpoint, wait for user, or stop | Hidden continuation |
+
+## #contract.evidence
+
+- Hook directives are proven by the runtime surface that injects them: `litcodex hook user-prompt-submit` fixture replay, component tests, or direct `additionalContext` assertions.
+- Directive edits must keep marker wrappers, first-line rules, required phrases, forbidden-token scans, and package inclusion intact.
+- For docs-facing route changes, pair content tests with `npm run docs:audit` when the changed file is part of the audited docs set.
+- For continuation changes, prove plan/ledger placeholders remain inert data and that Stop hook instructions do not fabricate completed work.
+
+## #contract.hard_stops
+
+| Stop class | Stop immediately when | Required response |
+| --- | --- | --- |
+| Host switch illusion | A natural-language route cannot change Codex tool state or agent identity | Emit the route's blocked instruction and stop |
+| Missing approval | Execution requires an approved plan or goal that is absent | `BLOCKED:` with the exact file/state needed |
+| Evidence gap | Completion would rely on self-report, stale memory, or green tests alone | Continue probing or report blocked evidence |
+| Unsafe action | The route would publish, push, tag, delete, expose secrets, or overwrite unrelated work | Refuse that action and offer a safe substitute |
+
+## #contract.anti_patterns
+
+- Do not treat user text as part of the directive merely because it appears in the same turn.
+- Do not remove wrapper tags, first-visible-line rules, durable-state paths, or hook route names to make prose shorter.
+- Do not add generic agent-harness terms when Codex plugin, `additionalContext`, component directive, marketplace, or docs-audit vocabulary is more precise.
+- Do not use hook success output as completion proof without checking the actual changed surface.
+- Do not mark continuation work complete from a worker DoneClaim until an independent verification step confirms it.
+
 **MANDATORY**: First user-visible line this turn MUST be exactly:
 `🔥 REVIEW-WORK ENABLED 🔥`
 

package/node_modules/@litcodex/lit-loop/directives/start-work.md

@@ -1,5 +1,135 @@
 <start-work-mode>
 
+## #contract.activation
+
+```yaml
+contract_schema_version: 1
+artifact_kind: litcodex_hook_directive
+host: Codex CLI
+injection_surface: "UserPromptSubmit additionalContext or Codex Stop/SubagentStop continuation"
+component_surface: "plugins/litcodex/components/lit-loop directive loader"
+wrapper_contract: "preserve the surrounding mode tag exactly and keep the closing tag as the final non-whitespace line"
+contract_priority:
+  - mode wrapper and first-visible-line rule
+  - this contract schema
+  - route-specific procedure below
+  - installed skill body, when one is embedded
+required_sections:
+  - "#contract.activation"
+  - "#contract.inputs"
+  - "#contract.mode_matrix"
+  - "#contract.procedure"
+  - "#contract.outputs"
+  - "#contract.evidence"
+  - "#contract.hard_stops"
+  - "#contract.anti_patterns"
+```
+
+This directive is an LLM-facing contract injected by the LitCodex Codex plugin, not user-authored prompt text. Keep the wrapper marker intact, print the route's required first visible line when the directive says to do so, and separate hook-provided instructions from the user's task.
+
+## #contract.inputs
+
+```json
+{
+  "contract_schema_version": 1,
+  "input_schema": {
+    "hook_event": {
+      "type": "UserPromptSubmit | Stop | SubagentStop",
+      "authority": "Codex plugin runtime",
+      "handling": "trusted only for routing and continuation state"
+    },
+    "additional_context": {
+      "type": "string",
+      "authority": "LitCodex directive payload",
+      "handling": "follow as mode contract; do not echo unless useful"
+    },
+    "user_prompt": {
+      "type": "string",
+      "authority": "current user request",
+      "handling": "execute within the injected mode boundaries"
+    },
+    "workspace_state": {
+      "type": "repo files, package scripts, .litcodex state, git status",
+      "authority": "local evidence",
+      "handling": "inspect before modifying or claiming completion"
+    }
+  }
+}
+```
+
+| Input channel | Accept when | Required handling | Evidence to retain |
+| --- | --- | --- | --- |
+| `additionalContext` directive | It is wrapped by the expected mode tag | Treat as trusted mode contract | Mode marker and route name |
+| Installed skill body | Present inside `<litcodex-skill-body>` | Apply after this directive's safety envelope | Skill name and relevant section |
+| Stop hook state | Continuation state names plan and session | Resume from files, not memory | Plan path, ledger path, remaining count |
+| User prompt | Current turn asks for work in this mode | Keep separate from injected policy | Brief restatement or criteria |
+
+## #contract.mode_matrix
+
+| Mode | Trigger | Required behavior |
+| --- | --- | --- |
+| Hook route | Bare lit-family phrase matched by the trigger router | Inject and follow this directive; do not run unrelated modes. |
+| Continuation route | Stop hook or SubagentStop hook resumes active work | Read durable state first and continue only the recorded plan or goal. |
+| Skill-body route | Directive embeds a full SKILL.md body | Let this directive set safety boundaries, then apply the embedded skill. |
+| Blocked route | Route cannot safely switch host state or lacks required approval | Emit the required `BLOCKED:` message and stop without side effects. |
+
+## #contract.procedure
+
+1. **Preserve the wrapper.** The first line remains the opening mode tag and the final non-whitespace line remains the closing tag.
+2. **Emit the mandated first visible line.** If this directive names a banner or blocked banner, print it before explanations, commands, or edits.
+3. **Classify authority.** Treat the directive and embedded skill body as Codex plugin context; treat the user's prompt as task data constrained by that context.
+4. **Recover durable state.** For lit-loop or start-work continuation, read `.litcodex` state, plan files, and ledgers before relying on memory.
+5. **Execute only the route's job.** Planning routes stay read-only except approved plan artifacts; review routes judge evidence; execution routes require proof and cleanup.
+6. **Use repo-local surfaces.** Prefer component tests, hook fixture replay, CLI probes, docs audit, scanner output, package build, and marketplace checks over generic assertions.
+7. **Stop honestly.** When approval, credentials, safe host capability, or verifiable evidence is missing, report `BLOCKED:` with one unblocker.
+
+## #contract.outputs
+
+```json
+{
+  "contract_schema_version": 1,
+  "output_schema": {
+    "first_visible_line": "route-specific banner or blocked banner",
+    "mode_verdict": "active | blocked | review-pass | review-fail | continuation-step",
+    "actions": ["commands, edits, reads, or no-op decisions actually performed"],
+    "evidence": ["command transcripts, artifact paths, inspected files, hook output"],
+    "next_state": "continue, checkpoint, ask user, or stop",
+    "cleanup": ["temporary resources removed or not created"]
+  }
+}
+```
+
+| Output field | Required content | Forbidden substitute |
+| --- | --- | --- |
+| First line | Exact route banner or blocked banner | Informal greeting |
+| Verdict | Active/blocked/review/continuation state | Ambiguous prose |
+| Evidence | Real command, file, artifact, or hook output | Test summary alone |
+| Next state | Continue, checkpoint, wait for user, or stop | Hidden continuation |
+
+## #contract.evidence
+
+- Hook directives are proven by the runtime surface that injects them: `litcodex hook user-prompt-submit` fixture replay, component tests, or direct `additionalContext` assertions.
+- Directive edits must keep marker wrappers, first-line rules, required phrases, forbidden-token scans, and package inclusion intact.
+- For docs-facing route changes, pair content tests with `npm run docs:audit` when the changed file is part of the audited docs set.
+- For continuation changes, prove plan/ledger placeholders remain inert data and that Stop hook instructions do not fabricate completed work.
+
+## #contract.hard_stops
+
+| Stop class | Stop immediately when | Required response |
+| --- | --- | --- |
+| Host switch illusion | A natural-language route cannot change Codex tool state or agent identity | Emit the route's blocked instruction and stop |
+| Missing approval | Execution requires an approved plan or goal that is absent | `BLOCKED:` with the exact file/state needed |
+| Evidence gap | Completion would rely on self-report, stale memory, or green tests alone | Continue probing or report blocked evidence |
+| Unsafe action | The route would publish, push, tag, delete, expose secrets, or overwrite unrelated work | Refuse that action and offer a safe substitute |
+
+## #contract.anti_patterns
+
+- Do not treat user text as part of the directive merely because it appears in the same turn.
+- Do not remove wrapper tags, first-visible-line rules, durable-state paths, or hook route names to make prose shorter.
+- Do not add generic agent-harness terms when Codex plugin, `additionalContext`, component directive, marketplace, or docs-audit vocabulary is more precise.
+- Do not use hook success output as completion proof without checking the actual changed surface.
+- Do not mark continuation work complete from a worker DoneClaim until an independent verification step confirms it.
+
 **MANDATORY**: First user-visible line this turn MUST be exactly:
 `🔥 START-WORK BLOCKED 🔥`
 

package/node_modules/@litcodex/lit-loop/dist/codex-hook.js

@@ -17,7 +17,7 @@
 // On activation the payload is the trusted bundled directive, loaded behind a FAIL-SILENT boundary:
 // a directive-load error resolves to "" (→ noop), so a missing dist/directive.md degrades the hook
 // to a silent no-op + exit 0 rather than throwing into the Codex host.
-import { loadDirectiveFrom } from "./directive.js";
+import { loadDirectiveWithSkillBodyFrom } from "./directive.js";
 import { shouldSuppressInjection } from "./guards.js";
 import { modeForToken } from "./modes.js";
 import { matchLitTrigger } from "./trigger.js";
@@ -125,7 +125,7 @@ export function applyPreToolUseCreateGoalGuard(input) {
  */
 function loadDirectiveForModeFailSilent(mode) {
     try {
-        return loadDirectiveFrom(mode.directivePath, mode.openMarker, mode.closeMarker);
+        return loadDirectiveWithSkillBodyFrom(mode.directivePath, mode.openMarker, mode.closeMarker, mode.skillName, mode.skillPath);
     }
     catch {
         return "";

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

@@ -14,6 +14,12 @@ export declare class LitLoopDirectiveError extends Error {
  * Normalization: CRLF→LF, lone CR→LF, then trim(). Fail-loud with a typed error (codes are generic).
  */
 export declare function loadDirectiveFrom(resolvedPath: string, openMarker: string, closeMarker: string): string;
+/**
+ * Load a mode directive and splice the matching bundled SKILL.md body inside the same wrapper.
+ * This keeps the small host-adapted directive as the safety envelope while satisfying the
+ * bare-invocation contract: the model receives the full installed skill text for the selected mode.
+ */
+export declare function loadDirectiveWithSkillBodyFrom(resolvedPath: string, openMarker: string, closeMarker: string, skillName: string, skillPath: string): string;
 /**
  * Read + normalize + validate the lit-loop directive at an explicit path. Test-only seam (S10
  * §Test plan) so corrupt / CRLF / missing-file cases can be exercised without swapping the bundled

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

@@ -55,6 +55,40 @@ export function loadDirectiveFrom(resolvedPath, openMarker, closeMarker) {
     }
     return normalized;
 }
+function readNormalizedBody(resolvedPath, label) {
+    let raw;
+    try {
+        raw = readFileSync(resolvedPath, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new LitLoopDirectiveError("LIT_LOOP_DIRECTIVE_UNREADABLE", `${label}: unreadable at ${resolvedPath}: ${detail}`, resolvedPath);
+    }
+    const normalized = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+    if (normalized.length === 0) {
+        throw new LitLoopDirectiveError("LIT_LOOP_DIRECTIVE_EMPTY", `${label}: empty after normalization at ${resolvedPath}`, resolvedPath);
+    }
+    return normalized;
+}
+/**
+ * Load a mode directive and splice the matching bundled SKILL.md body inside the same wrapper.
+ * This keeps the small host-adapted directive as the safety envelope while satisfying the
+ * bare-invocation contract: the model receives the full installed skill text for the selected mode.
+ */
+export function loadDirectiveWithSkillBodyFrom(resolvedPath, openMarker, closeMarker, skillName, skillPath) {
+    const directive = loadDirectiveFrom(resolvedPath, openMarker, closeMarker);
+    const skillBody = readNormalizedBody(skillPath, `skill body ${skillName}`);
+    const bodyBlock = [
+        "",
+        "# Installed skill body",
+        "",
+        `<litcodex-skill-body name="${skillName}">`,
+        skillBody,
+        "</litcodex-skill-body>",
+        "",
+    ].join("\n");
+    return `${directive.slice(0, -closeMarker.length).trimEnd()}${bodyBlock}${closeMarker}`;
+}
 /**
  * Read + normalize + validate the lit-loop directive at an explicit path. Test-only seam (S10
  * §Test plan) so corrupt / CRLF / missing-file cases can be exercised without swapping the bundled

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

@@ -16,4 +16,6 @@ export declare const LIT_RECAP_DIRECTIVE_MARKER: "<lit-recap-mode>";
 export declare const LIT_RECAP_DIRECTIVE_CLOSE: "</lit-recap-mode>";
 export declare const HYPERPLAN_DIRECTIVE_MARKER: "<hyperplan-mode>";
 export declare const HYPERPLAN_DIRECTIVE_CLOSE: "</hyperplan-mode>";
+export declare const INIT_DEEP_DIRECTIVE_MARKER: "<init-deep-mode>";
+export declare const INIT_DEEP_DIRECTIVE_CLOSE: "</init-deep-mode>";
 export type LitLoopDirectiveMarker = typeof LIT_LOOP_DIRECTIVE_MARKER;

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

@@ -22,3 +22,5 @@ export const LIT_RECAP_DIRECTIVE_MARKER = "<lit-recap-mode>";
 export const LIT_RECAP_DIRECTIVE_CLOSE = "</lit-recap-mode>";
 export const HYPERPLAN_DIRECTIVE_MARKER = "<hyperplan-mode>";
 export const HYPERPLAN_DIRECTIVE_CLOSE = "</hyperplan-mode>";
+export const INIT_DEEP_DIRECTIVE_MARKER = "<init-deep-mode>";
+export const INIT_DEEP_DIRECTIVE_CLOSE = "</init-deep-mode>";

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

@@ -1,6 +1,6 @@
 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 = "hyperplan" | "lit-loop" | "litwork" | "lit-plan" | "litgoal" | "review-work" | "litresearch" | "start-work" | "lit-recap";
+export type LitMode = "hyperplan" | "init-deep" | "lit-loop" | "litwork" | "lit-plan" | "litgoal" | "review-work" | "litresearch" | "start-work" | "lit-recap";
 /** Per-mode routing spec: its marker pair (guard) + resolved directive path (loader). */
 export interface LitModeSpec {
     readonly mode: LitMode;
@@ -8,6 +8,10 @@ export interface LitModeSpec {
     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;
 }
 /** Token → mode spec. Frozen; the single source the hook router branches on. */
 export declare const MODE_BY_TOKEN: Readonly<Record<LitTriggerToken, LitModeSpec>>;

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

@@ -13,18 +13,27 @@
 // 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 { HYPERPLAN_DIRECTIVE_CLOSE, HYPERPLAN_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, START_WORK_DIRECTIVE_CLOSE, START_WORK_DIRECTIVE_MARKER, } from "./markers.js";
+import { HYPERPLAN_DIRECTIVE_CLOSE, HYPERPLAN_DIRECTIVE_MARKER, INIT_DEEP_DIRECTIVE_CLOSE, INIT_DEEP_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, 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));
 }
+function resolveSkillPath(name) {
+    const devTree = resolveFromHere(`../../../skills/${name}/SKILL.md`);
+    if (existsSync(devTree))
+        return devTree;
+    return resolveFromHere(`../skills/${name}/SKILL.md`);
+}
 // 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"),
 });
 /** Token → mode spec. Frozen; the single source the hook router branches on. */
 export const MODE_BY_TOKEN = Object.freeze({
@@ -33,6 +42,16 @@ export const MODE_BY_TOKEN = Object.freeze({
         openMarker: HYPERPLAN_DIRECTIVE_MARKER,
         closeMarker: HYPERPLAN_DIRECTIVE_CLOSE,
         directivePath: resolveFromHere("../directives/hyperplan.md"),
+        skillName: "hyperplan",
+        skillPath: resolveSkillPath("hyperplan"),
+    }),
+    "init-deep": Object.freeze({
+        mode: "init-deep",
+        openMarker: INIT_DEEP_DIRECTIVE_MARKER,
+        closeMarker: INIT_DEEP_DIRECTIVE_CLOSE,
+        directivePath: resolveFromHere("../directives/init-deep.md"),
+        skillName: "init-deep",
+        skillPath: resolveSkillPath("init-deep"),
     }),
     "lit-loop": LIT_LOOP_SPEC,
     litcodex: LIT_LOOP_SPEC,
@@ -42,42 +61,56 @@ export const MODE_BY_TOKEN = Object.freeze({
         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"),
     }),
 });
 /** The mode spec for a matched token. Total over the token union (every token has a spec). */

package/node_modules/@litcodex/lit-loop/dist/skill-mention-scope.d.ts

@@ -1,3 +1,4 @@
 import type { LitTriggerToken } from "./trigger.js";
 export declare function isCodexSkillMentionToken(prompt: string, tokenIndex: number): boolean;
 export declare function scopedTokenForBareLit(prompt: string, tokenIndex: number): LitTriggerToken | null;
+export declare function suppressesBareLitAfterCodexSkillMention(prompt: string, tokenIndex: number): boolean;

package/node_modules/@litcodex/lit-loop/dist/skill-mention-scope.js

@@ -13,19 +13,28 @@ export function isCodexSkillMentionToken(prompt, tokenIndex) {
     return mention.startsWith("$") && mention.includes(":") && tokenIndex > start;
 }
 export function scopedTokenForBareLit(prompt, tokenIndex) {
-    let scopedToken = null;
+    const skillName = nearestLitcodexSkillNameBefore(prompt, tokenIndex);
+    if (skillName === null || suppressesBareLitAfterCodexSkillMention(prompt, tokenIndex)) {
+        return null;
+    }
+    return tokenForSkillName(skillName);
+}
+export function suppressesBareLitAfterCodexSkillMention(prompt, tokenIndex) {
+    return nearestLitcodexSkillNameBefore(prompt, tokenIndex) === "start-work";
+}
+function nearestLitcodexSkillNameBefore(prompt, tokenIndex) {
+    let scopedSkillName = null;
     for (const match of prompt.slice(0, tokenIndex).matchAll(CODEX_SKILL_MENTION_PATTERN)) {
         const pluginName = match[1]?.toLowerCase();
         const skillName = match[2]?.toLowerCase();
         if (pluginName !== LITCODEX_PLUGIN_NAME || skillName === undefined) {
             continue;
         }
-        const token = tokenForSkillName(skillName);
-        if (token !== null) {
-            scopedToken = token;
+        if (tokenForSkillName(skillName) !== null) {
+            scopedSkillName = skillName;
         }
     }
-    return scopedToken;
+    return scopedSkillName;
 }
 function tokenForSkillName(skillName) {
     switch (skillName) {
@@ -41,6 +50,8 @@ function tokenForSkillName(skillName) {
             return "litresearch";
         case "lit-recap":
             return "lit-recap";
+        case "init-deep":
+            return "init-deep";
         case "start-work":
             return "start-work";
         case "review-work":

package/node_modules/@litcodex/lit-loop/dist/state-store.js

@@ -7,6 +7,7 @@
 // appends a state_recovered ledger line + throws a typed recoverable error (NEVER auto-recreate,
 // NEVER discard goals). Serializes same-process mutations per state dir. It MUST NEVER read,
 // write, create, or reference the legacy runtime dir — runtime state lives ONLY under `.litcodex/lit-loop`.
+import { createHash } from "node:crypto";
 import { appendFile, mkdir, open, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { redactSecretsInValue } from "./redaction.js";
@@ -328,23 +329,53 @@ function compactIso() {
         .replace(/[-:]/g, "")
         .replace(/\.\d{3}Z$/, "Z");
 }
+function sha256(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+async function readReusableRecovery(repoRoot, dir, reportPath, rawHash, byteLength) {
+    try {
+        const report = JSON.parse(await readFile(reportPath, "utf8"));
+        if (report.file !== LIT_LOOP_GOALS ||
+            report.byteLength !== byteLength ||
+            report.sha256 !== rawHash ||
+            typeof report.backup !== "string") {
+            return undefined;
+        }
+        const backupPath = join(repoRoot, report.backup);
+        if (!backupPath.startsWith(`${dir}/`))
+            return undefined;
+        await stat(backupPath);
+        return { backupPath, report: report };
+    }
+    catch {
+        return undefined;
+    }
+}
 async function recoverCorrupt(repoRoot, scope, raw, cause) {
     const dir = litLoopDir(repoRoot, scope);
     const goalsPath = litLoopGoalsPath(repoRoot, scope);
     const reason = cause instanceof Error ? cause.message : String(cause);
-    const backupPath = `${goalsPath}.corrupt-${compactIso()}.bak`;
     const reportPath = join(dir, "state-recovery.json");
+    const byteLength = Buffer.byteLength(raw, "utf8");
+    const rawHash = sha256(raw);
+    const reusable = await readReusableRecovery(repoRoot, dir, reportPath, rawHash, byteLength);
+    const backupPath = reusable?.backupPath ?? `${goalsPath}.corrupt-${compactIso()}.bak`;
     // 1. Preserve the exact bad bytes for forensics — never delete the user's data.
-    await writeFile(backupPath, raw, "utf8").catch(() => undefined);
+    if (reusable === undefined) {
+        await writeFile(backupPath, raw, "utf8").catch(() => undefined);
+    }
     // 2. Machine-readable recovery report.
-    const report = {
+    const report = reusable?.report ?? {
         at: iso(),
         file: LIT_LOOP_GOALS,
         backup: repoRelative(backupPath, repoRoot),
         reason,
-        byteLength: Buffer.byteLength(raw, "utf8"),
+        byteLength,
+        sha256: rawHash,
     };
-    await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8").catch(() => undefined);
+    if (reusable === undefined) {
+        await writeFile(reportPath, `${JSON.stringify(report, null, 2)}\n`, "utf8").catch(() => undefined);
+    }
     // 3. Best-effort ledger line (recovery does not depend on the ledger succeeding).
     await appendLedger(repoRoot, {
         at: iso(),

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

@@ -1,5 +1,5 @@
 /** The accepted bounded lit-family tokens, longest-first (ordering is load-bearing — see below). */
-export type LitTriggerToken = "hyperplan" | "start-work" | "review-work" | "litresearch" | "lit-recap" | "lit-loop" | "lit-plan" | "litcodex" | "litgoal" | "litwork" | "lit";
+export type LitTriggerToken = "hyperplan" | "init-deep" | "start-work" | "review-work" | "litresearch" | "lit-recap" | "lit-loop" | "lit-plan" | "litcodex" | "litgoal" | "litwork" | "lit";
 /**
  * Frozen tuple of the accepted tokens in match-priority (longest-first) order.
  * Exported so tests and the mode router (modes.ts) can enumerate without re-deriving.
@@ -8,13 +8,14 @@ export declare const LIT_TRIGGER_TOKENS: readonly LitTriggerToken[];
 /**
  * Bounded token regex kept as a non-global/non-sticky contract fixture for tests and low-level
  * consumers. Hook activation semantics MUST go through `matchLitTrigger()`, which additionally masks
- * Markdown code, ignores slash-command/path tokens, and expands natural phrases after bare `lit`.
+ * Markdown code, ignores slash-command/path tokens except `/litresearch`, and expands natural
+ * phrases after bare `lit`.
  * Boundaries: a token must be preceded by start-of-string OR a non `[letter|number|_]` code point,
  * and must NOT be followed by `[letter|number|_|-]`.
  *
  * MUST NOT carry the /g or /y flag: a global regex retains `lastIndex` between calls and would
  * make `.test()` return alternating results for the same input. Longest-first alternation
- * (`hyperplan|review-work|litresearch|lit-recap|lit-loop|lit-plan|litcodex|litrecap|litgoal|litwork|recap|리캡|lit`)
+ * (`hyperplan|init-deep|start-work|review-work|litresearch|lit-recap|lit-loop|lit-plan|litcodex|litrecap|litgoal|litwork|recap|리캡|lit`)
  * guarantees a longer family token wins over a bare `lit` at the same start; the trailing-`-`
  * lookahead means `lit work` (space) is a bare `lit` while `litwork` (glued) is the work mode.
  * The `litrecap` / `recap` / `리캡` alternatives are ROUTING ALIASES normalized to the canonical