@xcompiler/cli 0.2.2 → 0.2.4

package/debug-wiki/wiki/agent/calibration-network-api.md

@@ -0,0 +1,36 @@
+---
+id: agent.calibration.network-api
+layer: agent
+createdAt: "2026-07-18T00:00:00.000Z"
+updatedAt: "2026-07-18T00:00:00.000Z"
+status: active
+category: network_api_failure
+summary: "Network/API failures are real gates and require endpoint repair or replacement"
+primaryError: "HTTP/API probe failed or returned unusable data"
+debugDemand: "Identify the failed URL/status, reject unusable responses, switch to a suitable API when needed, patch the integration, and verify."
+fingerprints:
+  - "cat:network_api_failure"
+  - "http:401"
+  - "http:403"
+  - "http:404"
+  - "http:429"
+  - "http:500"
+symptoms:
+  - "Network API failure detected"
+  - "HTTP 401/403/404/429/5xx"
+  - "http_fetch loops or empty body"
+resolutionPlan: "Use at most two probes, choose a reachable and schema-compatible API, then patch the real integration and validate with run_program plus tests."
+solution: "Do not hide API failures with static fake data. For 401/403 without user credentials, switch to a no-key public API. For 404/410, replace the endpoint. For 429, add fallback/timeout/caching or use a less constrained API. HTTP 2xx with empty or unparsable body is not a usable API."
+evidence:
+  - "Derived from calibrateDebugSuggestions network-api-failure and network-api-probe-loop rules"
+language: python
+stats:
+  uses: 0
+  successes: 1
+  failures: 0
+feedback: []
+---
+
+# Network/API debug calibration
+
+API failures are functional failures. The Debugger must repair the integration or switch API and verify the entrypoint.

package/debug-wiki/wiki/agent/calibration-python-imports.md

@@ -0,0 +1,33 @@
+---
+id: agent.calibration.python-imports
+layer: agent
+createdAt: "2026-07-18T00:00:00.000Z"
+updatedAt: "2026-07-18T00:00:00.000Z"
+status: active
+category: import_error
+summary: "Python import failures require real module/dependency repair"
+primaryError: "ModuleNotFoundError or ImportError"
+debugDemand: "Inspect actual src/tests layout, fix imports or add real dependencies, and never fake missing modules in production code."
+fingerprints:
+  - "cat:import_error"
+  - "err:modulenotfounderror"
+  - "err:importerror"
+symptoms:
+  - "ModuleNotFoundError"
+  - "cannot import name"
+  - "from src.<module> import"
+resolutionPlan: "Read the failing file and target module, compare actual symbols and paths, then patch the import or create the missing output/dependency."
+solution: "Use sibling module imports inside src and tests. If the missing name is a third-party import, add the real package name, not an import alias. Never add try/except ImportError fake modules, fake classes, or production mocks to bypass the error."
+evidence:
+  - "Derived from calibration rules ModuleNotFoundError, ImportError-name, src-prefix-import, mock-patch-target-src-prefix"
+language: python
+stats:
+  uses: 0
+  successes: 1
+  failures: 0
+feedback: []
+---
+
+# Python import debug calibration
+
+Import errors are contract signals. Fix the import graph or dependency manifest; do not simulate the missing dependency.

package/debug-wiki/wiki/system/debug-issue-flow.md

@@ -0,0 +1,29 @@
+---
+id: system.debug.issue-flow
+layer: system
+createdAt: "2026-07-18T00:00:00.000Z"
+updatedAt: "2026-07-18T00:00:00.000Z"
+status: active
+category: unknown
+summary: "Issue-first debug flow with explicit resolution plans"
+primaryError: "Debug attempts must repair recorded issues instead of hiding failures"
+debugDemand: "Record issue evidence, require an explicit issueResolutionPlan, apply a minimal repair, and verify before resolving."
+fingerprints:
+  - "cat:unknown"
+  - "debug:issue-resolution-plan"
+symptoms:
+  - "Debugger receives a routed issue"
+  - "Attempt claims done without a reusable repair plan"
+solution: "Treat every Debugger retry with issueId as issue handling. The LLM must output issueResolutionPlan before or while fixing the issue. The plan should state root cause hypothesis, target files/contracts, verification gate, and disconfirming evidence. Resolve only after a successful repair or verification action."
+evidence:
+  - "issueResolutionPlan is persisted to the issue and external wiki after success"
+stats:
+  uses: 0
+  successes: 1
+  failures: 0
+feedback: []
+---
+
+# Issue-first debug flow
+
+Failures become issues first. Debugger repairs the issue, not the symptom. The repair plan is reusable knowledge and must survive in the external wiki after the issue is resolved.

package/debug-wiki/wiki/system/no-poisoning.md

@@ -0,0 +1,29 @@
+---
+id: system.debug.no-poisoning
+layer: system
+createdAt: "2026-07-18T00:00:00.000Z"
+updatedAt: "2026-07-18T00:00:00.000Z"
+status: active
+category: tool_loop
+summary: "Do not poison XCompiler with generated project-specific fixes"
+primaryError: "Generated project failures must be fixed through process or agent behavior, not hardcoded into XCompiler."
+debugDemand: "Fix Debugger/Coder workflow, tool contracts, or prompts; never add generated project fixtures or domain-specific hacks to XCompiler core."
+fingerprints:
+  - "cat:tool_loop"
+  - "policy:no-poisoning"
+symptoms:
+  - "A real sample project fails repeatedly"
+  - "Proposed fix adds project fixture or generated-project rule into XCompiler"
+solution: "When a generated project exposes a recurring failure, fix the generic agent/tool/debug process. Do not add DBC/news/test-project-specific fixtures, hardcoded APIs, or one-off output rules to XCompiler core. External wiki entries may record the project issue and solution, but system/agent rules must remain general."
+evidence:
+  - "Project-specific hardcoding is treated as poisoning"
+stats:
+  uses: 0
+  successes: 1
+  failures: 0
+feedback: []
+---
+
+# No poisoning
+
+XCompiler can learn from generated projects, but the learning must be generalized. Specific project artifacts belong to the generated project or the external wiki layer.

package/dist/acp/index.d.ts

@@ -129,6 +129,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
         refactor: "refactor";
         self: "self";
     }>>;
+    phaseId: z.ZodDefault<z.ZodString>;
     projectType: z.ZodDefault<z.ZodEnum<{
         application: "application";
         library: "library";
@@ -222,6 +223,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
     version: "1";
     language: "python" | "typescript";
     intent: "greenfield" | "feature" | "refactor" | "self";
+    phaseId: string;
     projectType: "application" | "library" | "mixed";
     requirementDigest: string;
     globalPrompt: string;
@@ -278,6 +280,7 @@ declare const PlanSchema: z.ZodPipe<z.ZodObject<{
     version: "1";
     language: "python" | "typescript";
     intent: "greenfield" | "feature" | "refactor" | "self";
+    phaseId: string;
     projectType: "application" | "library" | "mixed";
     requirementDigest: string;
     globalPrompt: string;
@@ -362,6 +365,12 @@ interface ChatOptions {
      * 空输出、model token loop 等“表面成功但语义不可用”场景。
      */
     validate?: (text: string) => void;
+    /**
+     * Whether a provider response should increase its dynamic score.
+     * Step/workflow executors should disable this and score quality through
+     * their own validation instead of treating "returned text" as task success.
+     */
+    scoreSuccess?: boolean;
     /**
      * 调用者可传入回调，与 LLM 输出一同拿到实际产出该响应的 provider 名。
      * 主要用于追溯：在 FallbackClient 中服务于响应的是链中某一个后选 provider，
@@ -421,11 +430,12 @@ declare class AuditLogger {
     llmResponse(role: string, model: string, content: string, meta?: Record<string, unknown>): Promise<void>;
     llmError(role: string, model: string, err: unknown): Promise<void>;
     /**
-     * 记录一轮 Executor 思考：thoughts 文本、计划调用的 actions、是否完成。
-     * 写入 jsonl + markdown 折叠块，交付时可作为"AI 思考过程完整记录"。
+     * 记录一轮 Executor 执行摘要：简短 intent、issue 处理方案、计划调用的 actions、是否完成。
+     * 写入 jsonl + markdown 折叠块，交付时可追溯每轮决策和动作。
      */
     executorTurn(stepId: string, role: string, round: number, payload: {
         thoughts?: string;
+        issueResolutionPlan?: string;
         actions?: unknown[];
         done?: boolean;
         raw?: string;
@@ -489,11 +499,23 @@ interface ExecResult {
     stderr: string;
     timedOut: boolean;
     durationMs: number;
+    timeoutReason?: string;
+}
+interface ExecProgressWatch {
+    /** Host-side paths whose recursive size indicates install progress. */
+    paths: string[];
+    /** Kill the child only after this much time without size growth. */
+    idleTimeoutMs: number;
+    /** Poll interval for recursive size checks. */
+    checkIntervalMs?: number;
+    /** Human-readable label used in timeout diagnostics. */
+    label?: string;
 }
 interface ExecExtra {
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
+    progressWatch?: ExecProgressWatch;
 }
 /** 沙盒统一接口。任意 phase / tool 都通过此接口与运行时交互。 */
 interface Sandbox {
@@ -515,7 +537,7 @@ interface Sandbox {
     /**
      * 运行工程入口程序。
      *  - Python：`python <args>`（自动选用 venv 内解释器）。
-     *  - TypeScript：`npx tsx <args>`。
+     *  - TypeScript：默认 `npx tsx <entry>`；当 args 以 `npm`/`npx`/`node`/`tsx`/`tsc` 开头时执行对应项目命令。
      */
     runProgram(args: string[], extra?: ExecExtra): Promise<ExecResult>;
     /**
@@ -577,6 +599,8 @@ interface ToolContext {
     language?: Language;
     /** 当前 Step 的 write_file / append_file 单次 content 字节预算。 */
     writeChunkBytes?: number;
+    /** run_tests 未提供有效过滤参数时使用的当前阶段默认测试范围。 */
+    defaultTestArgs?: string[];
     /** Optional protocol/UI permission hook for sensitive tool operations. */
     requestPermission?: ToolPermissionRequester;
     /** Optional protocol/UI event hook for tool calls and file changes. */
@@ -653,6 +677,8 @@ interface HookContextMap {
     'compile.finish': {
         plan: Plan;
         planPath: string;
+        phasePlanPath?: string;
+        currentPlanPath?: string;
     };
     'run.before': {
         plan: Plan;
@@ -868,7 +894,7 @@ interface CompileOptions {
      * 已澄清的 topic.md 直接输入：跳过 intake / clarify / Addenda / Gate 1，把该文件
      * 内容当作冻结后的项目选题书，直接进入 decompose。常用于：
      *   - 用户上次已澄清并保留了 topic.md，重新跑 decompose 不想再问一遍
-     *   - 离线编辑了 topic.md 想直接拿来出 plan.json
+     *   - 离线编辑了 topic.md 想直接拿来出 phasePlan.json 与当前阶段计划
      * 与 --input 互斥；同时给则 --topic 优先并打印警告。
      */
     topicFile?: string;
@@ -924,6 +950,8 @@ interface ExecuteOptions {
     force?: boolean;
     /** Optional XXX.xc project file to keep in sync with execution progress. */
     projectFilePath?: string;
+    /** Optional debug wiki root directory. Defaults to XCompiler's own .xcompiler/debug-wiki. */
+    debugWikiPath?: string;
     /** Project-file history command label; defaults to run. */
     projectCommand?: string;
     /** Whether to append a history row when execution starts; defaults to true. */