devmethod-ai 0.1.0-rc.2 → 0.2.0

package/docs/RELEASE-0.2.0.md

@@ -0,0 +1,37 @@
+# DevMethod 0.2.0 — visual design through verified delivery
+
+Status: candidate prepared for maintainer review. Not published on npm. The registry still serves 0.1.0 under `latest`; npm authentication is required to publish this candidate. GitHub updates and package preparation are separate from publication.
+
+## Changes
+
+- The existing `design` stage now explicitly covers comparable artistic directions, an approved master screen, derived screen images and browser comparison. Stay in design while requested visual references are missing.
+- Existing approvals are retained for unchanged scope. Generated mockups, source references and browser captures are identified separately. The master is supplied as an actual image reference when the host supports it.
+- Design works alongside technology and architecture decisions; no framework or stack is imposed. There are still six skills and fourteen workflow stages, with no new standalone master/pages commands.
+- The README features the complete 2 min 58 s Lisière demonstration and two legible, complementary SVG diagrams for the overall workflow and delivery loop.
+- Documentation, narration, subtitles and the runnable prototype evidence cover framing, visual design, architecture, readiness, implementation, review, verification and local handoff.
+
+Image generation requires an available host tool; it is not bundled. The film contains illustrative commands and real generated images / application interactions, not a continuous Codex Desktop capture. The native pilot does not establish Claude Code or Cursor execution parity. The public CLI does not gain autonomous task dispatch.
+
+## Adopt without overwriting project work
+
+Until publication, use a reviewed GitHub revision:
+
+```sh
+npx --yes --package=github:montassarkhalloufi/DevMethod#<reviewed-commit> devmethod init --tool codex --dest ../devmethod-staging
+```
+
+After the registry confirms publication, the versioned command will be:
+
+```sh
+npx --yes devmethod-ai@0.2.0 init --tool codex --dest ../devmethod-staging
+```
+
+Stage and compare updates. Keep existing project decisions, customized skills, filled profiles and instructions. There is no automatic migration.
+
+## Candidate verification
+
+Local candidate checks passed: locked installation, 72 core tests, 24 greenfield tests, Markdown links, both diagrams rendered in Chrome, package-content inspection and installation smoke from the archive for all three host layouts, including a subset and customization preservation. Exact source revision, final archive digest and platform CI results are recorded in the release PR before publication. Platform installation checks do not prove authenticated agent behavior.
+
+Native workflow evidence is retained in the [Lisière execution record](media/visual-chain/execution.fr.md) and [visual pilot](../examples/visual-pilot/README.md). The release reuses that evidence for the unchanged skills; it does not claim fresh model runs.
+
+Publish only the reviewed archive with an explicit `latest` tag for an authorized final release. After publication, download the registry tarball, compare its integrity and run package smoke again. Keep 0.1.0 available as a rollback reference.

package/docs/RELEASE-CHECKLIST.md

@@ -0,0 +1,13 @@
+# Release checklist
+
+Public releases require maintainer review of the exact candidate under CONTRIBUTING.md. This checklist does not authorize publication.
+
+1. Record the source revision and intended candidate version. Keep accepted contracts and English documentation consistent. Rebuild and commit `dist/` with source; do not claim new commands exist in an older npm tarball.
+2. Run `npm ci`, `npm test`, and `npm pack --dry-run`. Inspect the actual package contents, notice, executable and payload. Run the packed CLI for every host, including a subset, conflict preservation, and `doctor --json`.
+3. Record current platform CI run and job conclusions. Older green runs apply to their recorded commits; they do not certify a changed CLI on all systems.
+4. Separately run the [native smoke protocol](../COMPATIBILITY.md#native-smoke-protocol). Record exact host/model versions and real behavior. Keep untested hosts labeled pending even if installation is green.
+5. Check the [workflow evaluation protocol](EVALUATION.md) before publishing behavioral or comparative claims. Record what was actually run; do not substitute a written example for a transcript.
+6. Update version and lockfile together for a new npm release, refresh release notes and compatibility evidence, and inspect the final candidate again. Use the `next` tag for release candidates; preserve the stable tag.
+7. After authorized maintainer publication, verify the registry artifact/version and smoke-test that exact tarball. Record its digest and provenance. A pushed branch or merged PR is not an npm publication.
+
+Keep the previous package available as a rollback reference. Adoption updates remain staged comparisons; this release does not automatically migrate user profiles or instructions.

package/docs/RELEASE-NOTES-0.1.0-rc.2.md

@@ -0,0 +1,32 @@
+# DevMethod 0.1.0-rc.2 — candidate, not published
+
+Historical rc.2 record. For the current supported scope and validation, read [the 0.1.0 release record](RELEASE-0.1.0.md).
+
+A mission now connects authorized scope, selected source context, acceptance checks and resumable evidence. The six existing skills and their invocations remain intact.
+
+- Offline read-only mission, discover, context and context-check commands capture explicit source authority, revisions and byte pins. Git provenance detects branch/index/raw content changes without executing Git content hooks.
+- Existing JSON checkpoints remain readable; optional Git, blockers and criterion metadata improve resumption. Blocked results remain blocked. Input sizes are bounded.
+- Installation provenance and read-only update preview from earlier merged PRs are included. A new conflict category distinguishes divergent upstream and local edits. No update-apply command or migration is introduced.
+- A bounded manual task planner validates dependencies, ownership, worktrees, attempts and stop states. It does not dispatch workers or claim universal host execution.
+- Optional stack profiles accompany a fictional Next.js/NestJS/Drizzle/PostgreSQL example, with real unit, database and production HTML checks. Source and runtime dependencies remain separate.
+- Package documentation includes adoption, context, updates, troubleshooting, evaluation protocols and release instructions.
+
+Compatibility: Node.js 22+; Git required only for Git-aware context/provenance. No runtime dependencies for the CLI. Legacy installation manifests and checkpoints remain readable. New conflict/outcome enum values require consumers to handle unknown classifications conservatively. Checkpoint artifacts now have explicit size limits; retain large logs outside compact pinned records.
+
+Limitations: native Codex/Claude/Cursor comparative behavior remains pending; token/cost measurements unavailable. Browser hydration and cloud/broker/other database profiles are not runtime-validated. Current evidence and exact remaining gates are in [RC2-VALIDATION.md](RC2-VALIDATION.md). No superiority over BMAD is claimed.
+
+## Publication procedure (maintainer only)
+
+Review the exact stacked PR commits and their platform CI, then authorize integration separately. After integration, use a clean checkout of the reviewed release commit:
+
+```sh
+npm ci
+npm test
+npm run check:docs
+npm pack --dry-run
+npm pack
+# Only after explicit maintainer publication authorization:
+npm publish --tag next --access public
+```
+
+Inspect the tarball to ensure docs/examples and generated CLI are included, without node_modules/build outputs/secrets. Verify the published registry version and tarball integrity, then repeat the packaged CLI smoke test. Preserve rc.1 as the rollback reference. This document authorizes none of those external actions.

package/docs/RELEASE-NOTES-0.1.0.md

@@ -0,0 +1,11 @@
+# DevMethod 0.1.0
+
+DevMethod packages a reusable six-module workflow for starting projects and improving existing ones. The release includes safe staged installation, read-only diagnostics and upgrade comparison, structured mission/context inspection, Git-aware checkpoint resumption, bounded manual planning and optional stack profiles with a runnable fullstack example.
+
+The final review corrected error messages that could expose malformed JSON content. A CLI regression verifies that checkpoint, manifest, diagnostics and update errors omit input bytes and preserve project files. The welcome guide now correctly describes partial and direct installations.
+
+The CLI runs offline after acquisition and has no runtime dependencies. Node.js 22+ is required; Git supports provenance features. Existing customizations are not overwritten or automatically migrated. Read [the adoption and release record](RELEASE-0.1.0.md) for commands and validation.
+
+Native agent evaluation remains separate. Codex fixture and child-process probes have recorded evidence, but repeated BMAD comparison is incomplete and general automatic dispatch is experimental. This release makes no superiority or universal native-host compatibility claim.
+
+PRs #6–#10 are merged. A from-zero local task manager now preserves its brief, implementation, independent acceptance tests and browser validation. Review exposed missing HTTP trust checks; the app was corrected and architecture guidance now explicitly covers browser-facing local services. See [the greenfield record](GREENFIELD-VALIDATION.md). Publication status and artifact verification are tracked in the release record.

package/docs/RESUMPTION.md

@@ -0,0 +1,87 @@
+# Checkpoint resumption
+
+The optional format 1 JSON checkpoint records source pins and evidence dependencies. Its read-only inspector is available through `devmethod resume` and `dist/checkpoint.js`; it does not execute tests, update hashes, change project files or grant permission. Existing Markdown checkpoints remain supported as a manual workflow. No migration or new module is required.
+
+## Record and resume
+
+1. Record the authorized scope, actual state, next action, source revisions and checks using the scoped-delivery checkpoint template. Preserve project instructions and accepted decisions.
+2. For machine inspection, write a separate JSON checkpoint using the contract below. Compute SHA-256 from the exact bytes of each relevant source and saved evidence artifact. Include code, tests, contracts and instructions that the evidence relies on. Record versions of tools or external sources in a pinned local inventory; refresh that inventory from the actual environment on resumption.
+3. On resumption, inspect the checkpoint against the actual project. Review changed sources and affected evidence, including transitive dependencies. Repeat the affected checks before recording replacement artifacts and hashes. Never merely rehash changed files to make an earlier success look current.
+4. Respect the original scope and current permissions. A ready report is evidence consistency, not authorization. A completed scope with stale evidence may need reassessment; it still supplies no next action and never authorizes additional backlog.
+
+Inspect a JSON checkpoint with the offline CLI:
+
+```sh
+devmethod resume --dest /absolute/project --checkpoint checkpoint.json --json
+```
+
+`--checkpoint` is required and must be relative to the destination; destination defaults to the current directory. Omit `--json` for a readable report. The command only inspects evidence and displays the recorded next action; it never executes that action. Exit 0 means `ready` or `complete`; exit 1 means `reverify`, `blocked` or `invalid`; exit 2 means invalid invocation. Callers must retain the report and respect the original scope even when inspection succeeds. Other command flags (`--tool`, `--modules`, `--dry-run`) are rejected.
+
+Example API usage from a source checkout (or replace the import with the installed package's absolute `dist/checkpoint.js` path):
+
+```js
+import { readCheckpoint } from './dist/checkpoint.js';
+const report = readCheckpoint('/absolute/project', 'checkpoint.json');
+console.log(JSON.stringify(report, null, 2));
+```
+
+The inspector does not exit the process. Callers choose their own policy from `status` and findings. `inspectCheckpoint(destination, input)` inspects an already parsed untrusted value with the same validation.
+
+## Format 1 contract
+
+This illustrative record uses placeholders; replace each hash with 64 lowercase hexadecimal characters before inspection. File paths are relative to the project. IDs are unique within sources and within evidence. Empty evidence is allowed for a newly started checkpoint but produces `reverify`.
+
+```json
+{
+  "format": 1,
+  "scope": "Correct the parser under the approved contract; local changes only.",
+  "status": "active",
+  "nextAction": "Review the verified parser diff.",
+  "sources": [
+    { "id": "parser", "path": "src/parser.ts", "sha256": "<source hash>" },
+    { "id": "contract", "path": "docs/parser-contract.md", "sha256": "<contract hash>" }
+  ],
+  "evidence": [
+    {
+      "id": "tests",
+      "path": "evidence/tests.txt",
+      "sha256": "<artifact hash>",
+      "sourceIds": ["parser", "contract"],
+      "dependsOn": [],
+      "outcome": "passed"
+    },
+    {
+      "id": "review",
+      "path": "evidence/review.md",
+      "sha256": "<artifact hash>",
+      "sourceIds": ["parser", "contract"],
+      "dependsOn": ["tests"],
+      "outcome": "passed"
+    }
+  ]
+}
+```
+
+`status` is `active`, `blocked` or `complete`. Active and blocked records require a nonempty `nextAction`; complete requires `null`. Evidence outcomes are `passed`, `failed`, `blocked` or `not-run` (JSON spelling for “not run”). Each evidence entry requires at least one source and may depend on other evidence IDs. Unknown IDs, duplicate IDs/paths, cycles and malformed hashes are invalid. Optional fields below are inspected; other additional fields may carry human context but do not affect inspection.
+
+A content change or unavailable source invalidates its evidence. A changed or unavailable artifact invalidates that evidence. Invalidated, failed and unrun prerequisites invalidate dependent evidence recursively; independent evidence remains usable. Timestamp age alone has no effect. If bytes change back to the pinned content, the content comparison is unchanged; this is not an audit history.
+
+Report format 1 includes destination, status, findings, per-source states and per-evidence states. Findings have stable category codes; message text may evolve. `ready` means active scope with all pins consistent and all recorded evidence passed. `complete` requires consistent pins and completed scope. `reverify` means changes, missing evidence, failed checks or unrun checks prevent relying on the record. `blocked` preserves an explicitly blocked scope, with findings still identifying stale evidence. `invalid` means the checkpoint or destination cannot be inspected. Consumers must examine evidence and findings even for blocked records.
+
+## Limits and validation
+
+Hashes are a local baseline, not signed evidence or proof that a check was executed honestly. The inspector cannot discover omitted dependencies, changes to an external host or service, unrecorded environment state, permission changes, or semantic equivalence. Pin and refresh those inputs explicitly. Existing project policies and manual verification remain authoritative.
+
+The inspector rejects absolute/traversal paths, Windows drive/stream/device aliases, symbolic paths and non-regular artifacts. Inspect a directory that is not being modified concurrently: preflight checks do not provide an operating-system sandbox against path replacement races. No network, subprocess, credentials, telemetry or host evaluation is involved.
+
+Automated tests exercise content changes, timestamp independence, selective and transitive invalidation, missing files, failed/unrun evidence, invalid schemas, unsafe paths, symlinks, completed/blocked state and byte preservation. These establish local validator behavior; native host resumption remains an evaluation requirement.
+
+## Optional candidate extensions
+
+Format 1 remains readable without these fields. New records may include `git` from `gitState(root)` in `dist/records.js`: branch, commit, statusSha256 and diffSha256. Resume reports git-changed or git-unavailable and requires reassessment while retaining independent valid pins. Git requires a committed repository, uses bounded offline index reads with fsmonitor disabled, never status/diff or content filters. Save evidence in an ignored directory to avoid self-induced status changes. Pin untracked content explicitly.
+
+`blockers` is an optional array of unresolved dependency descriptions; a nonempty array keeps the report blocked. Evidence may include criterionIds (nonempty unique IDs), kind (automated, manual, design-review, recommendation), and revision. These record the acceptance → change/source → verification → outcome → revision chain; referenced criteria remain the mission author's responsibility. A blocked evidence outcome cannot support downstream success. Record automated logs only after executing the command; self-review is not independent review.
+
+Sources and evidence are limited to 256 entries each; each JSON or pinned artifact is limited to 1 MiB. Keep larger logs separately and pin a reviewed compact result with provenance. Hashes of branch/status/diff are not full worktree backups; retain ordinary Git commits and backups for recovery.
+
+Git provenance hashes raw tracked files (up to 10000 files, 8 MiB each, 64 MiB total) without running Git content filters. Secret-like paths are excluded from content hashing; submodule contents, ignored/untracked contents and external state require explicit safe pins or manual verification. Index changes include staged content; raw working bytes detect dirty-to-dirty edits. Hash fields retain the names statusSha256/diffSha256 but are local metadata fingerprints, not Git diff output.

package/docs/ROADMAP.md

@@ -0,0 +1,39 @@
+# Roadmap
+
+Aim: a compact engineering workflow for verifiable changes in existing repositories. Compete through demonstrated outcomes. See the [BMad comparison](BMAD-COMPARISON.md) for sources and limits. Priorities are ordered; later work is not automatically authorized by completing an earlier item.
+
+| Priority | Outcome | Acceptance evidence | State |
+|---|---|---|---|
+| P0 | Diagnose an adopted installation without losing customizations | Read-only doctor, malformed-path tests, full/subset host coverage, packed CLI checks | Implemented in this source change; release pending |
+| P0 | Make first use and small fixes understandable | Quick/standard/major guidance, runnable B1 fixture, three starter prompts | Instructions/examples added; native behavioral evaluation pending |
+| P0 | Distinguish claims from proof | Criterion-to-check verification record and release checklist | Templates/procedure added |
+| P1 | Validate actual host behavior | Authenticated Codex, Claude Code and Cursor runs at pinned versions; all fourteen stages | Full cross-host evidence pending |
+| P1 | Measure usefulness against alternatives | Matched no-method, DevMethod and BMad runs; publish success, failure, time and available usage | Protocol plus B1 fixture available; comparative runs pending |
+| P1 | Trace installed versions | New manifests record package version and distribution provenance; old manifests remain readable | Implemented in candidate source; publication pending |
+| P2 | Preview safe upgrades | Classify unchanged, customized, added and removed files; produce reviewed diff without overwriting context | Implemented in candidate source; publication pending |
+| P2 | Detect stale project context | Identify affected decisions/checkpoints from source changes; do not treat age alone as staleness | Explicit pins and Git-aware context implemented; semantic completeness not claimed |
+| P2 | Validate structured state when needed | Versioned schema, actionable errors and transitions linked to evidence; coexist with existing trackers | Optional mission records implemented; no mandatory tracker migration |
+| Later | Coordinate bounded workers | Explicit scope, dependencies, ownership, worktrees, budgets, stop/recovery rules; supported host contract | Manual planner implemented; native dispatch blocked by adapter/evidence/budget gates |
+
+## What to add only after demand
+
+The [visual creation proposal](VISUAL-CREATION-PROPOSAL.md) scopes a possible direction-selection, mockup and prototype flow into the existing design stage. The procedure is now available through the design stage; see the [pilot record](missions/visual-workflow.md) for validation status. Image generation still requires a host tool.
+
+Additional stack packs, a workflow builder or orchestration should solve repeated problems shown by real projects. The six existing modules remain the core. Do not add persona counts, a dashboard, cloud services or a vector store as proxies for workflow quality.
+
+## Principles
+
+- Preserve accepted project decisions, existing instructions and current authorization.
+- Keep the CLI offline and dependency-free at runtime.
+- Load relevant context progressively; measure savings before claiming them.
+- Prefer a failed or blocked verification over a false claim of completion.
+- Separate source implementation, npm publication, OS installation and native model behavior.
+- Preserve required maintainer review for public releases; a recommended next step grants no new permission.
+
+## Current authorized development
+
+See [the milestone checkpoint](MILESTONES.md) for the focused implementation PRs, verification, dependencies and resume boundary. Provenance/update previews and checkpoint inspection are implemented in the linked PRs; fixture/comparison utilities are tested, while actual native and matched model evidence remain pending. Bounded orchestration is blocked on those prerequisites. The table above retains the roadmap's priority order; candidate implementation is not a released or behaviorally validated capability.
+
+## Current mission
+
+The earlier campaign is historical. See [the current evolution](EVOLUTION.md), [rc.2 validation](RC2-VALIDATION.md) and [release notes](RELEASE-NOTES-0.1.0-rc.2.md) for implemented capabilities and remaining gates. Optional stack profiles and a real Next/Nest/PostgreSQL fixture are within the new explicit user scope. No previous merge authorization carries forward.

package/docs/STACK-PROFILES.md

@@ -0,0 +1,9 @@
+# Optional stack profiles
+
+DevMethod's six modules and offline CLI remain independent of a technology stack. Select only the profile relevant to a mission; profiles are reference guidance, not scaffolding commands, new personas or automatic dependency upgrades.
+
+Start with the [profile index](../.agents/skills/project-foundation/references/profiles/README.md). It lists TypeScript, React/Next, Node/Nest, PostgreSQL/Drizzle, MongoDB, messaging, cloud/container/infrastructure and CI profiles with their evidence levels. The [fullstack fixture](../examples/fullstack/README.md) provides the first executable Next/Nest/PostgreSQL slice with pinned dependencies and real persistence tests.
+
+In an existing project, first read its manifest/lockfile, runtime and infrastructure pins, accepted decisions and actual commands. Record installed versions, selected profile and relevant official sources in mission context. Preserve conventions unless the mission explicitly authorizes a change. Documentation availability and new upstream versions do not establish compatibility with an existing application.
+
+The fullstack fixture has its own package and lockfile. It is development/evaluation input, not a DevMethod CLI runtime dependency. Other profiles are independently usable inspection guides with explicitly unexecuted checks. Installing the method does not provision services, migrate data, install Vercel skills or validate a native coding host.

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,16 @@
+# Troubleshooting
+
+| Symptom | Diagnosis and recovery |
+|---|---|
+| npm command lacks mission/doctor | Check the exact package version. rc.1 predates these commands; use the reviewed candidate checkout or tarball. |
+| init reports Conflict | No writes were applied. Keep filled profiles/instructions; install the candidate into a fresh directory, then preview and select a manual diff. |
+| doctor reports customization | Expected for adopted profiles and skills. Review the diff; do not overwrite to obtain a green status. |
+| update-preview reports conflict | Both upstream and local content changed. Retain both versions, select hunks manually, back up first, verify and restore selected files if needed. |
+| context capture fails on Git | Use a committed repository, inspect unsafe/symbolic or oversized tracked files, and keep provenance under the documented limits. Legacy checkpoints without Git remain available. |
+| context becomes stale immediately | Saving a report may change status. Use an existing ignored evidence directory; create/ignore it before capture. |
+| resume says reverify | Inspect changed pins, Git state and affected evidence. Repeat only affected checks; never refresh hashes to hide a stale result. |
+| plan says needs-reconciliation | Inspect the interrupted task's actual worktree and checkpoint; do not start it again automatically. |
+| host does not discover a skill | Confirm the selected host directory and SKILL.md, avoid duplicate profiles, read the fallback prompt in START_HERE.md. Installation alone is not native validation. |
+| database fixture cannot run | Check Docker and the documented local port. Keep database/e2e tests blocked if PostgreSQL is unavailable; unit tests do not replace them. |
+
+No CLI operation applies updates, changes project instructions, dispatches models or grants merge/publication permission. See the specific command reference for exit codes.

package/docs/UPDATES.md

@@ -0,0 +1,30 @@
+# Installed provenance and update previews
+
+`devmethod update-preview [--dest PATH] [--json]` compares an installation with the payload bundled in the CLI you invoke. It infers the installed host and module subset, includes foundation, and performs no writes, downloads, migrations or model calls. It does not check a registry for a newer version.
+
+New format 2 manifests include optional `provenance`: `packageName`, `packageVersion` and `payloadSha256`. The digest hashes JSON-encoded sorted `[path, sha256]` pairs for the host-profiled selected payload, excluding the manifest itself. This distinguishes payload changes even when package versions match. These are local records, not signatures or proof of release authenticity. Legacy manifests continue to work: an identical `init` preserves their original bytes and previews explicitly report unknown installed version. Never infer a legacy version from the CLI currently running.
+
+The format 1 JSON report contains installed/candidate provenance, findings and entries:
+
+| Classification | Meaning |
+| --- | --- |
+| unchanged | Local file, recorded baseline and candidate match. |
+| updated | Local file matches its baseline; candidate differs. |
+| customized | Local differs from baseline while upstream is unchanged, or local already equals the candidate. |
+| conflict | Local and candidate both differ from baseline and differ from each other, including local edits to upstream-deleted files. |
+| added | Candidate path was absent from the baseline; `collision` flags an existing local file. |
+| removed | Baseline file is unchanged locally and absent from the candidate. |
+
+Each entry includes available baseline, local and candidate SHA-256 hashes, plus `candidateChanged`. A locally customized file absent from the candidate is a conflict and has no candidate hash. The new conflict value is an additive report enum; consumers must handle unknown classifications conservatively. A missing file is explicit and retains a diagnostic error. Exit codes are 0 for a completed clean/warning preview, 1 for diagnostic or filesystem errors, and 2 for invalid invocation. Warnings require human review; exit 0 does not authorize applying changes.
+
+To review content differences, install the candidate CLI into a fresh staging directory with the same host/subset, then use your normal diff tool against the project. Preserve project profiles, instructions, accepted decisions and customizations intentionally. There is no automatic apply command. Unrecorded files outside candidate paths are not inventoried. Inspect directories without concurrent modification; symbolic-path checks are not an OS sandbox. No native-host compatibility or behavioral claim follows from these tests.
+
+## Verification checkpoint
+
+Historical provenance-slice validation (before 0.1.0; current results are in [the release record](RELEASE-0.1.0.md)) on macOS with Node.js: `npm ci` and `npm test` pass (23 tests, including all three layouts and subsets). `npm pack --dry-run --cache /private/tmp/devmethod-provenance-npm-cache` passes; a freshly extracted tarball successfully runs a Claude subset installation and JSON update preview with matching provenance. This is a packaged CLI smoke test, not Claude host evidence. The default npm cache was unwritable, so packaging used an isolated temporary cache; no cache ownership changes were made.
+
+Resume by reviewing ADR 003 and the CLI/manifest diff, then run the platform matrix against the exact candidate before claiming cross-platform execution. Do not apply updates automatically or publish this candidate without the release process.
+
+## Manual application and recovery
+
+Preview is the only update operation shipped. Before applying a reviewed staging diff manually, select exact paths/hunks, make a clean backup or Git commit of the current project (including filled profiles), and retain the old manifest. Apply only the selected content, preserving project instructions and decisions. Run project checks and doctor; customizations remain expected warnings. If verification fails, restore only those selected paths from the backup and re-run affected checks. Do not replace the baseline manifest to make intentional edits look pristine. There is no automatic apply or rollback command, and a hash difference is never overwrite authorization.

package/docs/VISUAL-CREATION-PROPOSAL.md

@@ -0,0 +1,21 @@
+# Visual creation proposal
+
+Historical proposal, 2026-09-13. The reusable procedure is now implemented in [visual creation](../.agents/skills/design-to-code/references/visual-creation.md). Follow the [pilot record](missions/visual-workflow.md) for observed execution and outstanding selection/verification; implementation of instructions does not establish end-to-end validation. The existing `design` stage can frame UX; `design-to-code` already describes implementation and fidelity checks against an approved reference. The missing procedure to evaluate is how to create and select that reference when none exists.
+
+## Proposed flow inside the existing design stage
+
+1. Reuse the mission's audience, main journey, constraints and existing brand/assets. Ask only for missing choices that materially affect the direction. Keep a short visual brief in the existing mission/design record.
+2. If no direction is approved, propose two or three genuinely different directions applied to the same key screen and content. For each, show typography, palette, layout density, imagery approach, a short rationale and trade-offs. For a fictional reading app, candidates might be an editorial layout with serif headings, a compact utilitarian library, and an illustrated reading journal; these are examples, not a default style imposed on projects.
+3. Let the user choose or combine directions before detailed production, unless selection was explicitly delegated. Record the chosen version and remaining assumptions in the existing design owner. An established reference skips this exploration.
+4. Produce the selected key screen at desktop/mobile sizes and its necessary empty, loading and error states. When an image tool is available, use its applicable skill for raster concepts, illustrations or image mockups; record the prompt, output path and selected version. An image-generation tool is available in this session, but no images were generated for this proposal. Tool availability depends on the host, not DevMethod installation. Keep precise UI text, tokens and interactions in the design record; a raster mockup cannot prove responsive behavior or accessibility.
+5. Build a small interactive prototype only when navigation, state changes or motion need validation. Use existing project tools and clearly labelled fixture data. Review the main journey, keyboard/focus and mobile behavior. Skip this extra artifact when a static reference already resolves the question.
+6. Pass the selected reference to `design-to-code`: actual assets, screen/version, viewports, tokens, content, states, interactions and criterion IDs. Resolve conflicts between the design record, mockup and product constraints before dependent implementation; do not silently choose the newest artifact.
+7. Render the implementation at the reference dimensions. Attach reference/capture pairs and interaction results to the same criterion evidence rows. Record mismatches, corrections and residual limitations, then invalidate affected visual evidence after changes. A successful build is insufficient for fidelity acceptance.
+
+## Bounded evaluation before adoption
+
+Use one fictional screen and its main interaction, without changing any project studied in a pilot. Success means the user can choose from visible alternatives, the selected reference is versioned and reusable, and the resulting browser UI has criterion-linked visual and interaction evidence. Check resumption from that reference and an intentional mismatch that must be caught. Measure created records, user interventions, elapsed time and exposed usage; do not claim savings without a comparable baseline. Store assets using project conventions and link them from one design owner rather than adding a mandatory document per step.
+
+## Relationship to BMad
+
+The official [Design UX and Architecture](https://docs.bmad-method.org/plan/design-ux-and-architecture/) page, inspected 2026-09-13, documents `bmad-ux`, `DESIGN.md` and `EXPERIENCE.md`, creative directions, wireframes, key-screen mocks and a handoff to external design tools. It also defines conflict precedence for those documents. These are documented capabilities, not behavior evaluated here. Creating visuals is therefore not exclusive to DevMethod; the proposed focus is a compact transition from a chosen reference to criterion-linked fidelity evidence. No superiority claim or comparative benchmark is established.

package/docs/VISUAL-WORKFLOW.md

@@ -0,0 +1,75 @@
+# Create a direction, then build it
+
+The 0.2.0 candidate and current GitHub source include a visual-creation procedure in the existing `design` stage. It preserves six modules and does not install an image service. The published npm `0.1.0` package predates this evolution; reinstalling that version does not obtain it. See the [0.2.0 release record](RELEASE-0.2.0.md) before choosing the installation command.
+
+## Start
+
+From the target repository, install the current reviewed GitHub source into a staging directory:
+
+```sh
+npx --yes --package=github:montassarkhalloufi/DevMethod devmethod init --tool codex --dest ../devmethod-staging
+```
+
+For reproducibility, replace the repository reference with `github:montassarkhalloufi/DevMethod#<reviewed-commit>`. Inspect the staging files and preserve existing instructions and customized profiles during adoption. Claude Code uses `--tool claude`; Cursor uses `--tool cursor`.
+
+In the agent conversation, not the terminal:
+
+```text
+$project-foundation design
+Create a visual direction for [product and audience].
+Show me alternatives, let me choose, then prepare the key screen mockups.
+```
+
+Use `/project-foundation design` in Claude Code or Cursor. An already approved direction skips new alternatives. A brief can specify that the agent chooses the direction if that is what you want.
+
+## What the procedure delivers
+
+1. A brief grounded in the product, audience and supplied references.
+2. Two or three comparable visible directions when the choice is open.
+3. A recorded user choice, or an explicitly delegated selection.
+4. Key-screen image mockups when an image tool is available, with prompts and versioned assets. Missing tooling is reported; an external-tool prompt is not an image.
+5. An interactive prototype for the behavior that needs checking. The prototype may become the implementation.
+6. Browser captures and interaction evidence compared with the approved reference, with mismatches and limitations recorded.
+
+A build passing is not visual acceptance. Image generation is performed by the host's tool, not by the installer. The workflow does not promise identical output across models, hosts or runs.
+
+## Recorded examples
+
+- [Lisière](../examples/visual-pilot/README.md): supervised visual pilot, generated directions, user-selected and approved mockup, implementation and browser checks. This is not an independent end-to-end agent evaluation.
+- [Mission and evidence](missions/visual-workflow.md): scope, checks and known typography/spacing differences.
+
+Source adoption is separate from npm publication. No new npm version is announced by this guide.
+
+## Full filmed chain
+
+The [4K French walkthrough](media/full-chain-4k/README.md) shows actual Codex CLI commands and outputs, the prior approved visual choices, a fresh implementation, review findings, corrections, browser interaction and verification. CLI transcripts are reformatted for legibility; the provenance and limitations are explicit.
+
+## Master screen → images des écrans → application
+
+Le parcours visuel reste dans `design` jusqu'à ce que les visuels demandés soient prêts. « Master » et « pages » désignent le contenu du travail, pas de nouvelles sous-commandes du CLI.
+
+Dans la conversation Codex, on peut envoyer successivement :
+
+```text
+$project-foundation design
+Propose trois directions comparables sur le même écran principal.
+```
+
+```text
+$project-foundation design
+Je choisis A. Finalise le master screen de cette direction.
+```
+
+Après examen et approbation du master :
+
+```text
+$project-foundation design
+Décline ce master approuvé en images des écrans demandés.
+Utilise le fichier du master comme référence visuelle.
+```
+
+Les écrans gardent la typographie, la palette et les composants du master. L'agent examine les résultats, identifie leur référence/version et soumet les ajouts inattendus à validation. Il n'invente pas de routes : bibliothèque, ajout et filtre peuvent être des états d'une seule application.
+
+La suite est `architecture` si des décisions restent nécessaires, puis `plan`, préparation `ready`, `implement`, `review`/`verify` et `integrate`. Les petites tranches peuvent regrouper préparation et réalisation. Les images précèdent l'implémentation qu'elles sont censées guider ; les captures navigateur servent ensuite à la comparaison.
+
+Le [film complet de 2 min 58 s](media/visual-chain/README.md) montre ce passage avec des images réellement générées à partir du master, puis une nouvelle implémentation. Il poursuit avec les choix d’architecture et de technologies, la préparation, l’implémentation, la revue, la vérification et la livraison locale. La génération exige un outil d'image disponible dans l'agent ; DevMethod fournit les instructions du parcours, pas un moteur d'image intégré au paquet npm.

package/docs/images/devmethod-delivery.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="650" viewBox="0 0 1200 650" role="img" aria-labelledby="title desc">
+<title id="title">DevMethod delivery loop</title><desc id="desc">Accepted scope, design and architecture guide implementation. Review and verification either justify delivery or return work to correction. A blocked slice keeps a handoff record.</desc>
+<defs><marker id="arrow" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto"><path d="M0 0L6 3L0 6" fill="#ddac86"/></marker></defs>
+<rect width="1200" height="650" rx="28" fill="#10272b"/><g font-family="Arial, sans-serif">
+<text x="52" y="65" fill="#eeb88e" font-size="16" letter-spacing="3">DEVMETHOD / THE DELIVERY LOOP</text><text x="52" y="117" fill="#fff9ef" font-size="36" font-weight="700">A finished slice needs evidence</text>
+<text x="52" y="154" fill="#b9ccc4" font-size="20">Design approval guides the work. Tests and browser checks verify the result.</text>
+<rect x="52" y="203" width="320" height="157" rx="16" fill="#1a363a" stroke="#49615e"/><text x="74" y="250" fill="#fff9ef" font-size="24" font-weight="700">Accepted references</text><text x="74" y="293" fill="#c6d7ce" font-size="18">Scope · design · architecture</text><text x="74" y="325" fill="#c6d7ce" font-size="18">Plan and readiness</text><rect x="440" y="203" width="320" height="157" rx="16" fill="#1a363a" stroke="#49615e"/><text x="462" y="250" fill="#fff9ef" font-size="24" font-weight="700">Implement and review</text><text x="462" y="293" fill="#c6d7ce" font-size="18">Build the real interactions</text><text x="462" y="325" fill="#c6d7ce" font-size="18">Review code, risks and tests</text><rect x="828" y="203" width="320" height="157" rx="16" fill="#1a363a" stroke="#49615e"/><text x="850" y="250" fill="#fff9ef" font-size="24" font-weight="700">Verify the result</text><text x="850" y="293" fill="#c6d7ce" font-size="18">Run the agreed checks</text><text x="850" y="325" fill="#c6d7ce" font-size="18">Compare UI with the design</text><g stroke="#ddac86" stroke-width="3" fill="none" marker-end="url(#arrow)"><path d="M378 281h54"/><path d="M766 281h54"/><path d="M988 365v75"/><path d="M600 450v-78"/><path d="M930 365v40H210v35"/></g>
+<rect x="828" y="452" width="320" height="117" rx="16" fill="#24483f" stroke="#74b49a"/><text x="850" y="490" fill="#fff9ef" font-size="23" font-weight="700">Checks pass → deliver</text><text x="850" y="526" fill="#c6d7ce" font-size="18">Integrate within permissions</text><text x="850" y="552" fill="#c6d7ce" font-size="18">Record evidence and handoff</text>
+<rect x="52" y="452" width="708" height="117" rx="16" fill="#3b3531" stroke="#ddac86"/><text x="74" y="491" fill="#fff9ef" font-size="23" font-weight="700">Failed check or changed constraint → correct</text><text x="74" y="526" fill="#decbbb" font-size="18">Fix the slice or revisit the affected design / architecture decision.</text><text x="74" y="552" fill="#decbbb" font-size="18">If blocked, preserve a checkpoint; do not mark the slice delivered.</text>
+<text x="52" y="616" fill="#b9ccc4" font-size="18">status / next resume from the evidence; they do not create an autonomous backlog.</text></g></svg>

package/docs/images/devmethod-flow.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="720" viewBox="0 0 1200 720" role="img" aria-labelledby="title desc">
+<title id="title">DevMethod: from idea to verified delivery</title><desc id="desc">Six stages connect product scope, visual design, architecture, planning, implementation and verified delivery. Revisit decisions when evidence changes.</desc>
+<rect width="1200" height="720" rx="28" fill="#10272b"/>
+<g font-family="Arial, sans-serif"><text x="52" y="64" fill="#eeb88e" font-size="16" letter-spacing="3">DEVMETHOD / THE COMPLETE WORKFLOW</text>
+<text x="52" y="119" fill="#fff9ef" font-size="38" font-weight="700">From an idea to a verified product</text>
+<text x="52" y="157" fill="#b9ccc4" font-size="20">Make the decisions visible. Build a useful slice. Check the result.</text>
+<rect x="52" y="202" width="352" height="183" rx="16" fill="#1a363a" stroke="#49615e"/><text x="76" y="237" fill="#eeb88e" font-size="17" font-weight="700">01</text><text x="76" y="278" fill="#fff9ef" font-size="23" font-weight="700">Understand the product</text><text x="76" y="316" fill="#eeb88e" font-size="18">Explore · frame</text><text x="76" y="350" fill="#c6d7ce" font-size="17">Users, scope and success criteria</text>
+<rect x="424" y="202" width="352" height="183" rx="16" fill="#1a363a" stroke="#49615e"/><text x="448" y="237" fill="#eeb88e" font-size="17" font-weight="700">02</text><text x="448" y="278" fill="#fff9ef" font-size="23" font-weight="700">Design the experience</text><text x="448" y="316" fill="#eeb88e" font-size="18">Design</text><text x="448" y="350" fill="#c6d7ce" font-size="17">Directions → master → screens</text>
+<rect x="796" y="202" width="352" height="183" rx="16" fill="#1a363a" stroke="#49615e"/><text x="820" y="237" fill="#eeb88e" font-size="17" font-weight="700">03</text><text x="820" y="278" fill="#fff9ef" font-size="23" font-weight="700">Choose the architecture</text><text x="820" y="316" fill="#eeb88e" font-size="18">Architecture</text><text x="820" y="350" fill="#c6d7ce" font-size="17">Technologies, boundaries, trade-offs</text>
+<rect x="52" y="409" width="352" height="183" rx="16" fill="#1a363a" stroke="#49615e"/><text x="76" y="444" fill="#eeb88e" font-size="17" font-weight="700">04</text><text x="76" y="485" fill="#fff9ef" font-size="23" font-weight="700">Prepare a useful slice</text><text x="76" y="523" fill="#eeb88e" font-size="18">Plan · ready</text><text x="76" y="557" fill="#c6d7ce" font-size="17">Dependencies and acceptance checks</text>
+<rect x="424" y="409" width="352" height="183" rx="16" fill="#1a363a" stroke="#49615e"/><text x="448" y="444" fill="#eeb88e" font-size="17" font-weight="700">05</text><text x="448" y="485" fill="#fff9ef" font-size="23" font-weight="700">Build and improve</text><text x="448" y="523" fill="#eeb88e" font-size="18">Implement · review</text><text x="448" y="557" fill="#c6d7ce" font-size="17">Working behavior, tests and fixes</text>
+<rect x="796" y="409" width="352" height="183" rx="16" fill="#1a363a" stroke="#49615e"/><text x="820" y="444" fill="#eeb88e" font-size="17" font-weight="700">06</text><text x="820" y="485" fill="#fff9ef" font-size="23" font-weight="700">Verify and deliver</text><text x="820" y="523" fill="#eeb88e" font-size="18">Verify · integrate · handoff</text><text x="820" y="557" fill="#c6d7ce" font-size="17">Evidence, delivery and resumption</text>
+<path d="M52 630h1096" stroke="#49615e"/><text x="52" y="664" fill="#c6d7ce" font-size="18">Adapt the depth to the project. Revisit decisions when constraints or checks change.</text><text x="52" y="694" fill="#9fb8af" font-size="16">Skill guidance for your coding agent · Image generation requires an available host tool.</text></g></svg>

package/docs/media/from-zero/README.md

@@ -0,0 +1,17 @@
+# DevMethod — French demonstration video
+
+[Watch/download the MP4](https://github.com/montassarkhalloufi/DevMethod/raw/refs/heads/main/docs/media/from-zero/devmethod-demo.fr.mp4) · [French subtitles](devmethod-demo.fr.srt) · [Narration and scenes](scenes.json)
+
+A short promotional/explanatory video: product promise, an actual from-zero Clair agent trial, real recorded browser interactions, the separate Lisière visual pilot, verification and a GitHub call to action. The explanatory cards summarize work; they are not a recording of every development step.
+
+The French narration is synthetic system speech (Thomas). No music, testimonials, customer results or comparative savings are invented. App records and generated book covers are fictional. The visible Lisière art-direction board is AI-generated; Clair's interface is implemented HTML/CSS. The source workflow is newer than npm 0.1.0; use the [source guide](../../VISUAL-WORKFLOW.md).
+
+## Reproduce
+
+Requires macOS `say` with Thomas, ffmpeg/ffprobe, Chrome and an installed Playwright module. Start Clair on localhost:8766 using the example README. From the repository root, run `node scripts/media/record-demo.cjs` (set PLAYWRIGHT_MODULE if needed), then `python3 scripts/media/encode-demo.py`. The narration text/timing lives in scenes.json. The recorder saves intermediate clips under /private/tmp/devmethod-video; the encoder writes MP4 and SRT here. Do not reuse old intermediate speech files after editing the narration.
+
+[Desktop capture](https://github.com/montassarkhalloufi/DevMethod/raw/refs/heads/main/docs/media/from-zero/captures/clair-desktop.png) and [mobile capture](https://github.com/montassarkhalloufi/DevMethod/raw/refs/heads/main/docs/media/from-zero/captures/clair-mobile.png) are browser evidence. Tests validate selected behavior, not all accessibility, platforms or deployment conditions. See the [example report](../../../examples/clair-from-zero/README.md).
+
+## Verification record
+
+Final MP4: 1280×720 H.264, AAC narration, French mov_text subtitle track; approximately 70.5 seconds, 2.5 MB. Scene screenshots and an encoded interaction frame were visually inspected. Audio is non-silent (mean -15.7 dB, peak -0.4 dB); no claim of a full human listening review. Six Clair logic/storage tests and the independent browser journey passed. The suite disables animation for evidence screenshots.

package/docs/media/from-zero/devmethod-demo.fr.srt

@@ -0,0 +1,59 @@
+1
+00:00:00,000 --> 00:00:01,698
+Une idée, c'est un début.
+
+2
+00:00:01,698 --> 00:00:04,278
+Un produit vérifié, c'est un parcours.
+
+3
+00:00:04,278 --> 00:00:08,963
+Dev Method guide votre agent de développement, du besoin aux preuves.
+
+4
+00:00:10,163 --> 00:00:14,324
+Pour cette démonstration, nous sommes partis d'un dossier vide.
+
+5
+00:00:14,324 --> 00:00:21,854
+Un agent a reçu Dev Method et un besoin simple : créer Clair, une application locale pour organiser ses priorités.
+
+6
+00:00:23,054 --> 00:00:25,862
+Voici le résultat réel dans le navigateur.
+
+7
+00:00:25,862 --> 00:00:29,873
+On ajoute une priorité, on la termine et on filtre la liste.
+
+8
+00:00:29,873 --> 00:00:33,283
+Les données restent disponibles après rechargement.
+
+9
+00:00:34,483 --> 00:00:38,815
+Dans le pilote visuel Lisière, trois directions ont été proposées.
+
+10
+00:00:38,815 --> 00:00:42,360
+Le choix humain a précédé la maquette et le prototype.
+
+11
+00:00:42,360 --> 00:00:46,627
+La génération d'images utilise les outils disponibles de l'agent.
+
+12
+00:00:47,827 --> 00:00:51,964
+Les tests et les vérifications navigateur accompagnent la livraison.
+
+13
+00:00:51,964 --> 00:00:59,448
+Ces pilotes sont de vrais essais encadrés, pas une garantie universelle ni une comparaison gagnée contre une autre méthode.
+
+14
+00:01:00,648 --> 00:01:02,877
+Découvrez Dev Method sur GitHub.
+
+15
+00:01:02,877 --> 00:01:09,216
+Installez le kit, décrivez votre objectif et commencez par une petite livraison vérifiable.

package/docs/media/from-zero/scenes.json

@@ -0,0 +1,50 @@
+[
+  {
+    "kind": "title",
+    "title": "De l’idée au produit vérifié.",
+    "eyebrow": "DEVMETHOD",
+    "text": "Une méthode pour guider votre agent, du besoin aux preuves.",
+    "voice": "Une idée, c'est un début. Un produit vérifié, c'est un parcours. Dev Method guide votre agent de développement, du besoin aux preuves.",
+    "duration": 10.162901999999999
+  },
+  {
+    "kind": "start",
+    "title": "Un dossier vide. Un besoin concret.",
+    "eyebrow": "01 — PARTIR DE ZÉRO",
+    "text": "Clair · Organiser ses priorités personnelles.\nKit installé, périmètre limité, données locales.",
+    "voice": "Pour cette démonstration, nous sommes partis d'un dossier vide. Un agent a reçu Dev Method et un besoin simple : créer Clair, une application locale pour organiser ses priorités.",
+    "duration": 12.891247
+  },
+  {
+    "kind": "app",
+    "title": "Un résultat que l’on peut utiliser.",
+    "eyebrow": "02 — CONSTRUIRE",
+    "text": "Ajouter · Terminer · Filtrer · Retrouver ses données",
+    "voice": "Voici le résultat réel dans le navigateur. On ajoute une priorité, on la termine et on filtre la liste. Les données restent disponibles après rechargement.",
+    "duration": 11.428389999999998
+  },
+  {
+    "kind": "visual",
+    "title": "Choisir avant de construire.",
+    "eyebrow": "03 — DONNER UNE DIRECTION",
+    "text": "Pilote visuel Lisière : propositions → choix → maquette approuvée → prototype.",
+    "voice": "Dans le pilote visuel Lisière, trois directions ont été proposées. Le choix humain a précédé la maquette et le prototype. La génération d'images utilise les outils disponibles de l'agent.",
+    "duration": 13.344036
+  },
+  {
+    "kind": "proof",
+    "title": "Des preuves, pas seulement un statut.",
+    "eyebrow": "04 — VÉRIFIER",
+    "text": "Tests exécutés · Interactions vérifiées · Limites documentées",
+    "voice": "Les tests et les vérifications navigateur accompagnent la livraison. Ces pilotes sont de vrais essais encadrés, pas une garantie universelle ni une comparaison gagnée contre une autre méthode.",
+    "duration": 12.821587
+  },
+  {
+    "kind": "end",
+    "title": "Donnez une méthode à votre prochain projet.",
+    "eyebrow": "À VOUS DE CONSTRUIRE",
+    "text": "github.com/montassarkhalloufi/DevMethod\nDécouvrez le guide et les exemples reproductibles.",
+    "voice": "Découvrez Dev Method sur GitHub. Installez le kit, décrivez votre objectif et commencez par une petite livraison vérifiable.",
+    "duration": 9.768163
+  }
+]