@xcompiler/cli 0.2.3 → 0.2.4

package/README.md

@@ -1,289 +1,222 @@
-# XCompiler — Extensible Compiler
+<p align="center">
+  <img src="docs/assets/xcompiler-icon.png" alt="XCompiler logo" width="128" height="128" />
+</p>
 
-> Multi-LLM, V-model-driven AI Software Factory CLI
-> Turn one paragraph of natural-language requirements into a runnable, tested, deliverable Python or TypeScript project
-> Apache License 2.0
+<h1 align="center">XCompiler</h1>
 
-[![license](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
-[![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
+<p align="center">
+  <strong>AI Software Factory Runtime</strong>
+</p>
 
-🌐 **Languages**: **EN** (default) · [简体中文](README.CN.md)
+> Turn natural-language requirements into runnable, tested Python or TypeScript projects through an iterative V-model workflow.
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@xcompiler/cli"><img src="https://img.shields.io/npm/v/@xcompiler/cli.svg" alt="npm package" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue.svg" alt="Apache-2.0 license" /></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D24-brightgreen.svg" alt="Node.js >= 24" /></a>
+</p>
+
+Languages: **EN** (default) · [简体中文](README.CN.md)
 
 ---
 
-## What is this
+## What XCompiler Does
 
-XCompiler splits "writing code" into two phases — **compile** and **execute** — modelled on a traditional compiler's `cc` / `a.out`:
+XCompiler is a reusable AI software factory runtime. It compiles a product request into an executable engineering plan, then runs that plan with sandboxed agents, guarded tools, tests, debug loops, audit logs, and resumable project state.
 
 | Command | Role | Input | Output |
 |---|---|---|---|
-| **`xcompiler build`** | **AI Compiler** — translates natural-language requirements into a phase plan and executable current-phase steps | A requirement text (`-i req.md`, `-t topic.md`, or interactive) | `phasePlan.json` + `plan.P1.json` (current phase Step DAG) + `topic.md` + `plan.md` |
-| **`xcompiler run`** | **AI Executor** — runs the current phase from the compiled phase plan | `phasePlan.json` (legacy `plan.json` remains readable) | Runnable Python/TypeScript project + green tests + `docs/05-delivery.md` |
+| `xcompiler build` | Compile requirements into a `phasePlan.json` plus the current phase plan, such as `plan.P1.json` | Requirement text (`-i req.md`, `-t topic.md`, or interactive input) | `topic.md`, `phasePlan.json`, `plan.P1.json`, `plan.md`, `<name>.xc` |
+| `xcompiler run` | Execute the current phase through the V-model workflow | `phasePlan.json` or legacy `plan.json` | Runnable project, tests, docs, audit trail, updated progress |
+| `xcompiler load` | Resume from a project file | `<name>.xc` | Continue the saved phase/task state |
+| `xcompiler append` / `xcompiler evolve` | Add new requirements to an existing project | Existing workspace/project file plus new requirement | Incremental plan and implementation |
+| `xcompiler acp` | Run as an ACP code-agent adapter | stdio JSON-RPC from an IDE/editor | Runtime-backed code-agent events and results |
 
-> Analogy: `xcompiler build` ≈ a compiler turning C source into machine instructions; `xcompiler run` ≈ the CPU executing those instructions.
-> Difference: XCompiler's "instructions" are V-model phases (REQUIREMENT / ARCH / CODE / TEST / REFACTOR / DELIVERY), and each "execution unit" is a sandbox-constrained multi-Agent loop.
-
-Every Step gets a git snapshot and an audit-log entry; failures automatically enter a DEBUG retry loop (≤ 3 rounds).
+The current architecture treats **Runtime as the only business entry point**. CLI and ACP are adapters: they parse input, load config, render output, and listen to Runtime events, while Runtime owns build/run/workflow/agent/tool/plugin/memory behavior.
 
 ---
 
-## Built-in V-model pipeline
-
-XCompiler encodes the **V-model** of software engineering directly as the decomposition skeleton of `xcompiler build` and the execution scheduler of `xcompiler run`. Each phase has mandatory artefacts, a tool whitelist, and a quality gate:
+## Iterative V-Model Pipeline
 
-```text
-                  ┌────────── xcompiler build (AI Compiler) ──────────┐
-                  │                                          │
-   Requirement ──► Intake ──► Clarify ──► PhasePlan ──► plan.P1.json
-        (NL)             │            │
-                         └─ Gate 1 ───┘ Gate 2  (two human confirmation gates)
+XCompiler combines a phase iteration model with the V-model. The planner first creates a high-level `phasePlan.json`, then expands only the active phase into a concrete `plan.P<N>.json`. Each current phase runs a full V-model cycle; future phases stay as goals until they become active.
 
+<p align="center">
+  <img src="docs/assets/iterative-v-model-pipeline.svg" alt="Iterative V-Model Pipeline" />
+</p>
 
-                  ┌─────────── xcompiler run (AI Executor) ──────────────┐
-                  │       topology executes V-model left → right    │
+V-model behavior:
 
-                  REQUIREMENT  ◄──────── verify ─────────►  DELIVERY
-                       │                                        ▲
-                       ▼                                        │
-                     ARCH      ◄───── refactor / docs ─────►  REFACTOR
-                       │                                        ▲
-                       ▼                                        │
-                     CODE      ◄────── test gate ──────────►   TEST
-                       │                                        ▲
-                       └─────────────► DEBUG (≤3 retries) ──────┘
-                                       (auto failure loop)
-```
-
-| Phase | Lead Agent / Skill | Mandatory Artefact | Quality Gate |
-|---|---|---|---|
-| REQUIREMENT | Planner | `topic.md` | Gate 1 human confirmation |
-| ARCH | Architect | `architecture.md`；TypeScript 同步维护 `package.json` | plan lint |
-| CODE | Coder (`patcher` / `author`) | `src/**.{py,ts}` | EditGuard line cap |
-| TEST | Tester (`tester`) | `tests/**.{py,ts}` | **tests exit=0** |
-| DEBUG | Debugger (`debugger`) | fix patch | ≤ `max_debug_retries` |
-| REFACTOR | Refactorer | optimised `src/` | tests do not regress |
-| DELIVERY | Author | `docs/05-delivery.md` | All Steps DONE + entry `--help` =0 |
+- `REQUIREMENT_ANALYSIS`, `HIGH_LEVEL_DESIGN`, `DETAILED_DESIGN`, and `CODE` generate their paired downstream test expectations.
+- `HIGH_LEVEL_DESIGN` defines system-level interfaces, external APIs, third-party libraries, and dependencies.
+- `DETAILED_DESIGN` defines internal module structure and implementation details.
+- Test failures are first recorded as issues, then routed back to the matching upstream stage for Debugger repair.
+- Completed-phase debug must provide a real patch/rewrite or successful verification evidence.
+- Network/API failures are treated as real gates: if the project API fails, the run must repair or switch API instead of hiding the failure.
 
 ---
 
-## System architecture
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│                          CLI layer                               │
-│  xcompiler  ─┬─ xcompiler build   (= xcompiler_build)    AI Compiler                    │
-│         └─ xcompiler run (= xcompiler_run)  AI Executor                    │
-│         + xcompiler ls / show                                         │
-└──────────────────┬───────────────────────────────┬──────────────┘
-                   │                               │
-                   ▼                               ▼
-        ┌────────────────────┐         ┌──────────────────────┐
-        │  Planner (compile) │         │   PhaseEngine (run)  │
-        │  - intake/clarify  │         │   - topology sched.  │
-        │  - decompose (V)   │         │   - DEBUG loop       │
-        │  - plan lint       │         │   - resumable        │
-        └─────────┬──────────┘         └──────────┬───────────┘
-                  │                                │
-                  ▼                                ▼
-            ┌──────────────────────────────────────────────┐
-            │                Agent / Skill layer            │
-            │  Architect · Coder · Tester · Debugger ·     │
-            │  Refactorer · Author                         │
-            │  Skills: patcher / author / tester /         │
-            │          dep_resolver / debugger / refactor  │
-            └──────────────────┬───────────────────────────┘
-                               │
-                               ▼
-        ┌─────────────────────────────────────────────────────┐
-        │             Tool layer (whitelist + EditGuard)       │
-        │  read_file · write_file · append_file ·             │
-        │  replace_in_file · run_program · run_tests · git_*  │
-        └──────────────────┬──────────────────────────────────┘
-                           │
-            ┌──────────────┼──────────────────┐
-            ▼              ▼                  ▼
-   ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
-            │  LLM Router  │ │   Sandbox    │ │   Workspace      │
-   │  chain +     │ │  subprocess  │ │   git + audit    │
-   │  fallback    │ │  / docker    │ │   + .xcompiler/       │
-   │  (ollama,    │ │  venv iso.   │ │ phasePlan/plan.Px │
-   │   openai)    │ │              │ │                  │
-   └──────────────┘ └──────────────┘ └──────────────────┘
-```
+## System Architecture
 
-The runtime also exposes a typed PluginHost across the compile, LLM, run, step,
-attempt and tool boundaries. Plugins can register Tools / Skills without bypassing
-the existing whitelist and EditGuard security model.
+<p align="center">
+  <img src="docs/assets/system-architecture.svg" alt="XCompiler System Architecture" />
+</p>
 
 Layer responsibilities:
 
-- **CLI**: argument parsing, workspace lock, `--force` / `--from` / `--phase` modes.
-- **Planner / PhaseEngine**: top-level scheduler for "compile" and "execute" respectively.
-- **Agent / Skill**: each Skill is a `(role + system prompt + tool whitelist)` bundle bound to one V-model phase.
-- **Tool**: atomic operations, all guarded by EditGuard / whitelist; writes are restricted to a Step's declared `outputs`.
-- **LLM Router**: multi-provider chain + fallbacks with full audit trail.
-- **Sandbox**: Python uses venv/pip/pytest; TypeScript uses npm/tsx/vitest, via subprocess or docker.
-- **Workspace**: git snapshots + `.xcompiler/audit.jsonl` + `.xcompiler/.lock`, fully resumable.
+- **Adapters**: argument/protocol parsing, config loading, user interaction, output rendering, exit codes.
+- **Runtime**: Runtime API, Build Service, Run Service, Event Stream, and Permission Broker; the only business entry point.
+- **Workflow and planning**: phase iteration, V-model scheduling, rollback/debug routing, iteration gates, resume.
+- **Agents / Skills**: role-specific prompts plus allowed tools for each stage.
+- **Tools**: guarded file edits, program/test execution, API fetches, dependency edits, git snapshots.
+- **LLM Router**: role chains, provider scores, cluster fallbacks, OpenAI-compatible/Ollama clients, audit.
+- **Workspace**: `phasePlan.json`, `plan.P<N>.json`, `<name>.xc`, `.xcompiler/audit.jsonl`, debug cache, project memory.
 
 ---
 
-## Quick start
+## Install From npm
 
 ```bash
-# 1. Install dependencies
-npm ci
-cp .env.example .env            # fill OPENROUTER_API_KEY for the default OpenRouter Free provider
-cp config.example.yaml config.yaml
+npm install -g @xcompiler/cli
+mkdir xcompiler-demo && cd xcompiler-demo
+cp "$(npm root -g)/@xcompiler/cli/config.example.yaml" config.yaml
+cp "$(npm root -g)/@xcompiler/cli/.env.example" .env
+# Edit .env and set OPENROUTER_API_KEY
+xcompiler doctor
+```
 
-# 2. Build and install as a global command
-npm run build
-npm link                        # or: npm install -g .
-xcompiler --help
+The default template uses OpenRouter Free mode through a `type: openai` OpenAI-compatible provider:
+
+```yaml
+model: openrouter/free
+base_url: https://openrouter.ai/api/v1
+```
+
+`config.yaml`, `llm_scores.yaml`, and `llm_scores_user.yaml` are local files and are intentionally not committed. The npm package ships `config.example.yaml` and `.env.example` as templates. `llm_scores.yaml` is XCompiler-maintained runtime state; create `llm_scores_user.yaml` only when you want fixed local score overrides such as `provider: 0` to disable one provider.
+
+---
+
+## Quick Start
 
-# 3. Write requirements → compile a plan
+```bash
 echo "Parse a DBC file into an Excel report" > req.md
 xcompiler build -i req.md --yes
-
-# 4. Execute the plan
 xcompiler run /tmp/xcompiler-<timestamp>/phasePlan.json
-
-# 5. Resume later from the generated project file
 xcompiler load /tmp/xcompiler-<timestamp>/xcompiler-<timestamp>.xc
 ```
 
-If you installed the published npm package instead of running from this source tree, create your own local config from the packaged templates first:
+Source checkout development:
 
 ```bash
-npm install -g @xcompiler/cli
-cp "$(npm root -g)/@xcompiler/cli/config.example.yaml" config.yaml
-cp "$(npm root -g)/@xcompiler/cli/.env.example" .env
-# then edit .env and set OPENROUTER_API_KEY
+npm ci
+cp .env.example .env
+cp config.example.yaml config.yaml
+npm run build
+npm link
+xcompiler --help
 ```
 
-`config.yaml` and `llm_scores.yaml` are user/local runtime files. They are intentionally not committed; the npm package only ships `config.example.yaml` and `.env.example` as templates.
-
-Dev mode (no build step):
+Dev mode without linking:
 
 ```bash
-npm run dev -- build
+npm run dev -- build -i req.md --yes
 npm run dev -- run path/to/phasePlan.json
 ```
 
-Incremental evolution on top of an existing workspace:
+Incremental development:
 
 ```bash
-# add a feature against the current project baseline
 xcompiler build -w path/to/workspace -i feature_req.md --intent feature --yes
-
-# or compile + execute in one go
 xcompiler evolve -w path/to/workspace -i refactor_req.md --intent refactor --yes
-
-# append a new requirement through clarification + V-model on the same project
 xcompiler append path/to/workspace/<name>.xc -i feature_req.md --yes
-
-# let stable XCompiler build and qualify its next generation in an isolated worktree
-xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
 ```
 
-### Common options
+Self-bootstrap:
 
-| Command | Option | Purpose |
-|---|---|---|
-| `xcompiler build` | `-i <file>` | Use a requirements file (non-interactive) |
-| `xcompiler build` | `-t <file>` | Reuse a previously clarified `topic.md` and skip Gate 1 |
-| `xcompiler build` | `--intent <greenfield\|feature\|refactor\|self>` | Choose greenfield, incremental, or isolated self-bootstrap planning |
-| `xcompiler build` | `--baseline-plan <file>` | Point incremental planning at an explicit existing `phasePlan.json` or legacy `plan.json` |
-| `xcompiler build` / `xcompiler run` | `--project-file <file>` | Create/update a specific `XXX.xc` project file |
-| `xcompiler build` | `--force` | Override the workspace lock and regenerate the plan |
-| `xcompiler evolve` | `...` | Compile an incremental plan, then immediately execute it in the same workspace |
-| `xcompiler load <XXX.xc>` | — | Load project config/progress and continue the current plan |
-| `xcompiler append <XXX.xc>` | `-i <file>` | Clarify and execute a new incremental requirement on the existing project |
-| `xcompiler bootstrap` | `--promote` | Explicitly fast-forward a qualified candidate; the default only creates a candidate and report |
-| `xcompiler bootstrap` | `--docker-qualification` | Opt into the experimental Docker qualification runner; subprocess is the default |
-| `xcompiler run` | `--reset` | Reset all Steps to PENDING |
-| `xcompiler run` | `--force` | Equivalent to `--reset` + override lock |
-| `xcompiler run` | `--from <stepId>` / `--phase <phase>` | Resume / run only one phase |
-| `xcompiler run` | `--dry-run` | Print topology only |
-| `xcompiler ls` | — | Scan workspace and list every phase plan's status |
-| `xcompiler show <stepId>` | — | Inspect a single Step (definition / outputs / recent audit) |
+```bash
+xcompiler bootstrap -r path/to/XCompiler -i self_req.md --yes
+```
 
 ---
 
-## Default runtime
+## Common Commands
 
-- **LLM**: OpenRouter Free mode by default, configured as an explicit `type: openai` OpenAI-compatible provider.
-  Put `OPENROUTER_API_KEY` in `.env`; `config.example.yaml` already points to `https://openrouter.ai/api/v1` and uses `model: openrouter/free`, so the copied default config is enough for a first validation run.
-  If the key is missing or invalid, XCompiler reports the failing provider, model, base URL, HTTP status/body, and an explicit hint to set `OPENROUTER_API_KEY`.
-  For production-like engineering runs, give each role a dedicated first-choice model and append `openrouter_free` (`model: openrouter/free`, `tags: [cluster]`) as the last fallback in every role chain.
-  Cluster providers default to the lower dynamic score band `0.2..0.5`, so they remain backups unless the dedicated models fail or their scores decay.
-  See [docs/openrouter.md](docs/openrouter.md) for the setup guide and official OpenRouter links.
-- **i18n**: set top-level `locale: en` or `locale: zh` in `config.yaml` to control CLI and prompt language.
-- **Sandbox**: `subprocess` by default (creates an isolated venv at `<workspace>/.sandbox/<project>/`); switch to `docker` for bind-mount + network / resource limits.
-- **Audit**: every run writes `<workspace>/.xcompiler/audit.jsonl` and `docs/process_log.md`, recording all LLM I/O, tool calls and Step state transitions.
-- **Cross-run debug memory**: `<workspace>/.xcompiler/debug_cache.json` persists DEBUG attempts; subsequent `xcompiler run` calls enter Debugger mode with prior failures fed back to the LLM.
+| Command | Purpose |
+|---|---|
+| `xcompiler build -i <file>` | Build a phase plan from a requirement file |
+| `xcompiler build -t <topic.md>` | Reuse a clarified topic and skip Gate 1 |
+| `xcompiler run <phasePlan.json>` | Execute the active phase plan |
+| `xcompiler run --from <stepId>` | Resume from a specific step |
+| `xcompiler run --phase <phase>` | Run only one phase/stage |
+| `xcompiler run --debug-wiki-path <dir>` | Reuse and update a shared layered debug wiki path |
+| `xcompiler load <name.xc>` | Load project config/progress and continue |
+| `xcompiler append <name.xc> -i <file>` | Add a new requirement to an existing project |
+| `xcompiler evolve -w <workspace> -i <file>` | Build and run an incremental change |
+| `xcompiler acp` | Start the ACP code-agent stdio adapter |
+| `xcompiler doctor` | Check config, LLM providers, sandbox, and skills |
+| `xcompiler ls` / `xcompiler show <stepId>` | Inspect plans and recent audit entries |
+| `npm run release:local -- vX.Y.Z` | Prepare a local release commit and tag without pushing |
 
 ---
 
-## Documentation
+## Runtime Defaults
 
-| Path | Content |
-|---|---|
-| [docs/XCompiler_design.md](docs/XCompiler_design.md) | Overall design: V-model phases, Agent / Skill / Tool abstractions, Sandbox & Workspace |
-| [docs/implementation_plan.md](docs/implementation_plan.md) | M1 → M6 milestones and landing steps |
-| [docs/openrouter.md](docs/openrouter.md) | OpenRouter Free-mode setup with `type: openai` provider config |
-| [docs/deploy.md](docs/deploy.md) | Deployment guide (local + Docker) |
-| [docs/plugin_api.md](docs/plugin_api.md) | Typed plugin API, lifecycle hooks, ordering and failure policy |
-| [docs/versioning.md](docs/versioning.md) | Core and Plugin API version sources, sync commands and release checks |
-| [docs/self_bootstrap.md](docs/self_bootstrap.md) | Generational bootstrap, worktree isolation, qualification gates and promotion protocol |
-| [docs/dev_audit_log.md](docs/dev_audit_log.md) | XCompiler's own delivery log (every requirement / decision / artefact / verification) |
-
-> Doc layering:
-> - `docs/` is the single documentation root; design documents use semantic names while V-model run artefacts use the `01-` through `05-` phase prefixes.
-> - `docs/dev_audit_log.md` documents "how we built XCompiler" and is itself a XCompiler deliverable.
-> - `<workspace>/docs/process_log.md` is auto-generated by the runtime `AuditLogger`, recording every interaction of "the user building a Python project with XCompiler" as that product's delivery summary.
+- **LLM**: OpenRouter Free mode by default. Missing/invalid keys produce provider/model/base URL/status/body diagnostics and an explicit `OPENROUTER_API_KEY` hint.
+- **LLM routing**: role-specific provider chains, XCompiler-maintained dynamic scores, user overrides from `llm_scores_user.yaml`, and `tags: [cluster]` fallback score bands for aggregated routes such as `openrouter/free`.
+- **Languages**: Python and TypeScript project generation, testing, execution, and entry checks.
+- **Sandbox**: `subprocess` by default; optional `docker` mode for bind-mount isolation and network/resource limits.
+- **Audit**: every run writes `.xcompiler/audit.jsonl`, LLM stream traces, `docs/process_log.md`, debug cache, debug wiki feedback, and project memory.
+- **Debug wiki**: Debugger issue repairs retrieve LLM-wiki style prior fixes by compact `DebugBrief`. The wiki is a layered Markdown knowledge base: bundled `wiki/system` policy pages, bundled `wiki/agent` calibration pages, and local `wiki/external` issue-resolution pages. Runtime regenerates `index.md` for review, `index.json` for retrieval, and `log.md` for append-only operations. By default it is copied to the XCompiler path (`$XC_PATH/.xcompiler/debug-wiki` when `XC_PATH` is set, otherwise the package/repo root); use `--debug-wiki-path <dir>` to share a different root. Successful issue repairs persist the LLM's `issueResolutionPlan` in `external`; failed reused fixes are marked `needs_review` through feedback overlays and later successful repairs create/correct external entries.
+- **Security gates**: project file access is guarded, write tools are scoped to declared outputs, and sensitive actions can be surfaced as permission events in adapter scenarios.
 
 ---
 
-## Runtime tuning (`config.yaml → agent.*`)
+## Runtime Tuning
 
-LLM routing is configured under `config.yaml → llm.*`. Use `roles.<Role>` arrays for role-specific chains, set `scores.<provider>: 0` to disable a provider, and tune cluster fallback score bounds with `cluster_score_min` / `cluster_score_max` when you want `openrouter/free` to be more or less aggressive as a backup.
+LLM routing is configured under `config.yaml -> llm.*`.
 
 | Field | Default | Effect |
 |---|---|---|
-| `max_rounds_per_step` | 6 | Upper bound on LLM dialogue rounds within a single Step |
-| `max_debug_rounds_per_step` | `max(8, 2 × max_rounds_per_step)` | DEBUG retry round cap |
-| `max_debug_retries` | 3 | Max DEBUG retry count |
-| `max_edit_lines_per_step` | `auto` | EditGuard cumulative write-line cap per Step; `auto` adapts to phase/tools/outputs/prompt context, while a number keeps a fixed hard cap |
-| `max_write_chunk_bytes` | `auto` | `write_file` / `append_file` per-call content byte budget; `auto` adapts to phase/context, while complex work should still split by module/function/class boundaries |
-| `sandbox_limits.network` | `download-only` | unrestricted outbound without published ports; use `off` for isolation; legacy `pypi-only` is rejected |
+| `roles.<Role>` | role dependent | Ordered/scored provider chain for Planner, Architect, Coder, Tester, Debugger |
+| `scores.<provider>` | `1.0` | Backward-compatible initial score; prefer `llm_scores_user.yaml` for manual overrides |
+| `llm_scores_user.yaml` | absent | Local user score overrides; `0` disables, `0.1..1` fixes effective priority |
+| `cluster_score_min/max` | `0.2..0.5` | Dynamic score band for providers tagged `cluster`; user overrides may still use `0.1..1` |
+| `agent.sandboxes.python.mode` | `subprocess` | Python project sandbox backend: local subprocess or Docker |
+| `agent.sandboxes.typescript.mode` | `subprocess` | TypeScript project sandbox backend: local subprocess or Docker |
+| `max_rounds_per_step` | `6` | LLM dialogue limit within a normal step |
+| `max_debug_rounds_per_step` | `max(8, 2 * max_rounds_per_step)` | Debugger round cap |
+| `max_debug_retries` | `3` | Debug retry attempts |
+| `--debug-wiki-path <dir>` | XCompiler path `.xcompiler/debug-wiki` | Shared layered debug wiki root |
+| `max_edit_lines_per_step` | `auto` | Adaptive EditGuard cumulative write-line budget |
+| `max_write_chunk_bytes` | `auto` | Adaptive per-call write chunk budget |
+| `agent.sandboxes.<language>.<local\|docker>.limits.network` | `download-only` | Outbound allowed, no inbound ports; `off` disables network |
 
 ---
 
-## Tests
+## Documentation
 
-```bash
-npm run typecheck
-npm test                        # vitest, ~140 cases
-npm run smoke:ollama            # real ollama end-to-end smoke test
-```
+| Path | Content |
+|---|---|
+| [docs/openrouter.md](docs/openrouter.md) | OpenRouter Free-mode setup and OpenAI-compatible provider notes |
+| [docs/acp.md](docs/acp.md) | ACP code-agent adapter protocol notes |
+| [docs/XCompiler_design.md](docs/XCompiler_design.md) | Core design and V-model concepts |
+| [docs/plugin_api.md](docs/plugin_api.md) | Plugin API, lifecycle hooks, tools, skills |
+| [docs/versioning.md](docs/versioning.md) | Version sources, release script, tag policy |
+| [docs/self_bootstrap.md](docs/self_bootstrap.md) | Self-bootstrap and qualification gates |
+| [docs/deploy.md](docs/deploy.md) | Local, Docker, and native package deployment |
 
 ---
 
-## Deployment
-
-Full steps in [docs/deploy.md](docs/deploy.md):
+## Tests
 
 ```bash
-# A. Local (Node 24 + Python 3)
-npm ci && npm run build && npm link
-xcompiler --help
-
-# B. Docker (multi-stage image + compose)
-docker build -t xcompiler:latest .
-docker compose run --rm xcompiler --help
+npm run version:check
+npm run typecheck
+npm run lint
+npm test
+npm run build
 ```
 
-The image bundles `python3 / git / docker.io / tini`. The sandbox can be `subprocess` (default) or `docker` (DooD — mount `/var/run/docker.sock`).
+Recent local release gate: 49 test files / 473 tests passed.
 
 ---
 

package/config.example.yaml

@@ -42,7 +42,7 @@ llm:
     #   think: false
 
   # 角色 → provider 数组（兼容单字符串）。
-  # 数组里的 provider 按 ScoreStore 评分降序使用；用户手动设置 score=0 时跳过该 provider。
+  # 数组里的 provider 按 ScoreStore 有效评分降序使用；有效评分为用户覆盖优先，否则使用动态评分。
   # 默认只启用 OpenRouter；如需本地备选，取消 providers 中对应块注释并加入各角色数组。
   roles:
     Planner:   [openrouter_free]
@@ -51,10 +51,12 @@ llm:
     Tester:    [openrouter_free]
     Debugger:  [openrouter_free]
 
-  # 评分快照（preflight 与运行时自动维护，落盘到同目录的 llm_scores.yaml）。
-  # 这里可以手工写初值；空 = 全部默认 1.0；显式写 0 表示用户禁用。
+  # 动态评分快照由 XCompiler 自动维护，落盘到同目录的 llm_scores.yaml，请勿手工编辑。
+  # 用户手动指定 provider 分数时，请在 config.yaml 同目录创建 llm_scores_user.yaml；
+  # 用户文件取值范围：0 表示禁用，0.1～1 表示固定覆盖动态优先级。
+  # 这里仅保留为兼容初始值；旧配置里显式写 0 仍表示用户禁用。
   # tags: [cluster] 的聚合/路由 provider 默认动态评分范围为 0.2～0.5；
-  # 可按需调整上下限（min 最低 0.1，max 最高 1.0）。
+  # 可按需调整动态上下限（min 最低 0.1，max 最高 1.0）。用户覆盖文件不受 cluster 动态上限限制。
   cluster_score_min: 0.2
   cluster_score_max: 0.5
   scores: {}
@@ -64,8 +66,6 @@ llm:
   role_fallbacks: {}
 
 agent:
-  # python | typescript
-  language: python
   max_steps: 50
   max_debug_retries: 3
   # Debugger 滑动窗口的硬上限：LLM 持续健康输出时窗口可扩到该值；
@@ -78,29 +78,61 @@ agent:
   # write_file / append_file 单次 content 字节预算。auto 会按 phase/tools/outputs/context 自适应；
   # 大型工程仍应拆成模块/函数/类边界增量写入，而不是单次写巨型文件。
   # max_write_chunk_bytes: auto
-  # subprocess | docker
-  # subprocess (默认)：在嬿主机 venv 内直接 spawn，快但无隔离
-  # docker: 使用系统 docker daemon，bind-mount 工程目录到容器；debug 时直接修改工程代码即生效
-  sandbox: subprocess
-  sandbox_limits:
-    cpu: 1
-    memory_mb: 1024
-    wall_seconds: 60
-    # off | download-only (default) | full
-    #   download-only — outbound HTTP/HTTPS allowed, no inbound port publishing
-    #   pypi-only     — legacy value, rejected because Docker cannot enforce a domain allowlist
-    #   full          — also publishes `expose_ports` to 127.0.0.1 for testing
-    #                   Python / Node network apps from the host side
-    network: download-only
-    # When network=full, container ports listed here are published on
-    # 127.0.0.1:<port> so host-side tests can reach the running app.
-    # expose_ports: [8000]
-  sandbox_docker:
-    # Default image is chosen from agent.language:
-    #   python     -> python:3.11-slim
-    #   typescript -> node:20-slim
-    image: python:3.11-slim
-    workdir: /workspace
-    pull: false
-    docker_bin: docker
-    extra_run_args: []
+  # 目标工程语言由 topic / 现有工程基线判定：明确写 Python/TS 时自动选择；
+  # 无法判断时在澄清阶段询问；非交互或 topic 模式仍无法判断则默认 Python。
+  sandboxes:
+    python:
+      # subprocess | docker
+      mode: subprocess
+      local:
+        sandbox_dir: .sandbox/python
+        python_bin: python3
+        inherit_env: true
+        limits:
+          cpu: 1
+          memory_mb: 1024
+          wall_seconds: 60
+          # off | download-only (default) | full
+          #   download-only — outbound HTTP/HTTPS allowed, no inbound port publishing
+          #   pypi-only     — legacy value, rejected because Docker cannot enforce a domain allowlist
+          #   full          — also publishes expose_ports to 127.0.0.1 for host-side tests
+          network: download-only
+          # expose_ports: [8000]
+      docker:
+        image: python:3.11-slim
+        workdir: /workspace
+        pull: false
+        docker_bin: docker
+        extra_run_args: []
+        sandbox_dir: .sandbox/python
+        limits:
+          cpu: 1
+          memory_mb: 1024
+          wall_seconds: 60
+          network: download-only
+          # expose_ports: [8000]
+
+    typescript:
+      mode: subprocess
+      local:
+        sandbox_dir: .sandbox/typescript
+        inherit_env: true
+        limits:
+          cpu: 1
+          memory_mb: 1024
+          wall_seconds: 60
+          network: download-only
+          # expose_ports: [3000]
+      docker:
+        image: node:24-slim
+        workdir: /workspace
+        pull: false
+        docker_bin: docker
+        extra_run_args: []
+        sandbox_dir: .sandbox/typescript
+        limits:
+          cpu: 1
+          memory_mb: 1024
+          wall_seconds: 60
+          network: download-only
+          # expose_ports: [3000]

package/debug-wiki/README.md

@@ -0,0 +1,12 @@
+# XCompiler Debug Wiki
+
+This directory is a bundled LLM-wiki style knowledge base for Debugger repair.
+
+- `wiki/system/` contains system-level debug policies and safety rules.
+- `wiki/agent/` contains agent-level calibration knowledge derived from recurring LLM failure patterns.
+- `wiki/external/` is created in the runtime copy and stores real project issue resolutions and feedback.
+- `index.md` is regenerated in the runtime copy as a human-readable catalog.
+- `index.json` is regenerated in the runtime copy as a machine-readable retrieval index.
+- `log.md` is an append-only runtime operation log for retrieval, failed reuse, and confirmed repairs.
+
+At runtime XCompiler copies `system` and `agent` pages into the configured debug-wiki root, builds `index.md` and `index.json`, and appends only real project feedback to the `external` layer.

package/debug-wiki/wiki/agent/calibration-fixtures.md

@@ -0,0 +1,33 @@
+---
+id: agent.calibration.fixtures
+layer: agent
+createdAt: "2026-07-18T00:00:00.000Z"
+updatedAt: "2026-07-18T00:00:00.000Z"
+status: active
+category: test_failure
+summary: "Fixture failures require valid samples, not repeated invented data"
+primaryError: "Missing or malformed test fixture"
+debugDemand: "Prefer user/workspace samples, official examples, or tmp_path for simple text; stop inventing complex domain fixtures after failures."
+fingerprints:
+  - "cat:test_failure"
+  - "err:filenotfounderror"
+  - "fixture:malformed"
+symptoms:
+  - "FileNotFoundError in tests"
+  - "Invalid syntax while parsing fixture"
+  - "malformed sample data"
+resolutionPlan: "Read the test and fixture, identify whether the fixture is missing or malformed, then use a real user/workspace/official sample or a minimal tmp_path sample only for simple formats."
+solution: "Tests must create every referenced fixture. For third-party or industry formats, use a real reference sample from user files, workspace files, official docs, upstream tests, or public standards. Do not repeatedly fabricate complex fixtures that the parser rejects."
+evidence:
+  - "Derived from calibration rules FileNotFoundError-test-fixture and fixture-content-malformed"
+language: python
+stats:
+  uses: 0
+  successes: 1
+  failures: 0
+feedback: []
+---
+
+# Fixture debug calibration
+
+Missing and malformed fixtures are test artifact issues. The Debugger should repair the fixture source of truth before changing implementation.