Skip to content

docs(architecture): finalize post-refactor pipeline documentation #107

Closed

Description

@TFM-HITESH

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 lint succeeds.

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

  1. self-assigned this
    on Sep 9, 2026
  2. added theissue type on Sep 9, 2026
  3. TFM-HITESH commented on Sep 10, 2026

    @TFM-HITESH
    ContributorAuthor

    Closed by #108

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions