Repository navigation
Description
Audit and finish the contributor-facing architecture documentation after the
lint and diff refactors.
GitHub #105 and #106 already updated most of the package map and execution
flows. This issue covers the remaining accuracy and safety clarifications. It
must not repeat work that has already landed.
Problem
The architecture docs now describe the current source, analysis, lint, diff,
mutation and output boundaries. They still need a final review against the
merged implementation, especially around mutation guarantees and limits.
The documentation must explain what a mutation run guarantees without implying
that a multi-file plan provides a transaction or rollback guarantee.
Fumadocs does not exist yet. Keep the current repository documentation intact
until the separate Fumadocs setup, content and deployment issues are complete.
Scope
Update only the contributor-facing architecture material:
docs/system-overview.md;- the architecture, components and pipeline sections of
docs/primer/README.md; - an existing architecture diagram, if the repository contains one and it no
longer matches the implementation; - internal links and package references that these sections use.
Do not rewrite the primer's user-oriented walkthroughs as part of this issue.
Do not move public documentation to Fumadocs in this issue.
Required content
Document and verify:
- the CLI and application boundaries;
- scope resolution and deterministic selection;
- thin dotenv loading and source-specific parsing;
- the conversion from source documents to value-free analysis facts;
- lint and diff as separate consumers of analysis;
- typed results and output adapters;
- side-effect-free mutation planning;
- complete preflight validation before replacement;
- locking and stale-state revalidation during mutation application;
- atomic replacement for each destination and preservation of captured file
permissions; - the absence of a global transaction or rollback guarantee across a
multi-file mutation plan; - post-fix reload and re-analysis;
- deterministic ordering;
- the boundary between raw source data and value-free analysis data;
- where future contributors should add source, analysis, engine, application,
mutation, diff or output changes.
Acceptance criteria
- No architecture section describes the removed runner-centric flow.
- The package responsibility table matches the merged repository tree.
- The lint pipeline is described from scope resolution through typed output and CLI exit mapping.
- The diff pipeline is described separately from lint and includes its analysis, comparison, output and exit-code stages.
- The docs distinguish source parsing from analysis construction.
- The docs identify which layers may retain raw values and source bytes.
- The docs state that engines and reporters consume value-free facts and
typed results. - The docs state that mutation planning performs no filesystem writes.
- The docs describe mutation preflight, locking, stale-state checks, per-file atomic replacement and permission preservation accurately.
- The docs state the limits of multi-file mutation application and do not promise global rollback or transactional replacement.
- The docs describe post-fix re-analysis.
- The architecture sections do not duplicate command-reference content.
- Every package and API reference matches the merged implementation.
- Internal links resolve.
- Any repository architecture diagram matches the documented pipeline.
- Examples contain no real secrets.
-
make lintsucceeds.
Non-goals
This issue does not include:
- setting up the Fumadocs application;
- writing or restructuring the public Fumadocs content;
- configuring documentation deployment or CI/CD;
- migrating public command references, rule references or help pages;
- changing the root README's public-facing content;
- documenting query semantics or implementation;
- documenting unimplemented future sources in detail;
- changing production code or architecture.
Dependencies
- The post-refactor source, analysis, lint, mutation and diff changes must
remain merged and accurately reflected by the docs. - Fumadocs work follows this issue through separate setup, content and
deployment tickets.
Activity
docs(architecture): finalize post-refactor pipeline documentation (#108)
TFM-HITESH commentedon Sep 10, 2026
Closed by #108