@neonwatty/limner 0.1.5 → 0.1.7

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.5",
+  "version": "0.1.7",
   "description": "Agent-guided visual fidelity workbench for turning images into HTML references and comparing references to real apps.",
   "type": "module",
   "bin": {

package/skills/limner/SKILL.md

@@ -19,11 +19,22 @@ Use `limner loop` for Ralph Loop-style polishing across one or more trajectories
 2. Compare with `limner loop compare --trajectory <trajectory-id>`.
 3. Read the generated comparison prompt and response target.
 4. Write or validate the agent response.
-5. Check state with `limner loop status --trajectory <trajectory-id>`.
-6. Move to the next scoped fix with `limner loop next --trajectory <trajectory-id>`.
-7. Close with `limner loop close --trajectory <trajectory-id>`.
+5. After validation, prefer `limner loop task --trajectory <trajectory-id> --executor subagent`.
+6. Record `limner loop action start --trajectory <trajectory-id> --from-run <run-id> --kind polish --executor subagent --summary "<short edit intent>"` before edits.
+7. Make one scoped edit from the task brief.
+8. Record `limner loop action complete --trajectory <trajectory-id> --action <action-id> --executor subagent --summary "<what changed>" --files "<paths>"` after edits, then rerun `limner loop compare --trajectory <trajectory-id>`.
+9. For comparison-only smoke runs with no intended edit, record `limner loop action skip --trajectory <trajectory-id> --from-run <run-id> --summary "Comparison smoke only; no edit intended"`.
+10. Check state with `limner loop status --trajectory <trajectory-id>`.
+11. Move to the next scoped fix with `limner loop next --trajectory <trajectory-id>`.
+12. Close with `limner loop close --trajectory <trajectory-id>`.
 
-Every meaningful loop interaction writes a ledger event. Use `--feedback "<short note>"` for a 255-character `agentFeedback` note about improving the current process. Use `limner ledger export <trajectory-id> --format markdown` to hand a compact trajectory history to another agent.
+The intended edit loop is `loop compare -> loop task --executor subagent -> loop action start -> edit -> loop action complete -> loop compare`. Every meaningful loop interaction writes a ledger event. Agent responses are stored in local SQLite with the full JSON body, hash, validation status, and freshness, so cached reuse is visible. Keep every action `--summary` under 255 characters. Use `--feedback "<short note>"` for a 255-character `agentFeedback` note about improving the current process. Use `limner ledger export <trajectory-id> --format markdown` to hand a compact trajectory history to another agent.
+
+Use `limner loop task --trajectory <trajectory-id> --executor subagent --format json` when another tool needs machine-readable task data.
+
+Limner records executor intent and action claims; it cannot prove an external orchestrator actually used a subagent.
+
+Agents can discover the current command surface with `limner --help`, `limner loop --help`, `limner loop task --help`, and `limner ledger --help`.
 
 ## Image To Reference