v2.9.1 — Fix Python 3.9 install crash (silent shim-generation failure since v2.7.0)

Critical install fix

Everything merged since v2.9.0:

Fix Python 3.9 install crash that silently skipped all shim generation (#99)

Who was affected: any machine whose python3 is 3.9 — notably the macOS-bundled /usr/bin/python3 3.9.6 — running any release from v2.7.0 through v2.9.0. npx @bitraptors/archie printed "Installed!" and exited 0, but wrote no slash commands and no workflow files, so Archie never appeared in Claude Code / Codex. Installs that worked on v2.6.0 and earlier broke on upgrade, because v2.7.0 moved shim generation from pure JavaScript into the Python connector loop.

Root cause: manifest.py used a str | None dataclass annotation without from __future__ import annotations. PEP 604 unions are evaluated at import time on Python 3.9, so the install loop died with a TypeError before writing anything — and the npx installer swallowed the failure.

Changes:

• manifest.py: lazy annotation evaluation — Python 3.9 is fully supported again (verified end-to-end on /usr/bin/python3 3.9.6)
• install.py: Python <3.9 now gets an actionable error message instead of a traceback
• archie.mjs: a missing python3 or a failed install step now prints a prominent "Install INCOMPLETE — no Claude/Codex commands were written" block and exits 1, instead of claiming success
• New regression test (tests/test_py39_compat.py): AST guard that fails the suite if any shipped module uses runtime-evaluated union annotations without the future import

If your install was affected: upgrade and re-run — npx @bitraptors/archie@latest . — no other action needed.

Full changelog: v2.9.0...v2.9.1

v2.9.0 — Product-law layer: domain invariants + product model

Everything merged since v2.8.5 (7 PRs, ~60 commits). Highlights:

Product-law layer — domain invariants + product model (#97)

/archie-deep-scan now captures what the product must do, not just how the code is shaped.

• Domain agent (Wave 1, always-on) extracts observed product laws (domain_invariants), cite-or-omit, stated as product rules with the code-level how in a separate mechanism field. Each law is tagged domain_role (core / supporting / platform); supporting subsystems are rationed so monetization/auth code can't crowd out the core.
• Product agent (Wave 2) adds product_model (overview + value workflow), derived_invariants (>=2-anchor derivation), and unenforced_invariants (advisory gap list, never enforced).
• New domain_invariant rule kind (observed -> blocks, derived -> warns); two-tier product-laws.md + product-model.md; a new PRODUCT viewer section (Product Overview, Product Laws, Unverified Gaps). Works on apps, libraries/SDKs, services, and CLIs.

Rule-file chunking (#94, #96)

Oversized topic rule files are now recursively split into an index + per-section files, so an agent loads only the ~1-5 KB chunk relevant to its task instead of a giant file. Adds an adoption gate for rules discovered on rerun.

Living Blueprint — /archie-sync change ledger (#91)

New /archie-sync records architectural changes and folds eligible claims back into the blueprint + per-folder intent layer (record-only Phase 1 -> fold Phase 2), reporting the architectural delta rather than file/ID accounting. Wired into the manifest with CC + Codex parity.

iOS platform-pitfall detection (#92)

Scanner detects the legacy-Xcode (no folder-sync) signal and requires real .swift files before flagging; finalize seeds platform pitfalls into the blueprint from scan signals (deduped by id).

Benchmark harness — internal (#93, #95)

Internal-only (not shipped via npm): measures Archie's effectiveness (control vs treatment) — git-worktree isolation, headless runner, stream-json metrics (tools/tokens/cost/time), blind A/B judge, Supabase store, per-arm savings, and a run/prep/auto CLI.

v2.8.5

Fixes

• finalize: preserve hand-authored AGENTS.md instead of overwriting it. Deep-scan Step 5 (finalize.py) wrote every rendered file with a blind overwrite, including AGENTS.md — clobbering any hand-curated content (Makefile quick-references, testing tables, etc.). Mergeable files now route through render_mergeable, so user-written content outside Archie's generated markers is preserved. Added a regression test.

Full Changelog: v2.8.4...v2.8.5

v2.8.4

What's changed

Scoped, language-agnostic verification in the "Fix this" prompt (#89)

The viewer's Fix this button no longer dumps a project's entire command catalog as "verification commands." Instead it emits a tiered ## Verifying your fix section:

• Floor (mandatory) — format · fast-lint scoped to changed packages · tests covering changed packages, so an agent can't silently under-verify.
• Conditional tier — build/type-check, regenerate, spec/schema/infra lint — each fires only if the diff touched that area.
• Reference menu — discovered commands, ordered format → lint → typecheck → build → test, that the agent picks the minimal covering set from.
• Fenced ceiling — heavy whole-repo / CI targets land in an explicit "do NOT run per fix" bucket.

Classification is convention-based with zero project-specific names — verified across Go (Make), npm/TS (colon scripts), Python, Rust, and Android (Gradle). The final command selection is handed to the executing agent, so it works in Claude Code, Codex, or any CLI.

Full changelog: v2.8.3...v2.8.4

v2.8.3 — telemetry records deep-scan depth

Telemetry: deep-scan depth

Anonymous, opt-in telemetry now records whether a /archie-deep-scan ran at default or comprehensive depth — so default vs comprehensive runs can be compared (duration, frequency, etc.).

Stored under a generic meta object ({"depth":"comprehensive"}) rather than a dedicated column; other commands send no meta. No new data is collected beyond the depth flag — still no source code, file paths, or repo names. Builds on the comprehensive-depth feature from v2.8.2.

🤖 Generated with Claude Code

v2.8.2 — comprehensive depth + universal ignore system

New: --comprehensive depth for /archie-deep-scan

Opt-in depth that lifts the output caps preventing a truly thorough baseline:

/archie-deep-scan --comprehensive

• A single Comprehensive Mode Contract governs every step: every item-count (rules, findings, pitfalls, decisions, trade-offs, components, guidelines, drift) becomes a floor, not a ceiling — surface everything that meets the quality bar, no upper bound.
• Lifts scope too: full dependency depth, reads .archiebulk content (within the ignore boundary), always-spawn all Wave-1 agents, full-history drift.
• Orthogonal to --incremental (they compose). Default depth is unchanged — same behavior as before, so existing runs are unaffected.
• Kept bounded by design: the architecture diagram (8–12 nodes) and mechanical safety/context budgets.

Validated on a real codebase: findings 7→12, pitfalls 7→9, with the new findings grounding out as real code issues (not padding). Comprehensive runs take materially longer (~2.5–3× a default scan) — that's the cost of exhaustiveness.

Fix: universal ignore system (both depths)

check_rules, refresh, and step-9 drift now honor .gitignore/.archieignore — no more false violations or drift noise on ignored/vendored files. IgnoreMatcher.is_ignored gained gitignore ancestor-directory semantics; new intent_layer.py filter-ignored command backs the drift file list.

🤖 Generated with Claude Code

v2.8.1 — snapshot hygiene + hook-runtime hardening

Patch release: keeps Archie from polluting the repos it runs on, and makes the enforcement hooks self-sufficient.

.archie/ snapshot hygiene

• Every installer path (npx, archie init, archie refresh) now writes a tool-managed .archie/.gitignore so Archie's vendored internals are never committed into your repo — and security scanners stop flagging Archie's own code as if it were yours.
• Excluded: _install_pkg/, viewer/ (+ node deps), all install-only standalone scripts, caches. Committable: your architecture artifacts (blueprint.json, rules.json, scan_report.md, per-folder CLAUDE.md, …).

Hooks work without a local install

• The small hook-runtime script set (_common, lint_gate, align_check, arch_review) is committed and allowlisted, so enforcement hooks run on a fresh clone with no npx step.
• That footprint is hardened: all file reads route through one path-validated sink (_common.safe_read_text), and the lint gate runs linters with shell=False (argv list) instead of an interpolated shell=True command — closing a subprocess-injection vector.

Other

• Viewer dependencies updated (npm audit fix → 0 vulnerabilities); the share-viewer route sentinel renamed to read as routing, not auth.

No changes to the deep-scan/blueprint output — re-running isn't required; this just cleans up what lands in git.

🤖 Generated with Claude Code

v2.8.0 — C4 architecture diagram

2.8.0 bundles everything since v2.7.0 (the interim 2.7.1 bump was never tagged/published, so its changes ship here too).

Deep-scan reasoning restructure

• Wave 2 split into 3 parallel agents (Design / Risk / Overview) instead of one monolithic reasoning agent — tighter, more precise prompts; same blueprint, better per-section accuracy; parallel wall-clock. Atomic merge via a single finalize call; --from 5 redo is idempotent.
• Denser finding/pitfall root_cause — decision + concrete mechanism + pf_NNNN cross-link.
• New check_crosslinks integrity check (WARN-only) and a snapshot/restore test harness for deep-scan state.

Telemetry

• Structured per-step + per-sub-agent summary everywhere — Wave 1 and Wave 2 fact/reasoning agents are individually timed and nested; standalone intent-layer reports its own duration.
• Supabase ingest updated to schema v2 (structured steps + sub-agents).

Rules taxonomy

• Canonical 9-kind rule taxonomy with a classify_kind heuristic; backfill_kinds CLI populates missing kinds; infrastructure kind added; /archie-scan + step-6 prompts aligned to the taxonomy.

C4 architecture diagram (new)

• A C4 Model tab in the viewer/share (Context / Container / Component), built deterministically from the scanner — structure is ground truth, AI is only a fallback for unparsed languages.
• Language-agnostic deployable detection (entry-stem rule + project/deploy manifests covering web, mobile, desktop); Go and Rust import parsing added for the real dependency graph.
• Container binary→datastore edges and component edges come from the real import graph. One build_bundle change feeds both share (Supabase) and the local viewer; no Supabase change. Works identically on Claude Code and Codex.

Viewer

• Surface previously-unshown blueprint data: a standalone Errors section (quick_reference.error_mapping), and pattern scenario triggers ("reach for this when…") folded directly onto the Communications cards.
• Rule-kind badges, hover tooltips explaining each kind, and a kind-distribution donut in Rules Management.

Re-run /archie-deep-scan to pick up the new reasoning structure, telemetry, rule kinds, and the C4 tab.

🤖 Generated with Claude Code

v2.7.0 — Wave 1 Data agent + persistence writers

Highlights

Wave 1 Data agent — a fifth specialist that produces a first-class inventory of the codebase's data models, persistence stores, and per-model lifecycle. The blueprint now answers what data exists, where it lives, how to add/modify/read it, and who writes it — questions the architecture sections couldn't answer before. (PR #79)

Persistence writers — finalize.py derives persistence_stores[*].writers post-Wave-2 by walking data_models and resolving each owned_by_component slug (with ancestor-walk for deep sub-folder paths) to the owning component. Surfaces in both the markdown topic file and the React share viewer as a per-store "Lives here / Written by" chip pair. (PR #81)

What's new

New blueprint sections

• data_overview — AI-written 1-2 sentence summary of the codebase's data shape
• data_models[*] — full inventory with:
  • description (optional, citation-required)
  • fields: [{name, type, description}] — every field, with optional business descriptions where the name doesn't already convey it
  • guarantees[] — schema-level rules (PK / FK / UNIQUE / NOT NULL / audit / soft-delete, etc.)
  • consumers: [{object, file, role}] — which classes/services use this model and how
  • lifecycle: {how_to_add, how_to_modify, how_to_read} — each is {prose, example} with real observed code snippets
  • lifecycle.backup_strategy + lifecycle.tests[]
  • owned_by_component — resolved owner component
• persistence_stores[*] — each with description, engine, role, migrations_dir, backup_strategy, owned_models, and the new derived writers[]

React share viewer

• New Data Models section with sorted Models (by consumer count) and Persistence Stores (by owned-model count)
• Per-model expandable cards showing field tables, guarantees, consumers with roles, and lifecycle code blocks
• Per-store cards with Lives here (model names) + Written by (writer components, teal-tinted chips)
• Architecture Diagram gains an editorial caveat note clarifying it shows the request-flow spine, not exhaustive dependencies

Pipeline changes

• Wave 1: 5th conditional agent ("Data") spawns when has_persistence_signal is detected (ORM dep, schema file, migrations dir, mobile local-persistence API)
• Wave 2 §3 (Probe D): "Data architecture" probe — write fan-in, read fan-out, denormalization, store-role split
• Wave 2 §7: named data-shaped pitfall classes — schema drift, orphan FK, denormalized field drift, missing audit trail, migration-without-model-update
• Wave 2 §8: editorial guidance ("8-12 well-chosen nodes; skip peripheral plumbing — editorial judgment beats coverage")
• Step 6 rule synthesis: new kind: data_contract + two new topics (data-modeling, schema-evolution)
• Step 9 drift: schema-drift focus class
• New .claude/rules/data-models.md topic file

Cross-CLI compatibility

• Both Claude Code and Codex CLI install + run the new Wave 1 Data agent identically through the templated workflow
• data-agent.md prompt byte-identical between .archie/workflow/claude/ and .archie/workflow/codex/; orchestration token-rendered per connector
• Codex archie.rules and Claude ARCHIE_PERMISSIONS cover every script call the new pipeline uses — no new permission prompts at runtime

Other improvements

• Scanner monorepo fix: .archiebulk now resolves by walking up the directory tree (editorconfig/prettier-style, bounded at filesystem root or $HOME, not at .git boundaries). Fixes subpackage scans where frontend_ratio collapsed to 0 because the bulk file lived at the parent monorepo root. Submodules with their own .git no longer block parent's bulk patterns.
• Validator: validate.py data cross-references data_models[*].location, lifecycle paths, store references — soft warnings on dangling references

Compatibility

• Backward compatible: blueprints produced before 2.7.0 render cleanly through the new viewer — legacy key_fields strings appear as Fields-table rows with empty type/description columns; old "Invariants" section renders under the new "Data Guarantees" label
• No breaking schema changes: all new fields are additive
• No new dependencies

Test plan completed

• 640/640 pytest passing (622 baseline + 18 new for writers derivation)
• scripts/verify_sync.py — 31 scripts + all workflow + viewer mirrors aligned
• tsc -b + vite build clean on share/viewer
• Cross-CLI parity verified on fresh install --target=all — workflow trees byte-identical where they should be, token-rendered where they should differ
• Install matrix passes: --target={claude,codex,all,auto}
• Permission audit: no new shell calls outside Claude ARCHIE_PERMISSIONS or Codex COMMAND_RULES
• End-to-end validation on BabyWeather.Android (18 models, 6 stores) — all 6 stores get correct writer attributions

Install / upgrade

npx @bitraptors/archie@2.7.0 /path/to/your/project

🤖 Generated with Claude Code

v2.6.0 — viewer-v2, rich rules, deep-scan skill, telemetry

First npm release since 2.5.3 — an 89-commit catch-up. Highlights:

Added

• Unified local viewer — /archie-viewer now runs the same React UI as the hosted share viewer. Blueprint + Files tabs, per-folder CLAUDE.md browser, click-to-view generated-files tree, an inline rule-management dashboard, and a "Fix this" button that generates agent-agnostic fix prompts for findings & pitfalls.
• Anonymous, opt-in usage telemetry + npm update checks — config.py, telemetry_sync.py, update_check.py, analytics.py. Consent is asked in-session by the slash commands (via a shared _shared/telemetry-consent.md fragment), not by the npx install — so CI / pipe / agent installs can't silently skip it. Three tiers: community / anonymous / off.
• /archie-deep-scan is now a modular skill — a SKILL.md router plus self-contained per-step files and fragments. The long pipeline survives /compact and resumes mid-run (--continue, --from N).
• Rich rules pipeline — rules carry inline severity_class / why / example / forced_by-enables-alternative; the rule synthesizer is the single producer of the unified shape; rule_index.py pre-computes a hot-path enforcement index.
• ARCHIE_TELEMETRY_ENDPOINT env override so test runs can't hit production.

Changed

• AGENTS.md is now the canonical agent context; CLAUDE.md is a thin pointer to it. .claude/rules/ topic files plus a browsable enforcement/ directory.
• Installer hardening — Node 18+ preflight, rejects unknown flags + --help, builds the local viewer at install time (cached by version).
• README + ARCHITECTURE.md fully resynced with the current architecture.

Fixed

• JUST_UPGRADED no longer prints "X → X" (installer overwrote the version marker before mark-upgraded re-read it).
• /archie-scan telemetry runs are now actually uploaded — the legacy telemetry.py path never fired the sync.
• config.py should-prompt answers via a stdout token, so a crash can't masquerade as "already prompted".
• Non-interactive installs surface a clear notice instead of silently skipping telemetry consent.
• Deep-scan Phase 0 scope + Intent Layer prompts are mandatory decision gates, not skippable clarifying questions.
• A degenerate from == to upgrade marker is dropped instead of emitted.

Full changelog: v2.5.3...v2.6.0