@winspan/claude-forge 8.54.4 → 9.12.0

package/dist/core/diagnostics/knip-runner.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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.
+ */
+export interface KnipReport {
+    available: true;
+    /** Files with zero importers (orphan / unreferenced modules). */
+    unusedFiles: string[];
+    /** Exported symbols with zero call sites (dead exports). */
+    unusedExports: string[];
+    /** Declared dependencies never imported. */
+    unusedDependencies: string[];
+    /** Raw knip exit code (0 = no findings; with --no-exit-code always 0). */
+    exitCode: number;
+}
+export interface KnipUnavailable {
+    available: false;
+    reason: string;
+}
+export type KnipResult = KnipReport | KnipUnavailable;
+export interface RunKnipDeps {
+    /** Repo root (defaults to process.cwd()). */
+    cwd?: string;
+    /** Test override: spawn knip and return its stdout / status. */
+    spawn?: (cwd: string) => {
+        stdout: string;
+        status: number | null;
+        error?: Error;
+    };
+    /** Test override: check whether the knip binary exists. */
+    binExists?: (cwd: string) => boolean;
+}
+export declare function runKnip(deps?: RunKnipDeps): Promise<KnipResult>;
+//# sourceMappingURL=knip-runner.d.ts.map

package/dist/core/diagnostics/knip-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knip-runner.d.ts","sourceRoot":"","sources":["../../../src/core/diagnostics/knip-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,IAAI,CAAC;IAChB,iEAAiE;IACjE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,4DAA4D;IAC5D,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,4CAA4C;IAC5C,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,0EAA0E;IAC1E,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,eAAe,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,CAAC;IAClF,2DAA2D;IAC3D,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACtC;AAwED,wBAAsB,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAyBrE"}

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/event-fields.d.ts

@@ -13,4 +13,31 @@ export declare function getCommand(e: ForgeEvent): string | undefined;
 export declare function getFilePath(e: ForgeEvent): string | undefined;
 export declare function getUserPrompt(e: ForgeEvent): string | undefined;
 export declare function getSubagentType(e: ForgeEvent): string | undefined;
+/**
+ * Matches the decision-id magic comment a Task/Agent spawn carries in its
+ * prompt header: `<!-- decision-id: XXXXXXXX -->`. The id is 6–8 lowercase
+ * hex chars (daemon mints 8-hex; some legacy hints use 6). Case-insensitive so
+ * an upper-cased hex still matches, normalised to lowercase by the caller.
+ *
+ * Decision c425f26f (spec 1544 § 1.2). Exported for unit tests.
+ */
+export declare const SPAWN_DECISION_ID_RE: RegExp;
+/**
+ * Pull the two plaintext spawn fields — `decision_id` + `subagent_type` — from
+ * a Task/Agent spawn's *decoded* tool_input. Returns `{null, null}` for
+ * non-spawn rows or rows missing the fields.
+ *
+ * CRITICAL (gzip one-way-door, decision c425f26f): callers MUST pass the
+ * already-decoded tool_input object (pre-codec on the write path, or
+ * `decodeToolInput`-ed on the backfill path) — NEVER the raw gzip blob. The
+ * extracted values are written to NEW plaintext columns so SQL can query them
+ * directly; they never flow back through `encodeToolInput` / gzip.
+ *
+ * @param toolName  the event's tool_name (only 'Task' / 'Agent' are spawns)
+ * @param toolInput the DECODED tool_input object (or null/undefined)
+ */
+export declare function extractSpawnFields(toolName: string | null | undefined, toolInput: unknown): {
+    decisionId: string | null;
+    subagentType: string | null;
+};
 //# sourceMappingURL=event-fields.d.ts.map

package/dist/core/event-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-fields.d.ts","sourceRoot":"","sources":["../../src/core/event-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAG5D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAG7D;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAI/D;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGjE"}
+{"version":3,"file":"event-fields.d.ts","sourceRoot":"","sources":["../../src/core/event-fields.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAG5D;AAED,wBAAgB,WAAW,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAG7D;AAED,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAI/D;AAED,wBAAgB,eAAe,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAGjE;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,QAAmD,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,SAAS,EAAE,OAAO,GACjB;IAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAqB5D"}

package/dist/core/event-fields.js

@@ -16,4 +16,47 @@ export function getSubagentType(e) {
     const s = e.tool_input?.subagent_type;
     return typeof s === 'string' ? s : undefined;
 }
+/**
+ * Matches the decision-id magic comment a Task/Agent spawn carries in its
+ * prompt header: `<!-- decision-id: XXXXXXXX -->`. The id is 6–8 lowercase
+ * hex chars (daemon mints 8-hex; some legacy hints use 6). Case-insensitive so
+ * an upper-cased hex still matches, normalised to lowercase by the caller.
+ *
+ * Decision c425f26f (spec 1544 § 1.2). Exported for unit tests.
+ */
+export const SPAWN_DECISION_ID_RE = /<!--\s*decision-id:\s*([0-9a-fA-F]{6,8})\s*-->/;
+/**
+ * Pull the two plaintext spawn fields — `decision_id` + `subagent_type` — from
+ * a Task/Agent spawn's *decoded* tool_input. Returns `{null, null}` for
+ * non-spawn rows or rows missing the fields.
+ *
+ * CRITICAL (gzip one-way-door, decision c425f26f): callers MUST pass the
+ * already-decoded tool_input object (pre-codec on the write path, or
+ * `decodeToolInput`-ed on the backfill path) — NEVER the raw gzip blob. The
+ * extracted values are written to NEW plaintext columns so SQL can query them
+ * directly; they never flow back through `encodeToolInput` / gzip.
+ *
+ * @param toolName  the event's tool_name (only 'Task' / 'Agent' are spawns)
+ * @param toolInput the DECODED tool_input object (or null/undefined)
+ */
+export function extractSpawnFields(toolName, toolInput) {
+    if (toolName !== 'Task' && toolName !== 'Agent') {
+        return { decisionId: null, subagentType: null };
+    }
+    if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput)) {
+        return { decisionId: null, subagentType: null };
+    }
+    const ti = toolInput;
+    const subagentType = typeof ti.subagent_type === 'string' && ti.subagent_type.length > 0
+        ? ti.subagent_type
+        : null;
+    let decisionId = null;
+    const prompt = typeof ti.prompt === 'string' ? ti.prompt : null;
+    if (prompt) {
+        const m = prompt.match(SPAWN_DECISION_ID_RE);
+        if (m)
+            decisionId = m[1].toLowerCase();
+    }
+    return { decisionId, subagentType };
+}
 //# sourceMappingURL=event-fields.js.map

package/dist/core/event-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-fields.js","sourceRoot":"","sources":["../../src/core/event-fields.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,UAAU,CAAC,CAAa;IACtC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC;IAChC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAa;IACvC,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,IAAI,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC;IAClE,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,WAAW,CAAC;IAC5D,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC;IAC3C,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAa;IAC3C,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC;IACtC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"event-fields.js","sourceRoot":"","sources":["../../src/core/event-fields.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,UAAU,CAAC,CAAa;IACtC,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,OAAO,CAAC;IAChC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAa;IACvC,MAAM,EAAE,GAAG,CAAC,CAAC,UAAU,EAAE,SAAS,IAAI,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC;IAClE,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAa;IACzC,IAAI,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC,WAAW,CAAC;IAC5D,MAAM,QAAQ,GAAG,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC;IAC3C,OAAO,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,CAAa;IAC3C,MAAM,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,aAAa,CAAC;IACtC,OAAO,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,gDAAgD,CAAC;AAErF;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAmC,EACnC,SAAkB;IAElB,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,OAAO,EAAE,CAAC;QAChD,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QAC5E,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IAClD,CAAC;IACD,MAAM,EAAE,GAAG,SAAoC,CAAC;IAEhD,MAAM,YAAY,GAAG,OAAO,EAAE,CAAC,aAAa,KAAK,QAAQ,IAAI,EAAE,CAAC,aAAa,CAAC,MAAM,GAAG,CAAC;QACtF,CAAC,CAAC,EAAE,CAAC,aAAa;QAClB,CAAC,CAAC,IAAI,CAAC;IAET,IAAI,UAAU,GAAkB,IAAI,CAAC;IACrC,MAAM,MAAM,GAAG,OAAO,EAAE,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IAChE,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;QAC7C,IAAI,CAAC;YAAE,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;IACzC,CAAC;IAED,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC;AACtC,CAAC"}

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

@@ -0,0 +1,90 @@
+/**
+ * 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 DECISION HINT protocol contract.
+ *
+ * Authority ruling (decision ed98c8e8, 2026-06-10): the project CLAUDE.md
+ * "DECISION HINT 协议契约" section is the SINGLE authoritative full text.
+ * This global body is a short pointer-style digest — core directives only,
+ * everything else (codegraph/grep 分工、并行细则、例外清单) lives in the
+ * project file. This kills the ~950-token triple-injection duplication
+ * (global block + project block + hint template all carrying the full text).
+ *
+ * Also carries the spec-before-change discipline (decision 393481d1): a
+ * cross-project user mandate that previously lived only as a hand-written
+ * block OUTSIDE the markers on one machine — now folded into the generator
+ * so every install gets it via inject-global (same path as decision def0adcb
+ * took for the cd/output-redirection Bash convention).
+ *
+ * Excludes the marker lines; `buildGovernanceBlock` wraps it.
+ */
+export declare const GOVERNANCE_PROTOCOL_BODY = "## claude-forge \u51B3\u7B56\u6CBB\u7406\u534F\u8BAE\uFF08\u5168\u5C40\u6CE8\u5165 \u00B7 \u538B\u7F29\u7248\uFF09\n\n> \u672C\u5757\u7531 `cf governance inject-global` \u81EA\u52A8\u5199\u5165/\u66F4\u65B0\uFF1B\u79FB\u9664\uFF1A`--remove`\u3002\n> \u5B8C\u6574\u534F\u8BAE\uFF08codegraph/grep \u5206\u5DE5\u3001\u5E76\u884C\u7EC6\u5219\u3001\u4F8B\u5916\u6E05\u5355\uFF09\u89C1\u5404\u9879\u76EE CLAUDE.md \u7684\u300CDECISION HINT \u534F\u8BAE\u5951\u7EA6\u300D\u8282\u3002\n\n**\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\u4E0D\u81EA\u5DF1 grep/find \u67E5\u4EE3\u7801\u3001\u4E0D Edit/Write \u5B9E\u65BD\u3002\n1. \u51B3\u7B56\uFF08\u7B2C\u4E00\u52A8\u4F5C\uFF09\uFF1A\u5148 spawn `decision-maker`\uFF08prompt \u5934\u5E26 `<!-- decision-id: XXXX -->`\uFF0C\u82E5\u6709\uFF09\uFF0C\u5B83\u8FD4\u56DE\u524D\u4E0D\u56DE\u7B54\u6B63\u6587\u3001\u4E0D\u52A8\u624B\u3002\n2. \u641C\u7D22/\u67E5\u4EE3\u7801 \u2192 spawn `Explore` / `doc-reviewer`\uFF1B\u5B9E\u65BD\uFF08\u7528\u6237\u6279\u51C6\u540E\uFF09\u2192 spawn `coder` \u7B49\u5B9E\u65BD agent\uFF1B\u5B9E\u65BD\u540E \u2192 spawn `verify-agent`\u3002\n3. \u53EF\u62C6\u5206\u7684\u72EC\u7ACB\u5DE5\u4F5C\u5728\u4E00\u6761\u6D88\u606F\u91CC batch spawn \u5E76\u884C\u8DD1\uFF1Bbypass\uFF1Aprompt \u672B\u5C3E\u52A0 `skip decision`\u3002\n\n> \u8BDA\u5B9E\u8FB9\u754C\uFF1A\u5F3A\u6307\u4EE4\u3001\u975E\u673A\u68B0\u9501\u2014\u2014\u63D0\u9AD8\u9075\u5B88\u7387\uFF0C\u4E0D\u505A 100% \u4FDD\u8BC1\u3002\n\n## Bash \u547D\u4EE4\u7EA6\u5B9A\uFF08\u51CF\u5C11\u6388\u6743\u5F39\u7A97\uFF09\n\n\u8DD1 Bash \u65F6**\u4E0D\u8981**\u5199\u300C`cd <\u8DEF\u5F84> && cmd > file`\u300D\u8FD9\u79CD\u300C\u590D\u5408\u547D\u4EE4 + cd + \u8F93\u51FA\u91CD\u5B9A\u5411\u300D\n\u7EC4\u5408\u2014\u2014\u5B83\u89E6\u53D1 Claude Code \u7684 path-resolution-bypass \u5B89\u5168\u68C0\u67E5\uFF08`Compound command\ncontains cd with output redirection - manual approval required`\uFF09\uFF0C\u8BE5\u68C0\u67E5**\u65E0\u6CD5**\u7528\n`permissions.allow` \u653E\u884C\uFF0C\u53EA\u80FD\u4ECE\u547D\u4EE4\u5199\u6CD5\u89C4\u907F\uFF1A\n\n- \u274C `cd /some/path && cmd > file`\uFF08\u89E6\u53D1\u5F3A\u5236\u4EBA\u5DE5\u6279\u51C6\uFF09\n- \u2705 \u7528\u7EDD\u5BF9\u8DEF\u5F84\uFF1A`cmd > /some/path/file`\uFF0C\u76EE\u6807\u8DEF\u5F84\u5199\u5168\n- \u2705 \u5DE5\u4F5C\u76EE\u5F55\u672C\u6765\u5C31\u6301\u4E45\u5728\u9879\u76EE\u6839\uFF0C**\u591A\u6570\u547D\u4EE4\u6839\u672C\u4E0D\u9700\u8981 `cd` \u524D\u7F00**\u2014\u2014\u76F4\u63A5\u8DD1\n- \u2705 \u5B9E\u5728\u8981\u6362\u76EE\u5F55\uFF0C\u5206\u4E24\u6761\u72EC\u7ACB\u547D\u4EE4\uFF0C\u6216\u4E0D\u5E26 `>` \u91CD\u5B9A\u5411\n\n> \u8FD9\u80FD\u6D88\u9664\u8DE8\u9879\u76EE\u53CD\u590D\u51FA\u73B0\u7684 `cd` \u6388\u6743\u5F39\u7A97\uFF0C\u4E14\u4E0D\u727A\u7272\u5B89\u5168\uFF08\u65E0\u9700\u5F00 bypassPermissions\uFF09\u3002\n> \u8FD9\u662F\u5F3A\u7EA6\u5B9A\u3001\u975E\u786C\u9501\u2014\u2014\u63D0\u9AD8\u9075\u5B88\u7387\uFF0C\u4E0D\u505A 100% \u4FDD\u8BC1\u3002\n\n## \u901A\u7528\u5DE5\u7A0B\u7EAA\u5F8B\uFF1A\u4EE3\u7801\u6539\u52A8\u524D\u5148\u5199 spec\uFF08\u6240\u6709\u9879\u76EE \u00B7 \u7528\u6237\u5F3A\u5236\uFF09\n\n\u4EFB\u4F55**\u6D89\u53CA\u4EE3\u7801\u6539\u52A8**\u7684\u4EFB\u52A1\uFF08bugfix / \u6837\u5F0F / \u5355\u70B9 / \u91CD\u6784 / \u65B0\u529F\u80FD\uFF09\u5B9E\u65BD\u524D**\u5FC5\u987B**\u5148\u5199\u4E00\u4EFD spec\n\u7ECF\u7528\u6237\u6279\u51C6\uFF0C\u518D spawn \u5B9E\u65BD agent\uFF1B\u9002\u7528**\u6240\u6709\u9879\u76EE**\u3002\n- \u6D41\u7A0B\uFF1Aspawn `planner`\uFF08\u6216\u9879\u76EE\u7EA6\u5B9A spec agent\uFF09\u5199 spec \u5230 `docs/design/` \u2192 \u7528\u6237\u6279\u51C6 \u2192 \u624D spawn `coder` \u5B9E\u65BD \u2192 \u5B9E\u65BD\u540E `verify-agent`\u3002\n- \u4E8B\u540E changelog / \u5B9E\u65BD\u8BB0\u5F55**\u4E0D\u80FD**\u66FF\u4EE3\u300C\u5B9E\u65BD\u524D\u7684 spec\u300D\uFF1B**\u4E0D\u5F97**\u4EE5\u300C\u5C0F / trivial / \u5DF2\u8BCA\u65AD\u6E05\u695A / \u53EA\u6539\u4E00\u884C\u300D\u4E3A\u7531\u8DF3\u8FC7\u3002\n- \u4F8B\u5916\uFF08\u4E0D\u9700 spec\uFF09\uFF1A\u7EAF\u67E5\u8BE2 / \u8BCA\u65AD / \u5143\u4EFB\u52A1\uFF08commit\u3001build\u3001restart\u3001\u6539\u7248\u672C\u53F7\u3001\u6539\u6587\u6863/\u6CE8\u91CA\uFF09\u3002\n\n> \u5F3A\u6307\u4EE4\u3001\u975E\u673A\u68B0\u9501\u2014\u2014\u63D0\u9AD8\u9075\u5B88\u7387\uFF0C\u4E0D\u505A 100% \u4FDD\u8BC1\u3002\u8FD9\u6761\u7531\u4E3B\u7EBF\u7A0B\u81EA\u5F8B\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;
+/**
+ * Strip legacy forge-resume residue from the GLOBAL CLAUDE.md content
+ * (decision ed98c8e8, 2026-06-10).
+ *
+ * The resume engine historically wrote "上次工作续接" blocks into
+ * `~/.claude/CLAUDE.md`; that target was later retired (resume now goes to
+ * the per-project CLAUDE.md only), leaving stale blocks behind that get
+ * re-injected into every session of every project. This removes all known
+ * forms:
+ *   1. UUID envelope: `<!-- forge:resume-begin:<uuid> -->…<!-- forge:resume-end:<uuid> -->`
+ *   2. Legacy markers: `<!-- forge:resume -->…<!-- forge:end-resume -->`
+ *      (both delegated to the shared `stripForgeResumeBlocks` util)
+ *   3. Bare fenced residue: optional `## 上次工作续接` heading +
+ *      ```forge-resume-body``` fence + trailing `_生成时间: …_` line.
+ *
+ * Called by `injectGlobalGovernance` on every run, so the one-time cleanup
+ * self-heals even if stale content reappears.
+ */
+export declare function stripLegacyResumeBlocks(content: string): string;
+/**
+ * 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;AAOH,eAAO,MAAM,uBAAuB,iCAAiC,CAAC;AACtE,eAAO,MAAM,qBAAqB,+BAA+B,CAAC;AAElE;;;GAGG;AACH,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,wBAAwB,48IAmCI,CAAC;AAE1C,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;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAY/D;AAQD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,GAAE,MAAoC,EAChD,IAAI,GAAE,MAAiC,GACtC,YAAY,CAyBd;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CACzC,UAAU,GAAE,MAAoC,GAC/C,YAAY,CAcd"}