devmethod-ai 0.1.0-rc.2 → 0.2.0

package/README.md

@@ -2,29 +2,56 @@
 
 From idea to delivery with your AI coding agents.
 
+[![npm](https://img.shields.io/npm/v/devmethod-ai?label=npm)](https://www.npmjs.com/package/devmethod-ai) [![license](https://img.shields.io/npm/l/devmethod-ai)](LICENSE) [![platform tests](https://github.com/montassarkhalloufi/DevMethod/actions/workflows/platform-tests.yml/badge.svg)](https://github.com/montassarkhalloufi/DevMethod/actions/workflows/platform-tests.yml)
+
+## Watch DevMethod build Lisière — 2 min 58 s
+
+[![Play the 4K demo: approved master and derived Lisière screens](docs/media/visual-chain/video-preview.jpg)](https://github.com/montassarkhalloufi/DevMethod/raw/refs/heads/main/docs/media/visual-chain/devmethod-du-besoin-au-produit-4k.fr.mp4)
+
+**[▶ Watch the video — 4K, French narration](https://github.com/montassarkhalloufi/DevMethod/raw/refs/heads/main/docs/media/visual-chain/devmethod-du-besoin-au-produit-4k.fr.mp4)** · [Subtitles and execution evidence](docs/media/visual-chain/README.md) · [Download the working prototype](https://github.com/montassarkhalloufi/DevMethod/raw/refs/heads/main/docs/media/visual-chain/lisiere-visual-source.zip)
+
+**Concrete example: Lisière, a personal reading library.** Start with an idea, compare three visual directions, approve a master screen, derive the other screen images, choose a suitable architecture, then build and verify the application.
+
+| Step shown | Concrete result |
+| --- | --- |
+| Explore and frame | Add books, filter readings and track three statuses |
+| Design | Three alternatives → selected editorial master → add-book and completed-reading images |
+| Architecture | HTML/CSS/JavaScript, testable book rules and browser-local storage |
+| Plan, ready and implement | Working form, filters, status changes and saved books |
+| Review and verify | Corrected alert/focus behavior, 6 tests and real Chrome desktop/mobile journeys |
+| Integrate and handoff | Local prototype, references, evidence and resumption context |
+
+The video uses illustrative Codex commands with real generated images and recorded application interactions. DevMethod guides the coding agent; image generation requires an available host tool. The visual workflow is in the current GitHub source and is not included in npm 0.1.0. [Follow the visual workflow](docs/VISUAL-WORKFLOW.md).
+
+![DevMethod workflow](docs/images/devmethod-flow.svg)
+
 DevMethod is the public name of the kit. Its entry-point skill remains `project-foundation`, preserving existing invocations and the six-module structure.
 
 A reusable workflow for taking a software project from exploration to delivery: decisions, UX, architecture, tickets, development, tests, review and handoff. Six focused skills support fourteen workflow stages, each ending with evidence, limitations and one suggested next command.
 
-**0.1 release candidate.** Installation profiles are provided for Codex, Claude Code and Cursor. Native authenticated Claude Code and Cursor sessions have not been validated yet. See [compatibility and smoke tests](COMPATIBILITY.md). The current skills and templates are primarily in French; they can follow the user's requested language.
+**npm stable: 0.1.0 (`latest`). Next release candidate: 0.2.0.** [0.2.0 changes and publication status](docs/RELEASE-0.2.0.md). The release includes mission/context inspection, Git-aware evidence resumption, explicit update conflicts, manual task planning and optional stack profiles. See the [release record](docs/RELEASE-0.1.0.md) for publication status and verification.
+
+For developers and small teams using coding agents in new or existing repositories. Requires Node.js 22+ and npm; Git is required for context provenance. Application examples have separate framework/database prerequisites. DevMethod records scope, decisions and verification; it does not certify agent output, infer all dependencies, deploy applications or run an autonomous backlog. Installation and deterministic fixture results are separate from native host validation. See [compatibility](COMPATIBILITY.md).
+
+Start with [missions and the tested source quick start](docs/MISSIONS.md), the [tested from-zero Pocket Tasks project](examples/pocket-tasks/README.md), then the [complete Next.js/NestJS example](examples/fullstack/README.md). Advanced references: [context and sizing](docs/MISSIONS.md), [safe updates](docs/UPDATES.md), [resumption](docs/RESUMPTION.md), [optional stack profiles](docs/STACK-PROFILES.md), [bounded manual planning](docs/ORCHESTRATION.md), [troubleshooting](docs/TROUBLESHOOTING.md), and [release status and evidence](docs/RELEASE-0.1.0.md).
 
 ## Install in a project
 
-Requires Node.js 22+ and npm. From your project directory, install directly from GitHub:
+Requires Node.js 22+ and npm. Install into a fresh staging directory first:
 
 ```bash
-npx --yes --package=github:montassarkhalloufi/DevMethod devmethod init
+npx --yes devmethod-ai@0.1.0 init --tool codex --dest ../foundation-staging
 ```
 
-Choose Codex, Claude Code or Cursor when prompted. For scripts, pass `--tool` explicitly:
+Choose `codex`, `claude` or `cursor`. If you omit `--tool`, an interactive terminal asks. For example:
 
 ```bash
-npx --yes --package=github:montassarkhalloufi/DevMethod devmethod init --tool claude --dest ../my-project --dry-run
+npx --yes devmethod-ai@0.1.0 init --tool claude --dest ../foundation-staging --dry-run
 ```
 
-Remove `--dry-run` to write. Select a subset with `--modules decision-architecture,scoped-delivery`; `project-foundation` is always included. Without `--modules`, all six modules are installed. The installer refuses divergent files and duplicate skills across host directories. It never edits AGENTS.md, CLAUDE.md or your package.json. Use a fresh staging destination when upgrading or changing module selection, then review and merge manually.
+Remove `--dry-run` to write. Select a subset with `--modules decision-architecture,scoped-delivery`; `project-foundation` is always included. Without `--modules`, all six modules are installed. The installer refuses divergent files and duplicate skills across host directories. It never edits AGENTS.md, CLAUDE.md or your package.json. Review the staging output, then merge only what the project needs.
 
-The GitHub command downloads the package through npm; the installer itself makes no network requests and has no runtime dependencies. For reproducible installs, append `#<reviewed-commit-sha>` to the GitHub package spec. The npm package name is `devmethod-ai`; the executable remains `devmethod`. After registry publication with the `next` tag, use `npx devmethod-ai@next init`. Until publication is confirmed, use the GitHub command above.
+The installer has no runtime dependencies and makes no network requests after npm obtains the package. To pin the final version, use `npx --yes devmethod-ai@0.1.0 init ...`. To use the visual workflow before 0.2.0 is published, use a reviewed repository commit: `npx --yes --package=github:montassarkhalloufi/DevMethod#<commit-sha> devmethod init ...`.
 
 Complete PROJECT_PROFILE.md with your real stack, commands, scope, deployment permissions and data requirements. Merge AGENTS.foundation.md into the project's existing instructions only after review. Claude Code reads CLAUDE.md: preserve its current content and, if the project has AGENTS.md, optionally add `@AGENTS.md` to import it. Keep existing accepted architecture decisions authoritative.
 
@@ -32,6 +59,44 @@ The installer includes `DEVMETHOD-LICENSE` so it preserves your application's LI
 
 Installation copies the reusable method and blank templates, not another project's context. Preserve filled profiles, decisions, tickets and instruction files separately. Manifest hashes describe the initial installation; local template customization is expected to change them. To install elsewhere, run the CLI again.
 
+## Verify the source checkout
+
+From a reviewed source checkout:
+
+```sh
+npm ci
+npm test
+npm run check:docs
+npm pack --dry-run
+node dist/cli.js init --tool codex --dest ../candidate-staging
+node dist/cli.js doctor --dest ../candidate-staging --json
+node dist/cli.js update-preview --dest ../candidate-staging --json
+```
+
+The package includes advanced docs and fictional examples. `init` copies only the skills and adoption templates, preserving the application. Read the package docs from its checkout or extracted tarball. The core CLI has no runtime dependencies; example applications install their own pinned dependencies separately.
+
+## Inspect an adopted installation
+
+From a reviewed source checkout, inspect an installed project without changing it:
+
+```bash
+node dist/cli.js doctor --dest /path/to/project --json
+```
+
+Doctor reports missing files, changes from the initial manifest and duplicate host copies. Customized profiles and skills produce warnings; they are preserved. It does not execute an agent or certify application quality. See [diagnostic codes and exit statuses](docs/DOCTOR.md).
+
+## Choose the amount of process
+
+The stages below are available entry points, not fourteen mandatory conversations.
+
+| Path | Typical work | Expected process |
+|---|---|---|
+| Quick | Clear bug fix inside existing contracts | Inline readiness, implementation, focused verification and review |
+| Standard | Feature spanning components or sessions | Ready slice, relevant contracts, checks and resumable evidence |
+| Major | New product decisions or consequential architecture changes | Resolve decisions, split into slices, verify integration |
+
+Risk and repository policy override apparent size. Reuse accepted UI, architecture and project context; only fill actual gaps. See [work sizing](.agents/skills/project-foundation/references/work-sizing.md) and [starter exercises](examples/README.md).
+
 ## Run the workflow
 
 In Codex: `$project-foundation status`.
@@ -44,7 +109,7 @@ Replace `status` with an action below. These are prompts to the skill, not shell
 |---|---|
 | `explore` | Problem, users, alternatives and constraints |
 | `frame` | Product scope, exclusions and success measures |
-| `design` | UX direction and acceptance criteria |
+| `design` | Visual directions, selected mockups and UX criteria; image tooling depends on the host |
 | `architecture` | Decisions, boundaries and contracts |
 | `plan` | Milestones and tickets with dependencies |
 | `ready TASK-1` | Readiness assessment before implementation |
@@ -59,12 +124,30 @@ Replace `status` with an action below. These are prompts to the skill, not shell
 
 See the [full command contract](.agents/skills/project-foundation/references/operating-commands.md). A failed check returns to correction; a blocked gate leads to handoff or replanning. Tests, code review and native permissions remain necessary.
 
+![DevMethod delivery loop: accepted references, implementation, verification and correction](docs/images/devmethod-delivery.svg)
+
+## More recorded examples
+
+[Detailed recorded Lisière chain](docs/media/full-chain-4k/README.md) · [Short Clair demo](docs/media/from-zero/README.md) · [Run Clair](examples/clair-from-zero/README.md). Clair is a separate from-zero example; the featured video above follows Lisière throughout.
+
+## Visual design and architecture
+
+DevMethod connects art-direction selection, an approved master screen, derived image mockups and browser fidelity checks with technology and architecture decisions. Follow the [visual workflow guide](docs/VISUAL-WORKFLOW.md) and [recorded Lisière pilot](examples/visual-pilot/README.md). These capabilities are included in the 0.2.0 candidate; npm 0.1.0 predates them. See the [0.2.0 release record](docs/RELEASE-0.2.0.md) for publication status.
+
 ## Included modules
 
 `project-foundation`, `decision-architecture`, `design-to-code`, `react-feature-engineering`, `reliable-ai-integration`, `scoped-delivery`.
 
 Use the modules your project needs. Adapt the workflow to your stack, architecture and delivery process.
 
+## Where DevMethod can improve
+
+The target is a compact engineering workflow for verifiable changes in existing repositories. BMad already documents adaptive planning, existing-codebase workflows and broader automation; DevMethod has not demonstrated parity or superiority. Read the [sourced comparison](docs/BMAD-COMPARISON.md), [prioritized roadmap](docs/ROADMAP.md), and [evaluation protocol](docs/EVALUATION.md). We aim to measure correct outcomes, honest evidence, context cost and reliable resumption under matched conditions.
+
+## Demo material
+
+The workflow illustration above is kept in the repository as an SVG so it remains reviewable and usable in dark mode. Try the [runnable bug-fix exercise](examples/README.md), which includes an intentionally failing baseline and an explicit task. It is a fixture, not a recorded model success. A real demonstration should preserve the observed failures, changes and checks; use the [native smoke protocol](COMPATIBILITY.md#native-smoke-protocol) to assess the host workflow.
+
 ## Verify and contribute
 
 ```bash
@@ -73,4 +156,6 @@ npm test
 npm pack --dry-run
 ```
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) and [COMPATIBILITY.md](COMPATIBILITY.md). Licensed under [MIT](LICENSE).
+Read [CONTRIBUTING.md](CONTRIBUTING.md), [COMPATIBILITY.md](COMPATIBILITY.md), and the [release checklist](docs/RELEASE-CHECKLIST.md). Licensed under [MIT](LICENSE).
+
+A bounded [native Codex pilot](docs/NATIVE-PILOT-RESULTS.md) now records actual fixture execution and independent review. It covers one matched B1 triple and two DevMethod probes, not a completed comparative campaign or general autonomous dispatch.

package/START_HERE.md

@@ -0,0 +1,24 @@
+# Start the kit
+
+DevMethod offers six independent modules; this installation contains the modules you selected. If this is a staging directory, review and copy its installed skill folder into the project while preserving existing files. If you installed directly into the project, the selected skills are already in place. If a version already exists, compare changes before updating it. Keep `PROJECT_PROFILE.md` and complete the stack, commands, scope, deployment permissions, and data requirements from the project before adoption. `ENGINEERING_POLICY.template.md` retains the included policy; merge it with `CONTRIBUTING.md` and existing instructions.
+
+In Codex, start with `$project-foundation status`. In Claude Code or Cursor, start with `/project-foundation status`. For an open-ended request:
+
+> Use the `project-foundation` skill for this project. Read existing instructions and sources, complete the profile without reinventing decisions, then deliver the following scope: [my objective]. Apply only relevant modules. Preserve the approved mockup, architecture boundaries, and React rules. Progress to a verified result within this scope.
+
+The installer copies the method and its blank templates, not the adopted project's context. Keep the completed profile, decisions, tickets, and instructions separately. The manifest describes the initial installation: local adaptations normally change its hashes. To update, install into a fresh folder and compare changes.
+
+If skills are not discovered automatically:
+
+> Read `.agents/skills/project-foundation/SKILL.md` and only its relevant references, then complete: [my objective].
+
+`AGENTS.foundation.md` provides a fragment to merge into existing instructions. It never replaces an `AGENTS.md`. The kit does not include third-party Vercel skills: apply versions already approved by the project; adding them is separate.
+
+Examples:
+
+- “Resume this ticket and deliver its complete slice.”
+- “Here is the approved mockup: implement this page and verify desktop/mobile.”
+- “Compare these two architectures against my budget and propose an ADR.”
+- “Fix the view/hooks/business separation of this feature without a global rewrite.”
+
+This kit reduces repetitive framing; it does not by itself prove application quality or production readiness.

package/VALIDATION.md

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

package/dist/checkpoint.js

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

package/dist/cli.js

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