Output Formats

Dual-Mode Output

Flag	Format	Default when
--format text	Human-readable, colored	stdout is a TTY
--format json	Structured JSON	--format json explicitly
--json	Shorthand for --format json	—

Default is always text. The paper’s principle — “zero special agent support required” — is preserved. Agents that want structured output add --json.

Text Output Format

$ lore constraints src/auth/interceptor.ts

── a7f3b2c1 (2026-03-15, [email protected]) ──────────────
   Intent: Prevent silent session drops during long-running operations
   Constraint: Auth service does not support token introspection
   Constraint: Must not add latency to non-expired-token paths

── b3d4e5f6 (2026-02-10, [email protected]) ─────────────
   Intent: Add retry logic to auth interceptor
   Constraint: Max 3 retries per request (SLA requirement)

• Results sorted reverse-chronologically (newest first)
• Each atom delimited by a header showing Lore-id, date, author
• Only the requested trailer type shown (plus intent for context)

JSON Output Schema

{
  "lore_version": "1.0",
  "command": "constraints",
  "target": "src/auth/interceptor.ts",
  "target_type": "file",
  "meta": {
    "total_atoms": 2,
    "filtered_atoms": 0,
    "oldest": "2026-02-10T09:15:00Z",
    "newest": "2026-03-15T14:30:00Z"
  },
  "results": [
    {
      "lore_id": "a7f3b2c1",
      "commit": "abc123def456",
      "date": "2026-03-15T14:30:00Z",
      "author": "[email protected]",
      "intent": "Prevent silent session drops during long-running operations",
      "body": "",
      "trailers": {
        "lore_id": "a7f3b2c1",
        "constraint": [
          "Auth service does not support token introspection",
          "Must not add latency to non-expired-token paths"
        ]
      },
      "files_changed": ["src/auth/interceptor.ts"],
      "superseded": false,
      "superseded_by": null
    }
  ]
}

All trailer keys in JSON output use lowercase snake_case: constraint, rejected, confidence, scope_risk, reversibility, directive, tested, not_tested, supersedes, depends_on, related. The lore_id field appears both at the result level and inside trailers.

Pagination and Limiting

Changed in v0.3.0

--limit is now a post-filter result cap (previously it controlled git scan depth). New --max-commits flag added for explicit scan depth control.

--limit is a result cap applied after all filtering (including supersession). --max-commits controls how many git commits are scanned (performance tuning for large repos).

lore constraints src/auth/ --limit 10          # 10 active results
lore constraints src/auth/ --since 2026-01-01  # only since date
lore constraints src/auth/ --since v1.2        # only since tag/ref
lore constraints src/auth/ --max-commits 500   # scan at most 500 commits