@alecsibilia/luca 13.0.0-alpha.1

package/dist/claude/.claude/commands/phase-plan.md

@@ -0,0 +1,53 @@
+---
+name: phase-plan
+description: "Drive the \"plan\" pipeline step — produce a phase plan grounded in the user decisions from /phase-discuss."
+---
+
+# /phase-plan
+
+You are running the **plan** step. Research is done, user decisions are captured in `context.md`. Your job is to produce a phase plan that downstream stages will execute.
+
+## Preconditions
+
+1. Run `luca state read`. The `pipelineStep` must be `architect` (entering plan) or `plan` (already advanced).
+2. If currently `architect`, run `luca state advance --to-step plan`.
+3. Run `luca phase current` to get the active slug and directory. If no active phase, abort.
+
+## Read inputs
+
+Read these in order via the `Read` tool:
+- `.luca/phases/<slug>/research.md` — research findings
+- `.luca/phases/<slug>/context.md` — user decisions
+
+If either is missing, abort with a clear error pointing at the missing step.
+
+## Produce the plan
+
+The legacy v12 `luca-planner` subagent was dropped per plan §5.6 — planning work is done by the architect mode-agent or, when invoked from the `/phase-plan` command flow, inline by the orchestrator. Synthesize the plan from:
+- The phase slug
+- The current `pipelineStep` (always `plan` here)
+- The research findings + user decisions read above
+- The repo's coding patterns (from research) and acceptance criteria
+
+The plan should be a markdown document with: objective, atomic tasks (waves), verification criteria per task, and success criteria for the phase.
+
+## Persist the plan
+
+Write the plan with the `Write` tool to the canonical path. Use the `dir` field from `luca phase current`; the plan path is `<dir>/plan.md`:
+
+```
+Write tool → <dir>/plan.md
+content: "<plan markdown>"
+```
+
+The stage-gate hook only permits this `Write` to `<dir>/plan.md` while `pipelineStep === "plan"` — any other path or step is blocked.
+
+## Advance
+
+Run `luca state advance --to-step plan-review` to hand off to plan-review.
+
+## What you must NOT do
+
+- Do NOT write code. Code writes are blocked in PLANNING.
+- Do NOT skip the synthesis step — read research.md + context.md before drafting the plan. The plan must be grounded in those inputs.
+- Do NOT write `plan.md` to any path other than `<dir>/plan.md`, or via `Edit` — the hook blocks every other `.luca/` write.

package/dist/claude/.claude/commands/repo-cleanup.md

@@ -0,0 +1,80 @@
+---
+name: repo-cleanup
+description: Scan the repository for AI-session debris and optionally clean it up.
+---
+
+# /repo-cleanup
+
+Scan the repository for AI-session debris — orphaned scripts, misplaced source files, tool artifacts, dead exports, `.luca/` contract violations, repo-root markdown debris — and optionally apply the remediations.
+
+The scan is performed by the **`luca-shadow-scanner`** subagent (strictly read-only). This command drives that scan and applies fixes through the **`luca repo cleanup-apply`** CLI (the destructive write half).
+
+## Parse arguments
+
+Parse `$ARGUMENTS` for flags:
+
+- `--quick` — quick scan (categories 1 + 3 only)
+- `--full` — full scan (all 7 categories, including dead exports)
+- `--dry-run` — show findings without applying anything
+- `--fix` — auto-apply every `auto_fixable` finding without prompting
+- `--category=N` — restrict to a single detection category (1–7)
+
+If no scan-mode flag is given, default to **`standard`** mode with interactive review.
+
+Resolve `<repo_vault>` from `.luca/config.json` → `muninn.vault`, falling back to `"default"`.
+
+## Step 1 — Scan
+
+Spawn the **`luca-shadow-scanner`** subagent via the `Agent` tool. The task prompt must include:
+
+- The scan mode (`quick` | `standard` | `full`) resolved from the flags.
+- Any `--category=N` filter — tell the scanner to report only that category.
+
+The subagent ends its response with a single JSON block conforming to `ShadowScanReportSchema` (`scan_mode`, `categories_scanned`, `findings[]`, `summary`, `scanned_at`).
+
+## Step 2 — Parse the report
+
+Take the **last JSON block** of the subagent's response as the `ShadowScanReport`. Each entry in `findings[]` has: `category`, `severity`, `file_path`, `description`, `recommendation`, `recommended_action` (`delete` | `move` | `gitignore`), `target_path?`, `auto_fixable`.
+
+Display the findings banner: total count plus the per-severity breakdown from `summary`.
+
+## Step 3 — Handle the findings
+
+- **No findings** (`summary.total === 0`) → report a clean scan and stop.
+
+- **`--dry-run`** → display all findings grouped by severity (critical first) and stop. Apply nothing.
+
+- **`--fix`** → for every finding where `auto_fixable === true`, stage that single finding object in a JSON file and run:
+
+  ```
+  # /tmp/luca-cleanup-finding.json holds the single finding object
+  luca repo cleanup-apply --file /tmp/luca-cleanup-finding.json --confirm
+  ```
+
+  Findings with `auto_fixable === false` (e.g. repo-root markdown, SUMMARY moves) are listed for the user but not auto-applied.
+
+- **Interactive mode** (default) → present each finding sorted by severity (critical first). For each one, offer three choices:
+
+  - **Fix** → stage the single finding object in a JSON file and run `luca repo cleanup-apply --file <path> --confirm`. For a `move`, the finding must carry `target_path`; if it does not, ask the user where it should go and add `target_path` to the file before running.
+  - **Keep** → record the user's decision so the file is not re-flagged next scan:
+
+    First call `mcp__muninn__muninn_remember` with `vault: "<repo_vault>"`, `concept: "shadow-debt:kept:<file_path>"`, and content noting the user approved keeping `<file_path>` with an ISO timestamp. Then promote it: `mcp__muninn__muninn_trust({ id: <returned id>, trust: "verified", vault: "<repo_vault>" })` — this is a user-confirmed decision. The `luca-shadow-scanner` recalls `shadow-debt:kept` entries and excludes them from future scans.
+  - **Skip** → take no action; the file will be flagged again on the next scan.
+
+## Step 4 — Store the cleanup metric
+
+After processing every finding, record what the cleanup did (`metric:*` routes to the repo vault per the vault-routing rule):
+
+```
+mcp__muninn__muninn_remember({
+  vault: "<repo_vault>",
+  concept: "metric:shadow-debt-cleanup-<ISO timestamp>",
+  content: JSON.stringify({
+    scan_mode, total, fixed, kept, skipped, cleaned_at
+  })
+})
+```
+
+The `luca-shadow-scanner` already stores the raw scan counts under `metric:shadow-debt-scan-*`; this metric captures the action outcome (`fixed` / `kept` / `skipped`).
+
+$ARGUMENTS

package/dist/claude/.claude/commands/todo-add.md

@@ -0,0 +1,28 @@
+---
+name: todo-add
+description: Add a new item to the development backlog.
+---
+
+# /todo-add
+
+Add a new todo to the development backlog. Todos persist in **MuninnDB** (concept `todo:<id>`, repo vault) — there is no `.luca/todos/` directory.
+
+## Steps
+
+1. **Parse the title.** Treat `$ARGUMENTS` as the todo title — a short imperative description (e.g. "Add retry to the upload client"). If no arguments were provided, ask the user what they'd like to add.
+
+2. **Create the todo.** Run the `luca todo add` CLI with the title:
+
+   ```
+   luca todo add --title "<title>" --source manual
+   ```
+
+   - `--source manual` marks this as a hand-entered item (vs. `gh-issue-#N` or `phase-research`).
+   - If the user supplied acceptance criteria or extra context, pass it as `--body "<text>"`.
+   - The `id` is derived from the title automatically; only pass an explicit `--id` if the user asked for a specific slug.
+
+3. **Execute the returned instruction.** `luca todo add` validates the input and prints a `mcp__muninn__muninn_remember` instruction blob (delegation pattern — the `luca` CLI cannot call MuninnDB directly). Execute that instruction **exactly as returned** to persist the todo.
+
+4. **Confirm.** Report that the todo was created and show its `id` (the kebab-case slug derived from the title) and its status (`pending`).
+
+$ARGUMENTS

package/dist/claude/.claude/commands/todo-check.md

@@ -0,0 +1,36 @@
+---
+name: todo-check
+description: List all items in the development backlog.
+---
+
+# /todo-check
+
+List the development backlog. Todos live in **MuninnDB** (concept `todo:*`, repo vault).
+
+## Steps
+
+1. **Parse the filter.** Check `$ARGUMENTS` for an optional status filter — one of `pending`, `backlog`, or `done`.
+
+2. **List the todos.** Run the `luca todo list` CLI:
+
+   ```
+   luca todo list
+   ```
+
+   Pass `--status <filter>` if a filter was given.
+
+3. **Execute the returned instruction.** `luca todo list` prints a `mcp__muninn__muninn_recall` instruction blob (delegation pattern). Execute it **exactly as returned** to recall the todos.
+
+4. **Parse each entry.** Each recalled memory's `content` is JSON conforming to `TodoSchema` (`id`, `title`, `body?`, `status`, `source?`, `updatedAt`). Parse every entry. If a status filter was requested, keep only todos whose `content.status` matches it.
+
+5. **Display.** Render a numbered checklist grouped by status, in this order:
+
+   1. ⬜ **Pending** — `status: "pending"`
+   2. 📋 **Backlog** — `status: "backlog"`
+   3. ✅ **Done** — `status: "done"`
+
+   For each todo, show its `id`, `title`, `source` (if set), and `updatedAt`.
+
+6. **Empty backlog.** If no todos came back, tell the user the backlog is empty and suggest `/todo-add` to start building it.
+
+$ARGUMENTS

package/dist/claude/.claude/hooks/context-refresher.ts

@@ -0,0 +1,285 @@
+#!/usr/bin/env bun
+/**
+ * context-refresher handler — `PostToolUse` hook that surfaces a
+ * per-step `<luca-reminder>` to combat context rot.
+ *
+ * This is the Claude Code delivery vehicle for the pure
+ * `computeContextRefresher()` algorithm 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. We do NOT
+ *      narrow on tool_name — the hook is registered with matcher `*`
+ *      because every tool call is a context-growth tick.
+ *   2. Load (or initialize) the sidecar `.claude/cache/
+ *      context-refresher-state.json`.
+ *   3. Increment the toolCallCount.
+ *   4. Read `.luca/state.json` for the current pipelineStep.
+ *   5. Call `computeContextRefresher()`.
+ *   6. If the verdict carries `nextState`, persist it back to the
+ *      sidecar. If the verdict carries a `refresh-emitted` reason,
+ *      emit the message via `additionalContext` in the PostToolUse
+ *      hook output JSON shape.
+ *   7. Exit 0 always (informational hook — never blocks).
+ *
+ * The Claude Code hook contract (PostToolUse):
+ *
+ *   stdin JSON shape (snake_case fields per the docs):
+ *     {
+ *       "session_id": "...",
+ *       "hook_event_name": "PostToolUse",
+ *       "tool_name": "<any>",
+ *       "tool_input": { ... },
+ *       "tool_response": { ... }
+ *     }
+ *
+ *   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)
+ *
+ *   Stdout JSON for context injection:
+ *     {
+ *       "hookSpecificOutput": {
+ *         "hookEventName": "PostToolUse",
+ *         "additionalContext": "<luca-reminder>...</luca-reminder>"
+ *       }
+ *     }
+ *
+ * Sidecar location: `.claude/cache/context-refresher-state.json`. This
+ * lives under `.claude/` rather than `.luca/` because it is hook-
+ * managed bookkeeping (the cross-invocation counter), not pipeline
+ * state. The `.luca/` contract is a strict allowlist of pipeline-state
+ * artifacts; the sidecar would violate that contract. `.claude/cache/`
+ * is a fresh subdirectory (Claude Code's harness ignores unknown
+ * files under `.claude/`, so we own the namespace) — wipe it freely
+ * during Phase H cleanup if needed.
+ *
+ * Failure-open philosophy (per E-1 / E-2 / E-3 reasoning, intentionally
+ * reused): if ANYTHING unexpected happens (stdin parse error, state.json
+ * missing/malformed, sidecar read/write failure), exit 0 silently. A
+ * hook that mis-emits a reminder is mildly annoying; a hook that
+ * crashes the session is worse. Choose silent skip.
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+
+import { appendLedger } from '@alecsibilia/luca-core/ledger'
+import {
+    computeContextRefresher,
+    type ContextRefresherCarryState,
+    type ContextRefresherInput,
+} from '@alecsibilia/luca-core/orchestration'
+import { loadCurrentState } from '@alecsibilia/luca-core/state'
+
+/**
+ * Shape of the relevant slice of the PostToolUse stdin payload. We do
+ * not introspect the payload beyond reading it; the matcher (`*`) is
+ * the only gate on this hook. Defensive typing — the harness may add
+ * fields and the handler should not break on them.
+ */
+interface PostToolUsePayload {
+    tool_name?: string
+    toolName?: string
+}
+
+/**
+ * On-disk sidecar shape. Identical fields to ContextRefresherCarryState
+ * with a `schemaVersion` for future migrations. The handler reads the
+ * sidecar with defensive defaults — a missing or malformed file
+ * collapses to "no prior state" (counter zero, no lastFiredStep).
+ */
+interface SidecarFile {
+    schemaVersion: 1
+    toolCallCount: number
+    lastFiredStep?: string
+    lastFiredAt?: string
+}
+
+const SIDECAR_RELATIVE_PATH = '.claude/cache/context-refresher-state.json'
+
+async function main(): Promise<number> {
+    const raw = await Bun.stdin.text()
+    if (!raw.trim()) {
+        // Empty stdin — nothing to do. Allow silently.
+        return 0
+    }
+
+    try {
+        // We don't need any field from the payload — the matcher (`*`)
+        // already filtered to "every tool call". We still parse to
+        // detect malformed payloads and fail open silently in that case.
+        JSON.parse(raw) as PostToolUsePayload
+    } catch {
+        // Malformed stdin is the harness's problem. Fail open silently.
+        return 0
+    }
+
+    const cwd = process.cwd()
+
+    // Load prior sidecar state (or default to a fresh counter).
+    const priorRaw = await readSidecar(cwd)
+    // Increment the counter to reflect THIS tool call BEFORE calling
+    // the algorithm — the algorithm's threshold check compares the
+    // post-increment value to toolCallsPerRefresh.
+    const priorState: ContextRefresherCarryState = {
+        toolCallCount: priorRaw.toolCallCount + 1,
+        ...(priorRaw.lastFiredStep !== undefined
+            ? { lastFiredStep: priorRaw.lastFiredStep }
+            : {}),
+        ...(priorRaw.lastFiredAt !== undefined
+            ? { lastFiredAt: priorRaw.lastFiredAt }
+            : {}),
+    }
+
+    const state = await loadCurrentState({ cwd })
+    const now = new Date().toISOString()
+
+    const input: ContextRefresherInput = {
+        currentStep: state.pipelineStep,
+        priorState,
+        now,
+        ...(state.complexity !== undefined
+            ? { complexity: state.complexity }
+            : {}),
+        ...(state.oversight !== undefined
+            ? { oversight: state.oversight }
+            : {}),
+    }
+
+    const verdict = computeContextRefresher(input)
+
+    // Persist nextState when present. We do this BEFORE writing to
+    // stdout so a downstream stdout error doesn't leave the counter
+    // un-incremented (which would let the refresher fire on every
+    // subsequent tool call until the counter caught up again).
+    if (verdict?.nextState !== undefined) {
+        await writeSidecar(cwd, verdict.nextState)
+    } else {
+        // No nextState in the verdict — either the algorithm returned
+        // null (idle step, no carry needed) or this is an
+        // unknown-current-step verdict. In either case persist a
+        // fresh counter from the increment so we don't lose ticks.
+        await writeSidecar(cwd, priorState)
+    }
+
+    // Emit a ledger event for the hook firing. Only log on decisive
+    // outcomes (emit vs skipped) — every tool call fires this hook, so
+    // logging every tick would flood the ledger. Failure-open.
+    if (verdict !== null && verdict.reason === 'refresh-emitted') {
+        try {
+            const runId = typeof (state as { sessionId?: unknown }).sessionId === 'string'
+                ? (state as { sessionId: string }).sessionId
+                : ''
+            appendLedger({
+                cwd,
+                runId,
+                event: 'hook.context-refresher.fired',
+                data: {
+                    pipelineStep: state.pipelineStep,
+                    decision: 'emitted',
+                    toolCallCount: priorState.toolCallCount,
+                },
+            })
+        } catch {
+            // Failure-open.
+        }
+    }
+
+    if (verdict === null) {
+        // Idle step or quiet skip. No additionalContext emitted.
+        return 0
+    }
+
+    if (verdict.reason !== 'refresh-emitted') {
+        // No reminder for this tick (cooldown active, counter below
+        // threshold, or unknown step — we don't surface internal
+        // warnings to the model).
+        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
+}
+
+/**
+ * Read the sidecar file, returning defaults on missing/malformed file.
+ * Never throws — every error path collapses to "no prior state".
+ */
+async function readSidecar(cwd: string): Promise<SidecarFile> {
+    const fallback: SidecarFile = { schemaVersion: 1, toolCallCount: 0 }
+    const p = join(cwd, SIDECAR_RELATIVE_PATH)
+    if (!existsSync(p)) return fallback
+    try {
+        const raw = await readFile(p, 'utf-8')
+        if (!raw.trim()) return fallback
+        const parsed = JSON.parse(raw) as Partial<SidecarFile>
+        if (typeof parsed.toolCallCount !== 'number') return fallback
+        return {
+            schemaVersion: 1,
+            toolCallCount: parsed.toolCallCount,
+            ...(typeof parsed.lastFiredStep === 'string'
+                ? { lastFiredStep: parsed.lastFiredStep }
+                : {}),
+            ...(typeof parsed.lastFiredAt === 'string'
+                ? { lastFiredAt: parsed.lastFiredAt }
+                : {}),
+        }
+    } catch {
+        return fallback
+    }
+}
+
+/**
+ * Write the sidecar file atomically (write-then-rename). On any error,
+ * swallow silently — we'd rather lose a counter tick than crash the
+ * session over a transient disk hiccup.
+ */
+async function writeSidecar(
+    cwd: string,
+    state: ContextRefresherCarryState,
+): Promise<void> {
+    const p = join(cwd, SIDECAR_RELATIVE_PATH)
+    const dir = dirname(p)
+    const tmp = `${p}.tmp`
+    const payload: SidecarFile = {
+        schemaVersion: 1,
+        toolCallCount: state.toolCallCount,
+        ...(state.lastFiredStep !== undefined
+            ? { lastFiredStep: state.lastFiredStep }
+            : {}),
+        ...(state.lastFiredAt !== undefined
+            ? { lastFiredAt: state.lastFiredAt }
+            : {}),
+    }
+    try {
+        await mkdir(dir, { recursive: true })
+        await writeFile(tmp, JSON.stringify(payload) + '\n', 'utf-8')
+        // Bun-supported rename via fs/promises (atomic on POSIX).
+        const { rename } = await import('node:fs/promises')
+        await rename(tmp, p)
+    } catch {
+        // Sidecar persistence failure is non-fatal — next invocation
+        // will recompute from a fresh counter. Silently absorb.
+    }
+}
+
+main().then(
+    (code) => process.exit(code),
+    (err) => {
+        // Defensive: any unexpected throw means we fail open silently.
+        // No stderr — informational hook; users shouldn't see internal
+        // errors.
+        void err
+        process.exit(0)
+    },
+)