The Lint Loop

Goal

One command. Sync workspace. Fix mistakes. Validate rules. Update files. Zero daemon.

---

What onde lint Does (User View)

You edit markdown freely. No onde running. No watcher required.
Run onde lint. It:

1. Reads changed files only.
2. Checks syntax + schema rules.
3. Fixes bookkeeping (IDs, counts, links, defaults, property order).
4. Validates everything.
5. Rewrites files to match clean state.
6. Prints exact result. Deterministic. Idempotent.

If clean → zero writes. If broken → tells you file, line, reason, fix path.

---

The 4 Exit States

Read the last line. Know what to do.

State	Output	Files Changed?	Your Action
CLEAN	✓ lint clean	No	Nothing. Continue.
FIXED	✓ fixed (N ops)	Yes	onde git commit. Done.
ERROR	✗ N errors	No	Fix listed lines. Re-run.
WARNINGS	✓ clean (N warnings)	No	Review later. Safe to commit.

Rule: Exit 1 = atomic. Zero files touched. Fix errors first.

---

Essential Flags

Pick by workflow. Not all needed day one.

Flag	What It Does	When to Use
--dry-run	Preview changes. Zero writes.	Before big reorg. CI checks.
--watch	Auto-run on file save.	Active editing session.
--soft	Errors → warnings. Exit 0.	Drafting. Schema too strict temporarily.
--fix	Apply all safe auto-fixes.	Quick cleanup.
--no-materialize	Validate + sync. Skip file rewrites.	Read-only check. Pipeline gate.
--continue-on-error	Write valid files. Skip broken ones.	Large workspace. One bad file shouldn’t block rest.

---

Reading Output & Fixing Fast

Output grouped by type. File:line first. Reason clear. Fix obvious.

Clean Run

onde lint ✓ clean
0 ops | 0 fixes | 0 errors | 0 warnings
tokens: 12,450 / — (no budget set)

Nothing changed. Skip commit.

Fixed Run

onde lint ✓ fixed (3 ops)
synced: 2 | auto-fixed: 5 | materialized: 2 files
tokens: 12,500 / 50,000 (25.0%) (+50)

Auto-fixes applied. Files rewritten. Ready to commit.

Error Run

onde lint ✗ 3 errors (1 warning)
ERR  tasks/active.md:12    unknown type "bug" — not in schema
ERR  tasks/active.md:25    broken link [[task-999]] — node not found
ERR  decisions/db.md:5     required property "confidence" missing
WARN tasks/active.md:18    partial link [[sarah]] — 2 matches
tokens: 12,450 / 50,000 (24.9%)

Fix path: Open file. Go to line. Apply suggestion. Re-run onde lint.
Errors block writes. Fix all → exit 0.

Warning Run

onde lint ✓ clean (2 warnings)
WARN tasks/active.md:18    partial link [[sarah]] — 2 matches, not resolved
WARN decisions/db.md:8     mirror text stale for task-882
tokens: 12,450 / 50,000 (24.9%)

Non-blocking. Commit safe. Fix when convenient.

---

Common Messages & Quick Fixes

Message	Cause	Fix
unknown type "X"	Type not in schema	Add to schema or change type::
broken link [[X]]	Target missing or deleted	Create node or remove link
required property "X" missing	Schema demands it	Add property or set @default in schema
invalid value "X" for status	Enum mismatch	Use valid value or extend schema enum
column mismatch	Dense row ≠ header cols	Match pipe count exactly
partial link [[X]] — N matches	Title ambiguous	Use ID link [[task-882]] or full title
file over budget — N/M	Token limit exceeded	Trim body, split file, or raise budget

Full catalog → Troubleshooting & Reference

---

Daily Workflow

Edit markdown freely (any editor)
│
▼
Run `onde lint`
│  Read last line.
│  CLEAN → continue.
│  FIXED → commit.
│  ERROR → fix listed lines → re-run.
│  WARNINGS → commit or fix later.
│
▼
`onde git commit` (auto-message from changes)
│
▼
Repeat.

Rules:

• Lint before commit.
• Lint after pull.
• Lint when output looks wrong.
• --watch optional. Not required.
• One command handles sync, validation, formatting, and bookkeeping.

---

Next Step: → Structure & Schema: Start Loose, Tighten When Ready