simplify-code/assets/ledger.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/simplify-code/ledger.schema.json",
  "title": "simplify-code ledger (findings.json)",
  "description": "One file holding the inferred project commands (config) and the ranked, resumable list of simplification findings. Written by the assembly step (SKILL.md Step 3) and updated as fixes are applied.",
  "type": "object",
  "required": ["config", "findings"],
  "properties": {
    "config": {
      "type": "object",
      "description": "Project build/test/lint/format commands, inferred ONCE by the model and cached. Re-inferred only if missing or the manifest changed.",
      "properties": {
        "build":   { "type": ["string", "null"] },
        "test":    { "type": ["string", "null"] },
        "lint":    { "type": ["string", "null"] },
        "format":  { "type": ["string", "null"] },
        "detected_from": { "type": "string", "description": "e.g. package.json | pyproject.toml | go.mod | Cargo.toml | pom.xml | Makefile" },
        "runtime": { "type": "string", "description": "node | python | go | rust | java | ..." },
        "include_tests": { "type": "boolean", "description": "false by default — test files are excluded from scope unless the user opted in" },
        "passes": { "type": "array", "items": { "enum": ["A", "B"] }, "description": "which passes ran: A=structural, B=consolidation/anti-pattern" },
        "inferred_at": { "type": "string", "description": "commit hash or marker used to detect manifest changes" }
      }
    },
    "engine": {
      "type": "object",
      "description": "Which detection engine produced the findings, for reproducibility.",
      "properties": {
        "ast_grep_version": { "type": "string" },
        "binary": { "type": "string", "description": "bundled <os>-<arch> | PATH | none(llm-fallback)" },
        "enrichment": { "type": "array", "items": { "type": "string" }, "description": "optional tools used, e.g. scc, knip, svelte-check" }
      }
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "kind", "detector", "title", "members", "severity", "confidence", "action", "verify", "status"],
        "properties": {
          "id": { "type": "string", "description": "stable id, e.g. c01 / f0001" },
          "kind": { "enum": ["structural", "lint", "metric", "consolidation"], "description": "structural=Pass A rule; lint=Biome/ruff; metric=scc/derived; consolidation=Pass B" },
          "title": { "type": "string", "description": "REQUIRED: one-line summary of the finding (what + where, human-scannable)" },
          "action": { "type": "string", "description": "REQUIRED: the concrete, executable change the agent should make (not a vague suggestion). The skill itself never performs it." },
          "verify": { "type": "string", "description": "REQUIRED: command(s) to confirm the change after the agent applies it (usually config.build/test/typecheck)" },
          "verdict": { "enum": ["consolidate", "partial", "keep-separate"], "description": "Pass B (consolidation) only: the judge's verdict" },
          "members": { "type": "array", "items": { "type": "object", "properties": { "file": {"type": "string"}, "line": {"type": "integer"} } }, "description": "Pass B only: the cluster's member locations" },
          "recommendation": { "type": "string", "description": "Pass B only: the concrete suggested change (never auto-applied)" },
          "file": { "type": "string" },
          "start_line": { "type": "integer", "minimum": 1 },
          "end_line": { "type": "integer", "minimum": 1 },
          "lang": { "type": "string" },
          "detector": { "type": "string", "description": "ast-grep ruleId, or enrichment tool id (svelte-check, scc, ...)" },
          "suggested_pattern": { "type": "string", "description": "catalog key from references/PATTERNS.md" },
          "signal": {
            "type": "object",
            "description": "metric values backing the finding (any subset)",
            "properties": {
              "cyclomatic": { "type": "number" },
              "lines": { "type": "number" },
              "nesting": { "type": "number" },
              "params": { "type": "number" },
              "dup_blocks": { "type": "number" }
            }
          },
          "fix_kind": { "enum": ["deterministic", "edit", "manual"], "description": "informational only (skill never applies): deterministic=an ast-grep autofix command exists; edit=a span edit the agent makes; manual=needs human judgment" },
          "difficulty": { "enum": ["mechanical", "semantic", "hard"] },
          "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
          "severity": { "type": "number", "minimum": 0, "maximum": 100, "description": "ranking score; biggest-win-first" },
          "status": { "enum": ["pending", "applied", "skipped"], "description": "pending initially; the ACTING agent updates it after acting (not this skill)" },
          "notes": { "type": "string" }
        }
      }
    }
  },
  "examples": [
    {
      "config": {
        "build": "pnpm -r build", "test": "vitest run", "lint": null, "typecheck": "pnpm -r typecheck",
        "format": null, "detected_from": "package.json", "runtime": "node",
        "include_tests": false, "passes": ["A", "B"]
      },
      "engine": { "ast_grep": "0.44.0", "cpd": "5.0.11", "scc": "3.7.0", "biome": "2.5.0", "binary": "linux-x64" },
      "summary": { "passA_structural": 180, "passB_consolidation": 9, "lint": 149, "kept_separate": 3 },
      "findings": [
        {
          "id": "c01", "kind": "consolidation", "detector": "dup-function", "verdict": "consolidate",
          "title": "Response helpers jsonErr()/json() copy-pasted across 21+ SvelteKit routes",
          "members": [
            { "file": "dashboard/src/routes/api/projects/+server.ts", "line": 6 },
            { "file": "dashboard/src/routes/api/stories/[id]/abandon/+server.ts", "line": 6 }
          ],
          "fix_kind": "edit", "difficulty": "semantic", "confidence": 0.95, "severity": 80,
          "action": "Create dashboard/src/lib/response.ts exporting json(data,status=200) and jsonErr(status,error)=json({error},status); replace the ~29 local definitions with `import { json, jsonErr } from \"$lib/response\"`.",
          "verify": "pnpm -r typecheck && vitest run",
          "status": "pending"
        },
        {
          "id": "f0002", "kind": "structural", "detector": "ts-deep-nesting",
          "title": "Deeply nested conditional in dispatch.ts — guard clauses",
          "members": [ { "file": "core/orchestrator/src/dispatch.ts", "line": 222 } ],
          "signal": { "nesting": 3 }, "fix_kind": "edit", "difficulty": "semantic",
          "confidence": 0.7, "severity": 22,
          "action": "Flatten with early returns (see references/PATTERNS.md → guard-clauses); read lines 218-236 and invert the outer conditions.",
          "verify": "pnpm -r typecheck && vitest run",
          "status": "pending"
        }
      ],
      "kept_separate": [
        { "detector": "dup-function", "title": "dead-letter.ts vs run-monitor.ts", "why": "Same skeleton, different concerns (Redis delivery-count vs DB elapsed-time); not duplication." }
      ]
    }
  ]
}