@albinocrabs/feynman 0.2.0 → 0.2.2

package/docs/lint-rules.md

@@ -0,0 +1,317 @@
+# Lint Rules Reference
+
+feynman includes a linter for ASCII diagrams in markdown files.
+Eight rules (L01-L08) enforce structural correctness.
+
+Run: `npx @albinocrabs/feynman lint <file.md>` or `feynman lint <file.md>`
+
+---
+
+## L01: Box Closure (severity: error)
+
+**What:** Every `┌` corner must have a matching `└` at the same column position;
+every `┐` must have a matching `┘` at the same column.
+
+**Why:** An unclosed frame box is visually deceptive — it implies containment
+it doesn't deliver, and the unclosed edge is often invisible at a glance.
+
+**Source:** [`lib/lint/rules.js#L66`](../lib/lint/rules.js)
+
+### Valid
+
+```
+┌─ Status ──────┐
+│  item-a  done │
+│  item-b  wait │
+└───────────────┘
+```
+
+### Invalid
+
+```text
+┌─ Status ─────────────┐
+│  item-a    done       │
+│  item-b    in progress│
+```
+
+Output:
+```text
+file:2:1: L01 Unclosed box: '┌' at line 2, col 1 has no matching '└' at same column
+```
+
+---
+
+## L02: Tree Chars (severity: error)
+
+**What:** The last child in each group of siblings must use `└──`, not `├──`.
+
+**Why:** `├──` means "more siblings follow"; `└──` means "last child." Using
+`├──` for the last item misleads the reader about the list's structure.
+
+**Source:** [`lib/lint/rules.js#L156`](../lib/lint/rules.js)
+
+### Valid
+
+```
+project
+├── src
+│   ├── components
+│   └── utils
+└── package.json
+```
+
+### Invalid
+
+```text
+project
+├── src
+│   ├── components
+│   ├── utils
+├── tests
+├── package.json
+```
+
+Output:
+```text
+file:6:1: L02 Last tree child uses '├──' but should use '└──'
+```
+
+---
+
+## L03: Arrow Style (severity: error)
+
+**What:** Only one arrow style is allowed per diagram.
+
+Recognized styles:
+
+```text
+→
+-->
+─→
+──>
+```
+
+**Why:** Mixed arrow styles force the reader to verify that the styles are
+equivalent rather than distinct, adding cognitive overhead without information.
+
+**Source:** [`lib/lint/rules.js#L227`](../lib/lint/rules.js)
+
+### Valid
+
+```
+[Step A] --> [Step B] --> [Step C]
+```
+
+### Invalid
+
+```text
+[Step A] --> [Step B] → [Step C] --> [Step D]
+```
+
+Output:
+```text
+file:1:1: L03 Mixed arrow styles: diagram uses '-->' and '→' — pick one style
+```
+
+---
+
+## L04: Column Widths (severity: error)
+
+**What:** All rows in a markdown table must have the same column count.
+The separator row (`|---|---|`) must match the header column count.
+
+**Why:** Mismatched column counts break the visual grid — the reader must
+count pipes instead of reading structure.
+
+**Source:** [`lib/lint/rules.js#L272`](../lib/lint/rules.js)
+
+### Valid
+
+```
+Option A    | Option B    | Option C
+------------|-------------|----------
+fast        | slow        | medium
+stateless   | persistent  | persistent
+```
+
+### Invalid
+
+```text
+Option A    | Option B
+------------|-------------|----------
+fast        | slow        | medium
+```
+
+Output:
+```text
+file:2:1: L04 Table separator has 3 columns but header has 2 columns
+```
+
+---
+
+## L05: Flow Integrity (severity: error)
+
+**What:** When two or more `[Box]` tokens appear on the same line, an arrow
+must exist between each consecutive pair.
+
+**Why:** Adjacent boxes without arrows are ambiguous — are they sequential
+steps, parallel options, or unrelated elements? An arrow makes the
+relationship explicit.
+
+**Source:** [`lib/lint/rules.js#L349`](../lib/lint/rules.js)
+
+Note: boxes separated by three or more spaces are treated as parallel layout
+(e.g. side-by-side comparison columns) and do not require an arrow.
+
+### Valid
+
+```
+[Auth] --> [Handler] --> [Response]
+```
+
+### Invalid
+
+```text
+[Auth] [Handler] [Response]
+```
+
+Output:
+```text
+file:1:1: L05 3 boxes on same line with no arrow between them: [Auth], [Handler], [Response]
+```
+
+---
+
+## L06: Priority Scale (severity: warn)
+
+**What:** When `▲` appears in a diagram, `▼` must also appear, and vice versa.
+
+**Why:** A priority scale with only one end is not a scale — the reader
+cannot determine whether the listed items are near the top or bottom of
+the full range.
+
+**Source:** [`lib/lint/rules.js#L399`](../lib/lint/rules.js)
+
+### Valid
+
+```
+▲ high
+  critical-bug
+  security-patch
+▼ low
+  cosmetic-fix
+```
+
+### Invalid
+
+```text
+▲ high
+  critical-bug
+  security-patch
+  performance-fix
+```
+
+Output:
+```text
+file:1:1: L06 Priority scale has '▲' but missing '▼' — scales require both ends
+```
+
+---
+
+## L07: No Mermaid + ASCII Mix (severity: warn)
+
+**What:** A document must not contain both a Mermaid fenced block and ASCII
+diagram characters such as box corners, arrows, or tree branches.
+
+**Why:** Mixing two diagram encoding systems forces the reader to context-switch
+between visual vocabularies. It also signals that the response lacks a coherent
+visual strategy.
+
+**Source:** [`lib/lint/rules.js#L441`](../lib/lint/rules.js)
+
+### Valid
+
+A file with only ASCII diagrams:
+
+```
+[A] --> [B] --> [C]
+```
+
+### Invalid
+
+A file with both a Mermaid block and ASCII art (shown as `text` fences to
+avoid triggering the rule):
+
+```text
+[A] --> [B]
+
+` ``mermaid
+graph TD
+  A --> B
+` ``
+```
+
+Output:
+```text
+file:4:1: L07 Response mixes Mermaid (line 4) and ASCII diagrams — use one format only
+```
+
+---
+
+## L08: Frame Width Discipline (severity: error)
+
+**What:** All rows inside a `┌─ … ─┐` frame block must have the same
+display width (measured in terminal columns).
+
+**Why:** Ragged right edges in a frame add visual noise without information.
+Consistent width makes the frame a clean visual container.
+
+**Source:** [`lib/lint/rules.js#L476`](../lib/lint/rules.js)
+
+Display width counts each Unicode character as 1 column (box-drawing
+characters, Latin, and Cyrillic are single-width; CJK characters are
+double-width).
+
+### Valid
+
+```
+┌─ Status ──────┐
+│  item-a  done │
+│  item-b  wait │
+│  item-c  ok   │
+└───────────────┘
+```
+
+### Invalid
+
+```text
+┌─ Status ─────┐
+│  item-a done │
+│  item-b in progress - this line is much wider than the frame header
+└─────────────────────────────┘
+```
+
+Output:
+```text
+file:3:1: L08 Frame row width 68 differs from frame header width 16 (line 1)
+```
+
+---
+
+## `language: text` Convention
+
+To include intentionally-invalid diagram examples in documentation (as this
+file does), wrap them in fences with the `text` language tag:
+
+````markdown
+```text
+[A] [B]    ← no arrow — intentionally invalid for L05
+```
+````
+
+The parser recognizes fenced code blocks but only lints blocks with no
+language tag or with diagram-relevant languages. Blocks tagged `text` are
+skipped.
+
+This is the recommended way to document "bad" examples without causing
+lint failures in your documentation files.

package/docs/self-improvement.md

@@ -0,0 +1,281 @@
+# Self-Improvement Loop Design
+
+This document designs a future feedback loop for feynman rules. It is a
+research spec only. Implementation is deferred to v0.3.0 under BENCH-V3-02.
+
+The goal is not automatic rule rewriting. The goal is a reviewable trail from
+lint failures to human-approved rule changes.
+
+---
+
+## Scope
+
+In scope:
+
+- Failure log schema for `feynman-lint`
+- Aggregation step for recurring failures
+- Rule-update proposal format
+- Human review gate
+- Rollout cadence
+- Kill-switch
+- Open questions for v0.3.0
+
+Out of scope:
+
+- Automatic edits to `rules/feynman-activate.md`
+- Telemetry upload or remote collection
+- Background daemon
+- Model-generated pull requests
+- Per-user analytics dashboard
+
+---
+
+## Loop Overview
+
+```
+[Claude response] --> [feynman-lint]
+                          |
+                     pass + fail
+                     |        |
+                     v        v
+                  [silent]    [local failure log]
+                               |
+                               v
+                         [aggregate patterns]
+                               |
+                               v
+                         [proposal file]
+                               |
+                               v
+                         [human review]
+                               |
+                       accept + reject
+                       |        |
+                       v        v
+                [rule PR]   [archive reason]
+```
+
+The loop stays local-first. A user can inspect every captured failure before
+anything affects rules.
+
+---
+
+## Failure Log Schema
+
+Each failed lint run writes one JSONL row. The path is proposed for v0.3.0:
+`~/.claude/.feynman/failures.jsonl`.
+
+```json
+{
+  "schema": 1,
+  "timestamp": "2026-05-06T21:10:00Z",
+  "feynmanVersion": "0.2.0",
+  "source": "stop-hook",
+  "rulesetIntensity": "full",
+  "documentHash": "sha256:...",
+  "issues": [
+    {
+      "rule": "L05",
+      "severity": "error",
+      "line": 12,
+      "column": 1,
+      "message": "2 boxes on same line with no arrow between them",
+      "diagramShape": "flow",
+      "snippetHash": "sha256:..."
+    }
+  ],
+  "context": {
+    "fileKind": "response",
+    "hasCodeFence": true,
+    "diagramChars": 42,
+    "lineCount": 9
+  }
+}
+```
+
+Privacy rule: raw response text is not logged by default. Hashes and structural
+metadata are enough to find repeated failure patterns without storing content.
+
+Optional debug mode can store redacted snippets, but only behind an explicit
+local config flag.
+
+---
+
+## Aggregation Step
+
+Aggregation groups failures by rule, diagram shape, and structural signature.
+It runs manually, not in the hook path.
+
+```
+[failures.jsonl]
+        |
+        v
+[group by rule + shape + signature]
+        |
+        v
+[rank by frequency + recency + severity]
+        |
+        v
+[candidate patterns]
+```
+
+Candidate score:
+
+```text
+score = (error_count * 3) + warn_count + recent_count - ignored_count
+```
+
+Aggregation output is a local markdown report:
+`~/.claude/.feynman/proposals/YYYY-MM.md`.
+
+---
+
+## Rule-Update Proposal Format
+
+Each proposal must be small enough for review in one PR.
+
+```markdown
+# Proposal: tighten L05 flow spacing guidance
+
+## Trigger
+
+- Rule: L05
+- Pattern: parallel boxes with one or two spaces
+- Count: 18 failures in 30 days
+
+## Evidence
+
+- Structural signature: multibox_same_line_no_arrow
+- Common shape: branch output rows
+- Existing docs affected: examples/api-flow.md, examples/deploy-pipeline.md
+
+## Proposed Rule Change
+
+Change prose in `rules/feynman-activate.md` to state that side-by-side
+parallel boxes use three or more spaces.
+
+## Test Plan
+
+- Add one valid fixture for parallel layout
+- Add one invalid fixture for adjacent boxes
+- Run `npm test`
+- Run `feynman-lint` over docs/examples
+
+## Rollout
+
+- Merge behind normal release process
+- Mention in changelog
+- No runtime migration
+```
+
+Proposal files are advisory. They do not modify rules by themselves.
+
+---
+
+## Human Review Gate
+
+Every proposal goes through a maintainer decision.
+
+```
+[proposal]
+     |
+     v
+[maintainer review]
+     |
+     +--> [accept] --> [normal PR]
+     |
+     +--> [revise] --> [proposal update]
+     |
+     +--> [reject] --> [archive with reason]
+```
+
+Review checklist:
+
+- Does the failure repeat across multiple prompts or files?
+- Is the current rule actually wrong, or is the diagram wrong?
+- Would the rule change increase unwanted diagrams?
+- Does it preserve declarative phrasing?
+- Does it keep the rule block under the size cap?
+- Does it add or update golden tests?
+
+No proposal is accepted without tests and docs/examples self-lint.
+
+---
+
+## Rollout Cadence
+
+Recommended cadence for v0.3.0:
+
+```text
+weekly    collect local failures, no action
+monthly   generate proposal report
+release   merge accepted rule changes
+hotfix    only for false positives that block normal use
+```
+
+Rule changes should batch by release unless a linter bug causes high-noise
+false positives.
+
+---
+
+## Kill-Switch
+
+The loop needs a hard local off switch before implementation.
+
+Proposed config:
+
+```json
+{
+  "selfImprovement": {
+    "enabled": false,
+    "logFailures": false,
+    "storeSnippets": false,
+    "proposalCadence": "manual"
+  }
+}
+```
+
+Default is off. If enabled, logging remains local. If disabled, the Stop hook
+does not write failure logs.
+
+Emergency behavior:
+
+```
+[selfImprovement.enabled=false] --> [no logs]
+[logFailures=false]             --> [no logs]
+[corrupt config]                --> [fail closed: no logs]
+[write error]                   --> [silent; never block Claude]
+```
+
+The hook must never fail a user prompt because logging failed.
+
+---
+
+## Data Retention
+
+Suggested defaults:
+
+- Keep aggregate reports until deleted by user.
+- Keep raw JSONL failure rows for 30 days.
+- Never write raw response text unless debug mode is explicitly enabled.
+- Provide `feynman self-improve purge` in v0.3.0 if the feature ships.
+
+---
+
+## Open Questions
+
+- Should this live behind `feynman doctor` checks or a separate subcommand?
+- Should proposal generation be part of `feynman lint --report`?
+- Should snippet redaction exist, or should raw snippets be disallowed entirely?
+- How should proposal scores account for false positives fixed in the same
+  release?
+- Should team-level aggregation exist, or is local-only the permanent boundary?
+- Can rule proposals remain useful without storing prompt context?
+
+---
+
+## Deferred Implementation
+
+Implementation is explicitly deferred to v0.3.0 (BENCH-V3-02). v0.2.0 ships
+only this design document. No runtime code, CLI command, hook behavior, config
+schema, or logging path is added in this milestone.