devmethod-ai 0.1.0-rc.2 → 0.2.0

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') };
+}

package/dist/mission.js

@@ -0,0 +1,85 @@
+import { object, text, id, safePath, secretPath, readLocal, digest, hash, gitState, validGit } from './records.js';
+const list = (v) => Array.isArray(v) && v.length <= 256 && v.every(text);
+const oneOf = (v, values) => typeof v === 'string' && values.includes(v);
+export function validateMission(v) {
+    if (!object(v) || v.format !== 1 || !id(v.id) || !oneOf(v.path, ['quick', 'standard', 'major']) || !text(v.outcome)
+        || !text(v.owner) || !oneOf(v.status, ['active', 'blocked', 'complete']))
+        throw new Error('Mission format 1 requires id, path, outcome, owner and status.');
+    for (const key of ['scope', 'exclusions', 'invariants', 'uncertainties', 'stopConditions'])
+        if (!list(v[key]))
+            throw new Error(`Mission ${key} must be a bounded string array.`);
+    if (!v.scope.length || !v.stopConditions.length)
+        throw new Error('Scope and stop conditions cannot be empty.');
+    if (v.status === 'complete' ? v.nextAction !== null : !text(v.nextAction))
+        throw new Error('Active/blocked mission needs nextAction; complete requires null.');
+    if (!Array.isArray(v.sources) || v.sources.length === 0 || v.sources.length > 64 || !v.sources.every(s => object(s)
+        && id(s.id) && safePath(s.path) && !secretPath(s.path) && oneOf(s.level, ['project', 'domain', 'mission', 'execution'])
+        && oneOf(s.kind, ['fact', 'assumption', 'proposal', 'accepted-decision']) && text(s.reason) && text(s.authority) && text(s.revision)))
+        throw new Error('Select 1–64 safe sources with level, reason, authority, kind and revision; secret paths are excluded.');
+    if (!Array.isArray(v.acceptance) || !v.acceptance.length || v.acceptance.length > 128 || !v.acceptance.every(c => object(c)
+        && id(c.id) && text(c.description) && list(c.changes) && c.changes.length > 0 && c.changes.every(safePath)
+        && text(c.verification) && oneOf(c.kind, ['automated', 'manual', 'design-review', 'recommendation'])))
+        throw new Error('Acceptance criteria require IDs, changes, verification and verification kind.');
+    if (!Array.isArray(v.dependencies) || v.dependencies.length > 128 || !v.dependencies.every(d => object(d) && id(d.id) && text(d.owner) && text(d.detail) && oneOf(d.status, ['resolved', 'blocked'])))
+        throw new Error('Dependencies require id, owner, detail and resolved/blocked status.');
+    const mission = v;
+    const sourceIds = new Set(mission.sources.map(s => s.id));
+    if (sourceIds.size !== mission.sources.length || new Set(mission.sources.map(s => s.path)).size !== mission.sources.length
+        || new Set(mission.acceptance.map(c => c.id)).size !== mission.acceptance.length
+        || new Set(mission.dependencies.map(d => d.id)).size !== mission.dependencies.length)
+        throw new Error('IDs and source paths must be unique.');
+    if (!Array.isArray(v.contradictions) || v.contradictions.length > 128 || !v.contradictions.every(c => object(c)
+        && list(c.sourceIds) && c.sourceIds.length >= 2 && c.sourceIds.every(s => sourceIds.has(s)) && text(c.detail) && typeof c.resolved === 'boolean'))
+        throw new Error('Contradictions require at least two selected source IDs, detail and resolved boolean.');
+    return { format: 1, id: mission.id, path: mission.path, outcome: mission.outcome,
+        scope: [...mission.scope], exclusions: [...mission.exclusions], invariants: [...mission.invariants], uncertainties: [...mission.uncertainties],
+        owner: mission.owner, status: mission.status, nextAction: mission.nextAction, stopConditions: [...mission.stopConditions],
+        acceptance: mission.acceptance.map(c => ({ id: c.id, description: c.description, changes: [...c.changes], verification: c.verification, kind: c.kind })),
+        sources: mission.sources.map(s => ({ id: s.id, path: s.path, level: s.level, reason: s.reason, authority: s.authority, kind: s.kind, revision: s.revision })),
+        dependencies: mission.dependencies.map(d => ({ id: d.id, owner: d.owner, status: d.status, detail: d.detail })),
+        contradictions: mission.contradictions.map(c => ({ sourceIds: [...c.sourceIds], detail: c.detail, resolved: c.resolved })) };
+}
+export function missionStatus(mission) {
+    if (mission.status === 'blocked' || mission.dependencies.some(d => d.status === 'blocked') || mission.contradictions.some(c => !c.resolved))
+        return 'blocked';
+    return mission.status === 'complete' ? 'complete' : 'ready';
+}
+function sourceHash(root, file) {
+    const bytes = readLocal(root, file, 256 * 1024);
+    const body = bytes.toString('utf8');
+    if (body.includes('\0') || /-----BEGIN [A-Z ]*PRIVATE KEY-----|(?:api[_-]?key|password|secret|token)\s*[:=]\s*["']?[A-Za-z0-9_\-/+]{20,}/i.test(body))
+        throw new Error(`Potential credential or binary source excluded: ${file}`);
+    return digest(bytes);
+}
+/** Metadata only; source text and command execution are deliberately excluded. */
+export function captureContext(root, input) {
+    const mission = validateMission(input);
+    return { format: 1, mission, git: gitState(root), sources: mission.sources.map(s => ({ ...s, sha256: sourceHash(root, s.path) })) };
+}
+export function inspectContext(root, input) {
+    if (!object(input) || input.format !== 1 || !validGit(input.git))
+        throw new Error('Expected context format 1 with Git provenance.');
+    const mission = validateMission(input.mission);
+    if (!Array.isArray(input.sources) || input.sources.length !== mission.sources.length)
+        throw new Error('Context pins must match mission selection.');
+    const pins = input.sources;
+    for (let i = 0; i < pins.length; i++) {
+        const pin = pins[i];
+        if (!object(pin) || !hash(pin.sha256) || Object.entries(mission.sources[i]).some(([k, value]) => pin[k] !== value))
+            throw new Error('Context source metadata differs from mission selection.');
+    }
+    const sources = mission.sources.map((s, i) => {
+        try {
+            return { id: s.id, state: sourceHash(root, s.path) === pins[i].sha256 ? 'unchanged' : 'changed' };
+        }
+        catch {
+            return { id: s.id, state: 'unavailable' };
+        }
+    });
+    const current = gitState(root);
+    const gitChanged = Object.entries(input.git).some(([key, value]) => current[key] !== value);
+    const stale = gitChanged || sources.some(s => s.state !== 'unchanged');
+    return { format: 1, missionId: mission.id, status: missionStatus(mission) === 'blocked' ? 'blocked' : stale ? 'reverify' : missionStatus(mission),
+        sources, gitChanged, currentGit: current, nextAction: mission.nextAction,
+        limitations: 'Explicit pins only. Git changes require reassessment; semantic contradictions, external state and untracked file contents need manual review. No execution authorization.' };
+}

package/dist/planner.js

@@ -0,0 +1,65 @@
+import { object, text, id, safePath } from './records.js';
+const strings = (v) => Array.isArray(v) && v.length <= 128 && v.every(text) && new Set(v).size === v.length;
+const overlaps = (a, b) => a.toLowerCase() === b.toLowerCase() || a.toLowerCase().startsWith(b.toLowerCase() + '/') || b.toLowerCase().startsWith(a.toLowerCase() + '/');
+export function inspectPlan(input) {
+    if (!object(input) || input.format !== 1 || typeof input.status !== 'string' || !['active', 'complete', 'cancelled'].includes(input.status)
+        || ![1, 2].includes(input.concurrency) || !text(input.contractOwner) || !strings(input.sharedContracts) || !input.sharedContracts.every(safePath)
+        || !Array.isArray(input.tasks) || !input.tasks.length || input.tasks.length > 128)
+        throw new Error('Expected bounded plan format 1, concurrency 1 or 2, contractOwner, sharedContracts and 1–128 tasks.');
+    for (const t of input.tasks)
+        if (!object(t) || !id(t.id) || !text(t.owner) || !safePath(t.worktree)
+            || !strings(t.owns) || !t.owns.length || !t.owns.every(safePath) || !strings(t.dependsOn) || !t.dependsOn.every(id)
+            || !strings(t.acceptance) || !t.acceptance.length || !safePath(t.checkpoint)
+            || typeof t.status !== 'string' || !['pending', 'running', 'passed', 'failed', 'blocked', 'cancelled'].includes(t.status)
+            || !Number.isInteger(t.attempts) || t.attempts < 0 || !Number.isInteger(t.maxAttempts) || t.maxAttempts < 1 || t.maxAttempts > 10 || t.attempts > t.maxAttempts
+            || typeof t.evidence !== 'string' || !['current', 'stale', 'missing'].includes(t.evidence))
+            throw new Error('Invalid task: require ownership, isolated worktree, dependencies, acceptance, bounded attempts, checkpoint and evidence state.');
+    const plan = input;
+    const byId = new Map(plan.tasks.map(t => [t.id, t]));
+    if (byId.size !== plan.tasks.length)
+        throw new Error('Duplicate task ID.');
+    for (const t of plan.tasks) {
+        if (t.dependsOn.some(d => !byId.has(d)))
+            throw new Error('Unknown dependency.');
+        if (t.owns.some(p => plan.sharedContracts.some(c => overlaps(p, c))) && t.owner !== plan.contractOwner)
+            throw new Error('Shared contracts require the single contract owner.');
+        if (['running', 'passed', 'failed'].includes(t.status) && t.attempts === 0)
+            throw new Error('Running, passed or failed tasks require a recorded attempt.');
+    }
+    for (let i = 0; i < plan.tasks.length; i++)
+        for (const b of plan.tasks.slice(i + 1)) {
+            const a = plan.tasks[i];
+            if (overlaps(a.worktree, b.worktree))
+                throw new Error('Worktrees must be distinct and non-nested.');
+            if (a.owns.some(p => b.owns.some(q => overlaps(p, q))))
+                throw new Error('Task ownership must not overlap, even across dependent tasks.');
+        }
+    const done = new Set();
+    while (done.size < plan.tasks.length) {
+        let progress = false;
+        for (const t of plan.tasks)
+            if (!done.has(t.id) && t.dependsOn.every(d => done.has(d))) {
+                done.add(t.id);
+                progress = true;
+            }
+        if (!progress)
+            throw new Error('Task dependency cycle.');
+    }
+    const results = new Map();
+    for (const key of done) {
+        const t = byId.get(key);
+        results.set(key, t.status === 'running' ? 'needs-reconciliation' : t.status === 'passed' ?
+            t.evidence === 'current' && t.dependsOn.every(d => results.get(d) === 'passed') ? 'passed' : 'blocked' :
+            t.status !== 'pending' ? t.status : t.attempts >= t.maxAttempts ? 'exhausted' : t.evidence === 'stale' ? 'blocked' :
+                t.dependsOn.every(d => results.get(d) === 'passed') ? 'eligible' : 'blocked');
+    }
+    const running = plan.tasks.filter(t => t.status === 'running').length;
+    if (running > plan.concurrency)
+        throw new Error('Running tasks exceed concurrency.');
+    if (plan.status === 'complete' && [...results.values()].some(s => s !== 'passed'))
+        throw new Error('Completed plan requires current passing evidence for every task.');
+    const candidates = plan.status === 'active' && running === 0 ? plan.tasks.filter(t => results.get(t.id) === 'eligible').slice(0, plan.concurrency).map(t => t.id) : [];
+    return { format: 1, status: plan.status, tasks: plan.tasks.map(t => ({ id: t.id, state: results.get(t.id) })), candidates,
+        adapter: 'manual-planning-only', dispatch: 'not-implemented',
+        limitations: 'Claims are supplied by the operator; validate checkpoint evidence and actual isolated worktrees before use. Running tasks require reconciliation. No retries, host dispatch or new authorization.' };
+}

package/dist/records.js

@@ -0,0 +1,76 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { parseJson, checkPath } from './filesystem.js';
+export const object = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+export const text = (v) => typeof v === 'string' && v.trim().length > 0 && v.length <= 8192;
+export const id = (v) => typeof v === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(v);
+export const digest = (v) => createHash('sha256').update(v).digest('hex');
+export const hash = (v) => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
+export function safePath(v) {
+    return typeof v === 'string' && v.length > 0 && v.length <= 1024 && !/[\\:\x00-\x1f\x7f]/.test(v)
+        && v.split('/').every(p => p.length > 0 && p !== '.' && p !== '..' && !/[. ]$/.test(p)
+            && !/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(p));
+}
+export const secretPath = (v) => /(^|\/)(\.env(?:\..*)?|\.git|\.ssh|\.npmrc|credentials(?:\..*)?|secrets?(?:\..*)?)(\/|$)|\.(pem|key|p12|pfx)$/i.test(v);
+export function readLocal(root, file, limit = 1024 * 1024) {
+    if (!safePath(file))
+        throw new Error('Expected a safe repository-relative path.');
+    const target = path.resolve(root, file);
+    checkPath(target);
+    const info = fs.lstatSync(target);
+    if (!info.isFile() || info.size > limit)
+        throw new Error(`Expected regular file within ${limit} bytes: ${file}`);
+    return fs.readFileSync(target);
+}
+export function readRecord(root, file) {
+    if (secretPath(file))
+        throw new Error('Secret-like record paths are excluded.');
+    const bytes = readLocal(root, file);
+    return parseJson(bytes.toString('utf8'));
+}
+function git(root, args) {
+    checkPath(path.resolve(root));
+    return execFileSync('git', ['--no-optional-locks', '-c', 'core.fsmonitor=false', '-C', path.resolve(root), ...args], {
+        encoding: 'utf8', timeout: 10000, maxBuffer: 8 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+        env: { ...process.env, GIT_PAGER: 'cat', GIT_TERMINAL_PROMPT: '0' }
+    });
+}
+export function gitState(root) {
+    // Avoid status/diff: repository-configured clean filters can execute even during reads.
+    // ls-files reads index metadata; hash raw tracked bytes ourselves, without conversion.
+    const index = git(root, ['ls-files', '--stage', '-z']);
+    const tracked = git(root, ['ls-files', '-z']).split('\0').filter(Boolean);
+    if (tracked.length > 10000)
+        throw new Error('Git provenance exceeds 10000 tracked files.');
+    let bytesRead = 0;
+    const working = tracked.map(file => {
+        if (!safePath(file) || secretPath(file))
+            return [file, 'excluded'];
+        const target = path.resolve(root, file);
+        checkPath(target);
+        if (!fs.existsSync(target))
+            return [file, 'missing'];
+        const info = fs.lstatSync(target);
+        if (info.isDirectory())
+            return [file, 'directory-or-submodule'];
+        bytesRead += info.size;
+        if (bytesRead > 64 * 1024 * 1024)
+            throw new Error('Git provenance exceeds 64 MiB of tracked content; use selected checkpoint pins instead.');
+        return [file, digest(readLocal(root, file, 8 * 1024 * 1024)), info.mode & 0o111];
+    });
+    const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    return { branch: git(root, ['rev-parse', '--abbrev-ref', 'HEAD']).trim(), commit: git(root, ['rev-parse', 'HEAD']).trim(),
+        statusSha256: digest(index + '\0' + untracked), diffSha256: digest(JSON.stringify(working)) };
+}
+export function validGit(v) {
+    return object(v) && text(v.branch) && typeof v.commit === 'string' && /^[a-f0-9]{40,64}$/.test(v.commit)
+        && hash(v.statusSha256) && hash(v.diffSha256);
+}
+export function discover(root) {
+    const files = git(root, ['ls-files', '-z']).split('\0').filter(v => safePath(v) && !secretPath(v));
+    if (files.length > 10000)
+        throw new Error('Discovery exceeds 10000 tracked paths; select sources explicitly.');
+    return files;
+}

package/dist/update.js

@@ -0,0 +1,57 @@
+import * as fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { bundledFiles, bundledProvenance } from './init.js';
+import { diagnose, validateManifest } from './doctor.js';
+import { parseJson, checkPath, stat } from './filesystem.js';
+const hash = (data) => createHash('sha256').update(data).digest('hex');
+/** Preview only. No staging writes, migrations, subprocesses, or network calls. */
+export function previewUpdate(destination) {
+    const report = { format: 1, destination: path.resolve(destination), status: 'ok', provenance: 'unknown', entries: [], findings: [] };
+    try {
+        const diagnostics = diagnose(report.destination);
+        report.findings.push(...diagnostics.findings);
+        report.status = diagnostics.status;
+        // Missing files are represented in the comparison, but remain diagnostic errors.
+        if (diagnostics.findings.some(f => f.severity === 'error' && f.code !== 'file-missing'))
+            return report;
+        const manifestPath = path.join(report.destination, 'kit-manifest.json');
+        checkPath(manifestPath);
+        const info = stat(manifestPath);
+        if (!info?.isFile() || info.size > 1024 * 1024)
+            throw new Error('Invalid manifest file.');
+        const manifest = validateManifest(parseJson(fs.readFileSync(manifestPath, 'utf8')));
+        report.installed = manifest.provenance;
+        report.provenance = manifest.provenance ? 'recorded' : 'unknown';
+        if (!manifest.provenance) {
+            if (report.status === 'ok')
+                report.status = 'warning';
+            report.findings.push({ code: 'provenance-unknown', message: 'Legacy installation: package version is unknown; recorded file hashes remain the comparison baseline.' });
+        }
+        const candidate = bundledFiles(manifest.tool, manifest.skills);
+        const hashes = Object.fromEntries([...candidate].map(([name, data]) => [name, hash(data)]));
+        report.candidate = bundledProvenance(hashes);
+        for (const name of [...new Set([...Object.keys(manifest.files), ...candidate.keys()])].sort()) {
+            const baseline = manifest.files[name]?.toLowerCase();
+            const next = hashes[name];
+            const file = path.join(report.destination, name);
+            checkPath(file);
+            const current = stat(file);
+            if (current && !current.isFile())
+                throw new Error(`Expected a regular file: ${name}`);
+            const actual = current ? hash(fs.readFileSync(file)) : undefined;
+            const customized = baseline !== undefined && actual !== baseline;
+            const classification = baseline === undefined ? 'added' : customized && baseline !== next && actual !== next ? 'conflict' : customized ? 'customized' : next === undefined ? 'removed' : baseline === next ? 'unchanged' : 'updated';
+            const collision = baseline === undefined && actual !== undefined;
+            report.entries.push({ path: name, classification, installedSha256: actual, baselineSha256: baseline, candidateSha256: next,
+                candidateChanged: baseline !== next, ...(actual === undefined ? { missing: true } : {}), ...(collision ? { collision: true } : {}) });
+            if ((customized || collision) && report.status === 'ok')
+                report.status = 'warning';
+        }
+    }
+    catch (error) {
+        report.status = 'error';
+        report.findings.push({ code: 'preview-failed', message: error instanceof Error ? error.message : String(error) });
+    }
+    return report;
+}

package/docs/ADR-001-distribution.md

@@ -0,0 +1,13 @@
+# ADR 001: Portable skill distribution
+
+Status: accepted, 2026-09-12.
+
+Distribute six Markdown skills with a strict TypeScript installer compiled to JavaScript. Require Node.js 22+ and npm, with no runtime dependencies. Store the source skills in `.agents/skills`; install one chosen host profile. Keep one copy of each skill per project to avoid ambiguous discovery. Commit dist/ alongside src/ so GitHub installation requires no build hooks. Use a lockfile for development dependencies.
+
+The fourteen workflow stages are arguments to the project-foundation skill. They are model instructions, not deterministic executable commands. Native host permissions and project decisions remain authoritative. A next-command suggestion never grants execution permission.
+
+Claude Code and Cursor each have a native installation profile. Format compliance and authenticated behavioral validation are separate gates. Personal interface metadata and icons are excluded. Installation conflicts fail before any file is written; existing project instructions must be merged intentionally.
+
+The init command chooses a host and optional modules, always includes project-foundation, and defaults to the current project. Non-interactive calls require an explicit host. Include a separately named MIT notice and reject symbolic paths and duplicate host copies. Install into directories that are not being concurrently modified: rollback covers files and directories created by this process, not concurrent external changes or process termination.
+
+Installation is offline after npm obtains the package. No telemetry, model call, credential storage or deployment is introduced. GitHub installation and npm registry publication are separate; registry publication requires maintainer authentication. Upgrade through a staging directory and intentional review of differences. Project context is never migrated automatically.

package/docs/ADR-002-read-only-diagnostics.md

@@ -0,0 +1,25 @@
+# ADR 002: Read-only installation diagnostics
+
+Status: proposed for maintainer review with this implementation.
+
+## Problem
+
+`init` safely refuses divergent files, but cannot explain whether an adopted installation is missing files, intentionally customized, or duplicated across hosts. Users need this diagnosis before comparing an update.
+
+## Proposed contract
+
+Add `devmethod doctor [--dest PATH] [--json]`. Infer the host from the existing format 2 manifest. Keep the existing manifest format and support installations made before this command. Do not compare an older installation against the current package's entire file list: that would confuse an upgrade with corruption.
+
+Validate the manifest structure and permitted paths before reading payload files. Require the root templates, license and selected module entry points in the manifest. Inspect recorded SHA-256 hashes, missing or non-regular files, symbolic paths and duplicate selected modules in other host directories. No writes, subprocesses, repairs, network access, or host execution.
+
+JSON report format 1 contains destination, status, optional inferred host/modules, checked/unchanged counts and findings with severity, code, optional path, and message. Codes identify categories; message wording may evolve. Exit 0 for a clean or customized installation, 1 for diagnostic errors, and 2 for invalid CLI invocation. Automation that requires pristine files must also inspect `status`, since customization is an expected warning.
+
+## Alternatives and limits
+
+Manual directory comparison remains useful for updates but does not offer a stable machine-readable diagnosis. Automatic repair would need a separate migration and ownership contract; it is excluded. Adding configuration/state engines is unnecessary for this diagnostic slice.
+
+Manifest hashes compare with a local baseline, not a signed release. Someone who changes both files and manifest can conceal changes. Doctor does not certify host discovery, prompt behavior, workflow gates, project readiness, or authenticity. It does not inventory unrecorded payload files or discover deleted optional entries in a modified manifest. Use a reviewed staging installation for that comparison. As with init, inspect a directory that is not being concurrently modified; symlink preflight is not an operating-system sandbox.
+
+## Validation
+
+Test all three host layouts and subsets, byte preservation, customized templates/skills, missing files, duplicate hosts, invalid manifests, traversal and symbolic paths, JSON output and exit codes. Run the existing installer tests after extracting shared filesystem checks. Exercise the command from the actual packed tarball. Native coding-agent validation remains a separate gate.

package/docs/ADR-003-installation-provenance.md

@@ -0,0 +1,15 @@
+# ADR 003: Local provenance and read-only update previews
+
+Status: proposed for maintainer review with this implementation.
+
+## Context and decision
+
+An installed format 2 manifest records file hashes but not the package version. Add optional package name/version and a deterministic host/subset payload digest without changing the format or rewriting legacy manifests. The bundled package metadata is the source of the new installation's version; an old installation without this record remains unknown.
+
+Add `update-preview` to compare recorded baseline, local bytes and the current CLI's bundled payload. Reuse manifest path validation and diagnostics before reading payload. Keep the operation offline and read-only, with no runtime dependencies. Preserve all six modules, host profiling and subset semantics. Classification and hashes expose upstream differences separately from local customization; no automatic overwrite, deletion or context migration is introduced.
+
+## Consequences and limits
+
+Version alone cannot establish payload equality; the digest includes selected host-profiled contents. Neither version nor digest establishes authenticity because manifests and package files are locally mutable. Missing optional historical entries cannot be reconstructed. Local changes to removed files stay classified as customization. Legacy idempotence preserves the original manifest only when its installation contract matches the requested payload. Content review uses a separate fresh staging installation and intentional diff.
+
+The filesystem contract inherits ADR 001 and ADR 002: reject symlinks and unsupported paths, assume no concurrent modification, and distinguish document/integrity checks from native-host behavior. Tests cover all host layouts and subsets, legacy/new idempotence, classification, preservation, path attacks and CLI results.

package/docs/ADR-004-checkpoint-resumption.md

@@ -0,0 +1,23 @@
+# ADR 004: Content-pinned checkpoint evidence
+
+Status: proposed for maintainer review with this implementation, 2026-09-13.
+
+## Decision and scope
+
+The authorized checkpoint-resumption milestone needs a bounded way to detect when previous verification no longer applies. Preserve the accepted six-module distribution, offline core and existing Markdown checkpoint workflow. Add an optional format 1 JSON record and dependency-free read-only API, owned by the checkpoint slice.
+
+Pin repository-relative source files and evidence artifacts with SHA-256. Link each evidence item to explicit source IDs and optional evidence prerequisites. Validate references and reject cycles before inspection. Propagate invalidation from changed or unavailable sources and artifacts to their dependent evidence; preserve independent results. Failed and unrun prerequisites cannot support downstream success. Ignore age as an invalidation signal.
+
+Keep scope/status/next action explicit. Completed scope requires a null next action. Inspection produces a report, never a state transition, automatic rehash, test execution, migration or new authorization. Blocked scope remains blocked until an authorized owner resolves it. Existing Markdown checkpoints continue manually; JSON is an opt-in companion rather than a replacement tracker.
+
+## Alternatives and consequences
+
+Keeping only prose is simplest but cannot reliably map changed inputs to affected evidence. Commit-only invalidation is too broad for independent work and misses uncommitted changes. Modification time confuses age with changed content. A scheduler or automatic repair system would expand permissions and operating complexity beyond this milestone.
+
+Explicit pins require authors to record complete dependencies. The inspector cannot certify honest evidence, external state or omitted inputs. Local hashes are not release signatures. Unknown schema versions fail with actionable diagnostics. Portable safe paths and symlink preflight bound ordinary reads but do not defend against concurrent filesystem replacement. Inspect a quiescent project directory.
+
+Revisit the schema only after native resumption runs expose concrete missing contracts. New schema versions must retain a deliberate compatibility path; this slice does not mandate adoption by existing projects.
+
+## Verification
+
+Tests cover selective/transitive invalidation, changed artifacts, failed and unrun prerequisites, unchanged bytes with old timestamps, absent files, malformed records, unsafe/symbolic paths and complete/blocked scope. Full installer tests and package inspection remain required. These tests are deterministic validator evidence, never native host behavior evidence.