devmethod-ai 0.1.0-rc.2 → 0.1.0

package/VALIDATION.md

@@ -0,0 +1,37 @@
+# Release candidate validation
+
+## Diagnostics and workflow improvement candidate
+
+Source change based on `758491c3e85621c6adae6b5c71d1b32c28a380af`; npm release pending. Local runtime: Linux x64, Node.js 24.19.0. The platform results below belong to the earlier candidate, not this change.
+
+- `npm ci --ignore-scripts --prefer-offline`, `npm test` (strict TypeScript build and 16 passing tests), and `npm pack --dry-run` passed.
+- The actual local tarball installed all three host profiles and their scoped-delivery subsets via offline npx. Packaged `doctor --json` returned healthy reports, and retained customized profiles with warning status.
+- Doctor accepted a format 2 installation produced by the previous source CLI (29 recorded files), as well as the new payload (31 recorded files).
+- Updated skill frontmatter passed the skill validator; local Markdown file links and `git diff --check` passed.
+- The B1 exercise produced the expected two failing tests. A temporary reference implementation passed both, confirming fixture solvability. This was a fixture check, not an independent model or BMad benchmark.
+
+The existing platform CI now also checks packaged diagnostics. Record that run's conclusions before claiming this change passed on macOS/Windows. Authenticated host behavior, matched comparative evaluations and npm publication remain separate pending gates. Review performed locally by the implementing agent; no independent review is claimed.
+
+## Earlier 0.1 candidate
+
+Date: 2026-09-12. Candidate: 0.1.
+
+Executed `npm test`: strict TypeScript build and 7 Node.js tests passed. Coverage: three host layouts, six skill names and relative references, SHA-256 manifests, MIT notice, selected modules, dry-run without writes, identical installation, conflict rejection before writes, preserved project instructions, invalid arguments, duplicate host detection, blocked paths and symlink rejection.
+
+`npm pack` produced the compiled CLI and skill payload without runtime dependencies. An actual offline `npx --package=<local-tarball> devmethod init --tool claude` installed all six modules successfully. Installation never migrates existing project context; customized templates normally differ from initial manifest hashes.
+
+These checks validate installation and documentation; they do not execute a Claude or Cursor model. Native authenticated evaluations remain pending, as documented in COMPATIBILITY.md.
+
+## Native operating-system results
+
+[GitHub Actions run 34720121631](https://github.com/montassarkhalloufi/DevMethod/actions/runs/34720121631) completed successfully for commit `0790845289eccfe4aa3cfd0fe9e849eeca11b0a7` with Node.js 22.23.2 on all three runners:
+
+| System | Architecture | Unit tests | Packaged npx installations |
+|---|---|---|---|
+| Ubuntu | x64 | 7 passed | Codex, Claude Code, Cursor passed |
+| macOS | ARM64 | 7 passed | Codex, Claude Code, Cursor passed |
+| Windows Server 2025 | x64 | 7 passed | Codex, Claude Code, Cursor passed |
+
+Each job rebuilt strict TypeScript, verified the committed build, packed the actual package and invoked npx against that tarball for each host. It checked all six installed modules and the SHA-256 manifest. Installation paths included spaces. This establishes the tested runtime combinations, not every OS version or an authenticated host session. Windows shell commands used Git Bash; PowerShell-specific interaction was not evaluated.
+
+Publication target: https://github.com/montassarkhalloufi/DevMethod. This report covers the 0.1 candidate source and local checks, not a stable release certification. Native authenticated compatibility remains pending.

package/dist/checkpoint.js

@@ -0,0 +1,171 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseJson, checkPath } from './filesystem.js';
+import { gitState, validGit } from './records.js';
+const object = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const identifier = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(value);
+const nonempty = (value) => typeof value === 'string' && value.trim().length > 0;
+// Portable repository-relative paths only: no Windows aliases, drives or streams.
+function safePath(value) {
+    return typeof value === 'string' && value.length > 0 && !/[\\:\x00-\x1f\x7f]/.test(value)
+        && value.split('/').every(part => part.length > 0 && part !== '.' && part !== '..'
+            && !/[. ]$/.test(part) && !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part));
+}
+function pinned(value) {
+    return object(value) && identifier(value.id) && safePath(value.path)
+        && typeof value.sha256 === 'string' && /^[a-f0-9]{64}$/.test(value.sha256);
+}
+function ids(value) {
+    return Array.isArray(value) && value.every(identifier) && new Set(value).size === value.length;
+}
+function validate(input) {
+    if (!object(input) || input.format !== 1)
+        throw new Error('Expected checkpoint format 1. Markdown checkpoints remain a manual workflow.');
+    if (!nonempty(input.scope) || typeof input.status !== 'string' || !['active', 'blocked', 'complete'].includes(input.status))
+        throw new Error('Checkpoint needs a nonempty scope and status active, blocked or complete.');
+    if (input.nextAction !== null && !nonempty(input.nextAction))
+        throw new Error('nextAction must be a nonempty string or null.');
+    if (input.status === 'complete' && input.nextAction !== null)
+        throw new Error('Completed scope must have nextAction null; completion authorizes no new work.');
+    if (input.status !== 'complete' && !nonempty(input.nextAction))
+        throw new Error('Active or blocked scope needs an explicit nextAction.');
+    if (!Array.isArray(input.sources) || !input.sources.every(pinned) || input.sources.length === 0)
+        throw new Error('sources must contain pinned IDs, safe relative paths and lowercase SHA-256 hashes.');
+    if (!Array.isArray(input.evidence) || !input.evidence.every(item => pinned(item) && object(item)
+        && ids(item.sourceIds) && item.sourceIds.length > 0 && ids(item.dependsOn)
+        && typeof item.outcome === 'string' && ['passed', 'failed', 'blocked', 'not-run'].includes(item.outcome)))
+        throw new Error('evidence needs pinned artifacts, sourceIds, dependsOn and outcome passed, failed or not-run.');
+    if (input.sources.length > 256 || input.evidence.length > 256)
+        throw new Error('Checkpoint supports at most 256 sources and evidence items.');
+    if (input.git !== undefined && !validGit(input.git))
+        throw new Error('Invalid Git checkpoint provenance.');
+    if (input.blockers !== undefined && (!Array.isArray(input.blockers) || !input.blockers.every(nonempty)))
+        throw new Error('blockers must be nonempty strings.');
+    for (const item of input.evidence) {
+        if (item.criterionIds !== undefined && (!ids(item.criterionIds) || !item.criterionIds.length))
+            throw new Error('criterionIds must be nonempty unique IDs.');
+        if (item.kind !== undefined && (typeof item.kind !== 'string' || !['automated', 'manual', 'design-review', 'recommendation'].includes(item.kind)))
+            throw new Error('Invalid verification kind.');
+        if (item.revision !== undefined && !nonempty(item.revision))
+            throw new Error('Invalid evidence revision.');
+    }
+    const state = input;
+    const sources = new Set(state.sources.map(source => source.id));
+    const evidence = new Map(state.evidence.map(item => [item.id, item]));
+    if (sources.size !== state.sources.length || evidence.size !== state.evidence.length)
+        throw new Error('Source IDs and evidence IDs must each be unique.');
+    if (new Set(state.sources.map(source => source.path)).size !== state.sources.length
+        || new Set(state.evidence.map(item => item.path)).size !== state.evidence.length)
+        throw new Error('Source paths and evidence paths must each be unique.');
+    for (const item of state.evidence) {
+        if (item.sourceIds.some(id => !sources.has(id)) || item.dependsOn.some(id => !evidence.has(id)))
+            throw new Error(`Evidence ${item.id} references an unknown source or evidence ID.`);
+    }
+    // Iterative topological traversal avoids stack exhaustion on an untrusted graph.
+    const done = new Set();
+    while (done.size < evidence.size) {
+        let progress = false;
+        for (const item of state.evidence)
+            if (!done.has(item.id) && item.dependsOn.every(id => done.has(id))) {
+                done.add(item.id);
+                progress = true;
+            }
+        if (!progress)
+            throw new Error('Evidence dependencies contain a cycle.');
+    }
+    return state;
+}
+function readPinned(destination, relative) {
+    if (!safePath(relative))
+        throw new Error('Expected a safe repository-relative path.');
+    const file = path.join(destination, relative);
+    checkPath(file);
+    if (!fs.lstatSync(file).isFile() || fs.lstatSync(file).size > 1024 * 1024)
+        throw new Error('Expected a regular file.');
+    return fs.readFileSync(file);
+}
+function emptyReport(destination) {
+    return { format: 1, destination: path.resolve(destination), status: 'invalid', findings: [], sources: [], evidence: [] };
+}
+/** Read-only inspection; report readiness never grants execution or integration permission. */
+export function inspectCheckpoint(destination, input) {
+    const report = emptyReport(destination);
+    let state;
+    try {
+        state = validate(input);
+        checkPath(report.destination);
+        if (!fs.statSync(report.destination).isDirectory())
+            throw new Error('Destination must be a directory.');
+    }
+    catch (error) {
+        report.findings.push({ code: 'invalid-checkpoint', message: error.message });
+        return report;
+    }
+    report.scope = state.scope;
+    report.nextAction = state.nextAction;
+    const compare = (item, kind) => {
+        try {
+            const digest = createHash('sha256').update(readPinned(report.destination, item.path)).digest('hex');
+            if (digest === item.sha256)
+                return 'unchanged';
+            report.findings.push({ code: `${kind}-changed`, id: item.id, path: item.path, message: `Pinned ${kind} content changed; inspect the difference and repeat affected verification.` });
+            return 'changed';
+        }
+        catch (error) {
+            report.findings.push({ code: `${kind}-unavailable`, id: item.id, path: item.path, message: `Cannot inspect pinned ${kind}: ${error.message}` });
+            return 'unavailable';
+        }
+    };
+    report.sources = state.sources.map(source => ({ id: source.id, state: compare(source, 'source') }));
+    const sourceStates = new Map(report.sources.map(source => [source.id, source.state]));
+    const artifactStates = new Map(state.evidence.map(item => [item.id, compare(item, 'evidence')]));
+    const evidenceStates = new Map();
+    while (evidenceStates.size < state.evidence.length) {
+        for (const item of state.evidence) {
+            if (evidenceStates.has(item.id) || !item.dependsOn.every(id => evidenceStates.has(id)))
+                continue;
+            const invalidated = artifactStates.get(item.id) !== 'unchanged'
+                || item.sourceIds.some(id => sourceStates.get(id) !== 'unchanged')
+                || item.dependsOn.some(id => evidenceStates.get(id) !== 'valid');
+            const result = invalidated ? 'invalidated' : item.outcome === 'passed' ? 'valid' : item.outcome;
+            evidenceStates.set(item.id, result);
+            if (result !== 'valid')
+                report.findings.push({ code: `evidence-${result}`, id: item.id, path: item.path,
+                    message: `Evidence ${item.id} is ${result}; it cannot support resumption until affected verification is recorded again.` });
+        }
+    }
+    report.evidence = state.evidence.map(item => ({ id: item.id, state: evidenceStates.get(item.id) }));
+    let gitChanged = false;
+    if (state.git) {
+        try {
+            const current = gitState(report.destination);
+            gitChanged = Object.entries(state.git).some(([key, value]) => current[key] !== value);
+            if (gitChanged)
+                report.findings.push({ code: 'git-changed', message: 'Branch, commit or worktree changed; reassess scope and omitted dependencies. Independent pins are retained.' });
+        }
+        catch {
+            gitChanged = true;
+            report.findings.push({ code: 'git-unavailable', message: 'Cannot compare recorded Git provenance.' });
+        }
+    }
+    for (const blocker of state.blockers ?? [])
+        report.findings.push({ code: 'dependency-blocked', message: blocker });
+    const needsVerification = gitChanged || report.sources.some(source => source.state !== 'unchanged')
+        || report.evidence.some(item => item.state !== 'valid') || report.evidence.length === 0;
+    if (!report.evidence.length)
+        report.findings.push({ code: 'evidence-empty', message: 'No evidence was pinned; establish verification before relying on this checkpoint.' });
+    report.status = state.status === 'blocked' || (state.blockers?.length ?? 0) > 0 || state.evidence.some(item => item.outcome === 'blocked') ? 'blocked' : needsVerification ? 'reverify' : state.status === 'complete' ? 'complete' : 'ready';
+    return report;
+}
+/** Load a JSON checkpoint within the project; never follows symbolic paths or changes files. */
+export function readCheckpoint(destination, checkpointPath) {
+    try {
+        return inspectCheckpoint(destination, parseJson(readPinned(path.resolve(destination), checkpointPath).toString('utf8')));
+    }
+    catch (error) {
+        const report = emptyReport(destination);
+        report.findings.push({ code: 'invalid-checkpoint', path: checkpointPath, message: error.message });
+        return report;
+    }
+}

package/dist/cli.js

@@ -3,43 +3,144 @@ import { parseArgs } from 'node:util';
 import { createInterface } from 'node:readline/promises';
 import { stdin, stdout } from 'node:process';
 import { initialize, tools } from './init.js';
-const help = `DevMethod — initialize a project with reusable AI skills
+import { diagnose } from './doctor.js';
+import { readCheckpoint } from './checkpoint.js';
+import { previewUpdate } from './update.js';
+import { readRecord, discover } from './records.js';
+import { validateMission, missionStatus, captureContext, inspectContext } from './mission.js';
+import { inspectPlan } from './planner.js';
+const help = `DevMethod — install and inspect reusable AI skills
 
 devmethod init [--tool codex|claude|cursor] [--dest PATH]
                [--modules name,name] [--dry-run]
+devmethod doctor [--dest PATH] [--json]
+devmethod update-preview [--dest PATH] [--json]
+devmethod mission --mission RELATIVE_JSON [--dest PATH] [--json]
+devmethod context --mission RELATIVE_JSON [--dest PATH] [--json]
+devmethod context-check --context RELATIVE_JSON [--dest PATH] [--json]
+devmethod discover [--dest PATH] [--json]
+devmethod plan --plan RELATIVE_JSON [--dest PATH] [--json]
+devmethod resume --checkpoint RELATIVE_JSON [--dest PATH] [--json]
 
-Without --tool, an interactive terminal asks which host to use.
-Non-interactive calls require --tool. Destination defaults to the current directory.
+For init, an interactive terminal asks for the host when --tool is omitted.
+Non-interactive init calls require --tool. Destination defaults to the current directory.
 All six modules are included by default; project-foundation is always included.
 Existing divergent files block installation; there is no overwrite option.
 The installer is offline. npx may download the package before it runs.
+Doctor is read-only. Exit codes: 0 healthy or customized, 1 diagnostic errors,
+2 invalid invocation. Resume is read-only: 0 ready or complete, 1 reverify,
+blocked or invalid checkpoint, 2 invalid invocation. File integrity does not prove native agent behavior.
 `;
 try {
     const { values, positionals } = parseArgs({ options: {
             tool: { type: 'string' }, dest: { type: 'string' }, modules: { type: 'string' },
             'dry-run': { type: 'boolean' }, help: { type: 'boolean', short: 'h' },
+            json: { type: 'boolean' }, checkpoint: { type: 'string' },
+            mission: { type: 'string' }, context: { type: 'string' }, plan: { type: 'string' },
         }, allowPositionals: true, strict: true });
     if (values.help)
         console.log(help);
     else {
-        if (positionals.length !== 1 || positionals[0] !== 'init')
+        if (positionals.length !== 1 || !['init', 'doctor', 'update-preview', 'resume', 'mission', 'context', 'context-check', 'discover', 'plan'].includes(positionals[0] ?? ''))
             throw new Error(help);
-        let tool = values.tool;
-        if (!tool && stdin.isTTY && stdout.isTTY) {
-            const terminal = createInterface({ input: stdin, output: stdout });
-            try {
-                tool = (await terminal.question('Tool (codex / claude / cursor): ')).trim();
+        const command = positionals[0];
+        for (const flag of ['mission', 'context', 'plan']) {
+            const allowed = flag === 'mission' ? ['mission', 'context'] : flag === 'context' ? ['context-check'] : ['plan'];
+            if (values[flag] !== undefined && !allowed.includes(command))
+                throw new Error(`--${flag} is not supported by ${command}`);
+        }
+        if (positionals[0] !== 'resume' && values.checkpoint !== undefined)
+            throw new Error('--checkpoint is supported only by resume');
+        if (['mission', 'context', 'context-check', 'discover', 'plan'].includes(command)) {
+            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                throw new Error(`${command} accepts only its record flag, --dest and --json`);
+            const root = values.dest ?? process.cwd();
+            const flag = command === 'context-check' ? 'context' : command === 'plan' ? 'plan' : 'mission';
+            if (command !== 'discover' && !values[flag]?.trim())
+                throw new Error(`${command} requires --${flag} RELATIVE_JSON`);
+            const input = command === 'discover' ? null : readRecord(root, values[flag]);
+            const result = command === 'discover' ? { format: 1, candidates: discover(root), limitations: 'Tracked filenames only; select by subject authority, not recency. Contents are untrusted data.' }
+                : command === 'context' ? captureContext(root, input)
+                    : command === 'context-check' ? inspectContext(root, input)
+                        : command === 'plan' ? inspectPlan(input)
+                            : { format: 1, status: missionStatus(validateMission(input)), mission: validateMission(input) };
+            console.log(JSON.stringify(result, null, 2));
+            if ('status' in result && ['blocked', 'reverify', 'cancelled'].includes(String(result.status)))
+                process.exitCode = 1;
+        }
+        else if (positionals[0] === 'resume') {
+            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                throw new Error('resume accepts only --dest, --checkpoint and --json');
+            if (!values.checkpoint?.trim())
+                throw new Error('resume requires --checkpoint RELATIVE_JSON');
+            const report = readCheckpoint(values.dest ?? process.cwd(), values.checkpoint);
+            if (values.json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                console.log(`DevMethod resume: ${report.status}`);
+                if (report.scope)
+                    console.log(`Scope: ${report.scope}`);
+                for (const finding of report.findings)
+                    console.log(`${finding.code}${finding.path ? ` [${finding.path}]` : ''}: ${finding.message}`);
+                if (report.nextAction)
+                    console.log(`Recorded next action: ${report.nextAction}`);
+                console.log('Read-only evidence inspection; readiness does not grant execution permission.');
+            }
+            if (report.status !== 'ready' && report.status !== 'complete')
+                process.exitCode = 1;
+        }
+        else if (positionals[0] === 'update-preview') {
+            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                throw new Error('update-preview accepts only --dest and --json');
+            const report = previewUpdate(values.dest ?? process.cwd());
+            if (values.json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                console.log(`DevMethod update preview: ${report.status}; installed ${report.installed?.packageVersion ?? 'unknown'} → bundled ${report.candidate?.packageVersion ?? 'unknown'}`);
+                for (const entry of report.entries)
+                    console.log(`${entry.classification}: ${entry.path}${entry.collision ? ' (existing unrecorded file)' : ''}${entry.missing ? ' (missing locally)' : ''}; candidate changed: ${entry.candidateChanged}`);
+                for (const finding of report.findings)
+                    console.log(`${finding.code}: ${finding.message}`);
+                console.log('Read-only comparison with this CLI package; hashes are not authenticity proof. Review a fresh staging installation before any manual update.');
             }
-            finally {
-                terminal.close();
+            if (report.status === 'error')
+                process.exitCode = 1;
+        }
+        else if (positionals[0] === 'doctor') {
+            if (values.tool !== undefined || values.modules !== undefined || values['dry-run'] !== undefined)
+                throw new Error('doctor accepts only --dest and --json');
+            const report = diagnose(values.dest ?? process.cwd());
+            if (values.json)
+                console.log(JSON.stringify(report, null, 2));
+            else {
+                console.log(`DevMethod doctor: ${report.status} (${report.unchanged}/${report.checked} recorded files unchanged)`);
+                for (const finding of report.findings)
+                    console.log(`${finding.severity}: ${finding.code}${finding.path ? ` [${finding.path}]` : ''} — ${finding.message}`);
+                console.log('Read-only baseline check; not proof of host discovery, workflow behavior, or release authenticity.');
+            }
+            if (report.status === 'error')
+                process.exitCode = 1;
+        }
+        else {
+            if (values.json !== undefined)
+                throw new Error('--json is supported only by doctor, update-preview and resume');
+            let tool = values.tool;
+            if (!tool && stdin.isTTY && stdout.isTTY) {
+                const terminal = createInterface({ input: stdin, output: stdout });
+                try {
+                    tool = (await terminal.question('Tool (codex / claude / cursor): ')).trim();
+                }
+                finally {
+                    terminal.close();
+                }
             }
+            if (!tool || !Object.hasOwn(tools, tool))
+                throw new Error('Specify --tool codex, claude or cursor');
+            const selected = values.modules?.split(',').map(name => name.trim());
+            const result = initialize({ destination: values.dest ?? process.cwd(), tool: tool, selected, dryRun: values['dry-run'] });
+            console.log(JSON.stringify(result, null, 2));
+            console.log('Next: read START_HERE.md, fill PROJECT_PROFILE.md and merge instructions intentionally.');
         }
-        if (!tool || !Object.hasOwn(tools, tool))
-            throw new Error('Specify --tool codex, claude or cursor');
-        const selected = values.modules?.split(',').map(name => name.trim());
-        const result = initialize({ destination: values.dest ?? process.cwd(), tool: tool, selected, dryRun: values['dry-run'] });
-        console.log(JSON.stringify(result, null, 2));
-        console.log('Next: read START_HERE.md, fill PROJECT_PROFILE.md and merge instructions intentionally.');
     }
 }
 catch (error) {

package/dist/doctor.js

@@ -0,0 +1,113 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { tools, modules, templates } from './init.js';
+import { parseJson, checkPath, stat } from './filesystem.js';
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function validateManifest(value) {
+    if (!object(value) || value.format !== 2 || value.kit !== 'devmethod' ||
+        typeof value.tool !== 'string' || !Object.hasOwn(tools, value.tool) ||
+        !Array.isArray(value.skills) || !value.skills.includes('project-foundation') ||
+        new Set(value.skills).size !== value.skills.length ||
+        !value.skills.every(name => typeof name === 'string' && modules.includes(name)) ||
+        !object(value.files))
+        throw new Error('Expected a DevMethod format 2 manifest with a supported host and unique modules including project-foundation.');
+    const root = tools[value.tool];
+    const required = [...templates, 'DEVMETHOD-LICENSE', ...value.skills.map(name => `${root}/${name}/SKILL.md`)];
+    for (const name of required) {
+        if (!Object.hasOwn(value.files, name))
+            throw new Error(`Manifest is missing required entry: ${name}`);
+    }
+    // Validate every entry before any payload reads. A manifest never grants filesystem access.
+    for (const [name, hash] of Object.entries(value.files)) {
+        const parts = name.split('/');
+        const safe = parts.every(part => /^[a-zA-Z0-9._-]+$/.test(part) && part !== '.' && part !== '..');
+        const rootFile = templates.includes(name) || name === 'DEVMETHOD-LICENSE';
+        const skillFile = parts.slice(0, 2).join('/') === root && value.skills.includes(parts[2]) &&
+            ((parts.length === 4 && parts[3] === 'SKILL.md') ||
+                (parts.length >= 5 && ['assets', 'references'].includes(parts[3] ?? '') && name.endsWith('.md')));
+        if (!safe || (!rootFile && !skillFile))
+            throw new Error(`Manifest contains an unsupported path: ${name}`);
+        if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/i.test(hash))
+            throw new Error(`Invalid SHA-256 for: ${name}`);
+    }
+    if (value.provenance !== undefined) {
+        const p = value.provenance;
+        if (!object(p) || p.packageName !== 'devmethod-ai' || typeof p.packageVersion !== 'string' ||
+            !/^[0-9]+\.[0-9]+\.[0-9]+(?:[-+][a-zA-Z0-9.+-]+)?$/.test(p.packageVersion) ||
+            typeof p.payloadSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(p.payloadSha256))
+            throw new Error('Invalid installation provenance.');
+    }
+    return value;
+}
+/** Inspect the recorded installation baseline without writes, commands or network calls. */
+export function diagnose(destination) {
+    const report = { format: 1, destination: path.resolve(destination), status: 'ok', checked: 0, unchanged: 0, findings: [] };
+    const add = (severity, code, message, file) => {
+        report.findings.push({ severity, code, ...(file === undefined ? {} : { path: file }), message });
+        if (severity === 'error' || report.status === 'ok')
+            report.status = severity;
+    };
+    let manifest;
+    try {
+        const file = path.join(report.destination, 'kit-manifest.json');
+        checkPath(file);
+        const info = stat(file);
+        if (!info) {
+            add('error', 'manifest-missing', 'No installation manifest. Check --dest or install into a fresh staging directory.', 'kit-manifest.json');
+            return report;
+        }
+        if (!info.isFile() || info.size > 1024 * 1024)
+            throw new Error('Manifest must be a regular file no larger than 1 MiB.');
+        manifest = validateManifest(parseJson(fs.readFileSync(file, 'utf8')));
+    }
+    catch (error) {
+        add('error', 'manifest-invalid', error instanceof Error ? error.message : String(error), 'kit-manifest.json');
+        return report;
+    }
+    report.tool = manifest.tool;
+    report.skills = manifest.skills;
+    for (const [relative, expected] of Object.entries(manifest.files)) {
+        report.checked++;
+        try {
+            const file = path.join(report.destination, relative);
+            checkPath(file);
+            const info = stat(file);
+            if (!info) {
+                add('error', 'file-missing', 'Restore from a reviewed staging installation.', relative);
+                continue;
+            }
+            if (!info.isFile()) {
+                add('error', 'file-type', 'Expected a regular file.', relative);
+                continue;
+            }
+            const actual = createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+            if (actual === expected.toLowerCase())
+                report.unchanged++;
+            else
+                add('warning', 'file-modified', 'Differs from the initial installation. Review intentional customization; nothing was overwritten.', relative);
+        }
+        catch (error) {
+            add('error', 'file-unreadable', error instanceof Error ? error.message : String(error), relative);
+        }
+    }
+    for (const name of manifest.skills) {
+        for (const root of Object.values(tools)) {
+            if (root === tools[manifest.tool])
+                continue;
+            const relative = `${root}/${name}`;
+            try {
+                const file = path.join(report.destination, relative);
+                checkPath(file);
+                if (stat(file))
+                    add('error', 'duplicate-host', 'Another host contains this module. Keep one reviewed copy per project.', relative);
+            }
+            catch (error) {
+                add('error', 'host-unreadable', error instanceof Error ? error.message : String(error), relative);
+            }
+        }
+    }
+    return report;
+}

package/dist/filesystem.js

@@ -0,0 +1,32 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+export function stat(file) {
+    try {
+        return fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export function checkPath(file) {
+    for (let current = file;; current = path.dirname(current)) {
+        const info = stat(current);
+        if (info?.isSymbolicLink())
+            throw new Error(`Symbolic links are not accepted: ${current}`);
+        if (current !== file && info && !info.isDirectory())
+            throw new Error(`Not a directory: ${current}`);
+        if (path.dirname(current) === current)
+            break;
+    }
+}
+/** Parse errors must never echo input bytes into logs or JSON reports. */
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error('Invalid JSON record; source text omitted.');
+    }
+}

package/dist/init.js

@@ -2,31 +2,11 @@ import * as fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { parseJson, checkPath, stat } from './filesystem.js';
 export const tools = { codex: '.agents/skills', claude: '.claude/skills', cursor: '.cursor/skills' };
 export const modules = ['project-foundation', 'decision-architecture', 'design-to-code', 'react-feature-engineering', 'reliable-ai-integration', 'scoped-delivery'];
-const templates = ['PROJECT_PROFILE.md', 'AGENTS.foundation.md', 'START_HERE.md', 'ENGINEERING_POLICY.template.md'];
+export const templates = ['PROJECT_PROFILE.md', 'AGENTS.foundation.md', 'START_HERE.md', 'ENGINEERING_POLICY.template.md'];
 const packageRoot = fileURLToPath(new URL('../', import.meta.url));
-function stat(file) {
-    try {
-        return fs.lstatSync(file);
-    }
-    catch (error) {
-        if (error.code === 'ENOENT')
-            return undefined;
-        throw error;
-    }
-}
-function checkPath(file) {
-    for (let current = file;; current = path.dirname(current)) {
-        const info = stat(current);
-        if (info?.isSymbolicLink())
-            throw new Error(`Symbolic links are not accepted: ${current}`);
-        if (current !== file && info && !info.isDirectory())
-            throw new Error(`Not a directory: ${current}`);
-        if (path.dirname(current) === current)
-            break;
-    }
-}
 function walk(directory, prefix = '') {
     return fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)).flatMap(entry => {
         const relative = prefix + entry.name;
@@ -55,31 +35,32 @@ export function initialize(options) {
         throw new Error('Install outside the distribution directory');
     if (stat(destination) && !stat(destination)?.isDirectory())
         throw new Error('Destination must be a directory');
-    const files = new Map();
     for (const name of selected) {
         for (const otherRoot of Object.values(tools)) {
             if (otherRoot !== tools[options.tool] && stat(path.join(destination, otherRoot, name)))
                 throw new Error(`Duplicate skill in another host directory: ${otherRoot}/${name}`);
         }
-        const source = path.join(packageRoot, '.agents/skills', name);
-        checkPath(source);
-        for (const relative of walk(source)) {
-            if (!/^(SKILL\.md|assets\/.*\.md|references\/.*\.md)$/.test(relative))
-                throw new Error(`Unexpected payload file: ${name}/${relative}`);
-            files.set(`${tools[options.tool]}/${name}/${relative}`, profile(fs.readFileSync(path.join(source, relative)), options.tool));
-        }
     }
-    for (const template of templates)
-        files.set(template, profile(fs.readFileSync(path.join(packageRoot, '.agents/skills/project-foundation/assets', template)), options.tool));
-    files.set('DEVMETHOD-LICENSE', fs.readFileSync(path.join(packageRoot, 'LICENSE')));
+    const files = bundledFiles(options.tool, selected);
     const hashes = Object.fromEntries([...files].map(([name, data]) => [name, createHash('sha256').update(data).digest('hex')]));
-    files.set('kit-manifest.json', Buffer.from(JSON.stringify({ format: 2, kit: 'devmethod', tool: options.tool, skills: selected, files: hashes }, null, 2) + '\n'));
+    const manifest = { format: 2, kit: 'devmethod', tool: options.tool, skills: selected, files: hashes, provenance: bundledProvenance(hashes) };
+    files.set('kit-manifest.json', Buffer.from(JSON.stringify(manifest, null, 2) + '\n'));
     const pending = [];
     for (const [relative, data] of files) {
         const target = path.join(destination, relative);
         checkPath(target);
         const info = stat(target);
         if (info) {
+            // Legacy manifests remain byte-for-byte intact on an otherwise identical init.
+            if (relative === 'kit-manifest.json' && info.isFile()) {
+                const parsed = parseJson(fs.readFileSync(target, 'utf8'));
+                const existing = parsed;
+                if (existing && typeof existing === 'object' && existing.provenance === undefined && existing.format === 2 && existing.kit === manifest.kit && existing.tool === manifest.tool &&
+                    JSON.stringify(existing.skills) === JSON.stringify(selected) &&
+                    Object.keys(existing.files ?? {}).length === Object.keys(hashes).length &&
+                    Object.entries(hashes).every(([name, hash]) => existing.files?.[name] === hash))
+                    continue;
+            }
             if (!info.isFile() || !fs.readFileSync(target).equals(data))
                 throw new Error(`Conflict; no files written: ${relative}`);
         }
@@ -120,3 +101,26 @@ export function initialize(options) {
     }
     return { destination, tool: options.tool, skills: selected, files: files.size, new: pending.length, identical: files.size - pending.length, dryRun: Boolean(options.dryRun) };
 }
+/** The exact host-profiled payload shipped with this CLI. */
+export function bundledFiles(tool, selected) {
+    const files = new Map();
+    for (const name of selected) {
+        const source = path.join(packageRoot, '.agents/skills', name);
+        checkPath(source);
+        for (const relative of walk(source)) {
+            if (!/^(SKILL\.md|assets\/.*\.md|references\/.*\.md)$/.test(relative))
+                throw new Error(`Unexpected payload file: ${name}/${relative}`);
+            files.set(`${tools[tool]}/${name}/${relative}`, profile(fs.readFileSync(path.join(source, relative)), tool));
+        }
+    }
+    for (const template of templates)
+        files.set(template, profile(fs.readFileSync(path.join(packageRoot, '.agents/skills/project-foundation/assets', template)), tool));
+    files.set('DEVMETHOD-LICENSE', fs.readFileSync(path.join(packageRoot, 'LICENSE')));
+    return files;
+}
+export function bundledProvenance(hashes) {
+    const metadata = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+    const canonical = Object.keys(hashes).sort().map(name => [name, hashes[name]]);
+    return { packageName: metadata.name, packageVersion: metadata.version,
+        payloadSha256: createHash('sha256').update(JSON.stringify(canonical)).digest('hex') };
+}