@winspan/claude-forge 8.54.4 → 9.2.0

package/dist/core/diagnostics/knip-runner.js

@@ -0,0 +1,100 @@
+/**
+ * knip static dead-code runner (spec f3dc1397 Option B2).
+ *
+ * Wraps the locally-installed `knip` binary and normalizes its `--reporter
+ * json` output into a compact `KnipReport` (counts + top-N lists). This is the
+ * "static dead-code / orphan-file" layer that the spec deliberately keeps OUT
+ * of `cf doctor` (knip needs build artifacts, is slower, and has occasional
+ * false positives that would pollute the always-on doctor signal).
+ *
+ * Baseline handling (spec §B2 关键): this is a mature codebase, so knip's first
+ * run WILL report a backlog of pre-existing dead code. We therefore run knip
+ * with `--no-exit-code` and present the findings as INFORMATION — `cf entropy`
+ * never fails the build on existing entropy. Use the reported numbers as a
+ * baseline to track over time, not a hard gate.
+ *
+ * Graceful degradation: if the knip binary is absent (not yet `npm install`ed),
+ * `runKnip` returns `{ available: false }` rather than throwing, so `cf
+ * entropy --static` prints an install hint instead of crashing.
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+function defaultBinExists(cwd) {
+    return fs.existsSync(path.join(cwd, 'node_modules', '.bin', 'knip'));
+}
+function defaultSpawn(cwd) {
+    const bin = path.join(cwd, 'node_modules', '.bin', 'knip');
+    const res = spawnSync(bin, ['--reporter', 'json', '--no-exit-code', '--no-progress'], { cwd, encoding: 'utf-8', maxBuffer: 32 * 1024 * 1024 });
+    return {
+        stdout: res.stdout ?? '',
+        status: res.status,
+        error: res.error ?? undefined,
+    };
+}
+/**
+ * knip --reporter json emits `{ files: string[], issues: [{ file, exports,
+ * dependencies, ... }] }`. We flatten exports/dependencies across issues and
+ * surface `files` as unused (orphan) files.
+ */
+function parseKnipJson(raw) {
+    const unusedFiles = [];
+    const unusedExports = [];
+    const unusedDependencies = [];
+    if (!raw.trim())
+        return { unusedFiles, unusedExports, unusedDependencies };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { unusedFiles, unusedExports, unusedDependencies };
+    }
+    const obj = parsed;
+    if (Array.isArray(obj.files))
+        unusedFiles.push(...obj.files);
+    const nameOf = (e) => typeof e === 'string' ? e : e?.name ?? null;
+    for (const issue of obj.issues ?? []) {
+        const file = issue.file ?? '';
+        for (const e of issue.exports ?? []) {
+            const n = nameOf(e);
+            if (n)
+                unusedExports.push(file ? `${file}: ${n}` : n);
+        }
+        for (const t of issue.types ?? []) {
+            const n = nameOf(t);
+            if (n)
+                unusedExports.push(file ? `${file}: ${n} (type)` : `${n} (type)`);
+        }
+        for (const d of issue.dependencies ?? []) {
+            const n = nameOf(d);
+            if (n)
+                unusedDependencies.push(n);
+        }
+    }
+    return { unusedFiles, unusedExports, unusedDependencies };
+}
+export async function runKnip(deps) {
+    const cwd = deps?.cwd ?? process.cwd();
+    const binExists = deps?.binExists ?? defaultBinExists;
+    const spawn = deps?.spawn ?? defaultSpawn;
+    if (!binExists(cwd)) {
+        return {
+            available: false,
+            reason: 'knip is not installed. Run `npm install` (knip is a devDependency).',
+        };
+    }
+    const { stdout, status, error } = spawn(cwd);
+    if (error) {
+        return { available: false, reason: `knip failed to spawn: ${error.message}` };
+    }
+    const { unusedFiles, unusedExports, unusedDependencies } = parseKnipJson(stdout);
+    return {
+        available: true,
+        unusedFiles,
+        unusedExports,
+        unusedDependencies,
+        exitCode: status ?? 0,
+    };
+}
+//# sourceMappingURL=knip-runner.js.map

package/dist/core/diagnostics/knip-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knip-runner.js","sourceRoot":"","sources":["../../../src/core/diagnostics/knip-runner.ts"],"names":[],"mappings":"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"}

package/dist/core/diagnostics/markers.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Onboarding marker files (spec ed8cf2db).
+ *
+ * Two marker files communicate "onboarding completed" state between the
+ * `cf init` / `cf project init` aggregator commands (spec 1) and the future
+ * `cf doctor` / `cf fix` diagnostic commands (spec 2):
+ *
+ *   - `~/.claude-forge/system-installed.json` — system-level (hooks, daemon,
+ *     LaunchAgent) onboarding state
+ *   - `<project_root>/.forge-installed.json` — per-project (CLAUDE.md,
+ *     `.forge-knowledge/`, `.gitignore`) onboarding state
+ *
+ * Markers are write-overwrite (no merging) — callers decide whether to noop
+ * before re-writing. Reads return `null` if the file is missing or malformed.
+ *
+ * Schema is a frozen contract between spec 1 (this file) and spec 2
+ * (doctor); any schema change MUST update both specs and bump `version`.
+ */
+export declare const SYSTEM_MARKER_FILENAME = "system-installed.json";
+export declare const PROJECT_MARKER_FILENAME = ".forge-installed.json";
+export declare const MARKER_SCHEMA_VERSION = 1;
+/** Per-step status used in project marker. */
+export type StepStatus = 'ok' | 'skipped' | 'failed';
+export interface SystemMarker {
+    version: 1;
+    /** ISO-8601 timestamp of (re-)initialization. */
+    initialized_at: string;
+    /** `package.json` version of claude-forge that wrote the marker. */
+    claude_forge_version: string;
+    /** Whether the macOS LaunchAgent was installed during onboarding. */
+    launchd_installed: boolean;
+    /** `process.platform` at time of write. */
+    platform: NodeJS.Platform;
+    /** Whether `cf init --full` was used (vs. plain `cf init`). */
+    full_mode: boolean;
+}
+export interface ProjectMarker {
+    version: 1;
+    initialized_at: string;
+    claude_forge_version: string;
+    /** Detected project type (node / python / rust / go / generic). */
+    project_type: ProjectType;
+    /** Per-step status (each step writes its own outcome). */
+    steps: {
+        claudemd: StepStatus;
+        knowledge: StepStatus;
+        gitignore: StepStatus;
+    };
+}
+export type ProjectType = 'node' | 'python' | 'rust' | 'go' | 'generic';
+export declare function systemMarkerPath(homeDir?: string): string;
+export declare function readSystemMarker(homeDir?: string): SystemMarker | null;
+export interface WriteSystemMarkerInput {
+    launchd_installed: boolean;
+    full_mode: boolean;
+    platform?: NodeJS.Platform;
+    /** Override version for tests. */
+    claude_forge_version?: string;
+    /** Override timestamp for deterministic tests. */
+    initialized_at?: string;
+}
+/**
+ * Write the system marker. Creates parent dir if needed. Returns the marker
+ * object that was written so callers can use it for summary output.
+ *
+ * Idempotency contract: callers are responsible for deciding whether to
+ * re-write. This function always overwrites if called.
+ */
+export declare function writeSystemMarker(input: WriteSystemMarkerInput, homeDir?: string): SystemMarker;
+export declare function projectMarkerPath(projectRoot: string): string;
+export declare function readProjectMarker(projectRoot: string): ProjectMarker | null;
+export interface WriteProjectMarkerInput {
+    project_type: ProjectType;
+    steps: ProjectMarker['steps'];
+    claude_forge_version?: string;
+    initialized_at?: string;
+}
+export declare function writeProjectMarker(projectRoot: string, input: WriteProjectMarkerInput): ProjectMarker;
+/**
+ * Detect project type by manifest-file priority. Pure file-system probe;
+ * no side effects, no dependency on storage or daemon.
+ *
+ * Priority order (spec ed8cf2db §3):
+ *   1. package.json  → node
+ *   2. pyproject.toml → python
+ *   3. Cargo.toml    → rust
+ *   4. go.mod        → go
+ *   5. else          → generic (assumed git repo)
+ */
+export declare function detectProjectType(projectRoot: string): ProjectType;
+/**
+ * Check whether the given directory is a git repository root (has `.git/`).
+ * Used as fail-fast precheck in `cf project init`.
+ */
+export declare function isGitRepo(projectRoot: string): boolean;
+//# sourceMappingURL=markers.d.ts.map

package/dist/core/diagnostics/markers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/markers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AASH,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAC9D,eAAO,MAAM,uBAAuB,0BAA0B,CAAC;AAE/D,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC,8CAA8C;AAC9C,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,CAAC,CAAC;IACX,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;IACvB,oEAAoE;IACpE,oBAAoB,EAAE,MAAM,CAAC;IAC7B,qEAAqE;IACrE,iBAAiB,EAAE,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,CAAC,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,mEAAmE;IACnE,YAAY,EAAE,WAAW,CAAC;IAC1B,0DAA0D;IAC1D,KAAK,EAAE;QACL,QAAQ,EAAE,UAAU,CAAC;QACrB,SAAS,EAAE,UAAU,CAAC;QACtB,SAAS,EAAE,UAAU,CAAC;KACvB,CAAC;CACH;AAED,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AAwBxE,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAWtE;AAED,MAAM,WAAW,sBAAsB;IACrC,iBAAiB,EAAE,OAAO,CAAC;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,kCAAkC;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,sBAAsB,EAC7B,OAAO,CAAC,EAAE,MAAM,GACf,YAAY,CAed;AAID,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAW3E;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,WAAW,CAAC;IAC1B,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IAC9B,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,uBAAuB,GAC7B,aAAa,CAiBf;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,CAQlE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAGtD"}

package/dist/core/diagnostics/markers.js

@@ -0,0 +1,153 @@
+/**
+ * Onboarding marker files (spec ed8cf2db).
+ *
+ * Two marker files communicate "onboarding completed" state between the
+ * `cf init` / `cf project init` aggregator commands (spec 1) and the future
+ * `cf doctor` / `cf fix` diagnostic commands (spec 2):
+ *
+ *   - `~/.claude-forge/system-installed.json` — system-level (hooks, daemon,
+ *     LaunchAgent) onboarding state
+ *   - `<project_root>/.forge-installed.json` — per-project (CLAUDE.md,
+ *     `.forge-knowledge/`, `.gitignore`) onboarding state
+ *
+ * Markers are write-overwrite (no merging) — callers decide whether to noop
+ * before re-writing. Reads return `null` if the file is missing or malformed.
+ *
+ * Schema is a frozen contract between spec 1 (this file) and spec 2
+ * (doctor); any schema change MUST update both specs and bump `version`.
+ */
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+import { FORGE_HOME } from '../constants.js';
+const require = createRequire(import.meta.url);
+export const SYSTEM_MARKER_FILENAME = 'system-installed.json';
+export const PROJECT_MARKER_FILENAME = '.forge-installed.json';
+export const MARKER_SCHEMA_VERSION = 1;
+// ── version lookup ───────────────────────────────────────────────────────
+let _cachedVersion = null;
+/**
+ * Resolve the running `claude-forge` package version. Cached to avoid
+ * repeated disk reads. Safe in tests — returns "0.0.0-test" if package.json
+ * cannot be read (e.g., in transient temp-dir tests).
+ */
+function getClaudeForgeVersion() {
+    if (_cachedVersion)
+        return _cachedVersion;
+    try {
+        const pkg = require('../../../package.json');
+        _cachedVersion = pkg.version;
+    }
+    catch {
+        _cachedVersion = '0.0.0-test';
+    }
+    return _cachedVersion;
+}
+// ── system marker ────────────────────────────────────────────────────────
+export function systemMarkerPath(homeDir) {
+    return path.join(homeDir ?? FORGE_HOME, SYSTEM_MARKER_FILENAME);
+}
+export function readSystemMarker(homeDir) {
+    const file = systemMarkerPath(homeDir);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== MARKER_SCHEMA_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write the system marker. Creates parent dir if needed. Returns the marker
+ * object that was written so callers can use it for summary output.
+ *
+ * Idempotency contract: callers are responsible for deciding whether to
+ * re-write. This function always overwrites if called.
+ */
+export function writeSystemMarker(input, homeDir) {
+    const dir = homeDir ?? FORGE_HOME;
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const marker = {
+        version: MARKER_SCHEMA_VERSION,
+        initialized_at: input.initialized_at ?? new Date().toISOString(),
+        claude_forge_version: input.claude_forge_version ?? getClaudeForgeVersion(),
+        launchd_installed: input.launchd_installed,
+        platform: input.platform ?? process.platform,
+        full_mode: input.full_mode,
+    };
+    fs.writeFileSync(systemMarkerPath(homeDir), JSON.stringify(marker, null, 2) + '\n', 'utf-8');
+    return marker;
+}
+// ── project marker ───────────────────────────────────────────────────────
+export function projectMarkerPath(projectRoot) {
+    return path.join(projectRoot, PROJECT_MARKER_FILENAME);
+}
+export function readProjectMarker(projectRoot) {
+    const file = projectMarkerPath(projectRoot);
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== MARKER_SCHEMA_VERSION)
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeProjectMarker(projectRoot, input) {
+    if (!fs.existsSync(projectRoot)) {
+        throw new Error(`writeProjectMarker: project root does not exist: ${projectRoot}`);
+    }
+    const marker = {
+        version: MARKER_SCHEMA_VERSION,
+        initialized_at: input.initialized_at ?? new Date().toISOString(),
+        claude_forge_version: input.claude_forge_version ?? getClaudeForgeVersion(),
+        project_type: input.project_type,
+        steps: input.steps,
+    };
+    fs.writeFileSync(projectMarkerPath(projectRoot), JSON.stringify(marker, null, 2) + '\n', 'utf-8');
+    return marker;
+}
+// ── project type detector ────────────────────────────────────────────────
+/**
+ * Detect project type by manifest-file priority. Pure file-system probe;
+ * no side effects, no dependency on storage or daemon.
+ *
+ * Priority order (spec ed8cf2db §3):
+ *   1. package.json  → node
+ *   2. pyproject.toml → python
+ *   3. Cargo.toml    → rust
+ *   4. go.mod        → go
+ *   5. else          → generic (assumed git repo)
+ */
+export function detectProjectType(projectRoot) {
+    const probe = (name) => fs.existsSync(path.join(projectRoot, name));
+    if (probe('package.json'))
+        return 'node';
+    if (probe('pyproject.toml'))
+        return 'python';
+    if (probe('Cargo.toml'))
+        return 'rust';
+    if (probe('go.mod'))
+        return 'go';
+    return 'generic';
+}
+/**
+ * Check whether the given directory is a git repository root (has `.git/`).
+ * Used as fail-fast precheck in `cf project init`.
+ */
+export function isGitRepo(projectRoot) {
+    const gitPath = path.join(projectRoot, '.git');
+    return fs.existsSync(gitPath);
+}
+//# sourceMappingURL=markers.js.map

package/dist/core/diagnostics/markers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markers.js","sourceRoot":"","sources":["../../../src/core/diagnostics/markers.ts"],"names":[],"mappings":"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"}

package/dist/core/governance/global-inject.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Global governance protocol injection (global-governance Phase 1,
+ * decision 7fa0f2ab).
+ *
+ * Other projects' Claude sessions read `~/.claude/CLAUDE.md` (the user-level
+ * global context) but NOT claude-forge's per-repo CLAUDE.md. So a pointer like
+ * "see <repo>/CLAUDE.md" is useless there — they can't resolve the path. We
+ * inject a *self-contained, condensed* copy of the DECISION HINT protocol
+ * contract directly into the global file, wrapped in idempotent markers.
+ *
+ * Idempotent: the block lives between `cf:governance:start` / `:end` markers.
+ * Re-running replaces the marker contents in place (never appends a duplicate).
+ * Reversible: `removeGlobalGovernanceBlock` strips the block.
+ *
+ * NOTE: this module deliberately takes the target path as a parameter so tests
+ * can point it at a temp HOME and NEVER touch the real `~/.claude/CLAUDE.md`.
+ */
+export declare const GOVERNANCE_MARKER_START = "<!-- cf:governance:start -->";
+export declare const GOVERNANCE_MARKER_END = "<!-- cf:governance:end -->";
+/**
+ * Resolve the real global CLAUDE.md path (`~/.claude/CLAUDE.md`).
+ * Production callers use this; tests pass an explicit temp path instead.
+ */
+export declare function defaultGlobalClaudeMdPath(): string;
+/**
+ * The condensed, self-contained DECISION HINT protocol contract. Distilled
+ * from the project CLAUDE.md "DECISION HINT 协议契约" section — kept short but
+ * complete enough that a Claude in any project knows to spawn decision-maker.
+ *
+ * Excludes the marker lines; `buildGovernanceBlock` wraps it.
+ */
+export declare const GOVERNANCE_PROTOCOL_BODY = "## claude-forge \u51B3\u7B56\u6CBB\u7406\u534F\u8BAE\uFF08\u5168\u94FE\u8DEF\u59D4\u6258 \u00B7 \u5168\u5C40\u6CE8\u5165\uFF09\n\n> \u672C\u5757\u7531 `cf governance inject-global` \u81EA\u52A8\u5199\u5165/\u66F4\u65B0\uFF1B\u79FB\u9664\uFF1A`--remove`\u3002\n\n**\u6838\u5FC3\uFF1A\u4E3B\u7EBF\u7A0B\u662F\u7EAF\u7F16\u6392\u8005\u2014\u2014\u53EA spawn agent\u3001\u4F20\u9012\u7ED3\u679C\u3001\u7B49\u7528\u6237\u6279\u51C6\u3001\u56DE\u586B outcome\uFF1B\n\u81EA\u5DF1\u4E0D grep/find \u67E5\u4EE3\u7801\u3001\u4E0D Edit/Write \u5B9E\u65BD\u3002** \u6536\u5230\u7528\u6237\u7684\u4EFB\u4F55\u8BF7\u6C42 / \u6307\u4EE4\uFF1A\n\n1. **\u51B3\u7B56\uFF08\u7B2C\u4E00\u52A8\u4F5C\uFF09**\uFF1A\u5FC5\u987B\u5148 spawn `decision-maker`\uFF08Task subagent_type='decision-maker'\uFF0C\n   prompt \u5934\u5E26 `<!-- decision-id: XXXX -->`\uFF08\u82E5\u6709\uFF09\uFF09\u3002\u5728\u5B83\u8FD4\u56DE\u524D\u4E0D\u56DE\u7B54\u6B63\u6587\u3001\u4E0D\u52A8\u624B\u3002\n   \u5B83 triage\uFF1A\u7410\u788E\u79D2\u653E\u8FC7 / \u503C\u5F97\u51FA\u65B9\u6848\uFF08\u9009\u9879\u00B7\u63A8\u8350\u00B7\u98CE\u9669\uFF09\u3002\n2. **\u641C\u7D22 / \u67E5\u4EE3\u7801**\uFF1A\u4EFB\u4F55 grep / find / git diff / \u8DE8\u6587\u4EF6\u67E5\u627E\uFF08\u5355\u6587\u4EF6\u5DF2\u77E5\u8DEF\u5F84\u7684 Read \u9664\u5916\uFF09\n   \u2192 spawn `Explore` \u6216 `doc-reviewer`\uFF1B\u4E3B\u7EBF\u7A0B\u4E0D\u81EA\u5DF1\u67E5\u3002\n3. **\u5B9E\u65BD**\uFF1A\u7528\u6237\u6279\u51C6\u540E\uFF0C\u5B9E\u8D28\u6539\u52A8\uFF08Edit/Write / \u591A\u6587\u4EF6 / \u65B0\u529F\u80FD / \u91CD\u6784 / bugfix\uFF09\n   \u2192 spawn `coder` / `refactor-specialist` / `hybrid-feature-with-safety` \u7B49\uFF1B\u4E3B\u7EBF\u7A0B\u4E0D\u81EA\u5DF1\u52A8\u624B\u3002\n4. **\u9A8C\u8BC1**\uFF1A\u5B9E\u65BD\u540E spawn `verify-agent` \u9A8C\u8BC1\u3002\n5. **\u5E76\u884C\u4F18\u5148\uFF08\u8981\u6548\u7387\uFF09**\uFF1A\u5DE5\u4F5C\u53EF\u62C6\u5206 / \u76F8\u4E92\u72EC\u7ACB\u65F6\uFF0C\u5728\u4E00\u6761\u6D88\u606F\u91CC batch spawn \u591A\u4E2A agent\n   \u5E76\u53D1\u8DD1\u2014\u2014\u4E0D\u6015\u6210\u672C\uFF0C\u4F18\u5148\u6548\u7387\uFF0C\u522B\u4E32\u884C\u5E72\u7B49\u3002\n6. **\u4F8B\u5916\uFF08\u65E0\u9700\u8D70\u4E0A\u8FF0\uFF09**\uFF1A\u7EAF\u786E\u8BA4\uFF08\"\u597D\u7684 / \u8C22\u8C22 / \u7EE7\u7EED\"\uFF09\u3001\u5143\u4EFB\u52A1\uFF08commit / build / restart daemon\uFF09\u3001\n   \u5355\u6587\u4EF6\u5DF2\u77E5\u8DEF\u5F84\u7684 Read\u3002\u82E5\u9879\u76EE\u6CA1\u6709\u5BF9\u5E94 agent\uFF0C\u7528\u53EF\u7528\u7684\uFF1B\u81F3\u5C11\u51B3\u7B56\u8D70 decision-maker\u3002\n7. bypass\uFF1Aprompt \u672B\u5C3E\u52A0 `skip decision` \u8DF3\u8FC7\u672C\u534F\u8BAE\u3002\n\n> \u8BDA\u5B9E\u8FB9\u754C\uFF1A\u8FD9\u662F**\u5F3A\u6307\u4EE4\u3001\u975E\u673A\u68B0\u9501**\u3002Claude Code \u73B0\u6709 hook \u65E0\u6CD5\u771F\u6B63\u5F3A\u5236\u5DE5\u5177\u8C03\u7528\n> \uFF08\u80FD\u62E6\u5DE5\u5177\u7684 deny \u5B9E\u6D4B\u5931\u6548\u3001\u5DF2\u5220\uFF09\u3002\u672C\u534F\u8BAE\u63D0\u9AD8\u9075\u5B88\u7387\uFF0C\u4E0D\u505A 100% \u4FDD\u8BC1\u3002";
+/** Wrap the protocol body in idempotent markers. */
+export declare function buildGovernanceBlock(body?: string): string;
+export interface InjectResult {
+    /** 'created' = file did not exist; 'inserted' = block added; 'updated' = block replaced; 'removed' = block stripped; 'absent' = nothing to remove. */
+    action: 'created' | 'inserted' | 'updated' | 'removed' | 'absent';
+    /** Resolved target path. */
+    path: string;
+    /** Backup path written before mutating an existing file (null if no pre-existing file). */
+    backupPath: string | null;
+}
+/** True when the file content already contains a governance marker block. */
+export declare function hasGovernanceBlock(content: string): boolean;
+/**
+ * Idempotently inject (or update) the governance block into `targetPath`.
+ *
+ * - File missing → create it (with the block as its content).
+ * - Block present → replace marker contents in place.
+ * - Block absent  → append the block (separated by a blank line).
+ *
+ * Always backs up a pre-existing file to `<path>.bak` before mutating.
+ */
+export declare function injectGlobalGovernance(targetPath?: string, body?: string): InjectResult;
+/**
+ * Remove the governance block from `targetPath` (reversible counterpart).
+ * Backs up the file first. Returns 'absent' when there is no block / no file.
+ */
+export declare function removeGlobalGovernanceBlock(targetPath?: string): InjectResult;
+//# sourceMappingURL=global-inject.d.ts.map

package/dist/core/governance/global-inject.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-inject.d.ts","sourceRoot":"","sources":["../../../src/core/governance/global-inject.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,eAAO,MAAM,uBAAuB,iCAAiC,CAAC;AACtE,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAElE;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;GAMG;AACH,eAAO,MAAM,wBAAwB,++FAsBO,CAAC;AAE7C,oDAAoD;AACpD,wBAAgB,oBAAoB,CAAC,IAAI,GAAE,MAAiC,GAAG,MAAM,CAEpF;AAED,MAAM,WAAW,YAAY;IAC3B,sJAAsJ;IACtJ,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;IAClE,4BAA4B;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,2FAA2F;IAC3F,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAWD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE3D;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,GAAE,MAAoC,EAChD,IAAI,GAAE,MAAiC,GACtC,YAAY,CAsBd;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,GAAE,MAAoC,GAC/C,YAAY,CAcd"}

package/dist/core/governance/global-inject.js

@@ -0,0 +1,129 @@
+/**
+ * Global governance protocol injection (global-governance Phase 1,
+ * decision 7fa0f2ab).
+ *
+ * Other projects' Claude sessions read `~/.claude/CLAUDE.md` (the user-level
+ * global context) but NOT claude-forge's per-repo CLAUDE.md. So a pointer like
+ * "see <repo>/CLAUDE.md" is useless there — they can't resolve the path. We
+ * inject a *self-contained, condensed* copy of the DECISION HINT protocol
+ * contract directly into the global file, wrapped in idempotent markers.
+ *
+ * Idempotent: the block lives between `cf:governance:start` / `:end` markers.
+ * Re-running replaces the marker contents in place (never appends a duplicate).
+ * Reversible: `removeGlobalGovernanceBlock` strips the block.
+ *
+ * NOTE: this module deliberately takes the target path as a parameter so tests
+ * can point it at a temp HOME and NEVER touch the real `~/.claude/CLAUDE.md`.
+ */
+import { existsSync, readFileSync, writeFileSync, copyFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+export const GOVERNANCE_MARKER_START = '<!-- cf:governance:start -->';
+export const GOVERNANCE_MARKER_END = '<!-- cf:governance:end -->';
+/**
+ * Resolve the real global CLAUDE.md path (`~/.claude/CLAUDE.md`).
+ * Production callers use this; tests pass an explicit temp path instead.
+ */
+export function defaultGlobalClaudeMdPath() {
+    return join(homedir(), '.claude', 'CLAUDE.md');
+}
+/**
+ * The condensed, self-contained DECISION HINT protocol contract. Distilled
+ * from the project CLAUDE.md "DECISION HINT 协议契约" section — kept short but
+ * complete enough that a Claude in any project knows to spawn decision-maker.
+ *
+ * Excludes the marker lines; `buildGovernanceBlock` wraps it.
+ */
+export const GOVERNANCE_PROTOCOL_BODY = `## claude-forge 决策治理协议（全链路委托 · 全局注入）
+
+> 本块由 \`cf governance inject-global\` 自动写入/更新；移除：\`--remove\`。
+
+**核心：主线程是纯编排者——只 spawn agent、传递结果、等用户批准、回填 outcome；
+自己不 grep/find 查代码、不 Edit/Write 实施。** 收到用户的任何请求 / 指令：
+
+1. **决策（第一动作）**：必须先 spawn \`decision-maker\`（Task subagent_type='decision-maker'，
+   prompt 头带 \`<!-- decision-id: XXXX -->\`（若有））。在它返回前不回答正文、不动手。
+   它 triage：琐碎秒放过 / 值得出方案（选项·推荐·风险）。
+2. **搜索 / 查代码**：任何 grep / find / git diff / 跨文件查找（单文件已知路径的 Read 除外）
+   → spawn \`Explore\` 或 \`doc-reviewer\`；主线程不自己查。
+3. **实施**：用户批准后，实质改动（Edit/Write / 多文件 / 新功能 / 重构 / bugfix）
+   → spawn \`coder\` / \`refactor-specialist\` / \`hybrid-feature-with-safety\` 等；主线程不自己动手。
+4. **验证**：实施后 spawn \`verify-agent\` 验证。
+5. **并行优先（要效率）**：工作可拆分 / 相互独立时，在一条消息里 batch spawn 多个 agent
+   并发跑——不怕成本，优先效率，别串行干等。
+6. **例外（无需走上述）**：纯确认（"好的 / 谢谢 / 继续"）、元任务（commit / build / restart daemon）、
+   单文件已知路径的 Read。若项目没有对应 agent，用可用的；至少决策走 decision-maker。
+7. bypass：prompt 末尾加 \`skip decision\` 跳过本协议。
+
+> 诚实边界：这是**强指令、非机械锁**。Claude Code 现有 hook 无法真正强制工具调用
+> （能拦工具的 deny 实测失效、已删）。本协议提高遵守率，不做 100% 保证。`;
+/** Wrap the protocol body in idempotent markers. */
+export function buildGovernanceBlock(body = GOVERNANCE_PROTOCOL_BODY) {
+    return `${GOVERNANCE_MARKER_START}\n${body}\n${GOVERNANCE_MARKER_END}`;
+}
+/**
+ * Build a regex that matches the full marker block (markers inclusive),
+ * tolerant of surrounding whitespace/newlines.
+ */
+function markerBlockRegex() {
+    const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`${esc(GOVERNANCE_MARKER_START)}[\\s\\S]*?${esc(GOVERNANCE_MARKER_END)}`);
+}
+/** True when the file content already contains a governance marker block. */
+export function hasGovernanceBlock(content) {
+    return markerBlockRegex().test(content);
+}
+function backupExisting(targetPath) {
+    const bak = `${targetPath}.bak`;
+    copyFileSync(targetPath, bak);
+    return bak;
+}
+/**
+ * Idempotently inject (or update) the governance block into `targetPath`.
+ *
+ * - File missing → create it (with the block as its content).
+ * - Block present → replace marker contents in place.
+ * - Block absent  → append the block (separated by a blank line).
+ *
+ * Always backs up a pre-existing file to `<path>.bak` before mutating.
+ */
+export function injectGlobalGovernance(targetPath = defaultGlobalClaudeMdPath(), body = GOVERNANCE_PROTOCOL_BODY) {
+    const block = buildGovernanceBlock(body);
+    if (!existsSync(targetPath)) {
+        mkdirSync(dirname(targetPath), { recursive: true });
+        writeFileSync(targetPath, `${block}\n`, 'utf8');
+        return { action: 'created', path: targetPath, backupPath: null };
+    }
+    const original = readFileSync(targetPath, 'utf8');
+    const backupPath = backupExisting(targetPath);
+    if (hasGovernanceBlock(original)) {
+        const next = original.replace(markerBlockRegex(), block);
+        if (next !== original)
+            writeFileSync(targetPath, next, 'utf8');
+        return { action: 'updated', path: targetPath, backupPath };
+    }
+    // Append, ensuring exactly one blank line of separation.
+    const sep = original.endsWith('\n') ? (original.endsWith('\n\n') ? '' : '\n') : '\n\n';
+    writeFileSync(targetPath, `${original}${sep}${block}\n`, 'utf8');
+    return { action: 'inserted', path: targetPath, backupPath };
+}
+/**
+ * Remove the governance block from `targetPath` (reversible counterpart).
+ * Backs up the file first. Returns 'absent' when there is no block / no file.
+ */
+export function removeGlobalGovernanceBlock(targetPath = defaultGlobalClaudeMdPath()) {
+    if (!existsSync(targetPath)) {
+        return { action: 'absent', path: targetPath, backupPath: null };
+    }
+    const original = readFileSync(targetPath, 'utf8');
+    if (!hasGovernanceBlock(original)) {
+        return { action: 'absent', path: targetPath, backupPath: null };
+    }
+    const backupPath = backupExisting(targetPath);
+    // Strip the block plus any immediately-trailing blank lines it left behind.
+    let next = original.replace(markerBlockRegex(), '');
+    next = next.replace(/\n{3,}/g, '\n\n').replace(/^\n+/, '');
+    writeFileSync(targetPath, next, 'utf8');
+    return { action: 'removed', path: targetPath, backupPath };
+}
+//# sourceMappingURL=global-inject.js.map

package/dist/core/governance/global-inject.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-inject.js","sourceRoot":"","sources":["../../../src/core/governance/global-inject.ts"],"names":[],"mappings":"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"}

package/dist/core/queue/index.d.ts

@@ -14,8 +14,6 @@
  */
 import type { SQLiteStorage } from '../storage/sqlite.js';
 import type { ForgeEvent } from '../types.js';
-export declare const QUEUE_DIR: string;
-export declare const DEAD_DIR: string;
 export declare const MAX_FILES = 500;
 export declare const TTL_DAYS = 7;
 /**
@@ -37,6 +35,21 @@ export interface ReplayResult {
     skipped: number;
     dead: number;
 }
+/**
+ * Options for {@link replayQueue}.
+ *
+ * `onReplayed` (queue-replay fix, 2026-05-29) fires once for each event that was
+ * successfully written to storage during replay, so the daemon can re-run the
+ * side effects the normal handleEvent path performs (TaskSegmenter.processPrompt
+ * / linkEvent). Without this hook, queued UserPromptSubmit events land in the
+ * events table but never produce a `tasks` row — the symptom the integration
+ * test guards. The hook is invoked synchronously after the row is committed;
+ * any error it throws is swallowed so replay accounting + file deletion still
+ * proceed (a failed side effect must not strand the queue file).
+ */
+export interface ReplayOptions {
+    onReplayed?: (event: ForgeEvent) => void;
+}
 /**
  * replayQueue — called by daemon after socket starts listening.
  *
@@ -48,5 +61,5 @@ export interface ReplayResult {
  *     - Other error → move to dead-letter, dead++
  *   - Bad JSON → move to dead-letter, dead++
  */
-export declare function replayQueue(storage: SQLiteStorage): Promise<ReplayResult>;
+export declare function replayQueue(storage: SQLiteStorage, options?: ReplayOptions): Promise<ReplayResult>;
 //# sourceMappingURL=index.d.ts.map

package/dist/core/queue/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/queue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAK9C,eAAO,MAAM,SAAS,QAAsB,CAAC;AAC7C,eAAO,MAAM,QAAQ,QAA0B,CAAC;AAChD,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,QAAQ,IAAI,CAAC;AAsB1B;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAYjC;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAgE/E"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/queue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAO9C,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,QAAQ,IAAI,CAAC;AAsB1B;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAYjC;AAID;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAUpD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA0EvB"}