@schnick371/devsteps-shared 1.1.0-next.3 → 2.0.0-next.1

package/dist/utils/codex-state.js

@@ -0,0 +1,64 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { validateCodexTarget } from './codex-payload.js';
+import { CODEX_LEDGER } from './codex-types.js';
+import { readSnapshotBytes, recognizedSnapshot } from './snapshot-manifest.js';
+import { assertSafeDirectory, assertSafeFile, assertUniqueKeys, workspacePath, } from './snapshot-paths.js';
+const digest = z.string().regex(/^[0-9a-f]{64}$/);
+const span = z
+    .object({ sha256: digest, prefix: z.enum(['', '\n', '\n\n']), created: z.boolean() })
+    .strict();
+const ledgerSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    host: z.literal('codex'),
+    mode: z.enum(['native', 'plugin']),
+    version: z.string().min(1),
+    files: z.record(z.string(), digest),
+    config: span.optional(),
+    agents: span.optional(),
+    ignore: span.extend({ path: z.string() }).optional(),
+})
+    .strict();
+/** A malformed or unsafe ledger is never interpreted as an absent installation. */
+export function readCodexLedger(root) {
+    const path = workspacePath(root, CODEX_LEDGER);
+    if (!assertSafeFile(path, true))
+        return {};
+    const bytes = readFileSync(path);
+    const ledger = ledgerSchema.parse(JSON.parse(bytes.toString('utf8')));
+    const keys = Object.keys(ledger.files);
+    assertUniqueKeys(keys);
+    for (const key of keys)
+        validateCodexTarget(key);
+    return { ledger, bytes };
+}
+export function readCodexTarget(path) {
+    return assertSafeFile(path, true) ? readFileSync(path) : undefined;
+}
+/** Host setup can create snapshots before the project itself has been initialized. */
+export function hasOnlyCodexSnapshots(devstepsDir) {
+    assertSafeDirectory(devstepsDir);
+    const entries = readdirSync(devstepsDir);
+    if (entries.length !== 1 || entries[0] !== 'backups')
+        return false;
+    const backups = join(devstepsDir, 'backups');
+    assertSafeDirectory(backups);
+    for (const name of readdirSync(backups)) {
+        const snapshot = join(backups, name);
+        const manifest = JSON.parse(readSnapshotBytes(join(snapshot, 'manifest.json')).toString('utf8'));
+        if (!manifest ||
+            typeof manifest !== 'object' ||
+            !('workspaceRoot' in manifest) ||
+            typeof manifest.workspaceRoot !== 'string')
+            return false;
+        recognizedSnapshot(snapshot, manifest.workspaceRoot);
+    }
+    return true;
+}
+//# sourceMappingURL=codex-state.js.map

package/dist/utils/codex-state.js.map

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

package/dist/utils/codex-types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+import type { FileUpdateStatus } from './agent-files-payload.js';
+export type CodexMode = 'native' | 'plugin';
+export interface CodexOptions {
+    codexMode?: CodexMode;
+    sourceCodexDir?: string;
+    packageVersion?: string;
+    dryRun?: boolean;
+    force?: boolean;
+    maxBackups?: number;
+    remove?: boolean;
+    tools?: string;
+}
+export interface CodexSpan {
+    sha256: string;
+    prefix: string;
+    created: boolean;
+}
+export interface CodexLedger {
+    schemaVersion: 1;
+    host: 'codex';
+    mode: CodexMode;
+    version: string;
+    files: Record<string, string>;
+    config?: CodexSpan;
+    agents?: CodexSpan;
+    ignore?: CodexSpan & {
+        path: string;
+    };
+}
+export interface CodexMutation {
+    path: string;
+    before?: Buffer;
+    after?: Buffer;
+}
+export interface CodexPlan {
+    mode: CodexMode;
+    mutations: CodexMutation[];
+    statuses: FileUpdateStatus[];
+    notes: string[];
+}
+export declare const CODEX_LEDGER = ".codex/devsteps/ownership.json";
+export declare const CODEX_CONFIG = ".codex/config.toml";
+/** Reject host-specific options before a legacy flow can write anything. */
+export declare function assertCodexOptions(host: string, options: CodexOptions): void;
+//# sourceMappingURL=codex-types.d.ts.map

package/dist/utils/codex-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-types.d.ts","sourceRoot":"","sources":["../../src/utils/codex-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE5C,MAAM,WAAW,YAAY;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,CAAC,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,MAAM,CAAC,EAAE,SAAS,GAAG;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;CACvC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,aAAa,EAAE,CAAC;IAC3B,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,eAAO,MAAM,YAAY,mCAAmC,CAAC;AAC7D,eAAO,MAAM,YAAY,uBAAuB,CAAC;AAEjD,4EAA4E;AAC5E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI,CAyC5E"}

package/dist/utils/codex-types.js

@@ -0,0 +1,46 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ */
+export const CODEX_LEDGER = '.codex/devsteps/ownership.json';
+export const CODEX_CONFIG = '.codex/config.toml';
+/** Reject host-specific options before a legacy flow can write anything. */
+export function assertCodexOptions(host, options) {
+    if (host !== 'codex' &&
+        (options.codexMode !== undefined ||
+            options.sourceCodexDir !== undefined ||
+            options.remove !== undefined)) {
+        throw new Error('Codex mode, payload and removal options require the codex host.');
+    }
+    if (options.codexMode !== undefined && !['native', 'plugin'].includes(options.codexMode)) {
+        throw new Error('Unsupported Codex mode; use native or plugin.');
+    }
+    if (host === 'codex') {
+        const supplied = options;
+        const forbidden = [
+            'model',
+            'modelProvider',
+            'approvalPolicy',
+            'sandboxMode',
+            'profile',
+            'reasoningEffort',
+            'subagentModel',
+            'subagentModelSource',
+            'runtime',
+            'plugin',
+            'runtimeProfile',
+            'model_reasoning_effort',
+            'approval_policy',
+            'sandbox_mode',
+            'model_provider',
+        ];
+        const unsupported = forbidden.find((key) => supplied[key] !== undefined);
+        if (unsupported)
+            throw new Error(`Unsupported Codex model/runtime-policy option: ${unsupported}`);
+    }
+    if (options.maxBackups !== undefined &&
+        (!Number.isSafeInteger(options.maxBackups) || options.maxBackups < 0)) {
+        throw new Error('Invalid maximum backup count.');
+    }
+}
+//# sourceMappingURL=codex-types.js.map

package/dist/utils/codex-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex-types.js","sourceRoot":"","sources":["../../src/utils/codex-types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AA+CH,MAAM,CAAC,MAAM,YAAY,GAAG,gCAAgC,CAAC;AAC7D,MAAM,CAAC,MAAM,YAAY,GAAG,oBAAoB,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,OAAqB;IACpE,IACE,IAAI,KAAK,OAAO;QAChB,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS;YAC9B,OAAO,CAAC,cAAc,KAAK,SAAS;YACpC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,EAC/B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iEAAiE,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,OAAO,CAAC,SAAS,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACzF,MAAM,IAAI,KAAK,CAAC,+CAA+C,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,IAAI,KAAK,OAAO,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,OAA6C,CAAC;QAC/D,MAAM,SAAS,GAAG;YAChB,OAAO;YACP,eAAe;YACf,gBAAgB;YAChB,aAAa;YACb,SAAS;YACT,iBAAiB;YACjB,eAAe;YACf,qBAAqB;YACrB,SAAS;YACT,QAAQ;YACR,gBAAgB;YAChB,wBAAwB;YACxB,iBAAiB;YACjB,cAAc;YACd,gBAAgB;SACjB,CAAC;QACF,MAAM,WAAW,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC,CAAC;QACzE,IAAI,WAAW;YACb,MAAM,IAAI,KAAK,CAAC,kDAAkD,WAAW,EAAE,CAAC,CAAC;IACrF,CAAC;IACD,IACE,OAAO,CAAC,UAAU,KAAK,SAAS;QAChC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,EACrE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;AACH,CAAC"}

package/dist/utils/contract-block.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Contract-block handling for agent host files.
+ *
+ * A contract file — `.github/copilot-instructions.md` for Copilot, `CLAUDE.md`
+ * for Claude Code — is shared property. The part above the marker belongs to the
+ * consuming project; only the delimited block belongs to DevSteps. So a contract
+ * file is never copied whole, unlike the agent/instruction/prompt payloads:
+ * DevSteps writes the block and leaves everything around it alone.
+ *
+ * The block is authored once (`scripts/templates/devsteps-contract-block.md`)
+ * and travels inside the packaged `.github/copilot-instructions.md`, which is
+ * where this module reads it from at runtime.
+ *
+ * The begin marker carries the sha256 of the block body, so a local edit inside
+ * the block is detectable without touching the project's own part of the file.
+ *
+ * @see EPIC-056 STORY-395 TASK-769 TASK-770 BUG-121 BUG-123
+ */
+export type ContractFileStatus = 'created' | 'updated' | 'unchanged' | 'skipped-modified'
+/** The installed package ships no contract block to write. */
+ | 'unavailable';
+export interface ContractFileResult {
+    status: ContractFileStatus;
+    path: string;
+    message: string;
+}
+export interface ManagedBlock {
+    /** Block including both markers, ready to write. */
+    text: string;
+    /** Block body without the markers, trimmed — what the marker hash covers. */
+    body: string;
+    /** sha256 recorded in the begin marker, or null when absent. */
+    recordedHash: string | null;
+    start: number;
+    end: number;
+}
+/** Locate the managed block in `content`, or null when it carries none. */
+export declare function extractManagedBlock(content: string): ManagedBlock | null;
+/**
+ * Read the authored contract block out of a packaged `.github` directory.
+ * Returns null when the package ships no contract file or it carries no block.
+ */
+export declare function readPackagedContractBlock(sourceGithubDir: string): string | null;
+export interface WriteContractBlockOptions {
+    /**
+     * Written above the block when the file is created. Belongs to the consuming
+     * project from that moment on and is never rewritten.
+     */
+    preamble?: string;
+    /** Replace the block even when it carries local edits. */
+    force?: boolean;
+}
+/**
+ * Decide what would happen to `targetPath`, without writing.
+ *
+ * `content` is the file the write would produce; it is absent when the plan
+ * changes nothing, which is what lets a dry run report an honest outcome.
+ */
+export declare function planContractBlock(targetPath: string, block: string, options?: WriteContractBlockOptions): ContractFileResult & {
+    content?: string;
+};
+/**
+ * Create or update the DevSteps contract block in a target file.
+ *
+ * - Creates the file with `preamble` plus the block when it does not exist.
+ * - Replaces the block in place when the file carries one.
+ * - Migrates a legacy Claude contract block to the shared marker pair.
+ * - Appends the block when the file exists without one.
+ * - Leaves a locally edited block untouched unless `force` is set, so a
+ *   workspace that tuned the block keeps its wording.
+ *
+ * The project's own content is never read for comparison, so editing it above
+ * or below the block never makes the file look modified.
+ */
+export declare function writeContractBlock(targetPath: string, block: string, options?: WriteContractBlockOptions): ContractFileResult;
+//# sourceMappingURL=contract-block.d.ts.map

package/dist/utils/contract-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-block.d.ts","sourceRoot":"","sources":["../../src/utils/contract-block.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAkBH,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,WAAW,GACX,kBAAkB;AACpB,8DAA8D;GAC5D,aAAa,CAAC;AAElB,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAMD,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAiBxE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhF;AAgBD,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,yBAAyB,GAClC,kBAAkB,GAAG;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAoD3C;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,yBAAyB,GAClC,kBAAkB,CAIpB"}

package/dist/utils/contract-block.js

@@ -0,0 +1,153 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Contract-block handling for agent host files.
+ *
+ * A contract file — `.github/copilot-instructions.md` for Copilot, `CLAUDE.md`
+ * for Claude Code — is shared property. The part above the marker belongs to the
+ * consuming project; only the delimited block belongs to DevSteps. So a contract
+ * file is never copied whole, unlike the agent/instruction/prompt payloads:
+ * DevSteps writes the block and leaves everything around it alone.
+ *
+ * The block is authored once (`scripts/templates/devsteps-contract-block.md`)
+ * and travels inside the packaged `.github/copilot-instructions.md`, which is
+ * where this module reads it from at runtime.
+ *
+ * The begin marker carries the sha256 of the block body, so a local edit inside
+ * the block is detectable without touching the project's own part of the file.
+ *
+ * @see EPIC-056 STORY-395 TASK-769 TASK-770 BUG-121 BUG-123
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const BEGIN_RE = /<!--\s*devsteps-managed:begin[^>]*-->/;
+const HASH_RE = /hash:\s*sha256:([0-9a-f]{64})/;
+const END_MARKER = '<!-- devsteps-managed:end -->';
+/**
+ * Delimiters of the first Claude contract block shipped by `init`/`setup_host`.
+ * Superseded by the shared marker pair above; recognised so a workspace that
+ * carries the old block is migrated in place instead of gaining a second one.
+ */
+const LEGACY_BEGIN = '<!-- devsteps:claude-contract:begin -->';
+const LEGACY_END = '<!-- devsteps:claude-contract:end -->';
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+/** Locate the managed block in `content`, or null when it carries none. */
+export function extractManagedBlock(content) {
+    const beginMatch = content.match(BEGIN_RE);
+    if (!beginMatch || beginMatch.index === undefined)
+        return null;
+    const endIndex = content.indexOf(END_MARKER, beginMatch.index);
+    if (endIndex === -1)
+        return null;
+    const end = endIndex + END_MARKER.length;
+    const text = content.slice(beginMatch.index, end);
+    const body = text.slice(beginMatch[0].length, text.length - END_MARKER.length).trim();
+    return {
+        text,
+        body,
+        recordedHash: beginMatch[0].match(HASH_RE)?.[1] ?? null,
+        start: beginMatch.index,
+        end,
+    };
+}
+/**
+ * Read the authored contract block out of a packaged `.github` directory.
+ * Returns null when the package ships no contract file or it carries no block.
+ */
+export function readPackagedContractBlock(sourceGithubDir) {
+    const source = join(sourceGithubDir, 'copilot-instructions.md');
+    if (!existsSync(source))
+        return null;
+    return extractManagedBlock(readFileSync(source, 'utf8'))?.text ?? null;
+}
+/** True when the installed block body no longer matches its recorded hash. */
+function isLocallyModified(block) {
+    return block.recordedHash === null || block.recordedHash !== sha256(block.body);
+}
+/** Replace a legacy Claude contract block with `block`, or return null. */
+function replaceLegacyBlock(content, block) {
+    const start = content.indexOf(LEGACY_BEGIN);
+    if (start === -1)
+        return null;
+    const endIndex = content.indexOf(LEGACY_END, start);
+    if (endIndex === -1)
+        return null;
+    return content.slice(0, start) + block + content.slice(endIndex + LEGACY_END.length);
+}
+/**
+ * Decide what would happen to `targetPath`, without writing.
+ *
+ * `content` is the file the write would produce; it is absent when the plan
+ * changes nothing, which is what lets a dry run report an honest outcome.
+ */
+export function planContractBlock(targetPath, block, options) {
+    const force = options?.force ?? false;
+    if (!existsSync(targetPath)) {
+        const preamble = options?.preamble ? `${options.preamble.trimEnd()}\n\n` : '';
+        return {
+            status: 'created',
+            path: targetPath,
+            message: 'Created with the contract block.',
+            content: `${preamble}${block}\n`,
+        };
+    }
+    const content = readFileSync(targetPath, 'utf8');
+    const installed = extractManagedBlock(content);
+    if (!installed) {
+        const migrated = replaceLegacyBlock(content, block);
+        if (migrated !== null) {
+            return {
+                status: 'updated',
+                path: targetPath,
+                message: 'Migrated the legacy contract block to the shared marker pair.',
+                content: migrated,
+            };
+        }
+        return {
+            status: 'updated',
+            path: targetPath,
+            message: 'Appended the contract block.',
+            content: `${content.trimEnd()}\n\n${block}\n`,
+        };
+    }
+    if (installed.text === block) {
+        return { status: 'unchanged', path: targetPath, message: 'Contract block is already current.' };
+    }
+    if (isLocallyModified(installed) && !force) {
+        return {
+            status: 'skipped-modified',
+            path: targetPath,
+            message: 'Contract block was edited locally — left unchanged. Re-run with force to replace.',
+        };
+    }
+    return {
+        status: 'updated',
+        path: targetPath,
+        message: 'Updated the contract block.',
+        content: content.slice(0, installed.start) + block + content.slice(installed.end),
+    };
+}
+/**
+ * Create or update the DevSteps contract block in a target file.
+ *
+ * - Creates the file with `preamble` plus the block when it does not exist.
+ * - Replaces the block in place when the file carries one.
+ * - Migrates a legacy Claude contract block to the shared marker pair.
+ * - Appends the block when the file exists without one.
+ * - Leaves a locally edited block untouched unless `force` is set, so a
+ *   workspace that tuned the block keeps its wording.
+ *
+ * The project's own content is never read for comparison, so editing it above
+ * or below the block never makes the file look modified.
+ */
+export function writeContractBlock(targetPath, block, options) {
+    const { content, ...result } = planContractBlock(targetPath, block, options);
+    if (content !== undefined)
+        writeFileSync(targetPath, content, 'utf8');
+    return result;
+}
+//# sourceMappingURL=contract-block.js.map

package/dist/utils/contract-block.js.map

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

package/dist/utils/contract-staleness.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Contract-block staleness (P4, TASK-957 / BUG-153). The managed block reaches a project only
+ * through init, setup_host or update_copilot_files, and an unchanged version label gives no
+ * signal, so a project kept running on an old block. Server start, health and doctor compare
+ * each installed block with the packaged one and name the refresh command.
+ */
+import type { CheckResult } from '../core/doctor-types.js';
+export interface ContractStaleness {
+    /** `absent`: no file carries a block; `unavailable`: the package ships none to compare. */
+    status: 'current' | 'outdated' | 'absent' | 'unavailable';
+    /** Files whose block differs from the packaged one, marked when edited by hand. */
+    outdated: string[];
+    message: string;
+}
+export declare const CONTRACT_REFRESH_HINT = "run update_copilot_files (MCP) or `devsteps update-copilot-files` to refresh it";
+export declare function checkContractStaleness(projectPath: string, sourceGithubDir: string | undefined): ContractStaleness;
+/** The staleness result as a doctor check: outdated warns, everything else passes. */
+export declare function contractStalenessCheck(result: ContractStaleness): CheckResult;
+//# sourceMappingURL=contract-staleness.d.ts.map

package/dist/utils/contract-staleness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-staleness.d.ts","sourceRoot":"","sources":["../../src/utils/contract-staleness.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,MAAM,WAAW,iBAAiB;IAChC,2FAA2F;IAC3F,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,aAAa,CAAC;IAC1D,mFAAmF;IACnF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,qBAAqB,oFACiD,CAAC;AAEpF,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,iBAAiB,CAiCnB;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CAS7E"}

package/dist/utils/contract-staleness.js

@@ -0,0 +1,67 @@
+/**
+ * Copyright © 2026 Thomas Hertel (the@devsteps.dev)
+ * Licensed under the Apache License, Version 2.0
+ *
+ * Contract-block staleness (P4, TASK-957 / BUG-153). The managed block reaches a project only
+ * through init, setup_host or update_copilot_files, and an unchanged version label gives no
+ * signal, so a project kept running on an old block. Server start, health and doctor compare
+ * each installed block with the packaged one and name the refresh command.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { extractManagedBlock, readPackagedContractBlock } from './contract-block.js';
+const CONTRACT_FILES = ['CLAUDE.md', '.github/copilot-instructions.md'];
+export const CONTRACT_REFRESH_HINT = 'run update_copilot_files (MCP) or `devsteps update-copilot-files` to refresh it';
+export function checkContractStaleness(projectPath, sourceGithubDir) {
+    const packaged = sourceGithubDir ? readPackagedContractBlock(sourceGithubDir) : null;
+    if (!packaged) {
+        return {
+            status: 'unavailable',
+            outdated: [],
+            message: 'No packaged contract block to compare',
+        };
+    }
+    const expected = extractManagedBlock(packaged)?.body;
+    const outdated = [];
+    let installed = 0;
+    for (const file of CONTRACT_FILES) {
+        const path = join(projectPath, file);
+        if (!existsSync(path))
+            continue;
+        const block = extractManagedBlock(readFileSync(path, 'utf8'));
+        if (!block)
+            continue;
+        installed++;
+        if (block.body === expected)
+            continue;
+        const edited = block.recordedHash !== sha256(block.body);
+        outdated.push(edited ? `${file} (edited by hand)` : file);
+    }
+    if (installed === 0) {
+        return { status: 'absent', outdated, message: 'No DevSteps contract block installed' };
+    }
+    if (outdated.length === 0) {
+        return { status: 'current', outdated, message: 'Contract block matches this release' };
+    }
+    return {
+        status: 'outdated',
+        outdated,
+        message: `Contract block outdated in ${outdated.join(', ')} — ${CONTRACT_REFRESH_HINT}`,
+    };
+}
+/** The staleness result as a doctor check: outdated warns, everything else passes. */
+export function contractStalenessCheck(result) {
+    return {
+        name: 'Contract block',
+        status: result.status === 'outdated' ? 'warn' : 'pass',
+        message: result.message,
+        ...(result.status === 'outdated'
+            ? { details: result.outdated, fix: CONTRACT_REFRESH_HINT }
+            : {}),
+    };
+}
+function sha256(content) {
+    return createHash('sha256').update(content, 'utf8').digest('hex');
+}
+//# sourceMappingURL=contract-staleness.js.map

package/dist/utils/contract-staleness.js.map

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

package/dist/utils/index.d.ts

@@ -6,52 +6,29 @@
  * Re-exports helper functions and constants from the utils layer.
  */
 import type { ItemType, Methodology } from '../schemas/index.js';
-export { CACHE_CONFIG, type CacheStats, ContextCache, clearGlobalCache, getCache, } from './cache.js';
+export { type FileUpdateStatus, listPayloadFiles } from './agent-files-payload.js';
+export { ATOMIC_TEMP_NAME, type AtomicWriteOptions, renameWithRetry, renameWithRetrySync, writeBytesAtomic, writeFileAtomic, writeJsonAtomic, } from './atomic-write.js';
 export { type BackupOptions, type BackupResult, backupGithubFiles, } from './backup-github-files.js';
-export { type CopiedGithubFiles, copyDevstepsDocs, copyGithubFiles, injectDevstepsComment, writeSetupMd, } from './init-helpers.js';
-export { type UpdateCopilotFilesOptions, type UpdateCopilotFilesResult, updateCopilotFiles, } from './update-copilot-files.js';
+export { CACHE_CONFIG, type CacheStats, ContextCache, clearGlobalCache, getCache, } from './cache.js';
+export { type ClaudeContractOptions, type ClaudeContractResult, type ClaudeContractStatus, renderClaudeContractPreamble, writeClaudeContractBlock, } from './claude-host.js';
+export { type ContractFileResult, type ContractFileStatus, extractManagedBlock, type ManagedBlock, readPackagedContractBlock, type WriteContractBlockOptions, writeContractBlock, } from './contract-block.js';
+export { CONTRACT_REFRESH_HINT, type ContractStaleness, checkContractStaleness, contractStalenessCheck, } from './contract-staleness.js';
+export { type CopiedGithubFiles, copyGithubFiles, injectDevstepsComment, writeSetupMd, } from './init-helpers.js';
+export { activeToolGroups, MCP_DEFAULT_TOOL_GROUPS, MCP_OPT_IN_TOOL_GROUPS, MCP_TOOL_GROUP_ENV_VAR, MCP_TOOL_GROUP_NAMES, type McpToolGroupName, mergeToolGroupEnv, type ParsedToolGroupSelection, parseToolGroupSelection, type ResolvedToolGroupSelection, selectToolGroups, type ToolGroupSelection, toolGroupEnv, } from './mcp-tool-groups.js';
+export { resolvePackagedGithubDir } from './packaged-github.js';
+export { readTextFile, stripBom } from './text-file.js';
+export { type AgentHostSelection, type UpdateAgentFilesOptions, type UpdateAgentFilesResult, type UpdateCopilotFilesOptions, type UpdateCopilotFilesResult, updateAgentFiles, updateCopilotFiles, } from './update-agent-files.js';
 /**
  * Type to plural directory mapping
  * Uses items/ subdirectory for git-inspired object store (SPIKE-008)
  */
 export declare const TYPE_TO_DIRECTORY: Record<ItemType, string>;
 /**
- * Get methodology configuration
+ * Get methodology configuration: the item types, their ID prefixes and their directories
  */
 export declare function getMethodologyConfig(methodology: Methodology): {
     item_types: ItemType[];
-    item_prefixes: {
-        epic: string;
-        story: string;
-        task: string;
-        bug: string;
-        spike: string;
-        test: string;
-    };
-    directories: string[];
-} | {
-    item_types: ItemType[];
-    item_prefixes: {
-        requirement: string;
-        feature: string;
-        task: string;
-        bug: string;
-        spike: string;
-        test: string;
-    };
-    directories: string[];
-} | {
-    item_types: ItemType[];
-    item_prefixes: {
-        epic: string;
-        story: string;
-        requirement: string;
-        feature: string;
-        task: string;
-        bug: string;
-        spike: string;
-        test: string;
-    };
+    item_prefixes: Record<string, string>;
     directories: string[];
 };
 /**
@@ -89,7 +66,7 @@ export declare function sanitizeFilename(name: string): string;
 /**
  * Normalizes escape sequences in description strings received from MCP tool calls.
  *
- * **Problem:** MCP clients (GitHub Copilot ≥ v1.0.0, Claude Code, etc.) transmit
+ * **Problem:** GitHub Copilot MCP clients transmit
  * multiline strings with literal two-character sequences `\n`, `\t` instead of
  * actual Unicode control characters. `JSON.parse` delivers these sequences unchanged,
  * so `writeFileSync` writes them verbatim — producing unreadable `.md` files.

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGjE,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,YAAY,EACZ,gBAAgB,EAChB,QAAQ,GACT,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,iBAAiB,EACtB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,YAAY,GACb,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAStD,CAAC;AAEF;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,WAAW;gBAGU,QAAQ,EAAE;;;;;;;;;;;gBAmBD,QAAQ,EAAE;;;;;;;;;;;gBA4B/E,QAAQ,EAAE;;;;;;;;;;;;EAyBpB;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,CAgBR;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYlD;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAmBjF;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAGtD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKrD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CASvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"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"}