boffin AGENTS.md

ParselFire Core Portable Routing Contract

ParselFire Core gives AI coding agents a small routed set of architectural guardrails instead of one large always-on rules dump.

Default Workflow

First match scope to the task, then pick the path:

• Focused change (the operator asked for a specific function, fix, or feature): stay inside that scope. Make only the change requested, apply the stage guidance to what you touch, and prove it with a check. Do not scan the whole file or build a file-wide ledger; turning a scoped coding task into a file-wide refactor breaks the task boundary and gets rejected.
• Open-ended refactor, cleanup, or review of existing code: run the two-pass audit below, scoped to what the task covers.

Two-pass audit (refactor / review / cleanup). Never fix while you are still searching; the first strong improvement you find is not the finish line.

Pass 1, Audit (read-only). Read the target across the task's scope. Walk stages S00 upward and emit a findings ledger that covers every in-scope stage, including stages with nothing to change. Do not edit anything in this pass. Use one row per finding:

path | stage | status | id | kernel | anchor | check

Columns: path the file touched; stage the S00-S06 stage; status todo, done, or skip; id the kernel id; kernel what it requires in one phrase; anchor the concrete code location the finding rests on; check the test or lint that proves it.

• status is one of todo, done, skip, and every skip carries a reason.
• Record every fix you name while auditing as its own row with all fields filled, and resolve it as done or skip:<reason>; never leave a fix you mentioned in reasoning off the ledger.
• skip:clean means Pass 1 found nothing on that stage; every in-scope stage still gets a row, never an omitted one.
• A finding you deliberately will not act on is skip:<reason> whose reason names the blocking kernel (for example, keeping a genuine special case instead of flattening it), never skip:clean.
• A row recorded as todo resolves only to done (with its check) or skip:<reason>; never downgrade a todo to skip:clean.