@seemseam/architec 0.2.10 → 0.2.11

package/README.md

@@ -8,89 +8,58 @@
 
 [English](README.md) | [中文](README.zh-CN.md)
 
-Architec is a Python 3.11+ command-line tool that reviews architecture risk in
-code changes. It builds compact evidence from the repository, asks the
-configured LLM to interpret that evidence, and writes advisory reports for
-humans and coding agents.
-
-The practical question it helps answer is:
+Architec is an advisory architecture analysis CLI. It helps answer one
+practical question:
 
 > Will this change make the codebase harder to maintain?
 
-Architec does not edit code, approve merges, or prove runtime correctness. It
-reports risks worth checking: duplicated logic, shadow implementations, unclear
-module boundaries, stale structure, cleanup candidates, hotspots, and topology
-pressure.
-
-## Package Status
-
-This checkout is prepared for Python packaging and has a draft npm launcher:
-
-| Registry | Package name | CLI command | Status in this checkout |
-| --- | --- | --- | --- |
-| PyPI | `architec` | `archi` | Metadata, README, license, and wheel/sdist contents are configured. Do not publish until companion dependencies are available on the target index and a new release version/tag is chosen. |
-| npm | `@seemseam/architec` | `archi` | Scoped launcher package is configured, but the scope ownership, Trusted Publishing setup, and Python dependency chain still need release validation. |
+It reviews current changes by default, asks an LLM to interpret compact
+selected-scope evidence, and reports architecture risks such as duplicated
+logic, shadow implementations, unclear boundaries, stale structure, topology
+pressure, and risky hotspots.
 
-The unscoped npm package name `architec` is already occupied by an unrelated
-package, so npm publishing should use a scope you control. The Python
-distribution name and command name are intentionally different: the
-distribution is `architec`, while the installed console command is `archi`.
+Architec does not make merge decisions and does not edit code. It gives
+structured advice for humans and coding agents to review.
 
-Use registry install commands only after the relevant package page shows the
-intended version. As of this audit, the existing `v0.2.10` tag points to an
-older commit, so a future registry release should use a new version and tag.
+## Why Architec
 
-## Install
+LLM-assisted development can move quickly, but architecture can drift quietly.
+Architec is designed to catch the kinds of issues that accumulate over time:
 
-Architec requires Python 3.11 or newer.
+- repeated implementations and "same idea twice" code;
+- compatibility paths that blur into canonical implementations;
+- changed files crossing intended module boundaries;
+- stale cleanup/archive candidates;
+- high-risk work landing in churn-heavy areas;
+- full-project topology pressure that is easy to miss during local edits.
 
-Local development install from this checkout:
+The default workflow is incremental-first:
 
 ```bash
-python3 -m pip install -e .
-```
-
-The package declares registry-style dependencies on `llmgateway>=0.1.1` and
-`hippocampus>=0.1.7` for PyPI compatibility. If those companion versions are
-not available from your configured package index yet, install the companion
-projects from source first, or wait for their registry releases before using
-normal dependency resolution.
-
-After a verified PyPI release, the expected install form is:
-
-```bash
-python3 -m pip install --user architec
+archi
 ```
 
-Do not add that command to automation until the PyPI project page shows the
-intended version.
-
-npm distribution is prepared as a thin launcher package. After a verified npm
-release, the expected install form is:
+Use full review when you want the whole-project baseline:
 
 ```bash
-npm install -g @seemseam/architec
+archi --full
 ```
 
-That package exposes the same `archi` command, then creates a user-cache Python
-virtual environment on first run and installs the matching Architec GitHub tag.
-It requires Node.js, Python 3.11+, git, and network access on first run.
-
 ## How It Fits Together
 
-Architec is the architecture review layer. It uses two companion components:
+Architec is the review layer. It uses two companion components:
 
 | Component | Command / package | Role |
 | --- | --- | --- |
-| **Architec** | `archi` / `architec` | Runs architecture review, calls the LLM through llmgateway, and writes results under `.architec/`. |
-| **Hippo** | `hippo` / `hippocampus` | Builds structural project snapshots under `.hippocampus/`: file manifests, code signatures, repository indexes, structure prompts, and metrics. |
+| **Architec** | `archi` / `architec` | Runs architecture review, calls the LLM through llmgateway, writes advisory results under `.architec/`. |
+| **Hippos** | `hippos` / `seemseam-hippos` | Builds structural project snapshots under `.hippos/`: file manifests, code signatures, repository indexes, structure prompts, and metrics. |
 | **llmgateway** | `llmgateway` | Owns provider credentials, base URLs, API style, model names, and strong/weak model routing. |
 
 ```text
 source tree + git changes
         |
         v
-Hippo structural snapshot  ->  .hippocampus/
+Hippos structural snapshot  ->  .hippos/
         |
         v
 Architec evidence builder  ->  selected-scope or full-project context
@@ -102,37 +71,93 @@ llmgateway LLM call        ->  strong / weak model tiers
 Architec review output     ->  .architec/
 ```
 
-Day-to-day `archi` runs use the LLM, but they do not refresh the full Hippo
-snapshot unless needed. `archi --full` reviews the whole project. Use
-`archi --refresh-from-hippo --full` when you want to refresh structural inputs
-before a full review.
+Day-to-day `archi` runs still use the LLM, but they avoid refreshing the whole
+Hippos snapshot unless requested. `archi --full` uses the Hippos snapshot more
+heavily, and `archi --refresh-from-hippos --full` refreshes it before review.
+
+## How It Works
+
+Architec combines deterministic code signals with LLM interpretation. The
+deterministic layer keeps the review grounded in concrete evidence; the LLM
+layer turns that evidence into readable architecture advice.
+
+1. **Select scope**
+   - `archi` reads the current git changes and focuses on changed files.
+   - `archi --full` reviews the whole project.
+
+2. **Read structural context**
+   - Hippos produces `.hippos/` snapshots: file manifests, code signatures,
+     repository indexes, metrics, and structure prompts.
+   - Architec checks whether that snapshot is present, stale, or unknown.
+
+3. **Build architecture evidence**
+   - Architec runs static scanners for duplicated logic, shadow
+     implementations, import-boundary pressure, cleanup/archive candidates,
+     hotspots, topology pressure, and snapshot freshness.
+   - Incremental review keeps selected-change concerns separate from broader
+     project context so small diffs are not drowned by global noise.
+
+4. **Ask the LLM for interpretation**
+   - Architec sends compact evidence to llmgateway.
+   - llmgateway chooses the configured strong or weak model tier and owns all
+     provider credentials.
+
+5. **Write advisory output**
+   - Architec ranks concerns, keeps raw artifacts for inspection, and writes
+     human-readable plus machine-readable output under `.architec/`.
+   - The result is advice, not an automatic merge decision or proof of runtime
+     correctness.
+
+## Install
+
+Architec requires Python 3.11+.
+
+Recommended install from PyPI:
+
+```bash
+python3 -m pip install --user architec
+```
+
+This installs:
+
+- `archi`, the Architec CLI;
+- `seemseam-llmgateway`, the package that provides the LLM provider gateway;
+- `seemseam-hippos`, the package that provides Hippos structural snapshots.
+
+The runtime imports remain `llmgateway` and `hippos`; no separate package index
+setup is required.
+
+Local development from this repository:
+
+```bash
+python3 -m pip install -e .
+```
 
 ## Configure LLM Access
 
-Architec gets LLM access through **llmgateway**. Configure provider credentials,
-base URL, API style, and model tiers in:
+Architec gets all LLM access through **llmgateway**. Configure provider
+credentials and model tiers in:
 
 ```text
 ~/.llmgateway/config.yaml
 ```
 
-Minimal shape:
+Minimal example:
 
 ```yaml
 version: 1
 provider:
   provider_type: openai
   api_style: openai_responses
-  base_url: https://your-llm-endpoint.example/v1
-  api_key: <set-locally>
+  base_url: https://your-llm-endpoint/v1
+  api_key: sk-...
 settings:
   strong_model: your-strong-model
   weak_model: your-fast-model
 ```
 
-Keep this file local and do not commit it. Architec does not store LLM provider
-credentials in `.architec/`; llmgateway owns provider configuration and request
-routing.
+Architec consumes the configured `strong_model` and `weak_model` tiers. It does
+not store model-provider credentials itself.
 
 Check the installation and LLM route:
 
@@ -145,60 +170,44 @@ If the check reports missing LLM configuration, update
 
 ## Quick Start
 
-Review the current git changes in the current directory:
+Review the current selected changes:
 
 ```bash
 archi
 ```
 
-Review another project path:
-
-```bash
-archi /path/to/project
-```
-
 Run whole-project architecture review:
 
 ```bash
 archi --full
 ```
 
-Refresh Hippo inputs before whole-project review:
+Save JSON output:
 
 ```bash
-archi --refresh-from-hippo --full
+archi --out review.json
+archi --full --out full-review.json
 ```
 
-Save JSON output:
+Refresh Hippos inputs before full review:
 
 ```bash
-archi --out review.json
-archi --full --out full-review.json
+archi --refresh-from-hippos --full
 ```
 
-## CLI Command Summary
+## Command Summary
 
 | Command | Purpose |
 | --- | --- |
-| `archi` | Incremental LLM architecture review for current git changes. |
-| `archi <path>` | Incremental review for another project root. |
+| `archi` | Incremental LLM architecture review for current selected changes. |
 | `archi --full` | Full-project LLM architecture review. |
-| `archi --refresh-from-hippo --full` | Refresh Hippo structural inputs, then run full review. |
-| `archi --check .` | Validate Hippo bundle state and llmgateway configuration. |
 | `archi --out review.json` | Save incremental review JSON. |
-| `archi --version` | Show the installed CLI version and latest release status when available. |
-| `archi update` | Reinstall the latest public Architec build through the configured installer. |
-| `archi uninstall --yes` | Remove the installed launcher, managed assets, configs, and dependencies. |
+| `archi --full --out full-review.json` | Save full-review JSON. |
+| `archi --refresh-from-hippos --full` | Refresh Hippos structural inputs, then run full review. |
+| `archi --check .` | Validate Hippos bundle state and llmgateway configuration. |
 
-Some compatibility commands and hidden flags remain for older automation, such
-as `archi code-review --full .`, `archi code-review --diff .`, `archi
-plan-review`, `archi status --snapshot`, and `archi fix-advice --review
-review.json`. New users should start with the top-level commands above and
-inspect the installed binary with:
-
-```bash
-archi --help
-```
+Advanced compatibility flags and older subcommands may still be accepted for
+existing automation, but new usage should prefer the commands above.
 
 ## What Architec Reports
 
@@ -210,10 +219,11 @@ Architec reports advisory concerns and signals, including:
 - **Cleanup/archive candidates**: stale or legacy-looking code and docs.
 - **Hotspots**: churn-heavy or structurally risky areas.
 - **Topology pressure**: flat or confusing project structure.
-- **Snapshot freshness**: missing, stale, or unknown Hippo context.
+- **Snapshot freshness**: missing, stale, or unknown Hippos context.
 - **Risk context**: optional external facts attached to existing concerns.
 
-The output is advice, not a pass/fail gate.
+The output is advisory. It is not a pass/fail result and is not proof of
+runtime correctness.
 
 ## Outputs
 
@@ -230,39 +240,36 @@ Architec writes generated files under `.architec/`:
   cache/
 ```
 
-Hippo writes structural inputs under `.hippocampus/`.
+Hippos writes structural inputs under `.hippos/`.
 
-Start with `.architec/architec-summary.md` for the human-readable report. Use
-`.architec/architec-analysis.json` for exact scores, concerns, signals, and
-artifact paths. Both `.architec/` and `.hippocampus/` are generated local
-project state and are normally not package payload.
+Start with `.architec/architec-summary.md` for the human-readable report, then
+open `.architec/architec-analysis.json` for exact scores, concerns, signals,
+and artifact paths.
 
-## Dependencies
+## Agent Command Compatibility
 
-The Python package declares:
+The commands above describe the current public workflow. Some older installed
+`archi` binaries may still show the previous command shape, where full review
+is `archi .` and incremental review is `archi --diff .`.
 
-- `llmgateway>=0.1.1`;
-- `hippocampus>=0.1.7`;
-- `PyYAML`, `certifi`, and `cryptography` from Python package indexes.
+Agents and automation should inspect the local binary before choosing commands:
 
-Before a PyPI release, maintainers must confirm that the companion package
-versions are available from the intended registry. Before an npm release,
-maintainers must confirm the npm scope, Git tag, and Python install target that
-the launcher will use.
+```bash
+archi --help
+```
 
-## No Login Required
+| Help output | Incremental review | Full review |
+| --- | --- | --- |
+| Includes `--full` | `archi` | `archi --full` |
+| Lacks `--full` but includes `--diff` | `archi --diff .` | `archi .` |
 
-Architecture analysis commands do not require `archi login`.
+## No Login Required
 
-Architec sends selected architecture evidence only to the LLM provider
-configured in llmgateway. Review your provider configuration before running
-analysis on private code. Do not commit local provider credentials,
-`.llmgateway/` config, or generated `.architec/` and `.hippocampus/` outputs
-unless you intentionally want to share them.
+Architecture analysis does not require `archi login`.
 
-Account-related commands may exist in the source tree for diagnostics or future
-commercial workflows, but they are not required for the GitHub/local analysis
-workflow described here.
+Account commands such as `archi login`, `archi whoami --json`, and
+`archi devices --json` may exist for diagnostics, but they are not part of
+normal Architec analysis.
 
 ## Development
 
@@ -275,27 +282,10 @@ PYTHONPATH=src python3 -m pytest -q
 Run Architec from this checkout:
 
 ```bash
-PYTHONPATH=src python3 -m architec --help
 PYTHONPATH=src python3 -m architec
 PYTHONPATH=src python3 -m architec --full
 ```
 
-## Release Maintainer Notes
-
-- `pyproject.toml`, `package.json`, and `src/architec/_version.py` currently
-  declare version `0.2.10`.
-- The existing `v0.2.10` tag points to an older commit. Do not reuse or move it
-  for a different release state.
-- Use a new `vX.Y.Z` git tag only after the version, package metadata, README,
-  and dependency strategy are final.
-- Do not publish from a dirty worktree unless that dirty state is explicitly
-  accepted for the release.
-- PyPI publishing should verify the `architec` project name, target version,
-  wheel/sdist contents, dependency resolution, and long description rendering.
-- npm publishing should verify the package scope, `bin` entry, files allowlist,
-  launcher smoke test, and Trusted Publishing configuration.
-- npm release details live in [docs/npm-release.md](docs/npm-release.md).
-
 ## More Documentation
 
 - [Usage manual](docs/usage-manual.md)