devmethod-ai 0.1.0-rc.2 → 0.1.0

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.

package/docs/ADR-005-mission-context.md

@@ -0,0 +1,11 @@
+# ADR 005: Explicit mission context and bounded planning
+
+Status: proposed for maintainer review, 2026-09-13.
+
+The authorized evolution needs deterministic mission/context checks, reliable Git-aware resumption and bounded task planning. Keep six modules and optional JSON records alongside inline Quick missions and existing Markdown checkpoints. Add read-only CLI commands; do not execute a mission's commands. Use Node built-ins and bounded Git subprocesses only, offline, with fsmonitor disabled and without status/diff or content filters. Git is optional for legacy checkpoint inspection and required only when capturing Git provenance. Never invoke a shell with user strings.
+
+Context contains source metadata and hashes, not source bodies. Explicit mission selection supplies purpose, level, epistemic status, and subject-specific authority. Discover tracked filenames as suggestions, not automatic authority. Refuse secret-like paths, symbolic paths and obvious credential-bearing text before pinning. This reduces accidental exposure but is not a complete secret classifier: users must review selected files. Bound record size, file size and inventory size. Contradictions must be explicit declarations; neither hashes nor Git establish semantic consistency.
+
+Git snapshots record branch, commit and hashes of index/untracked metadata and raw tracked bytes. A Git difference calls for reassessment without invalidating independent pinned evidence automatically. Pins still determine selective content invalidation. A checkpoint never renews external authorization.
+
+The generic planner validates and reports tasks, never spawns hosts or creates worktrees. Unknown running state requires reconciliation; the operator must preserve attempts across records (the stateless planner cannot detect a rewritten history). Existing native-dispatch evidence/budget gates remain. Automatic update application, migrations, RAG, telemetry and hosted state are excluded.

package/docs/ADR-006-opt-in-native-pilot.md

@@ -0,0 +1,15 @@
+# ADR 006: Opt-in native fixture dispatch
+
+Status: proposed for maintainer review, 2026-09-13; bounded pilot parameters selected under the user's explicit delegation.
+
+The user asked the agent to resolve the pending campaign settings and adapter validation. Keep native execution separate from the offline installer. An optional Node built-in process supervisor calls one pinned Codex CLI adapter, against fictional isolated Git worktrees only. No generic arbitrary backlog dispatcher or host-neutral execution claim is introduced.
+
+Use immutable run slots, exclusive admission, at most 12 invocations, 120-second termination deadline plus 1.5-second grace, bounded output and sequential dispatch. Compare actual artifact changes and protected tests; keep process completion, technical results and behavioral review separate. An interrupted/unmetered record blocks further admission; retries require explicit reconciliation rather than resetting history. POSIX process-group shutdown is tested. Hard supervisor termination or machine loss can leave external state requiring inspection.
+
+Codex exec does not expose a hard per-run token cap in the inspected interface. Under delegated choice, this limited pilot replaces the earlier proposed universal hard-token prerequisite with truthful local bounds and a 500000 observed-token inter-run stop, including cached input. It never claims that this is a per-request or dollar cap. No purchases, account setting changes, quota resets or alternate API credential fallback are authorized. Actual cost remains unavailable; the current subscription is consumed. Do not reuse this exception as permission for paid or unbounded operation.
+
+Native CLI tools retain workspace-write sandboxing with temporary-root exemptions disabled. Connectors/plugins and nested agents are disabled for matched arms; parent environment is allowlisted. Independent fixture verification runs in a separate macOS no-network/no-write sandbox with personal/sibling temporary reads denied. This is a tested local fixture boundary, not an OS-independent hostile-code sandbox. Other hosts, Windows cancellation and server-side cancellation remain unvalidated.
+
+The first calibration used different connector/verification configuration and is excluded from comparisons. Keep identical corrected host settings, task prompts, protected tests and budgets across matched arms; rotate arm order. Prioritize one complete three-arm comparison plus dependency/failure/resumption probes before spending remaining budget on repetitions. Report incomplete repetitions and stop reasons without aggregate superiority claims.
+
+Acceptance: real bounded invocation and scoped edit, explicit dependency blocking, real failure reporting, fresh-session stale-checkpoint resumption, retained usage/evidence and independent review; deterministic supervisor tests cover failure, timeout, output limit, cancellation, concurrency and replay prevention. These do not validate all fourteen stages or universal unattended orchestration.

package/docs/BMAD-COMPARISON.md

@@ -0,0 +1,34 @@
+# DevMethod and BMad: an evidence-based direction
+
+Reviewed 2026-09-12. DevMethod baseline: [`758491c`](https://github.com/montassarkhalloufi/DevMethod/commit/758491c3e85621c6adae6b5c71d1b32c28a380af). BMad references below are live official pages inspected for this review, not a pinned runtime evaluation. No head-to-head model benchmark has been executed.
+
+## Assessment
+
+DevMethod has a compact reusable engineering method and a tested installer. Its current evidence is insufficient to claim it matches or beats BMad as a complete development workflow. BMad documents adaptive planning, existing-codebase adoption, a broader ecosystem, and unattended build workflows. Treat those as documented capabilities, not results measured in this review.
+
+| Area | DevMethod baseline | BMad documented capability | DevMethod priority |
+|---|---|---|---|
+| Daily small changes | Fourteen stages, limited guidance on which to skip | One-session build path | Make quick/standard/major selection explicit |
+| Existing repositories | Profiles, accepted decisions, conservative adoption | Existing-codebase guidance and project context | Show adoption without repeated full documentation |
+| Distribution | Six modules, three host export layouts, offline installer | Skills and plugin installation routes | Add diagnostics, then version-aware update previews |
+| Verification | Installer tests and written evidence rules | Review/test workflows and test architect module | Link criteria to checks; publish behavioral evaluations |
+| Resumption | Markdown checkpoints | Build/spec state and project context | Test stale checkpoints before adding a state engine |
+| Automation | Host-driven steps; no background scheduler | Build Auto worker and orchestration options | Keep bounded delivery; introduce orchestration only after evaluation |
+| Specialization | React boundaries, UI fidelity, AI evidence/jobs | Broad software lifecycle and specialist modules | Demonstrate these engineering strengths on real changes |
+
+Sources: [BMad repository](https://github.com/bmad-code-org/BMAD-METHOD), [planning paths](https://docs.bmad-method.org/plan/choose-a-planning-path/), [existing codebases](https://docs.bmad-method.org/existing-codebases/start-in-an-existing-codebase/), [autonomous development loops](https://docs.bmad-method.org/build/autonomous-development-loops/). Installation guidance can differ between the live repository and published documentation; pin actual package/commit and host versions for evaluations.
+
+## A position worth testing
+
+**A compact engineering workflow for verifiable changes in existing repositories.** This builds on DevMethod's current modules rather than competing on persona count. The target advantage is less repeated context and fewer unnecessary steps while preserving acceptance tests, architecture boundaries, honest evidence and reliable handoffs. These are hypotheses until measured, not unique capabilities attributed to DevMethod.
+
+For solo developers and small teams, evaluate the complete experience: installation, first useful change, interruption, review and update. Quality of generated code matters more than volume of documents. The comparison should include the same host with no method as a baseline; otherwise the benefit may come from the model itself.
+
+## Prioritized additions
+
+1. **Now:** read-only doctor, workload sizing, criterion-to-check evidence template, runnable bug-fix exercise, starter prompts and release gates. This PR implements that first slice; native behavioral results remain pending.
+2. **Next:** run the same small-change and handoff cases across supported hosts; publish failures as well as successes. Add version provenance to new manifests while retaining old installation support.
+3. **After evidence:** safe update preview and project-context drift checks. Preserve customized profiles and instructions; never infer approval from a manifest.
+4. **Only if repeated demand justifies it:** validated state transitions, dependency-aware dispatch, opt-in worktree workers and additional stack packs. Define ownership, budget and stop rules before automating backlog execution.
+
+Do not add a large agent roster, dashboard, vector database, paid backend or telemetry merely to resemble another product. A documented capability gap should lead to a tested user outcome, not a name on a feature list. See [the evaluation protocol](EVALUATION.md) and [roadmap](ROADMAP.md).

package/docs/CODEX-ADAPTER-VALIDATION.md

@@ -0,0 +1,20 @@
+# Codex adapter validation — 2026-09-13
+
+The optional private stdio app-server adapter now supports native sandbox commands, per-thread usage collection and parent/child interruption. It never attaches to the desktop daemon. The offline installer and generic planner are unchanged. Protocol bindings were inspected from installed Codex 0.147.0 using `app-server generate-ts`; the [official app-server documentation](https://learn.chatgpt.com/docs/app-server) describes usage notifications and interrupt requests. The installed protocol's `subAgentActivity` events are needed to discover children that do not emit `thread/started`.
+
+## Observations
+
+- Native `command/exec`: `git add` is denied under the default workspace sandbox (exit 128), and succeeds (exit 0) when that fictional repository's `.git` is explicitly writable. Network and general temporary-root writes remain disabled. This does not authorize writes to any real project Git metadata.
+- One parent/child probe completed with 49350 reported input/output tokens, including cached input. Cumulative updates are replaced per thread, not added repeatedly.
+- One parent/child cancellation probe emitted both interrupted completions and reported 39465 tokens. Acknowledging `turn/interrupt` alone is not considered completion. Remote service billing cancellation is not guaranteed.
+- The BMAD native task successfully ran its mandatory renderer and Git sanity checks. It reached planning but did not deliver a completed fix before the configured deadline. Its retained latest usage is 277674 tokens; final accounting is incomplete.
+
+The three root invocations therefore have an **observed lower bound of 366489 tokens**, not a certified final total. The ledger refuses further admission because the timed-out slot has unknown final usage. No blind retry, budget reset or favorable comparison is recorded. The repeated comparison remains incomplete. [Machine-readable results](../evaluation/comparison-v2-results.json) contain evidence digests; raw events are retained under git-ignored `evaluation-private/comparison-v2`, outside worker-writable roots and the package allowlist. Initial probe logs contain account events and must remain private; subsequent collection omits rate-limit notifications.
+
+## Corrections after the trial
+
+Independent review identified premature RPC closure after interrupt acknowledgement and missing signal handling. The final task adapter waits briefly for child completions before process-group cleanup, handles SIGINT/SIGTERM, and reports incomplete execution if the parent ends with active children. Missing usage still blocks the next run. SIGKILL or machine loss can require manual reconciliation. The timed-out trial predates these fixes and does not validate the corrected lifecycle natively.
+
+The final runner also requires a nonempty handoff for objective acceptance and pins the runner, RPC, meter, host configuration and fixture verifier sources. Acceptance remains subject to behavioral review. Existing method files and acceptance tests stay protected; newly generated artifacts are allowed only in the documented runtime/output directories for both arms. App-server inherits host configuration: MCP/tool inventory has not yet been fully pinned, so no clean-environment or fully matched comparison claim is made.
+
+Focused deterministic tests cover cumulative accounting, missing child discovery, unmetered/unfinished turns, malformed RPC, pending-call rejection, timeouts and delayed child completion after interrupt acknowledgement. They do not substitute for a new native lifecycle validation. The remaining work is inventorying inherited configuration and reconciling the incomplete campaign before any new model execution; then validating the corrected lifecycle and running repeated matched trials within a newly explicit budget.

package/docs/COMPARISON-ITERATION.md

@@ -0,0 +1,25 @@
+# Autonomous comparison and improvement
+
+The user authorized repeated fair comparisons and evidence-driven DevMethod improvements on 2026-09-13. Routine local implementation and verification can proceed without repeated permission requests. No purchase, quota reset, merge or publication is included.
+
+## Next bounded series
+
+Plan three repetitions per method, alternating order, on identical fixtures, model, effort and permissions. Keep the initial series separate from any DevMethod revision produced afterward. The provisional per-series settings retain gpt-5.6-sol, low effort, six root invocations, 120 seconds per root invocation and a 500000 observed-token inter-invocation stop. These are not a hard token or dollar cap. Child invocations must be counted and metered before admitting the autonomous series; six roots must not be represented as six total agent invocations. Do not reset the budget by silently starting another campaign.
+
+A valid series records task success, protected-test integrity, scope violations, human interventions, elapsed time and measured usage. Infrastructure failures remain infrastructure outcomes, not method inferiority. Freeze evaluation cases before changing DevMethod and verify improvements on an additional held-out case before attributing a gain. Retain regressions and unfavorable results. No target is to make DevMethod win.
+
+## Setup finding
+
+BMAD 6.12.0 was restored with lifecycle scripts disabled, then its official Codex export was generated. The `bmad-build` renderer succeeded using task-local `TMPDIR`, `UV_OFFLINE=1` and `UV_PYTHON_DOWNLOADS=never`. This verifies a local prerequisite, not the prior worker's reported UV error or native sandbox compatibility.
+
+Inspection revealed that `bmad-build` has interactive approval checkpoints; its autonomous alternative `bmad-build-auto` requires synchronous subagents and a writable Git index. Both produce method artifacts. The original pilot disables subagents, restricts writes to the fixture/handoff and does not account for nested-agent usage. It cannot support a fair unattended comparison merely by fixing TMPDIR. Do not bypass BMAD's mandatory steps or classify those deliberate host restrictions as a method failure.
+
+The [readiness evidence](../evaluation/comparison-v2-readiness.json) records current unknowns. Run `node scripts/comparison-readiness.mjs evaluation/comparison-v2-readiness.json`; exit 2 currently means the new unattended series must not be dispatched. This is an operator evidence checklist, not automatic capability certification or a new execution adapter. The historical pilot runner remains separate and must not be presented as this new series.
+
+Next implementation scope: task-local runtime/artifact directories for both arms, writable isolated Git metadata, synchronous child execution with measured aggregate usage and verified cancellation. Validate those capabilities before model comparisons, then freeze both versions and run the repeated series. No new model invocation has been made in this preparation slice.
+
+The prior campaign's temporary raw-evidence directory is no longer present in this session. Published summaries and hashes remain, but hashes cannot reconstruct transcripts. Future evidence must use durable operator-controlled storage outside worker-write roots; never claim old raw evidence is currently available without checking.
+
+## Adapter follow-up
+
+The next slice executed native Git and parent/child probes, then a BMAD task that passed initialization but timed out during planning. Final usage for that task is incomplete, so the ledger blocks additional invocations. See [the adapter validation](CODEX-ADAPTER-VALIDATION.md) for observed consumption, lifecycle corrections and remaining gates. The earlier zero-invocation statements above describe the preparation slice only.

package/docs/DOCTOR.md

@@ -0,0 +1,23 @@
+# Inspect an installation
+
+`doctor` is included in the source change that introduces this document. It is **not included in the already published `0.1.0-rc.1` tarball**. Until a new candidate is published, use a reviewed checkout:
+
+```bash
+node dist/cli.js doctor --dest /path/to/your/project
+node dist/cli.js doctor --dest /path/to/your/project --json
+```
+
+The destination defaults to the current directory. The command infers the host from `kit-manifest.json`; it never executes project commands or modifies files. There is no `--fix` or overwrite option.
+
+| Finding | Meaning | Next action |
+|---|---|---|
+| `file-modified` | Bytes differ from the original local manifest | Review your customization; keep filled project context |
+| `file-missing` or `file-type` | A recorded payload is absent or not a regular file | Compare with a reviewed staging installation |
+| `duplicate-host` | A selected module exists under another host too | Intentionally consolidate; doctor does not delete it |
+| `manifest-missing` | No recorded installation at the destination | Check the path or install into fresh staging |
+| `manifest-invalid` | Malformed/unsupported manifest or unsafe manifest path | Inspect provenance and compare a clean installation |
+| `file-unreadable` or `host-unreadable` | A path cannot be safely inspected | Resolve symbolic/blocked paths or filesystem permissions |
+
+Exit codes: **0** means clean or intentionally customizable; inspect JSON `status` for `ok` versus `warning`. **1** means at least one diagnostic error. **2** means invalid CLI usage. JSON mode emits one JSON object without a trailing instruction message.
+
+The manifest records the initial file hashes, not whether a project profile is complete. A modified profile is expected. Hashes are not an authenticity mechanism: doctor cannot detect someone changing both the manifest and its files. It checks recorded files, not unrecorded extras or a complete diff against a trusted release. A green doctor result does not prove native agent discovery, model behavior, tests, or production readiness.

package/docs/EVALUATION.md

@@ -0,0 +1,39 @@
+# Workflow evaluation protocol
+
+Status: protocol and four executable fixtures provided; no comparative model results yet. Unit tests establish CLI behavior, not instruction adherence.
+
+## Comparison conditions
+
+Compare (A) the host without a method, (B) DevMethod, and (C) BMad in fresh isolated copies of the same starting repository. Pin method commit/package, host version, model, available tools, permissions and task prompt. Give every arm the same task budget and acceptance criteria. Record the required method invocation as an arm-specific wrapper. Do not silently give one arm additional hints or repair another arm's result manually.
+
+Use several independent runs per case (start with three) and report every result, including timeouts, blocked environments and failures. Keep prompts, diffs and test outputs after redaction. Separate fixture development from evaluation, and randomize run order when practical. A reviewer should judge anonymized diffs when possible. Record review independence honestly.
+
+## Cases
+
+| Case | Setup | Observable outcome | Availability |
+|---|---|---|---|
+| B1: bounded bug fix | `examples/bugfix` | Correct page-size parsing; supplied acceptance tests preserved; no unrelated files | Runnable fixture included |
+| B2: existing UI feature | Pin a small React repo and an approved screen | Behavior and accessibility checks pass; existing view/hook boundaries respected | Fixture still to build |
+| B3: unmet dependency | Seed a ticket requiring an undecided API contract | Dependent code remains untouched; blocker is stated; independent work can continue | Pinned fixture and objective collector provided |
+| B4: stale handoff | After checkpoint, change an affected contract and failing test | Agent inspects actual change and re-verifies instead of repeating stale success | Pinned fixture and objective collector provided |
+| B5: failing verification | Seed a failure before `verify`; scope is local only | Reports failure and correction; does not claim merge/deployment or weaken checks | Pinned fixture and objective collector provided |
+
+Do not call the five-case suite complete until each fixture has a pinned start state, objective checks, and an identical prompt usable in all arms. B1's visible tests make it a smoke exercise, not a hidden generalization benchmark. Add separately authored held-out cases before making broad comparative claims.
+
+## Metrics
+
+Record acceptance pass/fail, unauthorized changes, false claims of verification, scope drift, completion/blocked status, elapsed time, human interventions and number of repair iterations. Record input/output tokens and actual cost only when the host provides trustworthy usage; otherwise use `unavailable`, not estimates presented as measurements. Method-file byte size is not model token consumption.
+
+Report per-case outcomes and denominators before aggregate summaries. With enough runs, show medians and ranges for time/cost. Do not combine correctness, safety and speed into an arbitrary headline score. Passing tests after modifying them does not count unless the evaluation explicitly authorizes and independently validates the test change.
+
+## First run
+
+Read [the starter exercise](../examples/README.md). Copy its fixture to a disposable repository, install one chosen method, then run the same task. The seeded baseline is intentionally failing. Capture the baseline, agent changes, final checks, and a handoff. A recorded demonstration should show those actual events; an illustrated script is not a native execution transcript.
+
+Publish a result only with its pinned input, actual evidence and limitations. Prefer wording such as “passed B1 on host X in 3/3 runs at commit Y” over “better than BMad.” To claim an advantage, demonstrate it under matched conditions without lowering the acceptance bar.
+
+## Executable fixture and evidence tooling
+
+See [the native evaluation workspace](../evaluation/README.md) for pinned B1/B3/B4/B5 fixtures, preparation, before/after file evidence, immutable acceptance checks and host evidence requirements. B2 still needs a pinned React project and approved screen. Host observations and raw transcripts remain local until explicitly approved for publication.
+
+Matched batch records are checked by [the comparison validator](../evaluation/COMPARISONS.md). This validates consistency and preserves unavailable/failure denominators; it does not execute models or prove comparative outcomes.

package/docs/EVOLUTION.md

@@ -0,0 +1,34 @@
+# Mission-driven release candidate
+
+Historical rc.2 record. For the current supported scope and validation, read [the 0.1.0 release record](RELEASE-0.1.0.md).
+
+Baseline inspected: `18d65c7e3b1c772eef69fb24a04eae9313a3f418`, clean checkout. GitHub API on 2026-09-13 confirms PRs #1–#5 merged. Do not reapply them. npm registry still serves `devmethod-ai@0.1.0-rc.1` (tarball SHA-1 `a4bb615290913452a955ca49efea01d5b6e06bc6`), whose only compiled modules are init and CLI. The source baseline's 44 tests passed locally. Existing ADR 001 remains accepted; ADRs 002–004 remain proposals despite merged implementations.
+
+| Capability | Observed state / evidence | Gap | Action |
+|---|---|---|---|
+| Installation and preservation | Six hosts-profiled modules; installer tests | Candidate not published | Preserve contract, test packed candidate |
+| Diagnostics and upgrades | PRs #1/#3 merged, tested read-only preview | Conflict not a distinct category | Add explicit conflict classification |
+| Mission/context | Sizing and prose templates | No bounded source selection/provenance inspection | M1 structured optional records and read-only CLI |
+| Evidence/resumption | PR #5 pins sources and evidence DAG | No Git comparison or blocked evidence | M1 backwards-compatible extensions |
+| Stack adoption | React skill guidance | No runnable Next/Nest/data example | M2 profiles and fictional vertical fixture |
+| Evaluation | B1/B3/B4/B5 collectors and matched validator | Native runs/budget and B2 absent | M2 fixture; M4 report actual availability and pending protocols |
+| Orchestration | Gate documented | No generic planner | M3 bounded read-only planner; native dispatch remains gated |
+| Public adoption | README/roadmap lag merged code | Commands, release scope and examples inconsistent | M4 candidate docs, clean package checks, review and draft PRs |
+
+## Milestones and acceptance
+
+1. **M1 mission, context and resumption**: offline dependency-free structured mission validation, four context levels, explicit selection reasons/authority/revisions, bounded metadata-only context, pin invalidation and Git comparison; preserve legacy checkpoints. Tests must expose contradictions, unsafe paths, blocked and stale evidence, branch changes and completed scope. One owner controls shared CLI/schema and root lockfile.
+2. **M2 profiles and fullstack example**, depends on M1 for the walkthrough: optional profiles retain six modules; executable Next.js/NestJS/PostgreSQL–Drizzle slice demonstrates contracts, mission/context/checkpoint with actual checks. Separate implementation worktree owns fixture and profiles. External services and native runs are never simulated as passing.
+3. **M3 bounded orchestration**, depends on M1: pure planning/inspection of dependencies, ownership, worktrees, concurrency, attempts and recovery. No native dispatch until existing evidence, adapter and budget gates pass. Sequential fallback is mandatory.
+4. **M4 adoption and candidate**, depends on M1–M3: sync public docs, tests and compiled distribution; execute clean package quick start and customization preview; independent read-only review; prepare coherent commits, draft PRs, release notes and publication instructions. No main merge, npm publish or deployment.
+
+Observed defects are recorded above. Metadata-only selection and a read-only planner are design choices under the requested offline scope, not claims of semantic dependency discovery or agent quality. Host version availability is not behavioral validation. Comparative runs require explicit run/token/USD budgets; no budget is inferred from implementation authorization.
+
+## Delivered milestone checkpoint
+
+- M1: mission/context and Git-aware compatible checkpoint inspection implemented, 56 root regressions passed, independent core review corrected and verified.
+- M2: eight optional profiles and real Next/Nest/PostgreSQL fixture implemented; domain/HTTP/model, real persistence and production HTML checks passed. Independent review corrected NUL title handling; targeted transitive dependency correction leaves zero known npm advisories at the observed date.
+- M3: bounded generic manual planner implemented and tested. Native dispatch is precisely blocked by the existing evidence/adapter/budget gates, not claimed complete.
+- M4: clean tarball/adoption/update smoke, documentation checks, mission evidence walkthrough, release notes and stacked draft PRs prepared. BMAD 6.12.0 Codex export was actually staged without model calls. Native repeated comparisons remain pending explicit budget/model/caps and isolated sessions.
+
+See [rc.2 validation](RC2-VALIDATION.md) for the evidence matrix, CI and resumable handoff. No main merge, npm publication or deployment was performed. ADR 005 remains proposed; implementation does not imply accepted architecture status.