@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/.claude/hooks/continuation-messages.ts

@@ -0,0 +1,215 @@
+#!/usr/bin/env bun
+/**
+ * continuation-messages handler — `PostToolUse` hook that injects a
+ * mode-entry kick-off prompt after the pipeline advances.
+ *
+ * This is the Claude Code delivery vehicle for the pure
+ * `computeContinuationMessage()` builder in
+ * `@alecsibilia/luca-core/orchestration`. The algorithm decides whether
+ * to emit and what to say; this handler is glue:
+ *
+ *   1. Read the Claude Code PostToolUse payload from stdin.
+ *   2. If it isn't a `Bash` invocation of `luca state advance <step>`,
+ *      exit 0 silently (this hook only fires after pipeline advances).
+ *   3. Read `.luca/state.json` for the now-current `pipelineStep`.
+ *   4. Confirm the requested step matches the current step (i.e. the
+ *      advance succeeded). If not, exit 0 silently — the CLI's own
+ *      validation rejected the call, and an injected continuation for
+ *      a step we didn't actually enter would mislead the agent.
+ *   5. Call `computeContinuationMessage()`.
+ *   6. Emit the message via the Claude Code PostToolUse hook output
+ *      JSON shape:
+ *
+ *         {
+ *           "hookSpecificOutput": {
+ *             "hookEventName": "PostToolUse",
+ *             "additionalContext": "<system-reminder>...</system-reminder>"
+ *           }
+ *         }
+ *
+ *      Exit 0 — `additionalContext` is the hook's only effect on the
+ *      session.
+ *
+ * The Claude Code hook contract (PostToolUse):
+ *
+ *   stdin JSON shape (snake_case fields per the docs):
+ *     {
+ *       "session_id": "...",
+ *       "hook_event_name": "PostToolUse",
+ *       "tool_name": "Bash",
+ *       "tool_input": { "command": "luca state advance plan", ... },
+ *       "tool_response": { "stdout": "...", "stderr": "...", ... }
+ *     }
+ *
+ *   Exit codes:
+ *     0   → all signals come from stdout JSON
+ *     2   → block (not used here — this hook is informational)
+ *     *   → other non-zero → error (failure-open: we never use this
+ *           because a hook bug should never disrupt the session)
+ *
+ *   Stdout JSON for context injection:
+ *     {
+ *       "hookSpecificOutput": {
+ *         "hookEventName": "PostToolUse",
+ *         "additionalContext": "..."
+ *       }
+ *     }
+ *
+ * Failure-open philosophy (per E-1 / E-2 reasoning, intentionally
+ * reused): if ANYTHING unexpected happens (stdin parse error,
+ * state.json missing/malformed, command argv doesn't parse), exit 0
+ * silently. A hook that mis-injects a continuation will confuse the
+ * agent; a hook that crashes is worse. Choose silent skip.
+ */
+import { appendLedger } from '@alecsibilia/luca-core/ledger'
+import {
+    computeContinuationMessage,
+    type ContinuationInput,
+} from '@alecsibilia/luca-core/orchestration'
+import {
+    loadCurrentState,
+    parseAdvanceCommand,
+} from '@alecsibilia/luca-core/state'
+
+/**
+ * Shape of the relevant slice of the PostToolUse stdin payload. We
+ * only look at `tool_name` and `tool_input.command`; everything else
+ * is ignored. Defensive typing — the harness may add fields and the
+ * handler should not break on them.
+ */
+interface PostToolUsePayload {
+    tool_name?: string
+    toolName?: string
+    tool_input?: { command?: string }
+    toolInput?: { command?: string }
+}
+
+async function main(): Promise<number> {
+    const raw = await Bun.stdin.text()
+    if (!raw.trim()) {
+        // Empty stdin — nothing to do. Allow silently.
+        return 0
+    }
+
+    let payload: PostToolUsePayload
+    try {
+        payload = JSON.parse(raw) as PostToolUsePayload
+    } catch {
+        // Malformed stdin is the harness's problem. Fail open silently.
+        return 0
+    }
+
+    const toolName = payload.tool_name ?? payload.toolName
+    if (toolName !== 'Bash') {
+        // The Bash matcher catches every Bash call; we only act on
+        // `luca state advance`. Other Bash → silent skip.
+        return 0
+    }
+
+    const command = payload.tool_input?.command ?? payload.toolInput?.command
+    if (typeof command !== 'string') {
+        return 0
+    }
+
+    const requestedStep = parseAdvanceCommand(command)
+    if (requestedStep === null) {
+        // Not a `luca state advance` invocation.
+        return 0
+    }
+
+    const cwd = process.cwd()
+    const state = await loadCurrentState({ cwd })
+
+    // Confirm the advance actually happened by comparing the now-current
+    // step with the requested step. If they don't match the CLI rejected
+    // the transition (or the user wrote an exotic command form we didn't
+    // recognise); either way, skip silently rather than inject a
+    // misleading continuation.
+    if (state.pipelineStep !== requestedStep) {
+        return 0
+    }
+
+    const input: ContinuationInput = {
+        currentStep: state.pipelineStep,
+        ...(state.complexity !== undefined
+            ? { complexity: state.complexity }
+            : {}),
+        ...(state.oversight !== undefined
+            ? { oversight: state.oversight }
+            : {}),
+        ...(typeof state.currentPhase === 'number'
+            ? { currentPhase: state.currentPhase }
+            : {}),
+        ...(typeof state.totalPhases === 'number'
+            ? { totalPhases: state.totalPhases }
+            : {}),
+    }
+
+    const verdict = computeContinuationMessage(input)
+
+    // Emit a ledger event for the hook firing. Records whether a
+    // continuation was emitted (and why not, when applicable) so the
+    // postmortem analyzer has signal on hook coverage. Failure-open.
+    try {
+        const runId = typeof (state as { sessionId?: unknown }).sessionId === 'string'
+            ? (state as { sessionId: string }).sessionId
+            : ''
+        appendLedger({
+            cwd,
+            runId,
+            event: 'hook.continuation-messages.fired',
+            data: {
+                pipelineStep: state.pipelineStep,
+                decision: verdict === null
+                    ? 'skipped'
+                    : verdict.reason === 'unknown-current-step'
+                        ? 'skipped'
+                        : 'emitted',
+                reason: verdict === null ? 'no-continuation' : verdict.reason,
+            },
+        })
+    } catch {
+        // Failure-open.
+    }
+
+    if (verdict === null) {
+        // No continuation appropriate (e.g. advance into `idle`).
+        return 0
+    }
+
+    if (verdict.reason === 'unknown-current-step') {
+        // The algorithm flagged a data-integrity warning; we don't
+        // surface this to the model (it would be alarming and not
+        // actionable). Skip silently — the CLI's own validation will
+        // catch the underlying state.json corruption.
+        return 0
+    }
+
+    // Emit the additionalContext payload. Claude Code consumes the
+    // first valid JSON object on stdout for PostToolUse hooks.
+    const output = {
+        hookSpecificOutput: {
+            hookEventName: 'PostToolUse',
+            additionalContext: verdict.message,
+        },
+    }
+    process.stdout.write(JSON.stringify(output) + '\n')
+    return 0
+}
+
+// `parseAdvanceCommand` (and its `stripQuotes` helper) was promoted to
+// `@alecsibilia/luca-core/state` (see `packages/luca-core/src/state/
+// cli-parse.ts`) — both this hook and `pipeline-guard/handler.ts`
+// used byte-identical copies, so the helper now lives in luca-core
+// and is imported above (CF11).
+
+main().then(
+    (code) => process.exit(code),
+    (err) => {
+        // Defensive: any unexpected throw means we fail open silently.
+        // No stderr — this is a PostToolUse informational hook; users
+        // shouldn't see internal errors.
+        void err
+        process.exit(0)
+    },
+)

package/dist/claude/.claude/hooks/pipeline-guard.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env bun
+/**
+ * pipeline-guard handler — `PreToolUse` hook that vets pipeline-step
+ * transitions before they execute.
+ *
+ * This is the Claude Code delivery vehicle for the pure
+ * `checkPipelineGuard()` algorithm in `@alecsibilia/luca-core/orchestration`.
+ * The algorithm decides legality; this handler is glue:
+ *
+ *   1. Read the Claude Code PreToolUse payload from stdin.
+ *   2. If it isn't a `Bash` invocation of `luca state advance <step>`,
+ *      exit 0 (this hook only guards that one command).
+ *   3. Read `.luca/state.json` for the current `pipelineStep`.
+ *   4. Call `checkPipelineGuard()` with current + requested step.
+ *   5. Exit 0 on allow, 2 on block (Claude Code blocks the tool call
+ *      and surfaces the stderr message to the model).
+ *
+ * The Claude Code hook contract (PreToolUse):
+ *
+ *   stdin JSON shape (snake_case fields per the docs):
+ *     {
+ *       "session_id": "...",
+ *       "hook_event_name": "PreToolUse",
+ *       "tool_name": "Bash",
+ *       "tool_input": { "command": "luca state advance plan", ... }
+ *     }
+ *
+ *   Exit codes:
+ *     0  → allow the tool call
+ *     2  → block + send stderr to the model
+ *     *  → other non-zero → error (Claude Code surfaces to the user;
+ *           we never use this path because we'd rather fail open than
+ *           break the user's workflow on a parse error)
+ *
+ * Why a bun-script: the algorithm needs typed access to
+ * `checkPipelineGuard` + the pipeline-transitions table. A shell
+ * wrapper would have to re-implement the legality check or shell out
+ * to the `luca` CLI; both create drift surfaces. Direct TS import
+ * keeps the source of truth in one place.
+ *
+ * Failure-open philosophy: if ANYTHING unexpected happens (stdin
+ * parse error, state.json missing/malformed, command argv doesn't
+ * parse), we exit 0 and let the call through. Hooks that crash will
+ * break the user's session; hooks that wrongly block will frustrate
+ * them. Both are bad — but blocking is worse because the user can't
+ * recover without disabling the hook. Choose to fail open and lean
+ * on the CLI's own validation (the `luca state advance` command does
+ * its own legal-transition check independently).
+ */
+import { join } from 'node:path'
+
+import { appendLedger } from '@alecsibilia/luca-core/ledger'
+import {
+    checkPipelineGuard,
+    type PipelineGuardInput,
+} from '@alecsibilia/luca-core/orchestration'
+import {
+    loadCurrentState,
+    parseAdvanceCommand,
+} from '@alecsibilia/luca-core/state'
+
+/**
+ * Shape of the relevant slice of the PreToolUse stdin payload. We
+ * only look at `tool_name` and `tool_input.command`; everything else
+ * is ignored. Defensive typing — the harness may add fields and the
+ * handler should not break on them.
+ */
+interface PreToolUsePayload {
+    tool_name?: string
+    toolName?: string
+    tool_input?: { command?: string }
+    toolInput?: { command?: string }
+}
+
+async function main(): Promise<number> {
+    const raw = await Bun.stdin.text()
+    if (!raw.trim()) {
+        // Empty stdin — nothing to guard. Allow.
+        return 0
+    }
+
+    let payload: PreToolUsePayload
+    try {
+        payload = JSON.parse(raw) as PreToolUsePayload
+    } catch {
+        // Malformed stdin is the harness's problem, not ours. Fail open.
+        return 0
+    }
+
+    const toolName = payload.tool_name ?? payload.toolName
+    if (toolName !== 'Bash') {
+        // The hook also matches non-Bash tools if registered broadly,
+        // but pipeline-guard only cares about `luca state advance`.
+        return 0
+    }
+
+    const command = payload.tool_input?.command ?? payload.toolInput?.command
+    if (typeof command !== 'string') {
+        return 0
+    }
+
+    const requestedStep = parseAdvanceCommand(command)
+    if (requestedStep === null) {
+        // Not a `luca state advance` invocation, or shape doesn't
+        // match. Nothing to guard.
+        return 0
+    }
+
+    const cwd = process.cwd()
+    const state = await loadCurrentState({ cwd })
+
+    const input: PipelineGuardInput = {
+        currentStep: state.pipelineStep,
+        requestedStep,
+        ...(state.complexity !== undefined
+            ? { complexity: state.complexity }
+            : {}),
+        ...(state.oversight !== undefined
+            ? { oversight: state.oversight }
+            : {}),
+    }
+
+    const verdict = checkPipelineGuard(input)
+
+    // Emit a ledger event for the hook firing. The postmortem analyzer
+    // scans the ledger for `hook.pipeline-guard.fired` events to detect
+    // pipeline-guard rejections and forced transitions over time.
+    // Failure-open: any ledger-write error MUST NOT block the hook.
+    try {
+        const runId = typeof (state as { sessionId?: unknown }).sessionId === 'string'
+            ? (state as { sessionId: string }).sessionId
+            : ''
+        appendLedger({
+            cwd,
+            runId,
+            event: 'hook.pipeline-guard.fired',
+            data: {
+                pipelineStep: state.pipelineStep,
+                requestedStep,
+                decision: verdict.allowed ? 'allow' : 'block',
+                reason: verdict.allowed ? undefined : verdict.message,
+            },
+        })
+    } catch {
+        // Failure-open: never block the hook on a ledger-write error.
+    }
+
+    if (verdict.allowed) {
+        return 0
+    }
+
+    // Block: print to stderr (Claude Code surfaces to the model) and
+    // exit 2.
+    process.stderr.write(verdict.message + '\n')
+    return 2
+}
+
+// `parseAdvanceCommand` (and its `stripQuotes` helper) was promoted to
+// `@alecsibilia/luca-core/state` (see `packages/luca-core/src/state/
+// cli-parse.ts`) — both the pipeline-guard hook and the
+// continuation-messages hook used byte-identical copies, so the
+// helper now lives in luca-core and is imported above (CF11).
+
+// Touched to suppress unused-import in some toolchains; `join` may be
+// folded out by the bundler if unused, but kept here in case future
+// edits need explicit cwd handling.
+void join
+
+main().then(
+    (code) => process.exit(code),
+    (err) => {
+        // Defensive: any unexpected throw means we fail open. We
+        // explicitly do NOT exit 2 on internal errors — that would
+        // block the user's command on a hook bug.
+        process.stderr.write(
+            `pipeline-guard handler: internal error (failing open): ${
+                (err as Error).message
+            }\n`,
+        )
+        process.exit(0)
+    },
+)

package/dist/claude/.claude/settings.json

@@ -0,0 +1,41 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/pipeline-guard.ts",
+            "timeout": 5,
+            "statusMessage": "PreToolUse guard for `luca state advance` — blocks illegal pipelineStep transitions via the canonical legal-transitions table."
+          }
+        ],
+        "matcher": "Bash"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/continuation-messages.ts",
+            "timeout": 5,
+            "statusMessage": "PostToolUse continuation prompt for `luca state advance` — injects a mode-entry kick-off message via additionalContext when the pipeline advances."
+          }
+        ],
+        "matcher": "Bash"
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/context-refresher.ts",
+            "timeout": 5,
+            "statusMessage": "PostToolUse context-refresher — surfaces a per-step <luca-reminder> via additionalContext after every Nth tool call (default 30) or on a step change since the last fire."
+          }
+        ],
+        "matcher": "*"
+      }
+    ]
+  }
+}

package/dist/claude/skills/arch-audit/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: arch-audit
+description: "Find deepening opportunities — shallow modules, premature abstractions, misplaced seams. Uses the deletion test and promotion model to surface architectural friction. Use when user says \"audit architecture\", \"find refactoring opportunities\", \"what's shallow\", \"improve structure\", or invokes /arch-audit."
+---
+
+# arch-audit
+
+Surface architectural friction and propose deepening opportunities — refactors that turn shallow modules into deep ones, improve testability, and increase locality of change.
+
+## Vocabulary
+
+Use these terms exactly in every finding. Consistent language prevents drift into vague terms like "component," "service," or "boundary."
+
+- **Module** — anything with an interface and implementation (function, class, file, package). Scale-agnostic.
+- **Interface** — what a caller must know: types, invariants, error modes, ordering. Not just the type signature.
+- **Depth** — leverage at the interface. **Deep** = significant behavior behind a small interface. **Shallow** = interface nearly as complex as the implementation.
+- **Seam** — where behavior can be altered without editing in place. A boundary that accepts different adapters.
+- **Deletion test** — imagine deleting the module. Complexity vanishes → pass-through (shallow). Complexity reappears across callers → earning its keep (deep).
+- **Promotion tier** — where code lives based on caller count. Tier 1 (single caller, private). Tier 2 (shared within feature). Tier 3 (shared across features).
+
+## Step 1: Recall architectural context
+
+Query MuninnDB for past decisions so you don't re-suggest rejected refactors:
+
+```
+mcp__muninn__muninn_recall({
+  vault: "<repo_vault>",
+  context: ["architectural decisions", "rejected refactors", "module structure"],
+  tags: ["decision"],
+  limit: 15
+})
+```
+
+Resolve `<repo_vault>` from `.luca/config.json` → `muninn.vault`, falling back to `"default"`.
+
+If a `docs/context.md` exists, read it for project constraints and domain terminology (check the repo root for a legacy `context.md` as a fallback).
+
+**Guard**: if a past decision explicitly rejected a refactor you'd otherwise suggest, skip it. Only resurface if friction has materially worsened since the decision was recorded.
+
+## Step 2: Explore for friction
+
+Spawn one or more codebase-exploration subagents (the `Explore` agent, via the `Agent` tool) to walk the codebase. Provide this brief:
+
+> Walk the codebase and report friction. Look for:
+>
+> 1. **Shallow modules** — interface nearly as complex as implementation. Apply the deletion test: would removing this module concentrate complexity (earning its keep) or just redistribute it (pass-through)?
+> 2. **Concept bouncing** — understanding one concept requires reading across many small files
+> 3. **Premature abstractions** — interfaces/abstract types with a single implementation
+> 4. **Leaked coupling** — tightly-coupled modules that share internal details across their seam
+> 5. **Misplaced code** — helpers/utilities at promotion tier 3 (shared across features) that have only 1-2 callers
+> 6. **Untestable surfaces** — code that's hard to test through its current public interface
+>
+> For each finding, report: file path, what the friction is, deletion test result (if applicable), caller count.
+
+If the codebase is large, scope the exploration to specific areas the user mentions, or split into multiple focused subagents (e.g., one per package in a monorepo).
+
+Do NOT follow rigid heuristics. Explore organically. Note where you experience friction — where understanding breaks down, where you bounce between files, where interfaces feel heavier than what they hide.
+
+## Step 3: Present deepening candidates
+
+Synthesize subagent findings into a numbered list of **deepening opportunities**. For each candidate:
+
+```
+### <N>. <Short description>
+
+- **Files**: <paths involved>
+- **Problem**: <what the friction is — use vocabulary precisely>
+- **Deletion test**: <result — "vanishes" or "reappears across N callers">
+- **Promotion check**: <current tier vs appropriate tier based on caller count>
+- **Proposed direction**: <one sentence — what "deeper" looks like here>
+- **Risk**: <what could go wrong if refactored>
+```
+
+Order by impact (most friction first). Limit to 5-7 candidates — more than that is noise.
+
+**Do NOT propose interfaces or implementations yet.** Present candidates only.
+
+Ask: "Which of these would you like to explore?"
+
+## Step 4: Design alternatives (design-it-twice)
+
+For the candidate the user selects:
+
+1. **Frame the problem** — write a short explanation for the user:
+   - What constraints any new interface must satisfy
+   - What dependencies exist and their nature
+   - A rough illustrative sketch (not a proposal — just grounding)
+
+2. **Spawn 2-3 `Explore` / `Plan` subagents in parallel** (via the `Agent` tool) — each must produce a *radically different* interface design for the deepened module. Brief each subagent with:
+   - File paths and current coupling
+   - Caller list and their expectations
+   - The vocabulary (Module, Interface, Depth, Seam)
+   - Constraint: "Your design must be fundamentally different from the others"
+
+3. **Present designs sequentially** — let the user absorb each one:
+   - Interface signature (public surface)
+   - Usage example (how callers use it)
+   - What it hides (complexity kept internal)
+   - Trade-offs (what this design makes easy vs hard)
+
+4. **Compare and recommend** — contrast by:
+   - Depth (leverage at the interface)
+   - Locality (where change concentrates)
+   - Seam placement (where behavior can be swapped)
+   - Testability (how easy to test through the interface)
+
+   Give your recommendation. If elements from different designs combine well, propose a hybrid.
+
+5. **User decides** — they pick a design (or request iteration).
+
+## Step 5: Record the outcome
+
+After the user decides, store the result in MuninnDB.
+
+**If the refactor is accepted:**
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "decision:arch-audit-<descriptive-slug>",
+  content: "Accepted deepening: <what was refactored, which design was chosen, why>. Files: <paths>. Date: <ISO>.",
+  tags: ["decision", "architecture", "refactor"]
+})
+```
+
+Capture the returned id and promote this user-confirmed decision to the verified tier: `mcp__muninn__muninn_trust({ id: <returned-id>, trust: "verified", vault: "<repo_vault>" })`.
+
+**If the refactor is rejected:**
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "decision:arch-audit-rejected-<descriptive-slug>",
+  content: "Rejected deepening of <module>. Reason: <user's reason>. Friction level at time of rejection: <description>. Re-evaluate if: <conditions that would change the decision>.",
+  tags: ["decision", "architecture", "rejected"]
+})
+```
+
+Capture the returned id and promote it to the verified tier: `mcp__muninn__muninn_trust({ id: <returned-id>, trust: "verified", vault: "<repo_vault>" })`.
+
+The rejected decision prevents re-suggestion on future runs (Step 1 guard).
+
+Note: `decision:*` memories are project-scoped — they route to the **repo** vault.
+
+## Step 6: Plan the refactor (optional)
+
+If the user wants to proceed with implementation:
+
+- Ask: "Want me to create a plan for this refactor, or do it directly?"
+- If plan → suggest invoking `/lu` with the chosen design as context
+- If direct → proceed with implementation in the current session
+
+The chosen interface from Step 4 becomes the first test's target (interface-first task boundaries).
+
+## Behavioral Notes
+
+- **This is ad-hoc** — invoked when the user feels friction, not on a schedule
+- **No file dependencies** — everything lives in MuninnDB or is inlined in this skill
+- **Scope** — if the user doesn't specify an area, ask before exploring the entire codebase. For monorepos, start with one package.
+- **Vocabulary discipline** — use Module/Interface/Depth/Seam/Deletion Test consistently. Don't drift into "component," "service," "API," "boundary," "layer."
+- **Don't be prescriptive about tooling** — the skill identifies friction and proposes designs. It doesn't force a specific architecture style (DDD, hexagonal, etc.) unless the project already uses one.