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.

Pass 2, Apply. Drain the ledger one row at a time: make the single edit, run the narrowest check that proves it (a test or a lint), then mark the row done with how it was checked. Do not batch unrelated findings into one sweep.

The task is complete only when every ledger row is done or skip and the checks are green, not when the first improvement lands.

Minimalism still governs what you ADD (no speculative abstractions, no unrequested files, prefer the simplest correct change), but it never licenses dropping a stage, a trust-boundary validation, data-loss prevention, security, or accessibility. Non-trivial logic leaves one minimal runnable check behind.

Stage Pipeline

Walk stages from S00 upward when reasoning about code changes. Earlier stages override later ones on conflict. At each stage, inspect matching EXCLUDES first as a rejection filter, then matching KERNELS as positive guidance. Use the universal stage refs= and the loaded language-family ## STAGE-REFS to know which K ids belong to the current stage. Each K id has a mirrored X id with the same numeric suffix in the same leaf, so the same refs also locate the EXCLUDES to consult first. Each ## LEAVES record declares the stages= it carries; to cover the current stage, load every leaf whose stages= includes it. Stage-to-leaf resolution is a direct index lookup, never a filesystem search.

• S00 scope: stay within requested scope and keep blast radius low
• S01 invariants: prove exact invariants, preserve true special cases, obey contracts
• S02 state modeling: make meaningful states explicit, keep distinct outcomes distinct
• S03 lifecycle: centralize mutable state, clarify ownership, rebuild atomically
• S04 shared abstractions: extract shared invariants only after semantics are clear
• S05 boundaries: make subsystem boundaries explicit, thread semantics end to end
• S06 convergence: converge broadly, remove displaced layers

When a task touches code:

1. Load packs/universal/pack.urf.md.
2. Detect the active source family from the file being changed:
   • Python: also load packs/python-architecture/pack.urf.md
   • C++: also load packs/cpp-architecture/pack.urf.md
   • Plain C: stay on universal only
   • Ambiguous .h: use the C++ family only when the file contains C++ constructs
   • Any other language: stay on the universal index only
3. Treat each loaded pack.urf.md as a routing index, not as the dense guidance body.
4. Human-oriented packs/**/README.md guides are not part of the runtime guidance surface. Load only pack indexes and the leaf files resolved from those indexes.
5. From each loaded ## ROUTING, match signals= against the active code context to select your primary leaf per family. If several routes match, pick the route matching the change's dominant mechanic and let the stage walk pull in any remaining leaves; if no route matches, skip signal routing and select leaves directly from ## LEAVES stages= for the stages your change touches.
6. If your primary signal match is a late-stage refactoring leaf (one whose stages= lie entirely in S04-S06), you MUST ALSO load at least one early-stage correctness leaf (S01-S03) to serve as your rejection filter; pick it from ## LEAVES by choosing a leaf whose stages= includes the early stage your code's mechanics touch.
7. To cover a stage whose refs= ids are not in your loaded leaves, read ## LEAVES and load every leaf whose stages= includes that stage; resolve coverage from the index, not by searching the packs/ directory.
8. Consult X entries first at the current stage, then K entries, before proceeding to later stages.
9. When delegating code work to a subagent, pass the pack index paths and this contract, and require the subagent to run its own routing and stage walk from those indexes. Do not pre-select leaves in the delegation prompt; pre-selection bypasses routing and narrows the dose before the code is read.
10. Apply the guidance semantically: translate each kernel into what the code concretely does. Never paste kernel prose, pack vocabulary, or kernel ids verbatim into code or comments -- the one sanctioned in-code trace is a boffin: mark whose clause is the code's own words (see "After any code edit" for when to leave one).

Pre-Flight Review

• Re-read the loaded pack index and all loaded leaf packs; do not rely on memory.
• For a focused change, confirm you stayed within the requested scope and proved the change with a check; the ledger checks below apply to refactor/review tasks.
• For a refactor/review task, confirm the Pass 1 ledger lists a row for every in-scope stage; a stage with no row is an incomplete audit, not a clean file.
• Confirm every ledger row is done or skip, that each skip carries a reason, and that no row recorded as todo was downgraded to skip:clean.
• Confirm every fix named in Pass 1 reasoning has its own ledger row; a fix discussed but left unrecorded is an incomplete audit.
• If a change touches ownership, lifecycle, completion semantics, state-machine transitions, concurrent access, or logic encoded through flags or sentinels, name the exact invariant from stages S01-S03 it must preserve before editing.
• On user request, render the ledger and the blocking earlier-stage invariants as concise ordered bullets in the user's language.

After any code edit:

• Verify the edit with an external check (the narrowest test or lint that proves it), not by re-reading your own reasoning or the diff alone.
• Review the change as if a different author wrote it: read the final file region, not only the diff, and ask what a fresh reviewer would flag.
• Re-read the relevant leaf pack(s); confirm no ## EXCLUDES pattern was introduced and no earlier-stage (S00-S03) invariant was weakened to satisfy a later-stage (S04-S06) cleanup goal.
• A ledger finding may not be silently dropped: it ends as done (with its check) or skip:<reason>; a todo is never relabeled skip:clean.
• Present the filled ledger as the result; do not add rows for kernels that found nothing, and never cite a kernel a row does not actually rest on.
• When a loaded kernel actually changed a code decision -- and the change was not a purely stylistic rewrite of already-correct code -- leave one short host-language comment at that site. Start the comment with the boffin: prefix and state, in the code's own words, what the code now does or refuses (not what the kernel says). The natural judgment verb is encouraged (kept .../refused .../cut ...); the boffin: prefix is the machine-readable key; never add a kernel id or any pack vocabulary. Readability bar (the one mandatory wording check): if you mentally drop the boffin: prefix, the remaining sentence must still read as a comment a senior engineer would write -- otherwise rewrite the clause or drop the whole mark. This is only a mental check: always keep the boffin: prefix in the emitted comment. Budget: at most one mark per hunk, roughly three per changeset. Emit nothing when a .boffin-trace-off file exists at the repository root; only in venues that forbid tool marks, omit the boffin: prefix and keep the clause alone.

Keep runtime reads focused:

• default read set = packs/universal/pack.urf.md + one primary universal leaf
  • any additional universal leaves whose stages= are required by the stages your change's mechanics actually touch + zero or one language-family index + zero or more language leaves whose stages= are required by the same touched stages
• walk every stage S00-S06, but load leaves only for the stages the change's mechanics touch; clear an untouched stage on the universal index focus= line instead of loading its leaves
• for a focused coding change, the 3-5 entry budget is the dose you materially apply after walking every loaded stage; it is not a cap on the stage-walk
• use ## LEAVES stages= as the authoritative stage-to-leaf map; do not rely on filesystem search to discover which leaf covers a stage
• for a pure review, audit, or compliance task with no single edit seam, widen the read surface to one leaf per stage-family the file's mechanics actually touch across S00-S06

This file is the canonical portable instruction surface. Thin host adapters should mirror it without adding host-specific routing semantics.