devmethod-ai 0.1.0-rc.2 → 0.1.0

package/docs/GREENFIELD-VALIDATION.md

@@ -0,0 +1,36 @@
+# From-zero validation — Pocket Tasks
+
+Recorded 2026-09-13. Scope: a fictional single-user local task manager, from an empty application repository through brief, readiness, architecture, implementation, tests, independent review, actual browser acceptance and handoff. No deployment, paid service or real user data was involved.
+
+## Frozen input and method use
+
+The coordinator installed the project-foundation, decision-architecture and scoped-delivery modules from DevMethod 0.1.0 source before application code existed. The baseline commit in the isolated experiment was `0cf3474bfd777299873e51a2789829692c648130`. The frozen [brief](../examples/pocket-tasks/BRIEF.md) has SHA-256 `574ff435d8ac66f39cad76d0318c6476afea061737b0c217599c0e401c541125`. Neither the brief nor installed skills changed during the experiment. The builder filled the profile and recorded readiness, decisions and plan before implementation. The coordinator authored separate API acceptance before the implementation was available; the builder did not read or edit that harness.
+
+This used the current Codex workspace with a builder and a separate reviewer. It was not an isolated native-host benchmark or a matched BMAD trial. Host/model usage was not separately metered, and fourteen-stage universal coverage is not claimed. The public example preserves application sources and project records, excluding the private Git repository, installed skill copies, runtime data and conversation logs.
+
+## Findings and corrections
+
+Independent review reproduced a real defect: a JSON-shaped text/plain POST from an untrusted browser origin could mutate the loopback service. The builder added exact Host checks, mutation Origin/Sec-Fetch-Site validation, JSON media-type checks and non-mutation regression tests, preserving legitimate same-origin and Origin-free CLI requests. Architecture guidance now explicitly requires browser trust boundaries for local HTTP services. The observed app correction was review-directed; this experiment does not isolate the effect of the new guidance on a fresh agent.
+
+Browser acceptance also found a misleading error: a definitive validation rejection demanded reload as though save status were unknown. The UI now retains input and permits immediate correction for 4xx; network/5xx failures retain reconciliation guidance. Independent final review found no remaining blocker in these corrections.
+
+The initial sandbox denied HTTP listeners. Checks were rerun with authorized loopback access. An early independent Host assertion failed because fetch normalized its Host header; the harness now uses raw HTTP and verifies the transmitted header. No acceptance criterion was removed. The worker's own transport-framing correction and storage-error correction remain recorded in [worker evidence](../examples/pocket-tasks/docs/VERIFICATION.md).
+
+## Actual acceptance
+
+- Application tests: 9 passed, covering domain, HTTP, persistence, concurrent writes, corrupt-data preservation, browser trust checks and UI error recovery.
+- Independent tests: 9 passed, including seven nested contract cases plus the parent and the separate trust-boundary test. API creation/edit/completion/reopening/deletion, invalid/oversized bodies, persistence across restart, concurrent creates, static restrictions and hostile request non-mutation passed.
+- Real in-app browser: add with keyboard; edit/save; complete, filter, reopen; delete; restart and reload with persisted data; HTML-looking title remained literal with zero injected images; 390 × 844 layout inspected without horizontal overflow. Validation-only input retained focus and text, then accepted a corrected title without reload.
+- Actual initial local runtime: Node v23.10.0 on macOS. Node 22 platform execution is tracked by the release CI, separately from these local observations.
+
+## Reproduce
+
+```sh
+npm run test:greenfield
+cd examples/pocket-tasks
+npm start
+```
+
+Open `http://127.0.0.1:4318`. Tests use disposable files and ephemeral loopback listeners. The [application guide](../examples/pocket-tasks/README.md) explains backups, corruption recovery and single-process limits. The [independent acceptance](../evaluation/greenfield/acceptance.test.mjs) and [trust checks](../evaluation/greenfield/security.test.mjs) can target another copy using `PROJECT_DIR`. Package smoke also executes the application and independent suites from the extracted archive.
+
+A passing fictional local app supports this bounded delivery path. It does not establish production readiness, authentication, distributed storage, universal native compatibility or superiority over BMAD. Future comparisons still require both methods to execute correctly under the published evaluation protocol.

package/docs/MILESTONES.md

@@ -0,0 +1,39 @@
+# Historical milestone checkpoint
+
+This record describes the previous campaign, now merged as PRs #2–#5. Its merge authorization does not apply to the new mission. Current scope and evidence: [EVOLUTION.md](EVOLUTION.md) and [RC2-VALIDATION.md](RC2-VALIDATION.md).
+
+Baseline: `ce11461252f6a3b8e14f7af021c362e5d4742915`, matching main after merged PR #1. The starting checkout was clean. PR #1 introduced diagnostics and workflow guidance; ADR 001 is accepted and ADR 002 remains labeled proposed. New ADRs are proposals, not inferred maintainer acceptance. The initial boundary excluded main merges; the maintainer subsequently authorized merging these PRs after repeat testing and review. npm publication remains excluded.
+
+| Milestone | Delivered slice | Remaining gate |
+|---|---|---|
+| M1 native fixtures/evidence | [PR #2](https://github.com/montassarkhalloufi/DevMethod/pull/2): pinned B1/B3/B4/B5, objective collection and protected checks | B2 pinned React source/approved screen; actual authenticated host runs covering all fourteen stages; no synthetic substitute |
+| M2 provenance/update preview | [PR #3](https://github.com/montassarkhalloufi/DevMethod/pull/3): compatible manifests, offline read-only candidate comparison | Maintainer review; exact-candidate platform checks before cross-platform claims |
+| M3 checkpoint resumption | [PR #5](https://github.com/montassarkhalloufi/DevMethod/pull/5): optional JSON evidence DAG and read-only resume CLI, manual Markdown retained | Maintainer review and actual native resumption evidence; depends on M2's shared CLI branch |
+| M4 matched comparisons | [PR #4](https://github.com/montassarkhalloufi/DevMethod/pull/4): matched-condition/budget validator and per-arm denominators; depends on PR #2 | Explicit evaluation budget, pinned installed BMAD, authenticated host, actual runs and independent evidence review |
+| M5 bounded orchestration | Prerequisites and stop conditions recorded below | Blocked by native evidence and supported host dispatch/recovery contract; no scheduler or automatic dispatch implemented |
+
+Implementation tests are evidence for these local utilities only. They do not establish native instruction adherence, comparative results or orchestration readiness. Local environment/authentication observations are retained separately and excluded from public commits. No repeated model evaluation batch has been executed in this campaign.
+
+## Verification and ownership
+
+Implementation used separate worktrees with non-overlapping worker ownership. One owner controls manifest and CLI changes. Completed revisions received a separate read-only review. Review found an enum coercion bug in checkpoint validation; actual string checks and array regressions corrected it. Changes to a reviewed surface invalidate that surface's earlier review until rechecked.
+
+Required checks: `npm ci`, `npm test`, `npm pack --dry-run` and diff inspection. Packaging may use a disposable `--cache` path without changing the user's shared cache. Generated `dist/` remains committed. Each implementation PR records its exact checks and limits. Packed CLI checks are separate from authenticated model behavior. Native platform CI for PR #3 passed all three OS jobs in [run 34726451896](https://github.com/montassarkhalloufi/DevMethod/actions/runs/34726451896). Fixture CI initially failed on Windows because checkout converted pinned bytes to CRLF; commit `4e6be74` enforces LF for fixture paths without relaxing hashes. Check the latest PR jobs before claiming that correction passed on Windows.
+
+## Native budget gate
+
+Before running or retrying model evaluations, record the user's explicit maximum run count, combined input/output tokens and total USD. Also pin model, per-run limits and timeout, enforceable host limits, method commit, fixture and prompt. A missing approval or unenforceable cap blocks dispatch. Unknown usage is not zero; it blocks further runs under a hard cap. Authentication/version probes and fixture tests are not model evaluations. Resolve the pending budget question before continuing this gate.
+
+## Orchestration gate and authorized boundary
+
+Do not activate worker dispatch until actual native evidence confirms discovery, bounded edits, failure reporting, local-only integration and fresh-session resumption for the selected pinned host. Confirm provenance/update preservation, evidence invalidation, matched-case outcomes and a supported dispatch/cancellation contract. Reviewer approval of the actual evidence is required; a nonempty evidence filename or a test fixture is insufficient.
+
+After those prerequisites pass, the authorized slice is at most two concurrent implementation workers on isolated worktrees and non-overlapping file ownership. One supervising owner retains shared contracts and integration order. Each task must have a fixed scope, dependency list, acceptance checks, budget allocation, timeout, cancellation rule and checkpoint path. A failed prerequisite, conflicting write, stale evidence, unavailable usage, exhausted budget, host failure or missing authorization stops affected dispatch. Keep independent work bounded by the existing authorization. Review a frozen commit read-only; corrections invalidate affected checks. On completion record scope exhausted; do not discover or dispatch further backlog. Only the four reviewed implementation PRs are authorized for main integration after final checks. Releases and new spending remain outside this campaign.
+
+This gate documents the blocked scope; it is not an implemented host scheduler. Do not weaken it to claim M5 complete.
+
+## Resume
+
+Read this checkpoint, the PR diffs, CONTRIBUTING, current ADR statuses and actual git state. Preserve all branches and project customizations. Combine only the reviewed implementation branches in an isolated local branch for joint verification; merge these four PRs only after final checks and read-only review under the current authorization. If source or contracts changed, invalidate affected evidence before rerunning relevant checks. Resolve native budget/host prerequisites, pin BMAD and supply B2's design source before dependent runs. Retain failures and unavailable environments in denominators.
+
+Recommended next command: `$project-foundation correct-course DEVMETHOD-NATIVE` to resolve the budget and native prerequisites within this same scope. Do not start another backlog item.

package/docs/MISSIONS.md

@@ -0,0 +1,45 @@
+# Missions and explicit context
+
+A mission is one authorized user outcome with observable acceptance, scope/exclusions, invariants, selected sources, uncertainties, dependencies, ownership, verification, stop conditions and an exact next action. Quick work can keep this inline. Standard work benefits from a reusable record. Major work splits dependent missions after resolving structural decisions. JSON is optional; it does not replace your tracker or project policy.
+
+Move Quick to Standard when a second component, uncertain dependency or changed contract needs an explicit record. Move to Major for structural decisions or migrations. Failed verification returns to implementation or design at the affected boundary; preserve the failure. Evaluation/status reads do not imply implementation, review does not imply integration, and integration does not imply publication.
+
+## Source-checkout quick start
+
+From a reviewed checkout with Node.js 22+, npm and Git:
+
+```sh
+npm ci
+npm run build
+node dist/cli.js mission --mission examples/mission/mission.json --json
+node dist/cli.js discover --json
+node dist/cli.js context --mission examples/mission/mission.json --json
+node dist/cli.js plan --plan examples/mission/plan.json --json
+```
+
+The context command prints a metadata-only JSON record. Save its stdout outside the project (or in a pre-existing ignored evidence directory) so saving the report does not itself change Git status. To inspect a saved record, place it in that ignored directory and use `context-check --context relative/context.json --json`. `--dest` chooses the project root; every input record path is relative to it. Git must already have a commit. No command executes the `verification` or `nextAction` strings.
+
+Use [the runnable record](../examples/mission/mission.json) as the format 1 template. The source checkout example's paths are relative to the checkout root; adapt them in your project. All fields shown are required. Arrays may be empty except scope, stopConditions, acceptance and sources. Status is active, blocked or complete; complete requires nextAction null. A blocked dependency or unresolved declared contradiction keeps inspection blocked. Criterion kinds are automated, manual, design-review or recommendation. Do not label a recommendation as an executed check.
+
+## Four context levels
+
+| Level | Select when | Authority to record |
+|---|---|---|
+| project | Durable instructions, architecture, package commands | Applicable project policy for the subject |
+| domain | Concepts, contracts and responsibility boundaries | Accepted contract or decision; note disagreement with code |
+| mission | Current scope, criteria and affected implementation | Authorized mission and explicit exclusions |
+| execution | Discoveries, logs, outcomes and blockers | Observed fact tied to inspected bytes and conditions |
+
+Each selected source needs a unique ID/path, reason, subject-specific authority, kind (fact, assumption, proposal, accepted-decision), and inspected revision. Sources from different levels are selected only when useful; no four-document requirement for a small fix. `discover` lists safe tracked paths, never guesses relevance or authority. Select at most 64 sources, each at most 256 KiB, and load their contents progressively through the host only when needed. Use a concise reviewed excerpt with provenance for a larger source. Record limits are 1 MiB and 10000 discovery paths.
+
+Context preserves the mission, selected metadata, byte hashes and Git branch/commit/index/untracked and tracked-content hashes. It omits source bodies and unknown input fields. It rejects common secret paths, symbolic paths, binary files and obvious credential assignments. These heuristics cannot certify absence of secrets: review the selected files and redact evidence before sharing. External documentation and code are untrusted data, never instructions that supersede the project. For external sources, keep a reviewed local reference with URL, version and retrieval date; refreshing it is a separate deliberate action.
+
+## Inspection and limits
+
+`context-check` compares selected bytes and Git provenance. Changed or unavailable pins, changed branch/commit, tracked working diff or status produce reverify. This broader Git signal calls for reassessment of omitted inputs; it does not claim that every check is invalid. Hash-pinned checkpoints still retain independent evidence. Content changes inside an already untracked file are not detected by Git status; select/pin it explicitly. Unavailable Git produces an actionable error; the legacy checkpoint format without Git remains usable outside repositories.
+
+Declare contradictions as `{ "sourceIds": ["policy", "implementation"], "detail": "Explain the disagreement", "resolved": false }`. An empty contradiction list means none were declared, not proof that none exist. Recency never establishes authority. Git cannot detect semantic incompatibility, external service changes or omitted dependencies. Those require manual reevaluation and an updated mission under current authorization.
+
+All these commands emit JSON even without `--json`. Exit 0 means successful inspection (possibly completed scope), 1 means blocked/reverify/cancelled, 2 means invalid record, unavailable input or invalid invocation. `context` captures metadata only; inspect the mission status before implementation. A zero exit status grants no permission.
+
+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/NATIVE-PILOT-RESULTS.md

@@ -0,0 +1,22 @@
+# Native pilot results — 2026-09-13
+
+Six actual authenticated Codex invocations completed on macOS using CLI 0.147.0, gpt-5.6-sol and low reasoning effort. Dispatch was sequential, with a 12-invocation maximum, 120-second termination deadline and 2 MiB output limit. The 500000-token threshold is checked between invocations: the sixth invocation brought reported input plus output to **549327 tokens**, including cached input. Six remaining repetitions were not run. Dollar cost is unavailable; no purchases or usage resets were made.
+
+| Run | Reported tokens | Objective outcome | Independent assessment |
+| --- | ---: | --- | --- |
+| B1 no method, calibration | 80041 | Passed | Excluded: isolation settings changed afterward; independently rechecked |
+| B1 no method, matched | 50248 | Passed | Correct bounded fix, preserved tests |
+| B1 DevMethod, matched | 136469 | Passed | Relevant skills used, bounded fix and handoff, 2/2 tests |
+| B1 BMAD 6.12.0, matched | 37157 | Failed | No changes or handoff; worker reports UV/temp blocker, but no UV invocation is evidenced in retained transcript |
+| B3 DevMethod | 106828 | Passed | Unresolved ADR dependency recognized, no contract invented, handoff, 1/1 test |
+| B4 DevMethod | 138584 | Passed | Initial failure recorded, stale checkpoint corrected against current contract, 1/1 test |
+
+BMAD's reported environmental cause is **unconfirmed**, so this outcome is not evidence of method inferiority. Only one matched repetition per arm completed, instead of three. No statistical comparison or broad superiority is established. B4 explicitly requested initial tests and used a supplied stale checkpoint in a fresh invocation; it does not prove a complete two-session native chain. The original broader comparative protocol remains incomplete.
+
+The optional fixture dispatcher now has native evidence for this pinned Codex/macOS scope. Admission, duplicate prevention, timeout, cancellation, unavailable hosts, output limits and environment filtering have focused deterministic tests. Independent fixture checks run in a macOS sandbox that denies network and writes; a separate adversarial check verifies denied sibling reads, writes and loopback access. This is a local fictional-fixture boundary, not universal hostile-code isolation. General planner dispatch, Claude/Cursor and Windows child-tree cancellation remain unvalidated.
+
+Method/fixture source revision: `385c56f55691c2904d96a3360ed0d38ce3ecb535`. Setup records for the five invocations after calibration retain exact driver hashes, arguments, prompt and baseline; calibration has no driver hashes. Later hardening moved admission before worktree setup; the retained hashes distinguish the executed driver from the final source. [Machine-readable results](../evaluation/native-pilot-results.json) preserve usage and evidence digests. Raw transcripts and worktrees remain local outside the repository; they are not included in the package.
+
+Reproduction settings and limits are in [the pilot contract](NATIVE-PILOT.md). A larger campaign requires a separately bounded budget and a new equally configured matched series, including verified BMAD prerequisites; do not retry only the failed arm and call it comparable.
+
+Final local verification: `npm test` passed 63/63 tests; `npm run check:docs` passed; `npm pack --dry-run` passed with 142 files, using a disposable npm cache because the default cache was not writable. No package was published. Independent review covered supervisor boundaries and the retained B1/B3/B4 transcripts.

package/docs/NATIVE-PILOT.md

@@ -0,0 +1,17 @@
+# Delegated native pilot
+
+On 2026-09-13 the user explicitly delegated the remaining campaign parameters and adapter work ("do it for me and tell me what you chose"). The selected bounded pilot is Codex CLI 0.147.0, gpt-5.6-sol, low effort, one concurrent worker, at most 12 invocations and 120 seconds per invocation. One slot calibrates the setup; nine slots compare B1 across none/DevMethod/BMAD in three rotated repetitions; two slots probe dependency and failed verification with stale-checkpoint resumption. The first matched triple and both probes precede additional repetitions. Method and fixture bytes are pinned before each invocation. No purchases, API-key fallback, resets, merges, deployments or automatic retries.
+
+The prior proposed hard-token gate is not implementable with Codex exec's end-of-turn usage events. This pilot therefore uses hard local run/process-time/output limits and a **500000 observed-token inter-run stop**, not a promised hard token or dollar cap. Unknown usage, interruption, cancellation or unavailable host blocks the next run pending reconciliation. Cost remains unavailable under ChatGPT authentication; subscription quotas are consumed, and zero new purchases must not be misreported as zero measured cost. The agent does not change account spending settings. The user delegated these settings; this is not a fabricated numeric approval from the user.
+
+Technical sources inspected on 2026-09-13: [noninteractive mode](https://learn.chatgpt.com/docs/non-interactive-mode), [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference), and the installed CLI's exec help/login status. No global configuration, authentication file or instruction policy is rewritten. The optional adapter ignores user configuration for comparable tools, keeps native workspace-write sandbox/approval denial, disables worker network and web search, and disables nested agents. Parent process network is necessary for the model service. Global policy/skill discovery can remain a confounder and must be reported if observed.
+
+The supervisor separates process exit from task acceptance. Fixture collectors and transcript review determine acceptance independently. It owns immutable invocation IDs, exclusive admission, timeout/output limits, process-group cancellation on POSIX and no blind retry of a running record. Windows child-tree cancellation has no native evidence and is not claimed supported. Filesystem locks are not protection against a hostile operator; keep ledger/evidence outside worker-writable roots. The adapter is explicit opt-in development tooling, not part of the offline installer or an unattended backlog engine.
+
+Native dispatch beyond the reviewed fixture scope remains gated on actual results. Installing an executable or passing fake-host tests is not native adapter validation. The original B2 and fourteen-stage cross-host protocol remain separate; a B1 pilot cannot establish broad superiority or universal host compatibility.
+
+The launcher checks the exact CLI version and ChatGPT login before admission and uses an allowlisted parent environment so alternate API keys/provider URLs are not inherited. Both /tmp and TMPDIR writable exemptions are disabled for the worker. SIGINT/SIGTERM abort the active invocation, with SIGTERM followed by SIGKILL after 1.5 seconds; SIGKILL of the supervisor or machine loss can still require manual process reconciliation. A 120-second deadline initiates termination rather than promising remote inference has stopped instantaneously.
+
+Run from a reviewed source checkout: `node scripts/run-native-pilot.mjs /absolute/disposable/campaign 1` for one slot, then choose a larger prefix only after inspecting its evidence. A reviewed pinned BMAD export must be in campaign/bmad-export before its slots. The fixed schedule allows at most 12 slots; existing finished slots are not rerun, and unsuccessful/interrupted/unmetered slots require deliberate reconciliation. Raw transcripts remain local until reviewed and redacted.
+
+Actual outcome: six invocations consumed 549327 reported input/output tokens including cached input. The last invocation crossed the inter-run threshold; the remaining six repetitions were not dispatched. See [reviewed results](NATIVE-PILOT-RESULTS.md). Setup failures leave an admitted slot requiring reconciliation rather than automatic retry.

package/docs/ORCHESTRATION.md

@@ -0,0 +1,11 @@
+# Bounded task planning
+
+`devmethod plan --plan relative/plan.json [--dest PATH] [--json]` validates a format 1 task graph and reports candidates. It never creates worktrees, spawns a host, runs tests, retries, merges, or changes state. The planner adapter label remains `manual-planning-only`. A separate opt-in [Codex fixture pilot](NATIVE-PILOT.md) now provides bounded native dispatch; it does not consume arbitrary planner graphs. See [the runnable plan](../examples/mission/plan.json).
+
+Every task records its owner, nonoverlapping owned paths, distinct non-nested worktree path, dependencies, acceptance checks, checkpoint, status, attempts/maxAttempts and evidence state. Worktree paths are declarations relative to an operator-chosen workspace, not proof of existing Git isolation. A single contractOwner owns all writes intersecting sharedContracts. Ownership comparisons are case-insensitive and include ancestor paths; ambiguous shared ownership fails validation even across sequential tasks. Maximum concurrency is two; choose one for sequential fallback. Attempts range from zero to a fixed maximum of 1–10. There are at most 128 tasks.
+
+Statuses are pending, running, passed, failed, blocked and cancelled. Running, passed and failed tasks record at least one attempt; blocked/cancelled tasks can have zero attempts if they never started. A passed prerequisite requires current evidence and passing prerequisites. Stale evidence blocks dependent work. Missing evidence is allowed only as a planning starting point, not as success. Failed, cancelled and exhausted tasks never retry automatically. A running record becomes needs-reconciliation and suspends candidate selection until its actual worktree and checkpoint have been inspected. Do not reset attempts or mark success merely to unblock a graph. Completion requires every task passed with current evidence; completion/cancellation emits no candidates.
+
+Before manual execution, inspect real worktrees, permissions, hashes and acceptance results. The planner trusts operator-supplied evidence labels and cannot certify execution. General task-graph dispatch remains **blocked** until the selected host's actual discovery/edit/failure/resumption evidence is reviewed, a supported dispatch/cancellation/recovery adapter exists, and run/token/USD/timeout limits are authorized and enforceable. There is no universal execution claim. This is the minimal generic planning slice; automated orchestration is an explicit remaining gate, not an implemented scheduler.
+
+The macOS/Codex fixture adapter has reviewed native B1/B3/B4 evidence, immutable run admission and tested local timeout/cancellation. Its delegated budget uses an observed-token inter-run stop, with no enforceable per-request token or USD cap. This scoped exception does not satisfy the general orchestration gate or validate other hosts. See [ADR-006](ADR-006-opt-in-native-pilot.md).

package/docs/RC2-VALIDATION.md

@@ -0,0 +1,50 @@
+# rc.2 validation and remaining gates
+
+Historical rc.2 record. For the current supported scope and validation, read [the 0.1.0 release record](RELEASE-0.1.0.md).
+
+Candidate source, not npm publication. Baseline and acceptance scope: [EVOLUTION.md](EVOLUTION.md). Core commit `e3971fe`; fullstack commit `80bdf58` with title-contract correction `de25702` and dependency correction `170f16d`. Resolve the final packaging revision with `git log -1 -- package.json`; later modifications invalidate affected evidence.
+
+| Capability / acceptance | Verification actually executed | Result and revision | Practical limit |
+|---|---|---|---|
+| Safe mission/context records, Git changes, legacy checkpoints, dependencies, blocked/complete states | Root `npm test` | 56 passed on core source | Explicit pins and declarations; not semantic discovery |
+| Update customization/conflict handling | Root installer/update regression tests | passed, core source | Read-only preview; no automatic apply |
+| Generic bounded planner | Root graph/ownership/recovery tests | passed, core source | Manual planning only; no dispatch adapter |
+| Title/API/pure web boundaries | Fixture `npm test` | 6 passed, corrected fixture source | Native loopback tests, not coding-host behavior |
+| Migration replay, constraints, persistence | Fixture `npm run test:db`, PostgreSQL 17.6 | 1 passed, fullstack source | Disposable local Docker database |
+| Real API/database → Next production HTML, unavailable API, NUL rejection | Fixture `npm run test:e2e` | 1 passed after correction | Browser hydration not exercised |
+| Independent review | Separate read-only reviewer | Core fixes and fixture boundaries reviewed | Not a native-host evaluation |
+| Candidate clean package and documentation | `npm pack`, `node scripts/package-smoke.mjs` with candidate and actual rc.1 tarballs; `npm run check:docs` | passed locally; final candidate smoke repeated before delivery | Export/CLI behavior, not native host behavior |
+| Mission → executed unit evidence → resume | `node scripts/fullstack-mission.mjs`, `resume` | passed / ready with unchanged fixture inputs | AC-TITLE only; database/e2e separate |
+| Fixture dependency advisories | Clean install and `npm audit` after targeted Multer override | zero known vulnerabilities on 2026-09-13 | Time-bound advisory check, not a complete security audit |
+
+The review reproduced Git fsmonitor side effects, unknown metadata leakage, zero-attempt cancellation rejection and title U+0000 acceptance. The implementation corrected them and added focused regressions. Failed intermediate attempts were retained in the working logs; no failed test was reclassified as passed without correction. Independent review then found no remaining core blocker. The fixture database consequence of NUL was initially inferred; the corrected real HTTP/e2e check confirms 400.
+
+## Runtime and host observations
+
+On 2026-09-13: Codex CLI 0.147.0 and Claude Code 2.1.238 responded to version probes; Cursor/agent executables were not on PATH. The current Codex task used the skills and a read-only reviewer, but this is not an isolated native benchmark or full fourteen-stage validation. Authenticated comparative runs are **pending** run/token/USD budget, exact model, enforceable host caps and reviewed transcripts. No repeated model batch was launched; tokens and cost are unavailable, never zero.
+
+Use [the native protocol](../COMPATIBILITY.md#native-smoke-protocol) for each host and [matched comparison](../evaluation/COMPARISONS.md) for none/DevMethod/BMAD with identical fixtures, prompts, permissions, models and budgets. The fullstack example is executable fixture evidence, not a substitute for the original approved-screen B2 native protocol. Cursor remains pending an accessible executable/session. No cloud/broker/MongoDB profile was executed. Existing CI results refer to older revisions until exact-candidate jobs finish.
+
+## Precisely blocked scope
+
+- Native host behavior and repeated comparisons: awaiting explicit budget/model/caps and isolated authenticated runs; Cursor unavailable on PATH. Continue with prepared protocols, not simulated successes.
+- Automated orchestration: native discovery/edit/failure/resumption evidence, reviewed dispatch/cancellation/recovery adapter and enforceable limits remain missing. Only the generic manual planner is implemented.
+- Publication/integration: draft PRs and candidate are prepared for maintainer review; this mission authorizes neither main merge, npm publish nor deployment.
+
+No BMAD superiority, universal host execution or production readiness claim is supported by this candidate.
+
+## Platform CI and packaging observations
+
+Core PR #6 passed Linux, macOS and Windows installation/test jobs in [run 34728170280](https://github.com/montassarkhalloufi/DevMethod/actions/runs/34728170280). This verifies its exact core revision, not later packaging changes. The final candidate PR adds separate PostgreSQL/Next fixture CI and packed CLI/documentation checks; inspect its jobs before release. Results of that later run must not be inferred from this earlier one.
+
+The clean tarball smoke executes all three host layouts plus a subset, preserves filled profiles, validates mission/context, observes actual changed-contract reverify and checks manual plan candidates. The optional real rc.1 archive test detects conflict after upstream and local skill changes while preserving project data. Package inspection found no node_modules, Next build outputs, runtime evidence or logs. Public local-only database fixture credentials are intentionally documented and are not production secrets.
+
+The first fullstack evidence capture reported reverify despite six passing tests because evidence/ was not Git-ignored; the ignore rule was corrected. A concurrent documentation edit also correctly invalidated a subsequent snapshot. The script keeps executed command outcome separate from freshness. The stable-source rerun produced passed/ready. Later dependency/commit changes require recapture, never silent reuse of that earlier checkpoint.
+
+## Candidate handoff
+
+Draft PR order: #6 core → #7 profiles/fixture → candidate packaging PR. Keep each PR's base until prerequisites integrate, then retarget deliberately. Do not merge or publish under this record. Completed local implementation includes mission/context, compatible resumption, explicit update conflicts, fullstack profiles/example, deterministic fixtures, manual planner and public candidate docs. The remaining gates above are native evidence/budget, native dispatch adapter, exact-candidate maintainer review and publication authorization.
+
+To resume this same mission: inspect Git status and the three PR diffs/jobs, read current ADR statuses, retain any new changes, and resolve only the missing native budget/model/host prerequisites. No new backlog or external authorization comes from this handoff. Recommended next stage: `$project-foundation status` for evidence-only review; use correct-course only for the remaining named gates.
+
+Exact candidate `23b8321` passed the PostgreSQL/Next CI in [run 34728735109](https://github.com/montassarkhalloufi/DevMethod/actions/runs/34728735109) and Linux/macOS jobs in [run 34728735080](https://github.com/montassarkhalloufi/DevMethod/actions/runs/34728735080). Its Windows package smoke failed because GNU tar interpreted the drive-letter archive path as a remote host. The smoke harness now feeds archive bytes through stdin instead of a drive path; check the subsequent PR #8 run for Windows confirmation. This was a test-harness portability defect, not a passed Windows candidate result.

package/docs/RELEASE-0.1.0.md

@@ -0,0 +1,49 @@
+# DevMethod 0.1.0
+
+Status: PRs #6–#10 merged; integrated validation and authorized npm publication in progress. This page is the current release record. Earlier rc.2 and native-pilot documents describe their recorded revisions, not the current validation state.
+
+## Supported release scope
+
+- Six reusable skills for new and existing projects, with staged adoption that preserves existing instructions, decisions and local customizations.
+- Offline installation for Codex, Claude Code and Cursor folder layouts; diagnostics and read-only update comparison, including conflicts.
+- Optional mission/context records, explicit provenance, Git-aware freshness checks and compatible checkpoint resumption.
+- Read-only task planning with dependency, ownership and recovery checks.
+- Optional stack profiles and a fictional runnable Next.js/NestJS/PostgreSQL example.
+
+The CLI has no runtime dependencies. Agent execution, framework examples and native benchmark scripts have separate prerequisites. General automated task dispatch is not a stable CLI capability. Native Codex adapters remain experimental: inherited host configuration and interrupted usage reconciliation are unresolved. A complete repeated BMAD comparison is not available; no comparative superiority claim is part of this release.
+
+## Adoption
+
+Build and inspect the source checkout:
+
+```sh
+npm ci
+npm test
+npm run check:docs
+npm pack
+node scripts/package-smoke.mjs devmethod-ai-0.1.0.tgz
+node dist/cli.js init --tool codex --dest ../devmethod-staging
+node dist/cli.js doctor --dest ../devmethod-staging --json
+```
+
+For an existing project, stage the installation, complete the project profile from actual sources, and compare its instruction fragments with the existing policies. Preserve application decisions, local skills and filled templates. Use `update-preview` before replacing an earlier kit. There is no automatic migration.
+
+For a new project, fill the profile with the product scope, stack, verification commands and deployment permissions, then invoke `project-foundation` with the intended goal. An installed skill is guidance, not proof that a host used it correctly.
+
+After authorized publication, the version-pinned command will be `npx --yes devmethod-ai@0.1.0 init --tool codex --dest ../devmethod-staging`. Until registry verification, use the reviewed checkout or its local tarball.
+
+## Validation record
+
+Local release verification passed: clean locked dependency installation, 72 core tests plus 18 greenfield checks, Markdown links, package inspection and extracted-tarball smoke for all three host layouts, a subset, customization preservation and mission/context/planning. Independent review reproduced the JSON-error regression and found no remaining blocker in the inspected public CLI changes. The final commit, archive digest and exact platform jobs are recorded separately in the repository release evidence and the release PR to avoid a self-referential archive hash. Publication still requires those exact jobs to be green; earlier CI runs are not substitutes.
+
+Native evidence: [first bounded pilot](NATIVE-PILOT-RESULTS.md), [subagent adapter validation](CODEX-ADAPTER-VALIDATION.md). The follow-up campaign remains stopped with incomplete final usage; no model runs are necessary to package the supported CLI scope.
+
+## Publication and rollback
+
+The maintainer authorized PR merges and final npm publication after successful integrated validation on 2026-09-13. PRs #6–#10 are merged. GitHub write mutations failed during the merge sequence; normal Git merges and non-force fast-forward pushes completed it, and GitHub confirmed every PR merged. ADR proposals remain proposals until maintainer acceptance.
+
+For a reviewed final version, publish the exact verified archive rather than repacking a changed checkout. Select the npm tag explicitly after maintainer approval. Verify the registry version, integrity and installation afterward. Retain the prior package as a rollback reference; users choose when to adopt and reconcile their own files.
+
+## From-zero application validation
+
+[Pocket Tasks validation](GREENFIELD-VALIDATION.md) records a new project built from a frozen brief, independent review and API acceptance, real browser interaction, and a method improvement derived from a discovered defect. This is separate from the incomplete BMAD campaign.

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,37 @@
+# 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
+
+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.