@xcompiler/cli 0.2.3 → 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

@@ -430,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;
@@ -498,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 {
@@ -937,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. */