myArch: A Systematic Development Framework

myArch has two deliberately distinct index domains:

• arch.Quad is the preferred name for the original fixed, four-place architectonic address. arch.Idx remains its compatibility name.
• arch.idx.Idx is the definitive arbitrary-depth document index: numeric, alphabetic, Roman, symbolic, dotted or compact, optionally marked and wrapped.

They are not subtypes of one another. A Quad admits the empty root and abstract a / b halves and has a special four-branch ancestry; a document idx is a non-empty, arbitrary-depth sequence whose rendering policy is independent of its place. Keeping them separate makes those invariants visible instead of weakening either model.

The arch executable is both an agent-oriented linter and a human-oriented terminal workspace. Arguments select a deterministic CLI operation; bare arch on a real terminal opens the PyRatatui browser.

$ arch check docs src
$ arch --json plan docs | jq '.plans[] | select(.changed)'
$ arch apply --dry-run --diff docs
$ arch apply docs
$ arch                         # TUI when stdin/stdout are terminals

$ arch format --check src docs # report non-canonical configured header blocks
$ arch format --diff src docs  # print patches, never write
$ arch format src docs         # atomically format them
$ arch spec --input headers.yaml --output headers.yaml

The safety rule is structural: a file containing no recognized idx is never modified, even by --operation reindex --insertion all. In a partially indexed file, the default observed insertion scope fills only hierarchy depths already represented in that file. Every write is planned first, content-hash checked, and atomically replaced without normalizing newlines or the final newline.

Configuration is layered as command flags, an explicit --config, the nearest .arch.yaml, ~/.config/my/arch.yaml, then built-ins. Higher-precedence path rules are tried first:

default_spec: decimal
insertion: observed

specs:
  decimal:
    styles: [number]
    separator: '.'
  doctrine:
    styles: [number, alpha-lower, roman-lower]
    separator: '.'
    marker: '.'
    max_depth: 6

paths:
  - path: /absolute/path/to/canon.md
    spec: doctrine
  - regex: '^journal/[0-9]{4}/'
    spec: doctrine
  - glob: 'docs/**'
    spec: decimal

ignore:
  - 'vendor/**'

See the idx guide, design explanation, and rendered API page for document indexes; see the Header formatting guide for HeaderSpec, arch format, and the keyboard-first profile editor.