@neonwatty/limner 0.1.2 → 0.1.4

package/dist/schemas/ledger.js

@@ -0,0 +1,7 @@
+import { z } from 'zod';
+export const ledgerModeSchema = z.enum(['image-mockup', 'mockup-implementation', 'image-implementation']);
+export const trajectoryStatusSchema = z.enum(['active', 'closed']);
+export const iterationStatusSchema = z.enum(['active', 'closed']);
+export const ledgerEventActorSchema = z.enum(['user', 'agent', 'cli']);
+export const agentFeedbackSchema = z.string().max(255).optional();
+//# sourceMappingURL=ledger.js.map

package/dist/schemas/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../../src/schemas/ledger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,cAAc,EAAE,uBAAuB,EAAE,sBAAsB,CAAC,CAAC,CAAC;AAC1G,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AACnE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;AAClE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;AACvE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC"}

package/docs/agent-workflow.md

@@ -4,6 +4,24 @@ Limner is designed for agent-in-the-loop visual fidelity work.
 
 Prompt profiles: `ideal-to-mockup` for Phase 1, and `mockup-to-implementation` for Phase 2.
 
+Loop modes: `image-mockup`, `mockup-implementation`, and `image-implementation`.
+
+## Loop Ledger
+
+Use `limner loop` when a screen will need Ralph Loop-style iteration. Limner stores loop state and events in the global local-only ledger at `~/.limner/ledger.sqlite`.
+
+1. Start a trajectory with `limner loop start --mode <mode> --target <name> --name <human-name> --max-iterations <count>`.
+2. Run `limner loop compare --trajectory <trajectory-id>`.
+3. Read the generated agent comparison prompt and response target.
+4. Write or validate the agent response.
+5. Use `limner loop status --trajectory <trajectory-id>` to inspect current state.
+6. Use `limner loop next --trajectory <trajectory-id>` to begin the next scoped fix.
+7. Use `limner loop close --trajectory <trajectory-id>` when the trajectory is done.
+
+Every meaningful loop interaction writes a ledger event. Use `--feedback "<short note>"` on loop status for a 255-character `agentFeedback` note about improving the current process.
+
+Use `limner ledger export <trajectory-id> --format markdown` when an agent needs a compact case file for a trajectory.
+
 ## Phase 1: Image To Reference
 
 1. Run `limner init <image> --target <name>`.

package/docs/superpowers/plans/2026-06-12-global-loop-ledger.md

@@ -0,0 +1,160 @@
+# Global Loop 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 a global, local-only Limner loop ledger with trajectory-scoped Ralph Loop commands for `image-mockup`, `mockup-implementation`, and `image-implementation`.
+
+**Architecture:** Use `better-sqlite3` for `~/.limner/ledger.sqlite`, with a small storage layer under `src/core/ledger-*`. Add `limner loop` for trajectory lifecycle and `limner ledger` for query/export. Keep every meaningful interaction append-only in `ledger_events`, mirror current state in focused tables, and route all three comparison modes through loop adapters.
+
+**Tech Stack:** TypeScript, Commander, Zod, better-sqlite3, Vitest, Node 20+.
+
+---
+
+## File Map
+
+- Modify `package.json` and `package-lock.json` to add `better-sqlite3` and `@types/better-sqlite3`.
+- Create `src/schemas/ledger.ts` for modes, statuses, events, and input validation.
+- Create `src/core/ledger-paths.ts` for global home resolution and test overrides.
+- Create `src/core/ledger-db.ts` for SQLite opening, migrations, and transactions.
+- Create `src/core/ledger-store.ts` for trajectory, iteration, event, note, and export operations.
+- Create `src/core/ledger-store.test.ts` for storage behavior.
+- Create `src/core/loop-comparison-adapters.ts` for mode-specific compare execution.
+- Create `src/commands/loop.ts` and `src/commands/loop.test.ts`.
+- Create `src/commands/ledger.ts` and `src/commands/ledger.test.ts`.
+- Modify `src/cli.ts` and `src/index.ts` to register/export the new surfaces.
+- Modify `README.md`, `docs/agent-workflow.md`, and `skills/limner/SKILL.md`.
+
+---
+
+### Task 1: Add SQLite Dependency And Schemas
+
+**Files:** `package.json`, `package-lock.json`, `src/schemas/ledger.ts`, `src/index.ts`
+
+- [ ] Run `npm install better-sqlite3@12.10.0`.
+- [ ] Run `npm install -D @types/better-sqlite3@7.6.13`.
+- [ ] Create `src/schemas/ledger.ts` with:
+  - `ledgerModeSchema = z.enum(['image-mockup', 'mockup-implementation', 'image-implementation'])`
+  - `trajectoryStatusSchema = z.enum(['active', 'closed'])`
+  - `iterationStatusSchema = z.enum(['active', 'closed'])`
+  - `ledgerEventActorSchema = z.enum(['user', 'agent', 'cli'])`
+  - `agentFeedbackSchema = z.string().max(255).optional()`
+  - exported TypeScript types for each schema.
+- [ ] Export the new schemas/types from `src/index.ts`.
+- [ ] Run `npm run typecheck`; expect pass.
+
+### Task 2: Global Ledger Paths
+
+**Files:** `src/core/ledger-paths.ts`, `src/core/ledger-paths.test.ts`
+
+- [ ] Write tests for default home path and env override:
+  - default returns `<homedir>/.limner/ledger.sqlite`
+  - `LIMNER_LEDGER_HOME=/tmp/x` returns `/tmp/x/ledger.sqlite`
+  - snapshot dir resolves to `<home>/snapshots`
+- [ ] Implement `resolveLedgerHome(env = process.env)` and `resolveLedgerPaths(env = process.env)`.
+- [ ] Run `npm test -- src/core/ledger-paths.test.ts`; expect pass.
+
+### Task 3: SQLite Migrations
+
+**Files:** `src/core/ledger-db.ts`, `src/core/ledger-db.test.ts`
+
+- [ ] Write tests that opening a temp ledger creates tables:
+  - `trajectories`
+  - `iterations`
+  - `runs`
+  - `artifacts`
+  - `instruction_versions`
+  - `notes`
+  - `ledger_events`
+- [ ] Implement `openLedgerDatabase(paths)` using `better-sqlite3`.
+- [ ] Enable `PRAGMA foreign_keys = ON`.
+- [ ] Implement idempotent schema migrations with a `schema_meta` table and `schemaVersion = 1`.
+- [ ] Run `npm test -- src/core/ledger-db.test.ts`; expect pass.
+
+### Task 4: Ledger Store Core
+
+**Files:** `src/core/ledger-store.ts`, `src/core/ledger-store.test.ts`
+
+- [ ] Write tests for `startTrajectory`, `appendEvent`, `resolveTrajectory`, `advanceIteration`, `closeTrajectory`, and `exportTrajectoryJson`.
+- [ ] `startTrajectory` creates:
+  - `traj_<hash>` trajectory id
+  - `iter_001`
+  - `loop.started` event
+  - initial instruction version
+- [ ] `appendEvent` rejects `agentFeedback` longer than 255 chars.
+- [ ] `resolveTrajectory` returns one match or an ambiguity error with candidates.
+- [ ] `advanceIteration` closes the active iteration, creates the next `iter_NNN`, and writes `loop.next.started`.
+- [ ] `closeTrajectory` closes trajectory plus active iteration and writes `loop.iteration.closed`.
+- [ ] `exportTrajectoryJson` returns trajectory, iterations, events, notes, and artifacts.
+- [ ] Run `npm test -- src/core/ledger-store.test.ts`; expect pass.
+
+### Task 5: Loop CLI
+
+**Files:** `src/commands/loop.ts`, `src/commands/loop.test.ts`, `src/cli.ts`
+
+- [ ] Write CLI tests with `LIMNER_LEDGER_HOME` pointing at a temp dir.
+- [ ] Test `loop start --mode image-mockup --target checkout --name checkout-mobile --max-iterations 5` prints `Trajectory: traj_`.
+- [ ] Test implementation modes accept `--url`, `--storage-state`, and `--full-page` and store them in trajectory instructions/context.
+- [ ] Test `loop status --trajectory <id>` prints mode, status, active iteration, iteration count, and max.
+- [ ] Test `loop next --trajectory <id>` advances from `iter_001` to `iter_002`.
+- [ ] Test `loop close --trajectory <id>` closes the trajectory.
+- [ ] Test `--feedback` records short agent feedback and rejects overlong feedback.
+- [ ] Register `limner loop` in `src/cli.ts`.
+- [ ] Run `npm test -- src/commands/loop.test.ts`; expect pass.
+
+### Task 6: Loop Compare Adapter
+
+**Files:** `src/commands/loop.ts`, `src/core/loop-comparison-adapters.ts`, `src/core/ledger-store.ts`, `src/commands/loop.test.ts`
+
+- [ ] Add `loop compare --trajectory <id>` with ledger events before and after command execution.
+- [ ] Implement first-class adapters:
+  - `image-mockup` to `compareImageReference`
+  - `mockup-implementation` to `compareReferenceImplementation`
+  - `image-implementation` to source image versus implementation URL capture, with source image as expected and implementation screenshot as actual
+- [ ] For `image-implementation`, require a stored or supplied implementation URL and write the same agent-comparison pack shape as other image comparisons.
+- [ ] Write `loop.compare.started`, `loop.compare.awaiting_agent`, `loop.compare.validated`, or `loop.compare.failed`.
+- [ ] Snapshot compact artifacts: prompts, agent response, summaries, reports, and compact JSON metadata.
+- [ ] Run `npm test -- src/commands/loop.test.ts && npm run typecheck`; expect pass.
+
+### Task 7: Ledger CLI
+
+**Files:** `src/commands/ledger.ts`, `src/commands/ledger.test.ts`, `src/cli.ts`
+
+- [ ] Write tests for:
+  - `ledger list --active`
+  - `ledger list --mode image-implementation`
+  - `ledger status --trajectory <id>`
+  - `ledger show <id>`
+  - `ledger next --trajectory <id>`
+  - `ledger export <id> --format json`
+  - `ledger export <id> --format markdown`
+- [ ] Implement concise terminal output for agents.
+- [ ] Register `limner ledger` in `src/cli.ts`.
+- [ ] Run `npm test -- src/commands/ledger.test.ts`; expect pass.
+
+### Task 8: Docs And Skills
+
+**Files:** `README.md`, `docs/agent-workflow.md`, `skills/limner/SKILL.md`
+
+- [ ] Document global local-only ledger storage at `~/.limner/ledger.sqlite`.
+- [ ] Document the three modes: `image-mockup`, `mockup-implementation`, `image-implementation`.
+- [ ] Document `loop start`, `loop compare`, `loop status`, `loop next`, and `loop close`.
+- [ ] Document `agentFeedback` as a 255-character process-improvement field.
+- [ ] Run `rg -n "image-mockup|mockup-implementation|image-implementation|agentFeedback|ledger.sqlite" README.md docs/agent-workflow.md skills/limner/SKILL.md`; expect all files to mention the workflow.
+
+### Task 9: Full Verification
+
+**Files:** no edits
+
+- [ ] Run `npm test`; expect pass.
+- [ ] Run `npm run typecheck`; expect pass.
+- [ ] Run `npm run check:size`; expect pass.
+- [ ] Run `npm run build`; expect pass.
+- [ ] Run `npm run check`; expect pass.
+- [ ] Smoke `npm run dev -- loop --help`; expect loop commands.
+- [ ] Smoke `npm run dev -- ledger --help`; expect ledger commands.
+
+## Self-Review
+
+- Spec coverage: Covers global SQLite storage, trajectory-scoped commands, all three modes, event logging for every interaction, 255-character `agentFeedback`, snapshots, exports, max iteration state, ambiguity handling, and tests.
+- Placeholder scan: No TODO/TBD placeholders remain.
+- Type consistency: Uses `trajectoryId`, `iterationId`, `agentFeedback`, `image-mockup`, `mockup-implementation`, and `image-implementation` consistently.

package/docs/superpowers/specs/2026-06-12-global-loop-ledger-design.md

@@ -0,0 +1,254 @@
+# Global Loop Ledger Design
+
+## Goal
+
+Add a global, local-only Limner ledger for dogfooding visual fidelity loops across multiple projects at once. The ledger should help agents and package maintainers understand what was compared, which trajectory it belonged to, what iteration was active, what artifacts were produced, what failed, what the agent recommended, and what the agent noticed about improving Limner itself.
+
+This builds on `docs/superpowers/plans/2026-06-12-agent-comparison-scores.md`, which replaces artifact-only comparisons with agent-authored comparison artifacts. This design turns those artifacts into durable Ralph Loop-style trajectories.
+
+## Decisions
+
+- The ledger is global-first and local-only.
+- Primary storage is SQLite at `~/.limner/ledger.sqlite`.
+- Limner sends no telemetry.
+- Project artifacts stay in their original workspaces by default.
+- The ledger stores artifact paths and hashes, then snapshots compact agent-readable files.
+- Full screenshots are referenced in-place by default; a later pinning feature can copy selected images into `~/.limner`.
+- Every meaningful loop interaction writes a ledger event, including failures, status views, exports, and ambiguous command resolution.
+- Loop commands are trajectory-scoped. There is no project-wide current trajectory because multiple Codex sessions may polish multiple screens in the same project concurrently.
+- `loop compare` is the blessed path for active loop work.
+
+## Modes
+
+The loop layer uses the future comparison vocabulary:
+
+- `image-mockup`: source image to editable HTML mockup.
+- `mockup-implementation`: approved mockup to real implementation.
+- `image-implementation`: source image directly to real implementation.
+
+Temporary mappings to older internal compare commands may exist during migration, but those names should not appear in the loop UX.
+
+## Identity Model
+
+The ledger separates trajectories, iterations, and command executions.
+
+```text
+trajectory
+  trajectoryId: traj_...
+  humanId/name: checkout-mobile-polish
+  mode: image-mockup | mockup-implementation | image-implementation
+  projectRoot, workspaceRoot, target
+  source/artifact fingerprints
+  status, maxIterations
+  current instructions
+
+iteration
+  iterationId: iter_001
+  trajectoryId
+  focus
+  effective instruction snapshot
+  status
+
+run
+  runId
+  trajectoryId, iterationId
+  command
+  timestamps
+  result status
+  artifacts
+```
+
+Trajectory IDs are stable machine IDs. Human names make work readable. Iteration IDs are scoped to a trajectory. Run IDs describe individual CLI executions and may map to the existing Limner run logger.
+
+## CLI Shape
+
+Primary loop commands:
+
+```bash
+limner loop start --mode image-mockup --target checkout --name checkout-mobile-polish --max-iterations 5
+limner loop compare --trajectory traj_abc123
+limner loop status --trajectory traj_abc123
+limner loop next --trajectory traj_abc123
+limner loop close --trajectory traj_abc123
+```
+
+Trajectory resolution may accept explicit context:
+
+```bash
+limner loop status --target checkout --mode image-mockup
+```
+
+If more than one active trajectory matches, Limner refuses to guess, records a ledger event, and lists candidate trajectories.
+
+Ledger commands are query/export tools:
+
+```bash
+limner ledger list --active
+limner ledger list --project /path/to/app
+limner ledger list --mode image-implementation
+limner ledger status --trajectory traj_abc123
+limner ledger show traj_abc123
+limner ledger next --trajectory traj_abc123
+limner ledger export traj_abc123 --format markdown
+limner ledger export traj_abc123 --format json
+```
+
+## Mode Skills
+
+Limner should grow a plugin with three mode-specific skills backed by the same loop and ledger engine:
+
+```text
+limner-image-mockup-loop
+limner-mockup-implementation-loop
+limner-image-implementation-loop
+```
+
+Each skill shares the same state ritual: inspect the trajectory, run `limner loop compare`, read the agent comparison output, make one scoped fix, record feedback or notes, and advance or close the iteration.
+
+The skills differ by editable surface and inspection rules:
+
+- `image-mockup` edits `targets/<target>/reference/` and treats the source image as canonical.
+- `mockup-implementation` edits real app source, uses the approved mockup as canonical, and needs implementation URL/auth/framework/test guidance.
+- `image-implementation` edits real app source and treats the source image as canonical. Because there is no approved mockup bridge, it should call out ambiguity between product interpretation and implementation drift.
+
+## Instructions
+
+The ledger stores effective trajectory instructions. Skills provide defaults, but each trajectory records the actual edit and inspection instructions for the current work.
+
+Instruction changes are mutable but versioned. Each iteration snapshots the effective instructions so future agents can see which rules were active for each pass.
+
+Examples:
+
+```text
+editInstructions
+  Only edit targets/<target>/reference/index.html.
+  Only edit targets/<target>/reference/styles.css.
+  Do not change the source image unless explicitly asked.
+
+inspectInstructions
+  Read comparison-summary.json before editing.
+  Treat agent-response.json as the current critique.
+  Make one scoped fix per iteration.
+```
+
+For implementation modes, instructions may include app source paths, test commands, framework constraints, implementation URL, storage state path, or auth requirements.
+
+## Ledger Data
+
+The ledger uses state tables for query speed and an append-only event stream for debugging and product improvement.
+
+Core entities:
+
+```text
+trajectories
+iterations
+runs
+artifacts
+instruction_versions
+notes
+events
+```
+
+Useful derived fields:
+
+```text
+lastScore
+lastConfidence
+activeIterationId
+iterationCount
+maxIterations
+lastMajorDiffAreas
+nextRecommendedFix
+lastAgentStatus
+```
+
+The event stream is the source of behavioral insight. State tables are current mirrors or indexes.
+
+## Event Logging
+
+Every meaningful loop interaction writes a ledger event, even when it does not change state.
+
+Example event types:
+
+```text
+loop.started
+loop.status.viewed
+loop.compare.started
+loop.compare.awaiting_agent
+loop.compare.validated
+loop.compare.failed
+loop.compare.invalid_agent_response
+loop.next.started
+loop.iteration.closed
+loop.instructions.updated
+loop.max_iterations.changed
+loop.max_iterations.reached
+loop.resolution_ambiguous
+loop.note.added
+ledger.exported
+```
+
+Each event should include:
+
+```text
+eventId
+timestamp
+trajectoryId
+iterationId?
+runId?
+command
+eventType
+actor: user | agent | cli
+inputsSummary
+resultStatus
+artifactRefs
+agentFeedback?
+notes?
+```
+
+`agentFeedback` is an optional short text field for feedback on the current process or possible Limner improvements. It is capped at 255 characters. Longer commentary belongs in a note linked to the same trajectory, iteration, or event.
+
+## Snapshots
+
+The ledger references original artifacts by absolute path and hash. It also snapshots compact agent-readable files under `~/.limner/snapshots/`.
+
+```text
+~/.limner/
+  ledger.sqlite
+  snapshots/
+    traj_.../
+      iter_001/
+        comparison-summary.json
+        agent-response.json
+        agent-prompt.codex.md
+        report.md
+        notes.md
+```
+
+Snapshot selection should prefer agent prompts, agent responses, comparison summaries, reports, notes, and compact JSON metadata. Full screenshots remain in their source workspace by default.
+
+## Max Iterations
+
+Max iteration count is trajectory state in the ledger. When a trajectory reaches its max, Limner writes `loop.max_iterations.reached`, warns by default, and allows intentional continuation. A strict hard-stop mode can be added later for scripted workflows.
+
+## Error Handling
+
+Errors and refusals are ledgered:
+
+- ambiguous trajectory resolution writes `loop.resolution_ambiguous`;
+- missing artifacts write `loop.compare.failed` with path/hash context;
+- invalid agent responses write `loop.compare.invalid_agent_response` with schema errors and response path;
+- instruction updates write `loop.instructions.updated` and snapshot the new instruction version;
+- exports write `ledger.exported`.
+
+## Testing And Handoff
+
+Use a temporary global ledger path in tests so the real `~/.limner` is never touched. Unit tests should cover trajectory ID generation, trajectory resolution, event append, the 255-character `agentFeedback` limit, instruction versioning, and snapshot selection.
+
+CLI tests should cover `loop start`, `compare`, `status`, `next`, and `close`; ambiguous resolution; max iteration warnings; all three modes; and feedback recorded on loop events. Integration-style tests should cover invalid agent responses, markdown export, and JSON export. Exports must include current state, latest diffs, notes, artifacts, feedback, and event timeline.
+
+The repository quality gate remains `npm run check`.
+
+Top realistic failure modes are agents forgetting `--trajectory`, event streams becoming noisy, and mode-specific skills drifting from the shared loop engine.
+
+Negative cases to preserve are ambiguous trajectory selection, missing artifacts, invalid or schema-invalid agent responses, max iterations reached, overlong `agentFeedback`, and multiple active trajectories for the same project.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neonwatty/limner",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Agent-guided visual fidelity workbench for turning images into HTML references and comparing references to real apps.",
   "type": "module",
   "bin": {
@@ -45,6 +45,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "better-sqlite3": "^12.10.0",
     "commander": "^15.0.0",
     "playwright": "^1.57.0",
     "sharp": "^0.34.5",
@@ -52,6 +53,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/node": "^25.0.0",
     "eslint": "^10.4.1",
     "knip": "^6.16.1",

package/skills/limner/SKILL.md

@@ -9,6 +9,22 @@ Use Limner for structured visual fidelity loops.
 
 Prompt profiles: `ideal-to-mockup` for Image To Reference, and `mockup-to-implementation` for Reference To Implementation.
 
+Loop modes: `image-mockup`, `mockup-implementation`, and `image-implementation`.
+
+## Loop Ledger
+
+Use `limner loop` for Ralph Loop-style polishing across one or more trajectories. Limner stores loop state and events in a global local-only SQLite ledger at `~/.limner/ledger.sqlite`; it does not send telemetry.
+
+1. Start with `limner loop start --mode <mode> --target <name> --name <human-name> --max-iterations <count>`.
+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>`.
+
+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.
+
 ## Image To Reference
 
 1. Run `limner init <image> --target <name>` if the target does not exist.