graphite-code 0.5.3__tar.gz → 1.0.1__tar.gz

{graphite_code-0.5.3 → graphite_code-1.0.1}/ARCHITECTURE.md

@@ -24,10 +24,10 @@ The implementation stages are:
 1. **Collection — `ingest.py`, `config.py`, `git.py`.** Configuration establishes file-count and file-size limits and the cache and output locations. Ingestion normalizes project-relative paths, resolves candidates beneath the repository root, skips unsafe or ineligible files, and sorts accepted entries. Git-backed enumeration uses `GitRunner` with a trusted executable outside the repository, an argument vector, no shell, a filtered Git environment, a timeout, and a stdout cap. The filesystem fallback is also capped by configured file limits, but it does not provide every process control because no child process is involved.
 2. **Extraction — `extract/ast.py`, `cache.py`, `ts_bridge.py`, `ts_resolver.mjs`.** Per-language Tree-sitter extractors handle JavaScript/TypeScript, Python, Go, and Rust, while unsupported or unavailable parsers degrade to a file-level record. Extraction emits symbols, imports, calls, and containment edges in deterministic order. The content-addressed cache avoids repeated AST work. TypeScript/JavaScript may additionally use the Node compiler bridge for compiler-backed module resolution; bridge failure falls back to heuristic resolution rather than making Node mandatory.
 3. **Resolution — `resolve.py`.** `SourceIndex` builds the set of normalized, project-relative source identities, reads TypeScript aliases and workspace package entry points, prefers compiler-backed TypeScript results when available, and otherwise applies bounded heuristics. Global merge logic also resolves supported call identities and deterministically removes duplicates.
-4. **Graph and analysis — `graph.py`, `cluster.py`, `analyze.py`, `query.py`.** `graph.py` constructs a NetworkX `DiGraph` after sorting nodes and edges and normalizing IDs. Analysis filters to project nodes where appropriate and returns bounded, ordered results. Community detection constructs a deterministic undirected view and uses the configured seed (42 by default). JSON conversion preserves the graph's deterministic insertion order.
+4. **Graph and analysis — `graph.py`, `cluster.py`, `analyze.py`, `query.py`.** `graph.py` constructs a NetworkX `DiGraph` after sorting nodes and edges and normalizing IDs. Analysis filters to project nodes where appropriate and returns bounded, ordered results; the cycle report is a bounded search (per strongly connected component, one length level at a time up to length 8, under a 10 000-cycle budget) and `analysis.cycle_search` records whether the enumeration completed exactly or was truncated, so a repository with dense import cycles cannot make a build exhaust memory. Community detection constructs a deterministic undirected view and uses the configured seed (42 by default). JSON conversion preserves the graph's deterministic insertion order.
 5. **Validation and review — `validation.py`, `context.py`, `review.py`.** Bundle validation checks structural types, node and edge identity, referential integrity, metadata counts, and unsafe `source_file` paths. Review validates a supplied bundle before deriving graph impact evidence; its Git discovery also normalizes status records and rejects malformed or unsafe paths. By contrast, `cmd_query`, `cmd_impact`, `cmd_context`, and `GraphiteMCPServer._load` currently read JSON and call `graph_from_json` without `validate_graph_bundle` or a bounded-read helper. Those direct consumers therefore rely on callers to supply an already validated, reasonably sized artifact.
 6. **Export — `export/json.py`, `export/md.py`, `export/html.py`, `io.py`.** Exporters consume only canonical graph, cluster, analysis, and manifest data. JSON serialization provides the data encoding; HTML separately JSON-encodes script data, escapes `<`, `>`, and `&`, HTML-escapes the title, and uses text DOM APIs for runtime labels. Text and JSON outputs use temporary files, `fsync`, and `os.replace` for atomic replacement of each file.
-7. **Operations — `watch.py`, `daemon.py`, `daemon_health.py`, `bootstrap.py`, `init.py`, `windows_task.py`, `windows_startup.py`.** These modules watch for changes, maintain multi-project daemon status, evaluate health, generate integration instructions, and manage platform startup. Watch and daemon canonicalize inherited configuration; daemon child builds use fixed `--llm none` argv and a provider-scrubbed environment.
+7. **Operations — `watch.py`, `daemon.py`, `daemon_health.py`, `bootstrap.py`, `init.py`, `daemon_launch.py`, `windows_task.py`, `windows_startup.py`, `systemd_unit.py`, `launchd_agent.py`.** These modules watch for changes, maintain multi-project daemon status, evaluate health, generate integration instructions, and manage platform supervision. `daemon_launch.py` holds the one daemon argument vector (`python -P -m graphite daemon <base> …`); the Windows scheduled task, the Windows Startup-folder launcher, the systemd user unit and the launchd agent are each rendered from it, so every supervisor starts the same bounded, zero-LLM daemon under `-P`. Watch and daemon canonicalize inherited configuration; daemon child builds use fixed `--llm none` argv and a provider-scrubbed environment.
 8. **Provider lifecycle — `routing/lifecycle.py`, `routing/lifecycle_storage.py`, `routing/lifecycle_service.py`, and `routing/lifecycle_operator.py`.** Runtime observations, compatibility decisions, lifecycle authority, and invalidations live in an isolated database. Operator reads use an existing-database, query-only connection and bounded public records. Policy and verification preparation create non-activating content-hashed candidates; neither surface invokes a provider.
 9. **Optional overlays — `overlays.py` and `llm.py`.** Provider adapters may consume an already-built, fresh, validated graph only through `graphite overlay build`. The overlay manifest binds the canonical bundle fingerprint, exact lifecycle/model/routing identities, limits, creation time, outcome, and schema. Identity-derived contained paths, restrictive permissions, content-addressed payloads, and manifest-last atomic replacement isolate the output below `graph-out/overlays/`. Overlay staleness is independent of canonical freshness and cannot grant graph or routing authority.
 
@@ -42,9 +42,10 @@ The implementation stages are:
 | Validation and evidence | `validation.py`, `context.py`, `review.py` | Validate bundles and derive review/context evidence | Graph structures; review may use the Git adapter |
 | Export | `export/json.py`, `export/md.py`, `export/html.py`, `io.py` | Encode and atomically replace individual artifacts | Validated graph, analysis, clusters, manifest |
 | Optional model overlays | `overlays.py`, `llm.py` | Validate identity and canonical freshness; produce fingerprint-bound, non-authoritative annotations outside canonical artifacts | Existing canonical graph, explicit provider configuration, network only when separately authorized |
-| Operations and integration | `watch.py`, `daemon.py`, `daemon_health.py`, `bootstrap.py`, `init.py`, `windows_task.py`, `windows_startup.py` | Freshness, daemon health, generated instructions, and OS startup | Public core operations and explicit platform/process boundaries |
+| Operations and integration | `watch.py`, `daemon.py`, `daemon_health.py`, `bootstrap.py`, `init.py`, `daemon_launch.py`, `windows_task.py`, `windows_startup.py`, `systemd_unit.py`, `launchd_agent.py` | Freshness, daemon health, generated instructions, and OS supervision on Windows, Linux and macOS | Public core operations and explicit platform/process boundaries |
+| Platform shims | `_win32_ctypes.py`, `_cleanup_worker.py` | Typed call-time views of platform-only stdlib surfaces (Win32 ctypes, POSIX-only `os` members) so the portable core type-checks on every OS without `sys.platform` guards | Standard library only |
 
-The intended dependency direction is observable in current imports but is not enforced by a dedicated architecture linter. CLI and MCP adapt inputs; portable core modules do not import those UI entry points. Export consumes canonical graph and analysis data; extraction does not depend on exporters. Canonical graph construction, validation, and read operations do not depend on model providers. Windows startup and task management remain outside the portable core. External execution crosses explicit subprocess boundaries; Git uses the hardened `GitRunner`, while the TypeScript and Windows adapters have their own, not necessarily identical, controls. Contributors must preserve these directions and add tests if a boundary becomes mechanically important.
+The intended dependency direction is observable in current imports but is not enforced by a dedicated architecture linter. CLI and MCP adapt inputs; portable core modules do not import those UI entry points. Export consumes canonical graph and analysis data; extraction does not depend on exporters. Canonical graph construction, validation, and read operations do not depend on model providers. Platform supervision — the Windows scheduled task and Startup launcher, the systemd user unit, the launchd agent — remains outside the portable core. External execution crosses explicit subprocess boundaries; Git uses the hardened `GitRunner`, while the TypeScript and platform-supervisor adapters have their own, not necessarily identical, controls. Contributors must preserve these directions and add tests if a boundary becomes mechanically important.
 
 ## Trust boundaries
 
@@ -86,7 +87,7 @@ Treat paths, bytes, symlinks, encodings, file counts, and file sizes as hostile.
 
 **Process boundary.**
 
-Git, Node/TypeScript, and Windows task/startup integrations execute outside Python. `GitRunner` is the strongest current adapter: fixed executable discovery outside the repository, argv execution with `shell=False`, disabled stdin/stderr, filtered `GIT_*` environment, timeout, stdout cap, and typed sanitized failures. The TypeScript bridge uses argv, `subprocess.run`, captured output, a configured timeout, and a 500-character diagnostic cap, but it currently inherits the environment and does not impose an explicit output-byte cap. Windows adapters are platform-specific and must be reviewed on their own controls. Do not generalize Git's isolation guarantees to every subprocess.
+Git, Node/TypeScript, and the platform supervisors (`schtasks`, `systemctl --user`, `launchctl`) execute outside Python. `GitRunner` is the strongest current adapter: fixed executable discovery outside the repository, argv execution with `shell=False`, disabled stdin/stderr, filtered `GIT_*` environment, timeout, stdout cap, and typed sanitized failures. The TypeScript bridge uses argv, `subprocess.run`, captured output, a configured timeout, and a 500-character diagnostic cap, but it currently inherits the environment and does not impose an explicit output-byte cap. The supervisor adapters are platform-specific, take an injected runner in tests, and must be reviewed on their own controls. Do not generalize Git's isolation guarantees to every subprocess.
 
 **Artifact and browser boundary.**
 

{graphite_code-0.5.3 → graphite_code-1.0.1}/CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 
 Notable changes to graphite. Format follows [Keep a Changelog]; versioning is
-semver, pre-1.0 (minor versions may break things).
+semantic. From 1.0.0 the surfaces listed in `docs/compatibility.md` are
+stable: a breaking change to any of them is a major release.
 
 **A version number here is a coarse release label, not a fix marker.** Several
 behavioural fixes have shipped with no version change at all — the `-P`
@@ -12,6 +13,273 @@ machine-checkable identity; the version is for humans.
 
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 
+## [1.0.1] — 2026-09-05
+
+A patch release. Measured against the deployed 1.0.0 engine on this repository,
+the tree produces the same graph: 7260 of 7260 node ids survive, 20700 of 20700
+edge triples unchanged, every relation count equal, `analysis.cycles` identical.
+Only the engine fingerprint moves, because graphite's own bytes did.
+
+### Changed
+
+**Vendor-neutral wording throughout the replacement audit and docs.** The
+README opening, the `audit-replacement` help and reference text,
+`skill/SKILL.md` and the audit's own messages no longer name the legacy
+graph tool, and the README's opening comparative against it — an unmeasured
+claim dating to the initial commit (`fd58583`) — is removed rather than
+defended. In the audit's report, which is not a `schema_version`-stable
+surface, the `graphify` block is renamed `legacy` and the warning codes
+`graphify_paths_exist`, `graphify_text_references` and
+`graphify_gitignore_entries` become `legacy_paths_exist`,
+`legacy_text_references` and `legacy_gitignore_entries`. Detection is
+unchanged: the on-disk path patterns and the text-scan needle still match
+the legacy tool's literal artifact names — the one place the name must
+remain for the audit to find anything.
+
+### Fixed
+
+**The extraction cache grew without bound inside a partition (#66).** #23
+reclaims whole partitions a build can never read again and left the one it
+uses alone. Entries are keyed on the file's content hash, so every edit that
+triggers a rebuild wrote a new entry and orphaned the previous one, and
+nothing ever removed an orphan: a consumer checkout rebuilt by the daemon on
+every change reached 15,406 entries / 419 MB in a single partition, 11,592 of
+them from four days, against 1,780 / 62 MB for graphite's own tree on the
+same engine. Same rule as #23, one level down -- reachability, not age or
+size: a `Cache` now records every key it read (and found) or wrote, and after
+a build has extracted the tree and built its graph, `prune_unreachable_entries`
+deletes every other entry in the partition, reporting
+`[graphite] reclaimed N unreachable cache entries (X MB)` when it removed any.
+Older content checked out later re-extracts once (performance, never
+correctness). Safe without the build lock: `read` already treats a vanished
+file as a miss, so a concurrent reader re-extracts rather than fails. A build
+that touched nothing prunes nothing, only the exact `<2 hex>/<64 hex>.json`
+shape the cache writes is eligible, and a per-entry failure (a Windows handle
+race) is swallowed.
+
+**The deferred stdin close never fired on Linux or macOS.** `run_bounded_process`
+reads the child's pipes with a fixed-size read, and its two transports hand
+that reader different objects: on Windows a raw `io.FileIO`, whose `read(n)`
+returns whatever the child has written, and on POSIX a default `Popen` pipe,
+a `BufferedReader` whose `read(n)` keeps reading until it has n bytes or EOF.
+Off Windows the reader therefore saw nothing until the child exited, the
+`stdin_close_when` predicate never saw its marker, and every deferred close
+was the budget fallback -- so the #29 fix was inert there and the doctor's MCP
+deep probe spent its whole budget on every POSIX run. The reader now uses
+`read1` on buffered pipes; the Windows path is unchanged. The tests that
+pinned the deferral could not fail (one matched a marker that text-mode
+stdout writes as CRLF on Windows, the other's lower bound was satisfied by
+the child's own sleep) and now kill a never-defer mutant; the interval test
+that blocked the pre-push gate measures from the close instead of from
+launch, against the child's own life rather than a 0.25s constant.
+
+**The post-publication verifier's provenance arm asked an endpoint that
+never carries provenance.** `scripts/verify_published_release.py` read
+`urls[].provenance` from PyPI's legacy `/pypi/<project>/<version>/json`
+API, which has no such key, so the arm reported "no provenance" for 1.0.0
+while the Integrity API was already serving both GitHub attestation bundles
+(`jared0565/graphite`, `publish.yml`). The arm now reads the PEP 691 Simple
+JSON index (`Accept: application/vnd.pypi.simple.v1+json`), where PEP 740
+publishes a `provenance` URL per file; a test pins the endpoint so a
+regression to the legacy API fails. Re-run against 1.0.0: 6 of 6 arms.
+
+**Three findings from aramid's `llm-review` tier on the CI workflow and the
+benchmark, all confirmed and closed:**
+
+- The `coverage_floor` dispatch input could *lower* the floor for one run,
+  so a dispatched run could report green against a weaker gate than the
+  committed one. The enforcing step now refuses any requested value that is
+  not an integer at or above the committed `COVERAGE_FLOOR`; a dispatch can
+  only raise it (the negative control is unchanged). Proven with a fake
+  coverage across six arms: empty, 84 and 83 pass; 80, `abc` and -5 fail
+  before coverage is read.
+- `test_core_probe_cleanup_timeout_uses_single_global_slot_and_recovers`
+  raced its 0.5 s probe budget against runner load (#65): more than 0.4 s of
+  scheduling before the workspace lease is acquired yields a pure `timeout`,
+  after it a `cleanup_timeout` carrying `masked_*` keys — two CI failures in
+  three runs on one day, both shapes reproduced with a paced fake clock. The
+  test now freezes its injected `_clock` like the sibling probe tests (the
+  subject is the classification of a hung cleanup, not phase pacing; the
+  cleanup join still runs on real time), and the frozen-clock test still
+  kills both guarding mutants: a hung cleanup reported as `None`, and a
+  probe slot that never releases.
+- The `security` job's self-check asserted only that gitleaks and semgrep
+  ran, while the step's name claimed typecheck and a dependency audit. The
+  labels were measured from the job's own `prepush.json` artifact
+  (`gitleaks, mypy, python.exe, semgrep, shadow`): the assertion now covers
+  every configured scanner, and the step name, `SECURITY.md` and
+  `CONTRIBUTING.md` no longer claim a dependency audit — no gate run on
+  either machine has ever emitted one, although `aramid doctor` lists
+  pip-audit as present (reported to aramid). Measuring this exposed two
+  worse things: under aramid 0.6.0 the CI typecheck slot had **never run**
+  in `--all` mode (no `mypy` in `tools_ran`, nothing degraded) and the old
+  assertion called that clean; under 0.6.1 it runs over every `.py`, and
+  the job passed with exit 0 while its own report carried 786 block-tier
+  findings that the same report fails with on the maintainer's machine
+  (exit 1). Discriminated on the first run under the 0.7.0 pin (33286250634):
+  still 786 block-tier findings and exit 0 with CI's empty ledger, so
+  aramid's exit depends on ledger presence — `.aramid/` is gitignored, so
+  a fresh checkout cannot be gated by exit status at all. aramid confirmed
+  the mechanism from its code (channel round 151): its **fresh-ledger
+  rule** — the first pre-push run on a ledger with no baseline writes one
+  and downgrades findings the ratchet alone escalated to exit 0, so every
+  CI checkout is "the first run" — and from 0.7.1 the report says so
+  (`fresh_ledger_baseline`, `grandfathered`; both gate steps print them).
+  Both CI gate steps now
+  read the verdict from the report itself: any block-tier finding from a
+  non-mypy scanner, or from mypy inside the project's type-gate scope
+  (`src/graphite`), fails the step regardless of the exit status; mypy
+  findings on the deliberately untyped `tests/`, `scripts/` and
+  `benchmarks/` trees are counted and printed.
+- `benchmarks/build_benchmark.py` prepended the repository root to
+  `sys.path` to import its sibling — the shape the `-P` launch contract
+  forbids. It loads `synthetic_repo.py` by location now, CI runs it under
+  `-P`, and two tests pin the shape (no `sys.path` access in the module; the
+  script starts under `-P`).
+
+### Changed
+
+- CI pins `aramid==0.7.2`, the tool this machine runs (channel round 157;
+  0.7.0 and 0.7.1 were pinned briefly at rounds 148 and 152). 0.7.2 fixes
+  the tests-slot skip-streak false alarm this repository reported — the
+  registry key `tests` rode into `run_started.expected` beside the slot's
+  label, so `status` counted every pre-push run as a skipped suite (channel
+  rounds 155–157) — and stamps `run_id`/`recorded` in the check report, so
+  a `--no-record` measurement is distinguishable from a recorded one.
+  0.7.1's typecheck slot honours
+  `[tool.mypy] files`, so the 683 mypy rows that a whole-tree measurement
+  under 0.7.0 had written into the maintainer's ledger for `tests/` (675)
+  and `scripts/` (8) are retired with `ledger resolve --out-of-scope`, each
+  carrying the reason.
+  The two `mypy:syntax` ledger rows that 0.6.1 left unresolvable were NOT
+  retired with `ledger resolve --out-of-scope` as first written here: it
+  refused them (`is not open (status=fixed)`), because aramid's gate had
+  already marked them `fixed` on a push that ran mypy over other files
+  without opening `ci.yml` — a defect in aramid 0.6.1's examined-set
+  stamping, fixed on aramid's `main` (`e65f296`) for 0.7.1. The rows stay
+  `fixed`, the log being append-only; channel round 151 is their record.
+- mypy's configuration is back under `[tool.mypy]` in `pyproject.toml` and
+  `setup.cfg` is gone. It had moved there only because aramid 0.6.0's
+  typecheck runner armed on `[tool.mypy]` and then fed every changed file to
+  mypy; aramid 0.6.1 hands mypy only `.py`/`.pyi` (channel round 144), so
+  the CI pin is now `aramid==0.6.1` and the two `mypy:syntax` suppression
+  entries that bridged the defect are deleted rather than kept — a
+  workaround that outlives its root cause misdirects the next reader.
+
+### Documentation
+
+- **The generated CLI reference now renders nested subcommands.**
+  `scripts/gen_cli_reference.py` walked only the top level of the parser,
+  so the twenty-four commands that live one level down — under `route`,
+  `lifecycle`, `channel`, `incidents` and `overlay` — and every option they
+  own (`route reconcile --attempt-id`, for one) were absent from
+  `docs/reference/cli.md`, and the lockstep test could not see them drift.
+  Each nested command now has its own section under its group, and
+  `tests/test_cli_reference.py` requires every nested command and every
+  option it declares to appear there.
+- **Every CLI argument now declares help text.** Rendering the nested
+  commands exposed sixty-two arguments with none — every nested `--json`,
+  the `lifecycle policy prepare` and `verification prepare` inputs,
+  `route accept|reject|cleanup|review --task-id`, `record-outcome`'s
+  flags, `reconcile --attempt-id`, `policy --promote/--rollback`, the
+  `incidents ack|resolve` positionals and options — so both `--help` and
+  the reference were silent about them. Each now says what it takes and
+  what it binds to; a test walks the whole parser and fails on any
+  argument without help, so none can be added back.
+- New [user guide](docs/user-guide.md) and [knowledge base](docs/knowledge-base.md).
+- README: installation is `pip install graphite-code` (it had still said
+  `git clone` + `pip install -e .`, wrong since the 0.3.0 wheel), the `-P`
+  launch rule is explained where the command is introduced, the MCP
+  examples launch with `-P`, and a documentation index points at every
+  support page. CONTRIBUTING puts the dev environment outside the clone
+  and lists what CI enforces. ARCHITECTURE covers the platform
+  supervisors and the bounded cycle search. The Claude Code skill is
+  machine-neutral and versioned 1.0.0.
+
+## [1.0.0] — 2026-08-29
+
+The production-grade release. Nothing here is a claim CI cannot turn red:
+each item names the gate or test that enforces it. The declaration criteria
+and their evidence are in `docs/superpowers/specs/2026-08-29-production-grade-design.md`.
+
+### Fixed
+
+**The cycle report could not finish on a repository with dense import
+cycles** (#64). `analyze()` enumerated every simple cycle of the project
+graph before sorting and keeping twenty; on Django 5.2 (2 930 source files,
+`tests/` and `django/` importing each other) that is exponential — 13 GB and
+unfinished after thirty minutes, while each half alone reported cycles in
+seconds. The search is now bounded: cycles are enumerated inside strongly
+connected components one length level at a time up to length 8, under a
+10 000-cycle budget, and stop once a completed level holds the twenty
+shortest — exact whenever it stops that way, and deterministic across
+processes even when the budget bites. `analysis.cycle_search` records
+`length_bound`, `budget`, `examined`, `budget_exhausted`,
+`complete_through_length`, `cyclic_components` and `largest_component`, so a
+truncated answer says so. Django 5.2 now builds in 82 s (45 620 nodes,
+109 373 edges, 53 MB). Found by the real-repository benchmark; the synthetic
+corpus alone would never have shown it.
+
+**A lifecycle event claiming "no prior observation" over an UNAVAILABLE row
+raised `AttributeError`** instead of `lifecycle_transition_stale`
+(`routing/lifecycle_storage.py`); found while making the type gate clean.
+
+### Added
+
+- **Every supported cell gates merges.** The CI matrix is windows/ubuntu/macos
+  × CPython 3.11–3.14, all twelve cells blocking; the advisory `portability`
+  job is gone. Ubuntu and macOS 3.13 ran for the first time and pass.
+- **A type gate.** `python -m mypy` over `src/graphite` runs in the lint
+  job; 142 findings were fixed with zero `type: ignore` comments added, and
+  the gate is clean under `--platform` win32, linux and darwin.
+  `graphite/py.typed` ships (the artifact verifier refuses a wheel without
+  it) and the distribution carries `Typing :: Typed`.
+- **A coverage floor.** Branch coverage is collected on the 3.12 leg of each
+  OS, combined (83.04 % on the first measurement), and enforced at
+  `COVERAGE_FLOOR = 83`; a `workflow_dispatch` input overrides the floor for
+  one run as the negative control (floor 84 turns the job red).
+- **The security gates run in CI, unmodified.** A `security` job creates the
+  dev venv `aramid.toml` names and runs `aramid check --gate pre-commit|pre-push
+  --all --strict` against the committed configuration, asserting the tools
+  that ran (gitleaks, ruff, shadow; gitleaks, mypy, the suite, semgrep,
+  shadow) and refusing any degraded tool. A planted repo-root `graphite.py`
+  fails it at the pre-commit gate — and, under `python -m pytest`, every test
+  leg with it, which is the hazard the `-P` launch shape exists for.
+- `SECURITY.md` (GitHub private vulnerability reporting), `CODEOWNERS`, issue
+  templates, dependabot for actions and pip, `authors` metadata.
+- `daemon-install-linux` (systemd user unit), `daemon-install-macos`
+  (launchd agent), `daemon-uninstall-*` and `daemon-service-status`; all
+  three supervisors build their launch argv from one place, so `-P` is
+  present by construction. `daemon-health` reports the platform's supervisor.
+- `benchmarks/`: a deterministic synthetic corpus and a build benchmark; a CI
+  `benchmark` job records a 3 000-file build as an artifact and fails only
+  past a catastrophic budget. `capabilities` declares
+  `supported_repo_files: 7000` with its basis; `docs/benchmarks.md` holds the
+  measurements, including Django 5.2.
+- Reference documentation that cannot drift: `docs/reference/cli.md`
+  (generated from the parser; a test fails when stale),
+  `docs/reference/configuration.md` (every `Config` field and every
+  `GRAPHITE_*` variable the code reads, both directions tested),
+  `docs/reference/exit-codes.md` (every subcommand has a row),
+  `docs/compatibility.md` (what 1.x promises, the deprecation policy, the
+  support matrix).
+- Releases are built in CI from the approved tag with pinned tools
+  (`release-build-constraints.txt`), refused unless both digests equal the
+  reviewed ones, attached to the GitHub Release, and published with PEP 740
+  attestations that are true because this workflow built the bytes.
+
+### Changed
+
+- `Development Status :: 5 - Production/Stable`. From 1.0.0 the surfaces in
+  `docs/compatibility.md` are stable; a breaking change to any of them is a
+  major release.
+- The CI security job pins aramid 0.6.0 (the version the maintainer's
+  machine runs). mypy's configuration lives in `setup.cfg` for now: aramid
+  0.6.0's typecheck runner arms on `[tool.mypy]` and hands non-Python files
+  to mypy (accepted in channel round 140, fixed in aramid 0.6.1); both
+  files say when to move it back. Two reasoned entries in
+  `.aramid-suppressions.toml` from the same defect retire themselves.
+
 ## [0.5.3] — 2026-08-28
 
 ### Fixed

{graphite_code-0.5.3 → graphite_code-1.0.1}/CONTRIBUTING.md

@@ -4,17 +4,19 @@ Contributions should be focused, reviewable changes that preserve Graphite's det
 
 ## Development setup
 
-Graphite requires Python 3.11 or newer, Git, and an isolated virtual environment. Clone and enter the repository using paths appropriate for your system:
+Graphite requires Python 3.11–3.14, Git, and an isolated virtual environment **outside the clone**. Clone and enter the repository using paths appropriate for your system, then create the environment beside it rather than inside it:
 
 ```bash
 git clone https://github.com/jared0565/graphite.git
 cd graphite
-python -m venv .venv
+python -m venv ../.venvs/graphite-dev
 ```
 
+Two reasons for the location. An environment inside the checkout is read by the MCP trusted-source probe as an import shadow of the repository it was asked to trust, so `doctor --deep` reports it. And the release checks (`aramid.toml`, the CI `security` job) run the test suite through exactly that interpreter, `../.venvs/graphite-dev`, so that the suite tests the editable clone rather than whatever `graphite-code` wheel the machine interpreter has installed — a green run against the wrong distribution proves nothing.
+
 If you contribute from a fork, clone the fork's verified URL instead. Keep URLs and other environment-specific values outside shell metacharacters.
 
-Activate `.venv` using the command for your shell. Before installing already-declared extras, inspect `pyproject.toml` and confirm the exact extra and dependency names. Then install the declared development extra:
+Activate the environment using the command for your shell. Before installing already-declared extras, inspect `pyproject.toml` and confirm the exact extra and dependency names. Then install the declared development extra:
 
 ```bash
 python -m pip install -e ".[dev]"
@@ -87,20 +89,32 @@ Run a focused test while iterating. Replace the placeholder path with the test m
 python -m pytest tests/test_relevant_area.py -q
 ```
 
-Before requesting review, run all required checks:
+Before requesting review, run all required checks through the dev environment's interpreter:
 
 ```bash
 python -m ruff check .
-python -m pytest -q
+python -m mypy                 # [tool.mypy] in pyproject.toml; 0 errors is the gate
+python -m pytest -q -rs        # -rs: a skip is visible, not a silent pass
 python -m graphite --help
 ```
 
-Focused tests shorten the feedback loop; they do not replace the full Ruff, pytest, and CLI smoke checks. Add behavior-level tests for new or changed contracts and ensure failures are meaningful rather than dependent on local machine state.
+Focused tests shorten the feedback loop; they do not replace the full Ruff, mypy, pytest, and CLI smoke checks. Add behavior-level tests for new or changed contracts and ensure failures are meaningful rather than dependent on local machine state.
+
+What CI enforces on every push and pull request (`.github/workflows/ci.yml`): a `lint` job (ruff, mypy, the generated CLI reference in sync); a `test` matrix of Windows, Linux and macOS × Python 3.11–3.14 in which **every cell gates**; a `security` job that runs the same aramid pre-commit and pre-push gates as the local hooks (gitleaks, semgrep, ruff security rules, the repo-root shadow check, mypy, the suite) and asserts from the gate's JSON report that each scanner actually ran; the `coverage` floor; a `benchmark` job against the synthetic corpus; and an `artifact` job that builds the distribution twice and requires byte-identical results. The local git hooks are installed by `aramid` from the committed `aramid.toml`; do not push with `--no-verify`.
 
 Doctor changes require focused tests for stable doctor JSON, deterministic ordering, redaction, end-to-end deadlines, process cleanup, missing tools, and optional semantics. Cover both successful and adversarial outcomes. Cross-platform behavior must have Windows and POSIX coverage; use narrowly scoped platform skips only when an operating-system primitive truly has no counterpart, and test the portable contract on every platform.
 
 No live provider calls in automated tests are permitted. Exercise network and subprocess behavior through a fake worker, fake provider, and fake process boundary with controlled time, output, failures, and descendants. Tests must remain offline, deterministic, and safe to run without credentials.
 
+### Coverage floor
+
+CI collects branch coverage on the 3.12 leg of every OS, combines the three
+data files in the `coverage` job, and fails under `COVERAGE_FLOOR` in
+`.github/workflows/ci.yml`. The floor is the integer part of the measured
+total: raise it when a release measures higher, and never lower it without a
+CHANGELOG entry saying what was removed and why. No single leg's figure is
+the measurement -- platform-only code is covered on one OS each.
+
 ## Security expectations
 
 Treat repository files, file names, symlinks, Git metadata, generated graph data, and model output as untrusted input. Pass subprocess arguments as an argument vector and never interpolate untrusted values into a shell command. Preserve path containment, bounded I/O, explicit timeouts, atomic writes, output encoding, and safe error redaction at every relevant boundary.