graphite-code 1.0.0__tar.gz → 1.1.0__tar.gz

{graphite_code-1.0.0 → graphite_code-1.1.0}/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-1.0.0 → graphite_code-1.1.0}/CHANGELOG.md

@@ -13,6 +13,315 @@ machine-checkable identity; the version is for humans.
 
 [Keep a Changelog]: https://keepachangelog.com/en/1.1.0/
 
+## [Unreleased]
+
+## [1.1.0] — 2026-09-27
+
+A minor release. The agent channel's read surfaces gain fields, which is an
+addition under `docs/compatibility.md`. The channel's audit trail also
+closes three holes: status events taken on trust, deletions nobody saw, and
+an audit gate that could fail open. The graph itself does not change. On
+this repository, measured against the deployed 1.0.1 engine, 7659 of
+7659 node ids survive, 21788 of 21788 edge triples are unchanged, every
+relation count is equal, and `analysis.cycles` is identical. Only the
+engine fingerprint moves, because graphite's own bytes did.
+
+### Added
+
+**Every channel status now says who recorded it, and where each recipient
+stands.** `graphite_channel_list`, `graphite_channel_read` and `graphite
+channel list --json` carry `status_actor`, `status_at` and
+`status_verification` beside `status`, plus `recipients` (each recipient's
+own latest status and its verification, or `null`) and `unreceipted`
+(recipients with no event of any kind). `status` keeps its
+meaning: the newest event by any agent. `graphite_channel_read` also returns
+`history`, where every event carries its actor, time, commit and
+verification grade. `graphite channel show N` prints the same history after
+the body. Measured on the live channel on 2026-09-25: the one folded word
+misstated at least one recipient in 39 of the 212 rounds that carry events.
+Round 256 read `acknowledged` while one of its two recipients had recorded
+nothing. The read tool's description now says that reading records nothing,
+and that `graphite_channel_inbox` registers receipt.
+
+### Fixed
+
+**The channel report now verifies status events against their commits, as it
+already did for rounds.** A status event's `actor` was taken on trust. An
+event written by hand under another agent's trailer, rewritten after its
+commit, or edited and left uncommitted was invisible, because the forged
+actor was a participant and the file was tracked. Each event is now graded
+from one `git log` over `status/`. It is `verified` only when it has exactly
+one commit, a clean working copy, and a trailer naming its actor.
+`status_modified`, `status_discrepancy` and `status_uncommitted` are
+anomalies and fail `ok`. On the live channel all 408 events verified, with
+a planted-forgery control flagged. A comment had claimed this check existed.
+The read surfaces carry the same grade, so an actor is never shown bare:
+`status_verification` sits beside `status_actor`, each recipient's entry has
+its own `verification`, and the human report marks a failing attribution
+`UNVERIFIED`. This closes aramid llm-review finding `53368ee`.
+One trust limit remains, and it is stated here because it bounds what
+"verified" means. Every agent commits under the operator's git identity, so
+a trailer proves which agent label was attached, not which process
+committed. A hand-made commit under the claimed actor's own trailer still
+grades `verified`. Closing that needs signed commits.
+
+**The channel report now sees deletions, and a status event's number is
+never reused.** The report graded only the events and rounds still on disk,
+and a new event took `len(files) + 1`. An agent could therefore delete its
+own `blocked` event, commit the deletion, write a `done` into the same slot,
+and the report still read OK. A round file removed the same way vanished
+from the audit view entirely. The next number is now one past the highest
+the round has ever used, on disk or in history, and a history git cannot
+read refuses the write instead of passing for an empty one. Any status file
+or round that history or the index knows but the working tree lacks is
+reported as `status_deleted` or `round_deleted`, and a hole in a round's
+1..N sequence is reported as `status_seq_gap`. All three fail `ok`. The live channel's history
+holds no deletions or renames, so none fire there. This closes aramid
+llm-review finding `5db5889`.
+
+**Installing the channel's audit gate now fails closed.**
+`ensure_channel_hook` set `core.hooksPath` with `check=False` and always
+reported `changed: True`. A gate git never armed (a locked `.git/config`, or a
+higher-precedence override) was therefore reported as in place, and later
+commits would have passed with no agent trailer. The write now raises on
+failure. The value git will actually use is read back, and anything other
+than `.githooks` raises `hook_not_armed`. `changed` reports the observed
+before-and-after state. This closes aramid llm-review finding `0e87805`.
+
+**Stalling is judged per recipient.** A co-recipient's `done` no longer
+hides a recipient that was handed the round and never followed up. A
+withdrawn or superseded round never stalls. Rows gain `stalled_recipients`.
+The report lists recipients with no receipt per agent under `unreceipted`.
+They are visible but do not fail `ok`, because several registered agents
+have never called inbox, and a check that is always red is one nobody
+reads.
+
+**Reading the channel no longer rewrites its git index.** The report's
+`git status` refreshed stale stat data by rewriting `.git/index` under
+`index.lock`, the lock a concurrent broker `git add` needs. Channel git now
+runs with `GIT_OPTIONAL_LOCKS=0`. A test pins the index bytes across a
+report and a read with stale stat data.
+
+**A PEP 508 marker of the shape `(A) or (B)` was mis-parsed by the doctor's
+MCP distribution walk.** The marker evaluator unwrapped outer parentheses by
+checking only that the text started with `(` and ended with `)`, so
+`(extra == "a") or (python_version == "3.14")` was stripped to
+`extra == "a") or (python_version == "3.14"`. An `extra` marker of that shape
+then failed closed to "does not apply"; a plain marker of that shape raised
+and aborted the whole distribution walk, which is `probe_mcp`'s manifest
+source. Outer parentheses are now unwrapped only when the first `(` is closed
+by the last character, counting depth outside quoted values. Found by the
+new `tests/test_doctor_probes.py`; no installed distribution on the reference
+machine carried the shape, which is why the walk had never failed.
+
+### Changed
+
+**`scripts/mutation_tests.py` targets `scripts/` changes too.** The
+certifying launcher for aramid's mutation gate diffed `src/` only, so a
+mutant in the launcher itself skipped the targeted stage and its confirm ran
+the whole suite (465 s on the gate's first live drain, 2026-09-04, where the
+targeted stage kills in seconds). A changed `scripts/<stem>.py` now targets
+`tests/test_<stem>.py` and `tests/test_<stem>_*.py` like a changed source
+module.
+
+**Twelve modules gained a `tests/test_<stem>.py`.** aramid's mutation stage 1
+runs `tests/test_<module>.py` when it exists and otherwise `pytest -k
+<module>`; a run that selects nothing is booked a stage-1 survivor and every
+such mutant goes to a full-suite confirm, of which an item gets three. Nine
+modules had a `-k` fallback that collected zero tests (`doctor_probes`,
+`dependency_install`, `probe_process`, `ts_bridge`, `_win32_ctypes`,
+`process_contracts`, `routing/ollama_executor`, `routing/context_builder`,
+`routing/route_pool_execution`) and three collected one (`mcp_server`,
+`llm_probe`, `cluster`). Each now has a stage-1 file that pins its pure
+helpers directly; every file was proven able to fail by a hand mutant of its
+module. Three quirks were pinned as-is rather than changed: a cluster's
+kind label is `f"{kind}s"` verbatim (`classs`), a blank path in a TypeScript
+bridge edge normalises to `.` instead of being dropped, and an empty MCP
+`node_id` fuzzy-matches the first node.
+
+## [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:

{graphite_code-1.0.0 → graphite_code-1.1.0}/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,15 +89,18 @@ 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.
 

{graphite_code-1.0.0 → graphite_code-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: graphite-code
-Version: 1.0.0
+Version: 1.1.0
 Summary: Local-first, zero-LLM knowledge graph extraction for codebases.
 Project-URL: Homepage, https://github.com/jared0565/graphite
 Project-URL: Repository, https://github.com/jared0565/graphite
@@ -46,7 +46,22 @@ Description-Content-Type: text/markdown
 
 # Graphite
 
-Local-first, deterministic knowledge graph extraction for codebases. A safer, faster, cheaper replacement for `graphify`.
+Local-first, deterministic knowledge graph extraction for codebases — zero-LLM, daemon-maintained, agent-agnostic.
+
+**Status: 1.1.0, production/stable.** Published on PyPI as
+[`graphite-code`](https://pypi.org/project/graphite-code/) with PEP 740
+attestations; supported on Windows, Linux and macOS with Python 3.11–3.14
+(every cell gates CI). What 1.x promises — CLI, JSON outputs, `graph.json`,
+configuration, exit codes, the launch contract — is in
+[docs/compatibility.md](docs/compatibility.md).
+
+## Documentation
+
+- [User guide](docs/user-guide.md) — install, build the first graph, ask questions, onboard a repository for agents, keep graphs fresh with the daemon, upgrade and verify a release.
+- [Knowledge base](docs/knowledge-base.md) — symptoms, causes and remedies collected from operating graphite; read it before filing an issue.
+- [Agent integration guide](docs/agent-integration.md) — how a coding agent or script drives the query interface and grades its answers.
+- Reference, each page kept in lockstep with the code by a test: [CLI](docs/reference/cli.md), [configuration](docs/reference/configuration.md), [exit codes](docs/reference/exit-codes.md), [compatibility and support](docs/compatibility.md), [benchmarks](docs/benchmarks.md).
+- [Security policy](SECURITY.md) — supported versions and the private reporting path.
 
 ## Principles
 
@@ -68,16 +83,26 @@ Local-first, deterministic knowledge graph extraction for codebases. A safer, fa
 ## Installation
 
 ```bash
-git clone https://github.com/jared0565/graphite
-cd graphite
-pip install -e .
-```
-
-Requires Python 3.11 or newer. No model SDK or provider credential is required
-for canonical graph operation.
-
-An editable install is what makes `python -m graphite` work from any repository
-on the machine, which is how every onboarded project reaches it.
+python -m pip install --user graphite-code
+graphite --version          # version, engine fingerprint, cache and schema versions
+```
+
+The distribution is `graphite-code` (PyPI's `graphite` is another project);
+the import package is `graphite` and the console scripts are `graphite` and
+`graphite-mcp`. Requires Python 3.11–3.14. No model SDK or provider
+credential is required for canonical graph operation. Every release is built
+by CI from its tag, published with PEP 740 attestations, and verifiable from
+the index — see "Upgrading and verifying a release" in the
+[user guide](docs/user-guide.md).
+
+Installing for one interpreter is what makes `python -P -m graphite` work
+from any repository on the machine, which is how every onboarded project
+reaches it. Keep the `-P`: without it Python puts the current directory
+first on `sys.path`, so a `graphite.py` or `graphite/__init__.py` planted at
+a repository root would be imported instead of the installed package. The
+console scripts are immune by construction. Contributors install the clone
+editable into a virtual environment **outside** the checkout — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## System readiness and optional integrations
 
@@ -130,7 +155,7 @@ node "$GRAPHITE_PACKAGE_VALIDATOR" mcp || exit 1
 Only after the applicable validator command succeeds, enable the declared extra:
 
 ```bash
-python -m pip install -e ".[mcp]"
+python -m pip install --user "graphite-code[mcp]"
 ```
 
 The deep MCP probe launches an isolated interpreter from a guarded distribution-record import manifest. It rejects current working directory, user-site, and attacker-controlled selected-root shadows. The exact origin-verified trusted Graphite source may be inside the selected repository, but it is accepted only when its expected lexical, canonical, filesystem-identity, and module-origin checks all match; overlapping MCP dependency or distribution-metadata roots and alternate Graphite origins remain rejected.
@@ -162,7 +187,7 @@ Canonical commands ignore ambient `GRAPHITE_LLM*` settings and never read `GRAPH
 
 ## Machine-wide usage
 
-Installed editable, `python -m graphite` works from any project in any shell. The `graphite` / `graphite-mcp` console-script shims are equivalent wherever they are on PATH, but a shim directory that PowerShell and cmd see is not always on Git Bash's PATH — prefer `python -m graphite` in scripts and agent instructions.
+Installed for an interpreter, `python -P -m graphite` works from any project in any shell. The `graphite` / `graphite-mcp` console scripts are equivalent wherever they are on PATH — and shadow-proof by construction — but a scripts directory that PowerShell and cmd see is not always on Git Bash's PATH, so prefer `python -P -m graphite` in scripts, hooks and agent instructions. Everything `graphite init` generates (hooks, `.mcp.json`, editor tasks, daemon launchers) already carries the `-P`.
 
 To onboard a new or existing project, run one command from anywhere:
 
@@ -173,9 +198,9 @@ python -m graphite bootstrap /path/to/MyApp   # minimal variant: gitignore + AGE
 
 The machine-wide daemon (`graphite daemon /path/to/projects`) auto-discovers any project with standard markers (`.git`, `package.json`, `pyproject.toml`, `wrangler.toml`, `go.mod`, `Cargo.toml`) and keeps its graph fresh, so `init` is about wiring agent instructions, not registration. To exclude a directory (and its whole subtree) from supervision — e.g. a third-party SDK checkout — drop a `.graphite-ignore` file in it; the daemon skips it at the next discovery cycle.
 
-Set `GRAPHITE_PROJECTS_ROOT` to change the default base folder used by `daemon`, `daemon-status`, `daemon-health`, the Windows startup installers, and init/bootstrap daemon-visibility checks (defaults to the current directory when unset).
+Set `GRAPHITE_PROJECTS_ROOT` to change the default base folder used by `daemon`, `daemon-status`, `daemon-health`, the platform daemon installers, and init/bootstrap daemon-visibility checks (defaults to the current directory when unset).
 
-After upgrading graphite itself, restart the daemon: a long-running daemon keeps executing the code it loaded at start, and daemon state is in-memory only, so a restart both loads the new code and rebuilds every supervised graph — clearing `engine_changed` staleness across all managed projects in one pass.
+After upgrading graphite itself, restart the daemon — stop it, install, then start — because a long-running daemon keeps executing the code it loaded at start. A daemon started under the new code detects the engine change itself and rebuilds every supervised graph, clearing `engine_changed` staleness across all managed projects in one pass.
 
 ## Usage
 
@@ -257,13 +282,13 @@ graphite bootstrap C:/Projects/MyApp
 # Check daemon health
 graphite daemon-health C:/Projects
 
-# Audit whether Graphite can replace Graphify for a project
+# Audit whether Graphite can replace legacy graph tooling in a project
 graphite audit-replacement C:/Projects/MyApp
 ```
 
-## Graphify replacement audit
+## Legacy replacement audit
 
-Use the replacement audit before removing legacy Graphify files or ignore entries:
+Use the replacement audit before removing a legacy graph tool's files or ignore entries:
 
 ```bash
 graphite audit-replacement C:/Projects/MyApp
@@ -271,7 +296,7 @@ graphite audit-replacement . --json
 graphite audit-replacement . --fail-on-blocker
 ```
 
-The audit checks Graphite bootstrap state, graph freshness and validity, daemon visibility, daemon health, physical Graphify remnants, and Graphify text/config references. It reports recommendations but never deletes files automatically.
+The audit checks Graphite bootstrap state, graph freshness and validity, daemon visibility, daemon health, physical legacy-tool remnants, and legacy text/config references. It reports recommendations but never deletes files automatically.
 
 ## Daemon health
 
@@ -750,14 +775,17 @@ Then use `/graphite [path]` inside Claude Code. The skill defaults to zero-LLM m
 
 Complete the mandatory package-validation policy and MCP activation steps in [System readiness and optional integrations](#system-readiness-and-optional-integrations). Do not bypass or reorder the validator and install steps.
 
-Then configure Claude Code (Desktop) to use the local server. Add this to your `claude_desktop_config.json`:
+`graphite init` writes a project-local `.mcp.json` entry for Claude Code and
+Codex (and rewrites its own entry on every run, preserving foreign ones). To
+configure a client by hand, launch the server with `-P` — or use the
+`graphite-mcp` console script, which needs no flag:
 
 ```json
 {
   "mcpServers": {
     "graphite": {
       "command": "python",
-      "args": ["-m", "graphite.mcp"],
+      "args": ["-P", "-m", "graphite.mcp"],
       "cwd": "C:/Projects/YourProject"
     }
   }