@neonwatty/limner 0.1.6 → 0.1.8

package/docs/goals/db-native-agent-responses/goal.md

@@ -0,0 +1,91 @@
+# DB-Native Agent Responses
+
+## Objective
+
+Make Limner treat SQLite as the canonical store and submission path for agent comparison responses, so agents no longer rely on a magic `agent-response.json` file as package state.
+
+## Original Request
+
+Plan this out using GoalBuddy prep and do the work so Limner stores agent comparison responses in SQLite instead of using `agent-response.json`.
+
+## Intake Summary
+
+- Input shape: `existing_plan`
+- Audience: Limner users and agents dogfooding visual comparison loops across multiple projects
+- Authority: `approved`
+- Proof type: `test`
+- Completion proof: `npm run check` passes, docs/skills describe the DB-native workflow, and a fresh Seatify loop can submit/read an agent response through SQLite without depending on target-scoped `agent-response.json`.
+- Goal oracle: A local Limner workflow where `loop compare` produces a response submission path, `loop response submit` stores the full JSON in SQLite, ledger/export surfaces that row, and no docs/skills instruct agents to write canonical `agent-response.json`.
+- Likely misfire: Only copying response JSON into SQLite after reading the old file, while leaving the file as the real source of truth.
+- Blind spots considered: migration from existing local ledgers, direct compare command compatibility, stale response detection without file mtimes, generated artifact naming, agent discoverability, and preserving model-agnostic CLI behavior.
+- Existing plan facts: Keep responses local only; SQLite should store the full raw JSON; `agent_responses` belongs beside ledger events rather than inside the ledger event log; agent-readable skills/docs must explain the CLI commands; previous `agent-response.json` freshness semantics showed cached reuse and should become explicit DB submission state instead.
+
+## Goal Oracle
+
+The oracle for this goal is:
+
+`npm run check` passes and a fresh loop can validate a DB-submitted agent comparison response without treating captures/**/agent-response.json as canonical state.`
+
+The PM must keep comparing task receipts to this oracle. Planning, discovery, a passing tiny slice, or a clean-looking board is not enough. The goal finishes only when a final Judge/PM audit maps receipts and verification back to this oracle and records `full_outcome_complete: true`.
+
+## Goal Kind
+
+`existing_plan`
+
+## Current Tranche
+
+Complete the DB-native response submission and storage tranche: validate the current code path, implement the CLI/storage/prompt/doc changes, verify with tests and `npm run check`, then prepare the branch for PR/release follow-up if green.
+
+## Non-Negotiable Constraints
+
+- Keep Limner model-agnostic: accept JSON via CLI file or stdin rather than integrating a provider.
+- Keep logs and ledgers local; do not add remote telemetry.
+- Do not commit generated `.limner/`, `dist/`, `node_modules/`, or smoke artifacts.
+- Preserve supported comparison modes: `image-mockup`, `mockup-implementation`, and `image-implementation`.
+- Store the full agent response JSON in SQLite.
+- Do not leave `agent-response.json` as the canonical handoff/state file in docs, skills, or loop behavior.
+- Run `npm run check` before claiming implementation completion or opening a PR.
+
+## Stop Rule
+
+Stop only when a final audit proves the full original outcome is complete.
+
+Do not stop after planning, discovery, or Judge selection if a safe Worker task can be activated.
+
+Do not stop after a single verified Worker package when the broader owner outcome still has safe local follow-up work. Advance the board to the next highest-leverage safe Worker package and continue unless a phase, risk, rejected-verification, ambiguity, or final-completion review is due.
+
+## Slice Sizing
+
+Safe means bounded, explicit, verified, and reversible. It does not mean tiny.
+
+A good task is the largest safe useful slice.
+
+The Worker should complete the full coherent DB-native response submission slice, including tests and documentation, unless code inspection finds that the slice must be split.
+
+## Canonical Board
+
+Machine truth lives at:
+
+`docs/goals/db-native-agent-responses/state.yaml`
+
+If this charter and `state.yaml` disagree, `state.yaml` wins for task status, active task, receipts, verification freshness, and completion truth.
+
+## Run Command
+
+```text
+/goal Follow docs/goals/db-native-agent-responses/goal.md.
+```
+
+## PM Loop
+
+On every `/goal` continuation:
+
+1. Read this charter.
+2. Read `state.yaml`.
+3. Run the bundled GoalBuddy update checker when available and mention a newer version without blocking.
+4. Re-check the likely misfire: do not preserve `agent-response.json` as the canonical response channel.
+5. Work only on the active board task.
+6. Assign Scout, Judge, Worker, or PM according to the task.
+7. Write a compact task receipt.
+8. Update the board.
+9. Continue to the next safe local work package unless final audit proves the goal complete.

package/docs/goals/db-native-agent-responses/state.yaml

@@ -0,0 +1,240 @@
+version: 2
+
+goal:
+  title: "DB-Native Agent Responses"
+  slug: "db-native-agent-responses"
+  kind: existing_plan
+  tranche: "Implement SQLite-native agent response submission/storage and remove agent-response.json as canonical loop state."
+  status: done
+  oracle:
+    signal: "A fresh Limner loop can submit and validate an agent comparison response through SQLite, docs/skills describe that workflow, and npm run check passes."
+    cadence: "after Worker implementation and at final audit"
+    final_proof: "Receipt-backed npm run check result plus evidence that docs/skills and CLI behavior no longer make agent-response.json the canonical response state."
+  intake:
+    original_request: "Plan this out using GoalBuddy prep and make Limner stop using agent-response.json as canonical state."
+    interpreted_outcome: "Limner should make SQLite the source of truth and CLI submission channel for agent comparison responses."
+    input_shape: existing_plan
+    audience: "Limner users and agents running visual polish loops across multiple projects"
+    authority: approved
+    proof_type: test
+    completion_proof: "npm run check passes and a fresh loop validates a DB-submitted agent response without relying on target-scoped agent-response.json."
+    likely_misfire: "SQLite stores a copy of the file, but the file remains the true handoff/state mechanism."
+    blind_spots_considered:
+      - "Existing ledger migration from 0.1.7 rows that used response_path."
+      - "Direct compare commands may still need prompt/schema artifacts without a loop trajectory."
+      - "Freshness must become DB submission state rather than file existence timing."
+      - "Agents need docs/skills that reveal the submission CLI without reading code."
+      - "Seatify smoke artifacts should not be committed."
+    existing_plan_facts:
+      - "SQLite already has an agent_responses table with response_json."
+      - "Current 0.1.7 still reads captures/**/agent-response.json before storing rows."
+      - "The new workflow should accept response JSON through CLI file or stdin."
+      - "The full raw JSON must remain stored locally in SQLite."
+      - "Loop ledger exports should keep surfacing response evidence and action history."
+
+rules:
+  pm_owns_state: true
+  one_active_task: true
+  max_write_workers: 1
+  no_implementation_without_worker_or_pm_task: true
+  no_completion_without_judge_or_pm_audit: true
+  planning_is_not_completion: true
+  queued_required_worker_blocks_completion: true
+  continuous_until_full_outcome: true
+  missing_input_or_credentials_do_not_stop_goal: true
+  preserve_and_validate_existing_plan: true
+  intake_misfire_must_be_audited: true
+  goal_pressure_requires_oracle: true
+  no_completion_on_weak_proof: true
+  slice_policy:
+    max_consecutive_tiny_tasks: 2
+    prefer_vertical_slices: true
+    judge_picks_largest_safe_slice: true
+    worker_completes_whole_slice: true
+
+agents:
+  scout: installed
+  worker: installed
+  judge: installed
+
+visual_board:
+  selected: local
+  local:
+    status: starting
+    url: "http://goalbuddy.localhost:41737/db-native-agent-responses/"
+    command: "npx goalbuddy board docs/goals/db-native-agent-responses"
+
+active_task: null
+
+tasks:
+  - id: T001
+    type: judge
+    assignee: Judge
+    status: done
+    reasoning_hint: high
+    objective: "Validate the DB-native response plan against the current Limner code and choose the largest safe Worker implementation slice."
+    inputs:
+      - "docs/goals/db-native-agent-responses/goal.md"
+      - "Current Limner source, tests, README, docs, and skills"
+      - "Existing plan facts in goal.intake.existing_plan_facts"
+    constraints:
+      - "Read-only."
+      - "Do not implement."
+      - "Preserve the user's correction that agent-response.json must not remain canonical."
+    expected_output:
+      - "Decision"
+      - "Exact Worker objective"
+      - "allowed_files"
+      - "verify"
+      - "stop_if"
+      - "Any split tasks if the first slice is too large or risky"
+    receipt:
+      result: done
+      decision: approved
+      full_outcome_complete: false
+      summary: "Current code stores response_json in SQLite but still reads captures/**/agent-response.json as canonical input. Approve one vertical Worker slice: DB pending context on loop compare, loop response submit for file/stdin, validation from stored context, summary artifacts, ledger export, docs/skills updates."
+      evidence:
+        - "src/core/agent-comparison-pack.ts reads responsePath and readAgentResponse()."
+        - "src/commands/loop.ts records responseJson after compare, not as the submission channel."
+        - "src/core/agent-comparison-prompts.ts tells agents to write JSON to responsePath."
+        - "README.md and docs/agent-workflow.md instruct agent-response.json handoff."
+      worker:
+        objective: "Implement SQLite-native agent response submission and remove agent-response.json as canonical loop state."
+        allowed_files:
+          - "src/core/agent-comparison*.ts"
+          - "src/core/comparison-artifacts.ts"
+          - "src/core/current-artifacts*.ts"
+          - "src/core/ledger*.ts"
+          - "src/core/report-writer.ts"
+          - "src/commands/compare*.ts"
+          - "src/commands/loop*.ts"
+          - "src/commands/ledger*.ts"
+          - "src/schemas/*.ts"
+          - "src/index.ts"
+          - "README.md"
+          - "docs/agent-workflow.md"
+          - "skills/limner/SKILL.md"
+          - "templates/target/AGENT_GUIDE.md"
+        verify:
+          - "npm test -- agent-comparison-pack loop-agent-responses loop-task ledger"
+          - "npm run check"
+        stop_if:
+          - "The migration requires destructive changes to existing ledgers."
+          - "Direct compare commands cannot remain useful without an explicit user decision."
+          - "The implementation would require remote telemetry or model-provider coupling."
+  - id: T002
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: high
+    objective: "Implement the DB-native agent response submission/storage workflow selected by T001."
+    allowed_files:
+      - "src/core/agent-comparison*.ts"
+      - "src/core/comparison-artifacts.ts"
+      - "src/core/current-artifacts*.ts"
+      - "src/core/ledger*.ts"
+      - "src/core/report-writer.ts"
+      - "src/commands/compare*.ts"
+      - "src/commands/loop*.ts"
+      - "src/commands/ledger*.ts"
+      - "src/schemas/*.ts"
+      - "src/index.ts"
+      - "README.md"
+      - "docs/agent-workflow.md"
+      - "skills/limner/SKILL.md"
+      - "templates/target/AGENT_GUIDE.md"
+    verify:
+      - "npm test -- agent-comparison-pack loop-agent-responses loop-task ledger"
+      - "npm run check"
+    stop_if:
+      - "Need files outside allowed_files."
+      - "Current code shape contradicts the selected implementation approach."
+      - "A migration risk appears that requires an explicit Judge decision."
+      - "Verification fails twice with different root causes."
+    receipt:
+      result: done
+      changed_files:
+        - "src/core/agent-comparison*.ts"
+        - "src/core/ledger*.ts"
+        - "src/commands/loop*.ts"
+        - "src/commands/compare*.ts"
+        - "README.md"
+        - "docs/agent-workflow.md"
+        - "skills/limner/SKILL.md"
+        - "templates/target/AGENT_GUIDE.md"
+      commands:
+        - cmd: "npm test -- loop-agent-responses"
+          status: pass
+        - cmd: "npm test -- agent-comparison-pack comparison-artifacts loop-agent-responses loop-task ledger current-artifacts ledger-store"
+          status: pass
+        - cmd: "npm run typecheck"
+          status: pass
+        - cmd: "npm test"
+          status: pass
+        - cmd: "npm run check"
+          status: pass
+      summary: "Loop comparison prompts now submit responses through SQLite via loop response submit; stored comparison context validates submissions and writes summary artifacts without canonical agent-response.json."
+  - id: T003
+    type: worker
+    assignee: Worker
+    status: done
+    reasoning_hint: medium
+    objective: "Run a fresh local smoke workflow, preferably Seatify if available, and record evidence without committing generated artifacts."
+    allowed_files:
+      - "No repo file writes; smoke may write only external workspace/ledger artifacts."
+      - "/Users/neonwatty/Desktop/seatify-ux-limner-artifacts/2026-06-04/limner-workspaces/A-public-homepage/targets/homepage-desktop/captures/image-reference"
+    verify:
+      - "Run a fresh loop compare and loop response submit using the source CLI."
+      - "Confirm ledger export includes a fresh validated agent response row."
+    stop_if:
+      - "Seatify workspace is unavailable."
+      - "Smoke workflow needs credentials or external publishing."
+      - "Generated artifacts would need to be committed."
+    receipt:
+      result: done
+      changed_files:
+        - "/Users/neonwatty/Desktop/seatify-ux-limner-artifacts/2026-06-04/limner-workspaces/A-public-homepage/targets/homepage-desktop/captures/image-reference"
+      commands:
+        - cmd: "LIMNER_LEDGER_HOME=/tmp/limner-db-native-smoke.kZldTK npm run dev -- --workspace /Users/neonwatty/Desktop/seatify-ux-limner-artifacts/2026-06-04/limner-workspaces/A-public-homepage loop start --mode image-mockup --target homepage-desktop --name db-native-seatify-smoke --max-iterations 2"
+          status: pass
+        - cmd: "LIMNER_LEDGER_HOME=/tmp/limner-db-native-smoke.kZldTK npm run dev -- --workspace /Users/neonwatty/Desktop/seatify-ux-limner-artifacts/2026-06-04/limner-workspaces/A-public-homepage loop compare --trajectory traj_2da3a56dc1909a61"
+          status: pass
+        - cmd: "test ! -e targets/homepage-desktop/captures/image-reference/agent-comparison/agent-response.json"
+          status: pass
+        - cmd: "LIMNER_LEDGER_HOME=/tmp/limner-db-native-smoke.kZldTK npm run dev -- --workspace /Users/neonwatty/Desktop/seatify-ux-limner-artifacts/2026-06-04/limner-workspaces/A-public-homepage loop response submit --trajectory traj_2da3a56dc1909a61 --from-run 2026-06-14T125413357Z-db02fl --file targets/homepage-desktop/captures/image-reference/agent-comparison/agent-response.example.json"
+          status: pass
+        - cmd: "LIMNER_LEDGER_HOME=/tmp/limner-db-native-smoke.kZldTK npm run dev -- --workspace /Users/neonwatty/Desktop/seatify-ux-limner-artifacts/2026-06-04/limner-workspaces/A-public-homepage loop task --trajectory traj_2da3a56dc1909a61 --executor subagent"
+          status: pass
+      summary: "Fresh Seatify homepage loop validated DB-native response submission: pending missing row, fresh validated row, comparison summary, task brief, and skipped no-op action were all recorded."
+  - id: T999
+    type: judge
+    assignee: Judge
+    status: done
+    reasoning_hint: high
+    objective: "Audit whether DB-native agent responses satisfy the original user outcome for this tranche."
+    inputs:
+      - "All done task receipts"
+      - "Last verification"
+      - "Current dirty diff"
+    constraints:
+      - "Do not implement."
+      - "Reject completion if agent-response.json remains canonical in loop behavior, docs, or skills."
+      - "Reject completion if npm run check has not passed after implementation."
+      - "Reject completion if required Worker work is still queued or active."
+    expected_output:
+      - "complete | not_complete"
+      - "full_outcome_complete: true | false"
+      - "missing evidence"
+      - "next task if not complete"
+    receipt:
+      result: done
+      decision: complete
+      full_outcome_complete: true
+      summary: "Oracle satisfied: npm run check passed; Seatify smoke validated loop response submit; docs/skill/target guide teach SQLite submission; current loop comparison code no longer uses agent-response.json as canonical state."
+
+checks:
+  dirty_fingerprint: "main...origin/main clean before GoalBuddy control files"
+  last_verification:
+    result: unknown
+    task: null
+    commands: []

package/docs/superpowers/plans/2026-06-13-agent-response-sqlite.md

@@ -0,0 +1,70 @@
+# Agent Response SQLite Evidence Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Store every loop comparison's full `agent-response.json` evidence in SQLite so freshness, validation, and recommendations are centralized.
+
+**Architecture:** Add an `agent_responses` table beside `ledger_events`, not inside the event log. `writeAgentComparisonPack` reports response JSON/hash/freshness; `loop compare` records that evidence with trajectory, iteration, and run IDs. Ledger exports summarize DB rows and mark cached reuse plainly.
+
+**Tech Stack:** TypeScript, better-sqlite3, Zod comparison schema, Vitest, GitHub Actions, npm release workflow.
+
+---
+
+## Files
+
+- Modify `src/core/ledger-db.ts`: create `agent_responses`.
+- Modify `src/core/agent-comparison-pack.ts`: expose response JSON, hash, and freshness.
+- Modify `src/core/ledger-store.ts`: add `recordAgentResponse`.
+- Modify `src/core/ledger-queries.ts`: export agent response rows.
+- Modify `src/core/ledger-markdown.ts`: render `## Agent Responses`.
+- Modify `src/commands/loop.ts`: record response evidence after compare.
+- Tests: `src/core/ledger-db.test.ts`, `src/core/agent-comparison-pack.test.ts`, `src/core/ledger-store.test.ts`, `src/commands/loop.test.ts`, `src/commands/ledger.test.ts`.
+- Docs: update `README.md`, `docs/agent-workflow.md`, and `skills/limner/SKILL.md` only if CLI/user behavior changes.
+
+## Data Contract
+
+Create table:
+
+```sql
+agent_responses (
+  response_id text primary key,
+  trajectory_id text not null references trajectories(trajectory_id) on delete cascade,
+  iteration_id text,
+  run_id text,
+  mode text not null,
+  profile text,
+  response_path text not null,
+  response_hash text,
+  freshness text not null,
+  validation_status text not null,
+  input_fingerprint_json text,
+  response_json text,
+  score_json text,
+  top_fix text,
+  created_at text not null
+)
+```
+
+Freshness values: `missing`, `cached`, `stale`, `invalid`. `fresh` is reserved for future run-scoped response creation.
+
+## Tasks
+
+- [ ] **Task 1: DB schema and store API**
+
+Add `agent_responses` to `ledger-db.ts` and assert it exists in `ledger-db.test.ts`. Add `recordAgentResponse` to `ledger-store.ts`; it inserts one row with `response_id = createLedgerId('resp')`. Add a store test that starts a trajectory, records a validated cached response with `response_json`, then exports the row.
+
+- [ ] **Task 2: Pack response evidence**
+
+In `agent-comparison-pack.ts`, compute whether `agent-response.json` existed before the pack was written, read the raw response text when present, hash it, and expose fields on `AgentComparisonPackResult`: `responseJson`, `responseHash`, `freshness`, `profile`, `inputFingerprint`, `topFix`, `score`. Map missing to `missing`, invalid JSON/schema to `invalid`, active comparison mismatch to `stale`, and validated pre-existing response to `cached`.
+
+- [ ] **Task 3: Record from loop compare**
+
+In `compareLoop`, after a compare returns and before/after the event append, call `store.recordAgentResponse` when `result.agentComparison` exists. Include trajectory ID, active iteration ID, run ID, trajectory mode, pack profile, response path/hash/json, freshness, validation status, input fingerprint, score, and top fix. Add loop tests for validated cached and missing/awaiting rows.
+
+- [ ] **Task 4: Export and docs**
+
+Export `agentResponses` from `ledger-queries.ts` and render `## Agent Responses` in `ledger-markdown.ts`, including run, status, freshness, response hash, score, top fix, and path. Add ledger markdown tests showing `freshness: cached`. Update docs/skill if needed to say full agent responses are stored in local SQLite.
+
+- [ ] **Task 5: Verify and release path**
+
+Run `npm run check`, smoke Seatify with a fresh trajectory, confirm the DB row says `freshness: cached` for the reused response, then make a commit, push, open PR, monitor CI, merge when green, trigger npm release workflow, reinstall, and rerun Seatify expecting the installed CLI to expose the same evidence.

package/docs/superpowers/plans/2026-06-13-loop-action-ledger.md

@@ -0,0 +1,257 @@
+# Loop Action Ledger Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add first-class action logging so each Limner comparison can be followed by an explicit subagent handoff, polish action, skip, or completion record.
+
+**Architecture:** Reuse `ledger_events` for v1. Action events store `actionId`, source comparison `runId`, executor, status, summary, files, and commit in `inputs_summary`; edited files are also artifact refs. `loop task` becomes the bridge from validated comparison evidence to an agent or subagent action.
+
+**Tech Stack:** TypeScript, Commander, Zod, better-sqlite3, Vitest, Markdown docs, bundled Codex skill instructions.
+
+---
+
+## File Structure
+
+- Modify `src/schemas/ledger.ts`: action kind/status/executor schemas and 255-character summary validation.
+- Modify `src/core/ledger-events.ts`: validate action event summaries.
+- Modify `src/commands/loop.ts`: `recordLoopAction`, enriched `getLoopTask`, action event context.
+- Modify `src/commands/loop-cli.ts`: `loop action start|complete|skip`, plus `loop task --executor`.
+- Modify `src/core/agent-task-brief.ts`: source run ID, desired executor, action logging commands.
+- Modify `src/core/ledger-markdown.ts`: action history section.
+- Tests: `src/commands/loop.test.ts`, `src/core/agent-task-brief.test.ts`, `src/core/ledger-store.test.ts`, `src/commands/ledger.test.ts`.
+- Docs: `README.md`, `docs/agent-workflow.md`, `skills/limner/SKILL.md`.
+
+## Event Contract
+
+Event types: `loop.action.started`, `loop.action.completed`, `loop.action.skipped`, `loop.action.failed`. `inputs_summary` shape:
+
+```json
+{
+  "actionId": "act_0123456789abcdef",
+  "kind": "polish",
+  "executor": "subagent",
+  "fromRunId": "2026-06-13T020201866Z-rkm2tn",
+  "summary": "Resize and reposition dashboard preview",
+  "files": ["targets/homepage-desktop/reference/styles.css"],
+  "commit": "abc1234"
+}
+```
+
+## Task 1: Add Ledger Action Types
+
+**Files:** `src/schemas/ledger.ts`, `src/core/ledger-events.ts`, `src/core/ledger-store.test.ts`
+
+- [ ] **Step 1: Write the failing validation test**
+
+Add to `src/core/ledger-store.test.ts`:
+
+```ts
+it('rejects overlong action summaries', () => {
+  const store = createLedgerStore(db);
+  const trajectory = store.startTrajectory(createInput());
+  expect(() => store.appendEvent({
+    trajectoryId: trajectory.trajectoryId,
+    iterationId: trajectory.activeIterationId ?? undefined,
+    eventType: 'loop.action.started',
+    actor: 'agent',
+    inputsSummary: JSON.stringify({ summary: 'x'.repeat(256) }),
+  })).toThrow(/255/);
+});
+```
+
+- [ ] **Step 2: Run the failing test**
+
+Run: `npm test -- src/core/ledger-store.test.ts`
+
+Expected: FAIL because action summaries are not validated yet.
+
+- [ ] **Step 3: Add schemas, validation, and verify**
+
+Add to `src/schemas/ledger.ts`:
+
+```ts
+export const ledgerActionKindSchema = z.enum(['polish', 'handoff', 'manual-edit', 'verification', 'no-op']);
+export const ledgerActionStatusSchema = z.enum(['started', 'completed', 'skipped', 'failed']);
+export const ledgerActionExecutorSchema = z.enum(['subagent', 'agent', 'user', 'cli']);
+export const ledgerActionSummarySchema = z.string().min(1).max(255);
+export type LedgerActionKind = z.infer<typeof ledgerActionKindSchema>;
+export type LedgerActionStatus = z.infer<typeof ledgerActionStatusSchema>;
+export type LedgerActionExecutor = z.infer<typeof ledgerActionExecutorSchema>;
+```
+
+In `src/core/ledger-events.ts`, if `eventType` starts with `loop.action.`, parse `inputsSummary`, require a string `summary`, and validate it with `ledgerActionSummarySchema`.
+
+Run: `npm test -- src/core/ledger-store.test.ts`
+
+Expected: PASS.
+
+## Task 2: Add Core Action Recording
+
+**Files:** `src/commands/loop.ts`, `src/commands/loop.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Import `recordLoopAction` and add cases for `started`, `completed`, and `skipped`:
+
+```ts
+const action = recordLoopAction({
+  ledgerEnv,
+  trajectoryId: started.trajectoryId,
+  status: 'started',
+  kind: 'polish',
+  executor: 'subagent',
+  fromRunId: 'run_123',
+  summary: 'Resize dashboard preview',
+});
+expect(action.actionId).toMatch(/^act_/);
+```
+
+Assert exported events contain `loop.action.started`, `loop.action.completed`, and `loop.action.skipped`, and that parsed `inputsSummary` includes `actionId`, `fromRunId`, `executor`, `summary`, `files`, and `commit` when supplied.
+
+- [ ] **Step 2: Run the failing test**
+
+Run: `npm test -- src/commands/loop.test.ts`
+
+Expected: FAIL because `recordLoopAction` does not exist.
+
+- [ ] **Step 3: Implement `recordLoopAction` and verify**
+
+In `src/commands/loop.ts`, add `LoopActionInput` with `status`, `kind`, `executor`, `summary`, optional `actionId`, `fromRunId`, `files`, `commit`, and the existing trajectory selector fields. Use `createLedgerId('act')` when no action ID is supplied. Append event type `loop.action.${status}`, actor `agent` for `subagent` or `agent`, actor `user` for `user`, and actor `cli` for `cli`. Return `{ actionId }`.
+
+Run: `npm test -- src/commands/loop.test.ts`
+
+Expected: PASS.
+
+## Task 3: Add CLI Commands
+
+**Files:** `src/commands/loop-cli.ts`, `src/commands/loop.test.ts`
+
+- [ ] **Step 1: Add command normalization coverage**
+
+Add a test that passes files as `['src/app/page.tsx', 'src/app/globals.css']` to `recordLoopAction` and asserts the exported action event stores both files and creates `edited-file` artifact refs.
+
+- [ ] **Step 2: Implement `loop action`**
+
+Add Commander subcommands:
+
+```bash
+limner loop action start --trajectory <id> --from-run <run-id> --kind polish --executor subagent --summary "Resize dashboard preview"
+limner loop action complete --trajectory <id> --action <action-id> --summary "Adjusted preview sizing" --files "src/app/page.tsx,src/app/globals.css" --commit abc1234
+limner loop action skip --trajectory <id> --from-run <run-id> --summary "Smoke test only; no polish intended"
+```
+
+Each command prints `Action: <action-id>`.
+
+- [ ] **Step 3: Verify CLI and tests**
+
+Run: `npm run dev -- loop action start --help`
+
+Expected: help lists `--trajectory`, `--from-run`, `--kind`, `--executor`, and `--summary`.
+
+Run: `npm test -- src/commands/loop.test.ts`
+
+Expected: PASS.
+
+## Task 4: Make Task Briefs Subagent-Ready
+
+**Files:**
+- Modify: `src/core/agent-task-brief.ts`
+- Modify: `src/commands/loop.ts`
+- Modify: `src/commands/loop-cli.ts`
+- Test: `src/core/agent-task-brief.test.ts`
+- Test: `src/commands/loop.test.ts`
+
+- [ ] **Step 1: Write failing assertions**
+
+Update tests to expect JSON fields `sourceRunId`, `desiredExecutor`, `actionStartCommand`, and `actionCompleteCommandExample`. Expect Markdown to include `## Action Logging`, `limner loop action start`, `limner loop action complete`, and `limner loop action skip`.
+
+- [ ] **Step 2: Enrich task lookup and command**
+
+Change `latestValidatedComparison` to return `{ summaryPath, inputsSummary, runId }`. Add `--executor <executor>` to `loop task`, default `subagent`. When appending `loop.task.viewed`, include `inputsSummary: JSON.stringify({ sourceRunId, desiredExecutor })`.
+
+- [ ] **Step 3: Update task output and verify**
+
+Add action commands to `buildAgentTaskBrief` JSON and Markdown. The start command must include `--trajectory`, `--from-run`, `--kind polish`, `--executor`, and `--summary`. The complete command example must include `--trajectory`, `--action <action-id>`, `--summary`, and `--files`.
+
+Run: `npm test -- src/core/agent-task-brief.test.ts src/commands/loop.test.ts`
+
+Expected: PASS.
+
+## Task 5: Show Actions in Ledger Exports
+
+**Files:**
+- Modify: `src/core/ledger-markdown.ts`
+- Test: `src/commands/ledger.test.ts`
+
+- [ ] **Step 1: Write failing Markdown export test**
+
+Create a fixture with one `loop.action.completed` event. Assert the markdown export contains:
+
+```md
+## Action History
+- act_
+  - status: completed
+  - executor: subagent
+  - from run: run_123
+  - summary: Resize dashboard preview
+```
+
+- [ ] **Step 2: Implement action formatting and verify**
+
+Parse `loop.action.*` events from `exported.events`, read `inputsSummary`, and render `## Action History` before artifact sections. If no actions exist, render `- None recorded`.
+
+Run: `npm test -- src/commands/ledger.test.ts`
+
+Expected: PASS.
+
+## Task 6: Document the Agent Workflow
+
+**Files:**
+- Modify: `README.md`
+- Modify: `docs/agent-workflow.md`
+- Modify: `skills/limner/SKILL.md`
+
+- [ ] **Step 1: Document the loop**
+
+Document:
+
+```text
+loop compare -> loop task --executor subagent -> loop action start -> edit -> loop action complete -> loop compare
+```
+
+Also document `loop action skip` for comparison-only smoke runs.
+
+- [ ] **Step 2: Update skill instructions and verify**
+
+In `skills/limner/SKILL.md`, instruct agents to prefer `limner loop task --executor subagent`, record `loop action start` before edits, record `loop action complete` after edits, record `loop action skip` when no edit is intended, and keep `--summary` under 255 characters.
+
+Run: `rg "loop action|--executor subagent|Action Logging" README.md docs/agent-workflow.md skills/limner/SKILL.md`
+
+Expected: each file has at least one matching workflow reference.
+
+## Task 7: Final Verification
+
+**Files:**
+- All files above
+
+- [ ] **Step 1: Run the aggregate gate**
+
+Run: `npm run check`
+
+Expected: lint, typecheck, Vitest, build, Knip, and file-size guard all pass.
+
+- [ ] **Step 2: Run a local smoke flow**
+
+Run:
+
+```bash
+npm run dev -- loop action start --trajectory <existing-test-trajectory> --from-run <validated-run-id> --kind polish --executor subagent --summary "Smoke action start"
+npm run dev -- loop action skip --trajectory <existing-test-trajectory> --from-run <validated-run-id> --summary "Smoke test only"
+npm run dev -- ledger export <existing-test-trajectory> --format markdown
+```
+
+Expected: export contains `## Action History` with both action records.
+
+- [ ] **Step 3: PR handoff notes**
+
+Include the top risks: wrong trajectory, executor intent recorded but external orchestrator did not use a subagent, and action completed without follow-up comparison. Include commands run, smoke trajectory ID, generated ledger excerpt, and the residual risk that Limner records action claims but cannot independently prove who edited files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neonwatty/limner",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Agent-guided visual fidelity workbench for turning images into HTML references and comparing references to real apps.",
   "type": "module",
   "bin": {