@neonwatty/limner 0.1.7 → 0.1.9

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neonwatty/limner",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "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

@@ -17,24 +17,24 @@ Use `limner loop` for Ralph Loop-style polishing across one or more trajectories
 
 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.
+3. Read the generated comparison prompt.
+4. Submit the agent response with `limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json`.
 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>`.
+10. Check state with `limner loop status --trajectory <trajectory-id>` or `limner loop status --trajectory <trajectory-id> --format json`.
 11. Move to the next scoped fix with `limner loop next --trajectory <trajectory-id>`.
 12. Close with `limner loop close --trajectory <trajectory-id>`.
 
-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.
+The intended edit loop is `loop compare -> loop response submit -> loop task --executor subagent -> loop action start -> edit -> loop action complete -> loop compare`. Every meaningful loop interaction writes a ledger event. Agent responses are submitted to local SQLite with the full JSON body, hash, validation status, and freshness. 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.
+Use `limner loop task --trajectory <trajectory-id> --executor subagent --format json` when another tool needs machine-readable task data. The task is generated from the latest validated response stored in SQLite and includes a stable `comparisonSource`; do not depend on mutable files under `captures/**` as the source of truth.
 
 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`.
+Agents can discover the current command surface with `limner --help`, `limner loop --help`, `limner loop response --help`, `limner loop task --help`, and `limner ledger --help`.
 
 ## Image To Reference
 
@@ -44,32 +44,22 @@ Agents can discover the current command surface with `limner --help`, `limner lo
 4. Edit `reference/index.html` and `reference/styles.css`.
 5. Run `limner compare image-reference --target <name>`.
 6. Read `captures/image-reference/agent-comparison/agent-prompt.codex.md`.
-7. Write `captures/image-reference/agent-comparison/agent-response.json`.
-8. Rerun `limner compare image-reference --target <name>` so Limner validates `image-comparison.json` and `comparison-summary.json`.
+7. Submit JSON with `limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json`.
+8. Use the validated `image-comparison.json` and `comparison-summary.json`.
 9. Use the validated next-iteration guidance for one scoped mockup fix.
 
-Optional structured spec layer:
-
-- Run `limner compare image-reference --target <name> --spec`.
-- Edit `contract/visual-spec-instructions.md` to customize the agent prompt for this target, or pass `--spec-instructions <path>` for a shared policy file.
-- Use `captures/image-reference/spec/agent-prompt.codex.md` for Codex or `captures/image-reference/spec/agent-prompt.claude.md` for Claude.
-- Use the generated `captures/image-reference/spec/agent-response.schema.json` for strict structured output when the agent supports it.
-- The agent should inspect the ideal image and reference screenshot separately. The side-by-side is comparison context, not the image to parse.
-- Have the agent write `captures/image-reference/spec/agent-response.json`.
-- Rerun the same command so Limner can validate the response and emit the spec and diff JSON artifacts.
-
 ## Reference To Implementation
 
 1. Confirm the reference HTML is approved.
 2. Ensure every important region has both `referenceSelector` and an implementation selector in `appSelector`.
 3. Run `limner compare reference-implementation --target <name> --url <implementation-url>`.
 4. Read `captures/reference-implementation/agent-comparison/agent-prompt.codex.md`.
-5. Write `captures/reference-implementation/agent-comparison/agent-response.json`.
-6. Rerun the same command so Limner validates image, structure, and summary comparison artifacts.
+5. Submit JSON with `limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json`.
+6. Use the validated image, structure, and summary comparison artifacts.
 7. Use the validated next-iteration guidance for one scoped implementation fix.
 
 ## Constraints
 
-- Limner does not call an AI vision model itself. Agent comparison and the `--spec` workflow require an external agent.
+- Limner does not call an AI vision model itself. Agent comparison requires an external agent.
 - Limner does not make final pass/fail judgments.
 - Limner logs only local JSONL events under `.limner/runs/`.

package/templates/target/AGENT_GUIDE.md

@@ -11,8 +11,8 @@ Prompt profiles: `ideal-to-mockup` for Loop 1, and `mockup-to-implementation` fo
 3. Edit `reference/index.html` and `reference/styles.css` until the reference is a faithful HTML facsimile.
 4. Run `limner compare image-reference --target <target>`.
 5. Read `captures/image-reference/agent-comparison/agent-prompt.codex.md`.
-6. Write `captures/image-reference/agent-comparison/agent-response.json`.
-7. Rerun the comparison and use the validated next-iteration guidance for one scoped mockup fix.
+6. Submit JSON with `limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json`.
+7. Use the validated next-iteration guidance for one scoped mockup fix.
 
 ## Loop 2: Reference To Implementation
 
@@ -20,8 +20,8 @@ Prompt profiles: `ideal-to-mockup` for Loop 1, and `mockup-to-implementation` fo
 2. Add implementation selectors to `contract/regions.json` using `appSelector`.
 3. Run `limner compare reference-implementation --target <target> --url <implementation-url>`.
 4. Read `captures/reference-implementation/agent-comparison/agent-prompt.codex.md`.
-5. Write `captures/reference-implementation/agent-comparison/agent-response.json`.
-6. Rerun the comparison and use the validated next-iteration guidance for one scoped implementation fix.
+5. Submit JSON with `limner loop response submit --trajectory <trajectory-id> --from-run <run-id> --file ./response.json`.
+6. Use the validated next-iteration guidance for one scoped implementation fix.
 
 ## Rule