devmethod-ai 0.3.1 → 0.4.1

package/dist/cli.js

@@ -32,7 +32,9 @@ Non-interactive init calls require --tool. Destination defaults to the current d
 All six modules are included by default; project-foundation is always included.
 Existing divergent files block installation; there is no overwrite option.
 The installer is offline. npx may download the package before it runs.
-Workflow stages are skill arguments: project-foundation explore|frame|design|architecture|plan.
+After installation, select devmethod-review (or any documented devmethod-<stage>)
+in your agent. No npx is needed to run a workflow. Full installs expose 14 stages;
+subsets expose commands backed by installed modules. project-foundation <stage> still works.
 Use the host-native skill syntax; these are not executable CLI subcommands.
 The JSON plan inspector is read-only. Markdown PLAN/tickets and legacy missions
 are agent-readable guidance; init never creates or migrates mission records.

package/dist/commands.js

@@ -0,0 +1,20 @@
+/** Native stage entry points; module selection remains the six-module contract. */
+export const stageOwners = {
+    'devmethod-explore': 'project-foundation',
+    'devmethod-frame': 'project-foundation',
+    'devmethod-design': 'design-to-code',
+    'devmethod-architecture': 'decision-architecture',
+    'devmethod-plan': 'scoped-delivery',
+    'devmethod-ready': 'scoped-delivery',
+    'devmethod-implement': 'scoped-delivery',
+    'devmethod-review': 'scoped-delivery',
+    'devmethod-verify': 'scoped-delivery',
+    'devmethod-integrate': 'scoped-delivery',
+    'devmethod-correct-course': 'project-foundation',
+    'devmethod-next': 'scoped-delivery',
+    'devmethod-status': 'project-foundation',
+    'devmethod-handoff': 'scoped-delivery',
+};
+export function commandSkills(selected) {
+    return Object.entries(stageOwners).filter(([, owner]) => selected.includes('project-foundation') && selected.includes(owner)).map(([name]) => name);
+}

package/dist/doctor.js

@@ -2,6 +2,8 @@ import * as fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { tools, modules, templates } from './init.js';
+import { commandSkills } from './commands.js';
+import { isReviewRuntimePath } from './review-runtime.js';
 import { parseJson, checkPath, stat } from './filesystem.js';
 function object(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
@@ -15,6 +17,7 @@ export function validateManifest(value) {
         !object(value.files))
         throw new Error('Expected a DevMethod format 2 manifest with a supported host and unique modules including project-foundation.');
     const root = tools[value.tool];
+    const supportedSkills = [...value.skills, ...commandSkills(value.skills)];
     const required = [...templates, 'DEVMETHOD-LICENSE', ...value.skills.map(name => `${root}/${name}/SKILL.md`)];
     for (const name of required) {
         if (!Object.hasOwn(value.files, name))
@@ -25,9 +28,10 @@ export function validateManifest(value) {
         const parts = name.split('/');
         const safe = parts.every(part => /^[a-zA-Z0-9._-]+$/.test(part) && part !== '.' && part !== '..');
         const rootFile = templates.includes(name) || name === 'DEVMETHOD-LICENSE';
-        const skillFile = parts.slice(0, 2).join('/') === root && value.skills.includes(parts[2]) &&
+        const skillFile = parts.slice(0, 2).join('/') === root && supportedSkills.includes(parts[2]) &&
             ((parts.length === 4 && parts[3] === 'SKILL.md') ||
-                (parts.length >= 5 && ['assets', 'references'].includes(parts[3] ?? '') && name.endsWith('.md')));
+                (parts.length >= 5 && ['assets', 'references'].includes(parts[3] ?? '') && name.endsWith('.md')) ||
+                isReviewRuntimePath(parts));
         if (!safe || (!rootFile && !skillFile))
             throw new Error(`Manifest contains an unsupported path: ${name}`);
         if (typeof hash !== 'string' || !/^[a-f0-9]{64}$/i.test(hash))
@@ -93,7 +97,7 @@ export function diagnose(destination) {
             add('error', 'file-unreadable', error instanceof Error ? error.message : String(error), relative);
         }
     }
-    for (const name of manifest.skills) {
+    for (const name of [...manifest.skills, ...commandSkills(manifest.skills)]) {
         for (const root of Object.values(tools)) {
             if (root === tools[manifest.tool])
                 continue;

package/dist/init.js

@@ -2,6 +2,8 @@ import * as fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { commandSkills } from './commands.js';
+import { reviewRuntimeFiles } from './review-runtime.js';
 import { parseJson, checkPath, stat } from './filesystem.js';
 export const tools = { codex: '.agents/skills', claude: '.claude/skills', cursor: '.cursor/skills' };
 export const modules = ['project-foundation', 'decision-architecture', 'design-to-code', 'react-feature-engineering', 'reliable-ai-integration', 'scoped-delivery'];
@@ -35,7 +37,7 @@ export function initialize(options) {
         throw new Error('Install outside the distribution directory');
     if (stat(destination) && !stat(destination)?.isDirectory())
         throw new Error('Destination must be a directory');
-    for (const name of selected) {
+    for (const name of [...selected, ...commandSkills(selected)]) {
         for (const otherRoot of Object.values(tools)) {
             if (otherRoot !== tools[options.tool] && stat(path.join(destination, otherRoot, name)))
                 throw new Error(`Duplicate skill in another host directory: ${otherRoot}/${name}`);
@@ -104,7 +106,7 @@ export function initialize(options) {
 /** The exact host-profiled payload shipped with this CLI. */
 export function bundledFiles(tool, selected) {
     const files = new Map();
-    for (const name of selected) {
+    for (const name of [...selected, ...commandSkills(selected)]) {
         const source = path.join(packageRoot, '.agents/skills', name);
         checkPath(source);
         for (const relative of walk(source)) {
@@ -113,6 +115,18 @@ export function bundledFiles(tool, selected) {
             files.set(`${tools[tool]}/${name}/${relative}`, profile(fs.readFileSync(path.join(source, relative)), tool));
         }
     }
+    if (selected.includes('scoped-delivery')) {
+        for (const name of reviewRuntimeFiles) {
+            const compiled = name.endsWith('.mjs') ? name.replace(/\.mjs$/, '.js') : name;
+            const source = path.join(packageRoot, 'dist', compiled);
+            checkPath(source);
+            let data = fs.readFileSync(source);
+            // Explicit .mjs modules work inside CommonJS, ESM and package-less projects.
+            if (name.endsWith('.mjs'))
+                data = Buffer.from(data.toString().replace(/(from ['"]\.\/[^'"]+)\.js(['"])/g, '$1.mjs$2'));
+            files.set(`${tools[tool]}/scoped-delivery/scripts/${name}`, data);
+        }
+    }
     for (const template of templates)
         files.set(template, profile(fs.readFileSync(path.join(packageRoot, '.agents/skills/project-foundation/assets', template)), tool));
     files.set('DEVMETHOD-LICENSE', fs.readFileSync(path.join(packageRoot, 'LICENSE')));

package/dist/review-agent.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { prepareReview } from './review-cli.js';
+import { openReview } from './review-open.js';
+// Installed with scoped-delivery. The agent supplies its real review record;
+// no demo mode, package download or repository command is available here.
+try {
+    const { values, positionals } = parseArgs({ options: {
+            dest: { type: 'string' }, review: { type: 'string' },
+            output: { type: 'string' }, markdown: { type: 'string' }, open: { type: 'boolean' },
+        }, allowPositionals: false });
+    if (positionals.length || !values.review || !values.output || !values.markdown) {
+        throw new Error('Expected --review REAL_JSON --output FRESH_HTML --markdown FRESH_MD [--dest PROJECT] [--open].');
+    }
+    const result = prepareReview({ destination: values.dest ?? process.cwd(), review: values.review,
+        output: values.output, markdown: values.markdown });
+    console.log(JSON.stringify(result, null, 2));
+    if (values.open)
+        openReview(result.outputs[0]);
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+}

package/dist/review-runtime.js

@@ -0,0 +1,9 @@
+/** Exact installed runtime allowlist; never permit arbitrary scripts in manifests. */
+export const reviewRuntimeFiles = [
+    'review-agent.mjs', 'review-cli.mjs', 'review-open.mjs', 'review-model.mjs',
+    'review.mjs', 'records.mjs', 'filesystem.mjs', 'review-browser.js', 'review-ui.css',
+];
+export function isReviewRuntimePath(parts) {
+    return parts.length === 5 && parts[2] === 'scoped-delivery' && parts[3] === 'scripts' &&
+        reviewRuntimeFiles.some(name => name === parts[4]);
+}

package/docs/ADR-009-visible-workflow-commands.md

@@ -0,0 +1,11 @@
+# ADR 009: Discoverable workflow commands
+
+Status: accepted for implementation under the user's explicit request, 2026-09-13.
+
+The user requested that documented workflow commands, especially review, be exposed and execute in the agent without npx. Keeping only stage arguments meets neither discoverability nor the selected interaction. Registering bare review/plan commands could collide with host commands. Expose fourteen namespaced devmethod-* skills as short adapters to the existing stage contract and procedure modules. Preserve project-foundation invocations and the six-module selection contract. This amends ADR 001's entry-point restriction without changing its filesystem or permission boundaries.
+
+A full installation ships all entry points; subsets include only entries backed by selected procedures. Manifest file hashes include adapters, while skills continues to identify selected procedure modules. Validation permits only the known applicable adapter paths and continues to accept old manifests without them. Initialization checks cross-host duplicates and preflights conflicts before writing. Update preview reports additions without overwriting existing installations.
+
+The agent performs a review with installed instructions and resources; the optional presentation CLI does not perform checks. Install the structured format reference to remove the former dependence on package documentation. This release does not change the design workflow, browser UI, mission schemas or permission model.
+
+Revisit if native-host testing shows ambiguous automatic routing, discovery limits or real demand for a different grouping. More commands do not establish superiority over another method. Automated packaging/integrity tests and manual instruction inspection are not native model execution evidence.

package/docs/ADR-010-installed-review-renderer.md

@@ -0,0 +1,9 @@
+# ADR 010: Complete review delivery with an installed renderer
+
+Status: accepted under the user's request to fix review generation/opening and update GitHub/npm documentation, 2026-09-13.
+
+The previous adapter stopped at findings when the separate CLI was unavailable. Install a narrow report entry point and its existing renderer dependencies with scoped-delivery. This directly completes the requested interaction using the accepted offline HTML design. Asking the user to launch npx is no longer the primary workflow. A runtime download on every review would retain a network dependency; duplicating the rendering implementation would create competing behavior. Instead derive installed modules from the same compiled sources and preserve exact browser bytes.
+
+Use explicit .mjs module filenames to work regardless of the adopting project's package type. The manifest permits only the enumerated runtime files in scoped-delivery/scripts, never arbitrary scripts. Installation preflight, hashes and update preview apply to these files. The helper accepts a real result JSON and fresh HTML/Markdown paths, optionally opening through the existing fixed OS adapter. It performs no review itself and has no demo mode. The agent owns inspection and evidence before calling it.
+
+Keep quick reviews light and respect explicit report-only/headless requests. When opening is requested, execute generation and local opening under that authorization. Preserve files on opening failure and report the precise limit. Revisit only for demonstrated runtime portability problems or an actual need for live reports; no server, unrelated design change or extra command is introduced.

package/docs/COMMANDS-VALIDATION.md

@@ -0,0 +1,13 @@
+# Command validation
+
+Candidate: 0.4.0, based on main 18e003f. Date: 2026-09-13.
+
+Local checks on the candidate worktree: `npm ci --ignore-scripts`, `npm test` (95 passed), `npm run test:greenfield` (24 passed), `npm run check:docs`, skill-creator quick validation (14 adapters), `npm pack --dry-run`, and packed smoke tests passed. HTTP fixture tests required permission to bind localhost outside the filesystem/network sandbox; no assertion was bypassed.
+
+Packed smoke used the actual npm 0.3.1 archive as its migration baseline. Full Codex/Claude/Cursor installations include all 14 adapters and the review format reference; hashes, subset installation, read-only diagnostics and local-customization conflicts passed. The legacy profile and customized foundation bytes remained intact. The public CLI still presents results rather than performing review.
+
+Release CI and registry results are attached to the corresponding PR/GitHub release after execution. This file records local candidate evidence, not a prior assertion of remote success.
+
+Manual instruction inspection: each adapter executes its named stage using the existing contract, preserves arguments and authorization, and does not automatically run the suggested next stage. Review points to the installed procedure and format; it distinguishes actual inspection from optional CLI rendering. Existing architecture dialogue, conditional plans, exploration and design rules remain in their owners.
+
+Limits: no fresh authenticated Codex, Claude Code or Cursor invocation or menu-discovery check has been run for these adapters. File links, frontmatter and install checks alone do not establish conversational behavior. Existing comparative studies do not measure this release.

package/docs/COMMANDS.md

@@ -0,0 +1,36 @@
+# Run DevMethod in your agent
+
+Version 0.4.0 exposes every documented workflow stage as a discoverable skill. Install the skills once using the existing installer. Afterwards select a command in the agent and supply its target; no npx invocation or running DevMethod service is needed.
+
+| Workflow | Codex | Claude Code / Cursor |
+|---|---|---|
+| Explore | `$devmethod-explore` | `/devmethod-explore` |
+| Frame | `$devmethod-frame` | `/devmethod-frame` |
+| Design | `$devmethod-design` | `/devmethod-design` |
+| Architecture | `$devmethod-architecture` | `/devmethod-architecture` |
+| Plan | `$devmethod-plan` | `/devmethod-plan` |
+| Ready | `$devmethod-ready TASK-1` | `/devmethod-ready TASK-1` |
+| Implement | `$devmethod-implement TASK-1` | `/devmethod-implement TASK-1` |
+| Review | `$devmethod-review TASK-1` | `/devmethod-review TASK-1` |
+| Verify | `$devmethod-verify TASK-1` | `/devmethod-verify TASK-1` |
+| Integrate | `$devmethod-integrate TASK-1` | `/devmethod-integrate TASK-1` |
+| Correct course | `$devmethod-correct-course` | `/devmethod-correct-course` |
+| Next | `$devmethod-next` | `/devmethod-next` |
+| Status | `$devmethod-status` | `/devmethod-status` |
+| Handoff | `$devmethod-handoff` | `/devmethod-handoff` |
+
+The entry points load the existing [stage contract](../.agents/skills/project-foundation/references/operating-commands.md) and relevant procedure. They are not separate copies of the method. The old `project-foundation <stage>` syntax remains supported. No bare `/review` is registered over the host's own command.
+
+A full installation exposes all fourteen commands. Foundation-only installs expose explore, frame, correct-course and status. Design requires design-to-code; architecture requires decision-architecture; plan, ready, implement, review, verify, integrate, next and handoff require scoped-delivery. Module selection and the manifest's six module names are unchanged. Other technical modules remain available when selected.
+
+## Review actual work
+
+For example, select `$devmethod-review` and add `the current uncommitted diff against HEAD`. The agent reads actual changes and relevant contracts, executes applicable checks and reports located findings, evidence and limits. A clear ticket, PR, revision or path selection can replace that target. An ambiguous scope is clarified only when it affects the review.
+
+A review does not silently fix product code. Small reviews can stay in the conversation; substantial reviews use the existing tracker or the installed structured review format. Checks that were not run remain explicitly unverified. To inspect and view results in one request, use `$devmethod-review the current changes, then open the report`. The agent generates Markdown/HTML from its real JSON and opens the report using the installed offline renderer. It does not ask you to run npx. A small review may stay in the conversation unless a report is requested. The separate shell viewer only presents existing records and remains available for manual use; fictional demo results never replace your review.
+
+## Adopt into an existing project
+
+Install the candidate into a fresh staging directory with the same host and selected modules. Compare it with your existing installation. Copy the new `devmethod-*` folders and merge the relevant foundation/delivery resources, including scoped-delivery/scripts for offline report generation, preserving local customizations. Do not overwrite the filled project profile, instructions, mission records or a divergent skill. Keep the previous manifest until you have intentionally reconciled all adopted baseline files; never replace hashes merely to hide modifications. `update-preview` can classify changes read-only; it does not apply them.
+
+Do not run `init` over a customized installation expecting it to upgrade: conflicts block all writes. Both legacy single-file missions and PLAN/tickets missions remain readable, with no automatic migration. If the host does not discover the added skills, reload/reopen its session and inspect its configured skill directory. As a fallback ask it to read the installed `devmethod-review/SKILL.md` directly. Discovery and model behavior need host-specific verification; file installation tests alone do not prove autocomplete behavior.

package/docs/EVALUATION.md

@@ -37,3 +37,7 @@ Publish a result only with its pinned input, actual evidence and limitations. Pr
 See [the native evaluation workspace](../evaluation/README.md) for pinned B1/B3/B4/B5 fixtures, preparation, before/after file evidence, immutable acceptance checks and host evidence requirements. B2 still needs a pinned React project and approved screen. Host observations and raw transcripts remain local until explicitly approved for publication.
 
 Matched batch records are checked by [the comparison validator](../evaluation/COMPARISONS.md). This validates consistency and preserves unavailable/failure denominators; it does not execute models or prove comparative outcomes.
+
+## Evidence-backed review detection
+
+The [review detection cases](../evaluation/review-detection/README.md) add sensitive-data sinks, concurrent/partial/timeout effects, unchanged consumers/old data and a correct control. Reproduce the seeds separately from running reviews, retain original findings before oracle adjudication, and report detected/missed defects and false positives. Fixture tests and report schema checks do not demonstrate model detection; no new model performance claim is made without observed runs.

package/docs/RELEASE-0.4.0.md

@@ -0,0 +1,15 @@
+# DevMethod 0.4.0
+
+## Direct workflow commands
+
+All fourteen documented stages now have discoverable devmethod-* skill entries. Select `$devmethod-review` in Codex or `/devmethod-review` in Claude Code/Cursor and add the review target. The agent inspects the work and executes relevant checks without requiring the user to launch npx. The optional CLI remains a renderer/validator for recorded review results.
+
+This additive pre-1.0 minor release preserves project-foundation invocations, the six procedure modules, approved design behavior, legacy missions and installation conflict protection. Module subsets install only entry points backed by available procedures. Manifest integrity and read-only update previews cover the added files. Review record documentation is installed with scoped-delivery.
+
+## Migration
+
+Follow [command adoption](COMMANDS.md#adopt-into-an-existing-project): stage a fresh installation and intentionally merge adapters/resources. Do not overwrite divergent skills or filled project context. No mission or instruction migration runs automatically. Old manifests remain readable by the new CLI; older CLI versions may reject manifests containing new adapter paths, so use the matching or newer CLI for diagnostics.
+
+## Verification
+
+Candidate checks and publication evidence are recorded in [command validation](COMMANDS-VALIDATION.md). Automated checks cover installation, hashes, links, module subsets, conflicts, legacy preview and the packed CLI. Manual instruction inspection is distinct from a native model run. Host autocomplete and fresh native execution remain unverified unless explicitly recorded there. No new BMAD superiority claim is made.

package/docs/RELEASE-0.4.1.md

@@ -0,0 +1,13 @@
+# DevMethod 0.4.1
+
+Fix the incomplete review-to-report flow introduced in 0.4.0. Ask `devmethod-review` to review changes and open the report: the agent performs the review, generates real JSON/Markdown/HTML results and opens the HTML itself. README and review guides now lead with this agent workflow; terminal demos are secondary.
+
+The scoped-delivery installation now includes a narrowly allowlisted offline renderer. It needs Node.js 22+ but no npm, network, global CLI or application package dependency. Explicit .mjs modules work in CommonJS, ESM and package-less projects. The existing trusted renderer and OS opening adapter are reused; the installed entry point accepts only an explicit real record and fresh report paths, with no demo mode. Invalid records and existing outputs remain protected. Opening failure retains the generated files.
+
+Adopt through a fresh staging installation and intentional merging, including scoped-delivery/scripts and the updated review instructions. Preserve customized files and old manifests; new diagnostics support older installations. The legacy shell viewer remains compatible. Product code and design behavior are unchanged.
+
+Automated verification covers all three host layouts and all three package modes, report content from a supplied fixture, schema rejection, overwrite protection, OS-opening dispatch and runtime path allowlisting. OS-opening dispatch is intercepted in tests and is not proof of a graphical browser opening. Full native agent behavior is separate from these runtime checks. Executed counts, CI and npm verification are recorded in the GitHub release.
+
+Review instructions now trace relevant sensitive data to logs/errors/API/telemetry, probe failure and recovery scenarios, inspect affected consumers and old data beyond the diff, and require concrete impact for architecture criticism. Application leak detection remains distinct from report redaction. Controls stay proportionate to risk. The existing evaluation protocol gains four review cases with five reproducible seeded defects, a correct control and explicit missed/false-positive accounting. Fixture/scorer validation is not a measured model detection improvement.
+
+A [bounded independent review](../evaluation/review-detection/observed-0.4.1/README.md) confirmed 4 of 5 expected defects with no observed false positive. The timeout scenario was mentioned as a risk but not reproduced and remains unconfirmed. One small run without a matched baseline does not establish improved general detection.

package/docs/REVIEW-GUIDE.md

@@ -2,6 +2,12 @@
 
 DevMethod 0.3 adds a review workflow and an offline browser interface. Version 0.3.1 expands the documentation and the existing narrated film with this journey. The CLI presents recorded results; it does not inspect code or run tests on your behalf.
 
+## Review and open your real results
+
+Use `$devmethod-review the current changes, then open the report` in Codex, or `/devmethod-review` with the same request in Claude Code/Cursor. The agent inspects the work and executes relevant checks, records actual findings and limits, generates JSON/Markdown/HTML, and opens the report. The renderer ships with scoped-delivery: no user-run npx command or server is needed. Browser opening failures retain the files and are reported separately from review findings. See [the complete flow](REVIEWS.md).
+
+The following terminal example is only a manual tour of fictional data, not the main workflow.
+
 ## Try the packaged example
 
 Use Node.js 22+ from a normal project directory, with a fresh output filename:

package/docs/REVIEWS.md

@@ -1,8 +1,14 @@
 # Review results, reports and browser consultation
 
-The agent's `project-foundation review` stage performs project-aware inspection under [the review workflow](../.agents/skills/scoped-delivery/references/review-workflow.md). The CLI `devmethod review` only validates and presents recorded results. It never runs repository commands, discovers evidence on disk, or performs the review itself.
+The agent's `devmethod-review` command (also `project-foundation review`) performs project-aware inspection under [the review workflow](../.agents/skills/scoped-delivery/references/review-workflow.md). The CLI `devmethod review` only validates and presents recorded results. It never runs repository commands, discovers evidence on disk, or performs the review itself.
 
-## Use the installed package
+## From review to open report
+
+After installation, invoke `$devmethod-review the current changes, then open the report` in Codex, or `/devmethod-review` with that request in Claude Code/Cursor. The agent performs the inspection and checks, writes the real result JSON, then generates Markdown and HTML and opens the report. No terminal command is required from the user. The installed scoped-delivery renderer works offline with Node.js 22+ and does not require npm or a global CLI.
+
+The agent follows [report delivery](../.agents/skills/scoped-delivery/references/review-report.md). Generation preserves earlier snapshots; failed opening preserves the files and produces an explicit limitation. A report-only request omits browser opening. Small reviews can remain in the conversation unless a report is requested.
+
+## Manual viewer and fictional demo (optional)
 
 After 0.3.0 publication, from a temporary or project directory:
 
@@ -26,27 +32,7 @@ Existing outputs are never overwritten. Choose a fresh path for a newer snapshot
 
 ## One versioned source
 
-Use existing conventions, or `docs/missions/<mission-id>/reviews/<review-id>/review.json`, with generated `REVIEW.md` and deliberately included `preuves/`. Tickets link stable finding IDs; the report and UI derive results from the JSON. Do not maintain another independent score or status table.
-
-Format 1 is validated by the same pure model in the CLI and browser. See the [complete fictional example](../examples/review/review.json) and [compiled validator](../dist/review-model.js). Unknown formats, unknown/missing fields, duplicate IDs, invalid destinations and dangling references are rejected with errors that omit source contents. Arrays are bounded to 256 items, text fields to 16,384 characters, and input to 4 MiB. Image data has a separate limit of approximately 1 MiB per PNG/JPEG.
-
-| Object | Required fields and ownership |
-|---|---|
-| Review | format, id, title, project, mission, tickets, date, scope, exclusions, revision, technologies, sources, checks, findings, evidence, limits, policy, summary |
-| revision | commit (recorded revision label), dirty (explicit uncommitted changes); no automatic Git execution |
-| technologies | name, version, detectedFrom (actual manifest/lockfile/source evidence) |
-| ticket | id, title, url (HTTPS or null; local/unpublished destinations remain unavailable) |
-| source | id, title, kind (documentation/skill/project), publisher, technology, version, url, consultedAt, access (consulted/unavailable/unverified), usage, compatibility, provenance; consulted requires a date |
-| check | id, title, domain, kind (automated/manual), status (passed/failed/not-run/blocked/out-of-scope), result, reason, evidenceIds, revision, targets; unexecuted/excluded checks need a reason |
-| finding | id, title, domain, severity (critical/major/moderate/minor), severityReason, confidence (confirmed/suspected), resolution (open/in-progress/resolved/accepted-risk), location, trigger, expected, observed, impact, reproduction, evidenceIds, correction, tradeoffs, sourceIds, ticketIds, verification, resolutionEvidenceIds, targets |
-| location | path or component description, line (positive integer or null), component (text or null); display metadata, never arbitrary file access |
-| evidence | id, title, kind (text/log/screenshot/diagram), content (text alternative or excerpt), url (HTTPS or null), image (null or explicit PNG/JPEG object) |
-| image | mime=image/png or image/jpeg, base64, alt, origin=captured/explanatory, privacyReviewed=true; only deliberately included reviewed images, not filesystem paths or remote images |
-| policy | blockingSeverities, requireAllChecks, rationale; project-owned explicit policy, no numeric risk score |
-
-A confirmed finding still needs evidence or reproduction. A resolved finding requires resolution evidence IDs; schema validation checks the references, **not the truth of execution or whether the fix really works**. Authors must retain the original evidence and supply fresh verification. Closing a panel never changes resolution. Finding counts include all resolution states and stay independent from filtered results; uncertain unresolved findings have a separate count. Failed-check counts are separate from finding counts.
-
-A blocking confirmed open finding or a failed check requires corrections. Otherwise a blocked check yields blocked; no passed checks, an unresolved suspected finding, or required unrun checks yields incomplete. Otherwise the conclusion is ready **on the verified scope**, with exclusions and limits still visible. This conclusion does not authorize integration/deployment or replace repository policy.
+The [installed review format reference](../.agents/skills/scoped-delivery/references/review-format.md) owns fields, statuses and conclusion rules. It is shipped with scoped-delivery so authoring does not require a package download. The [complete fictional example](../examples/review/review.json) and [compiled validator](../dist/review-model.js) support optional browser export. Use one result owner and derive reports from it.
 
 ## Browser journey
 

package/evaluation/review-detection/README.md

@@ -0,0 +1,30 @@
+# Review detection cases
+
+This extends the existing [workflow evaluation protocol](../../docs/EVALUATION.md) for review quality. It is not another delivery workflow. Four small cases contain five known defects and a correct control. All credentials and personal data in these fixtures are synthetic.
+
+## Cases and expected findings
+
+The evaluator-owned [oracle](oracle.json) records expected findings and their scope. The [reproduction tests](reproduce.test.mjs) demonstrate application behavior directly, before any report masking:
+
+| Case | Expected | Evidence |
+|---|---|---|
+| SENSITIVE | LEAK: token/email and provider error reach logs, telemetry and API output | Captured synthetic outputs contain the sentinel values |
+| SUBMISSION | RACE, PARTIAL, TIMEOUT: duplicate effects under interleaving, interrupted notification, or effect-before-timeout | Controlled gates and injected failures observe two effects for one key |
+| COMPATIBILITY | CONTRACT: changed response breaks existing stored data and an unchanged consumer | Missing total and NaN invoice result |
+| CONTROL | No defect under its stated trim/reject contract | Contract tests pass; adding an architecture layer is a preference, not a blocking defect |
+
+Run `node --test evaluation/review-detection/reproduce.test.mjs`. These tests deliberately assert the presence of seeded defects: a green result means the evaluation input is reproducible, not that the application is correct or a model detected anything. They are included in npm test through tests/review-detection.test.mjs.
+
+## Conduct a detection evaluation
+
+Use fresh isolated projects and the existing protocol's pinned method/host/model, equal budgets, permissions and transcript requirements. Give the reviewer only the case's fixture files, the relevant project contract and this neutral task: “Review these changes and affected interactions. Report evidence-backed defects, impact and unverified risks; do not fix code.” For COMPATIBILITY identify compatibility.mjs as changed and keep consumer.mjs available as unchanged context. For CONTROL preserve the comment's accepted contract. Do not provide oracle.json, reproduction tests, expected IDs or this case table to the reviewer. Keep the oracle outside the review workspace; editing seed files invalidates the run.
+
+Save the original findings before consulting the oracle. A separate evaluator compares scenarios, locations, evidence and impact, not keywords. Link each confirmed finding to one or more expected defect IDs only when the reproduction and impact support the match. A risk still awaiting verification is not a confirmed detection. Treat a duplicate description of the same defect as one detected defect. Classify unsupported blockers (including personal architecture/style preferences on the control) as false positives. Do not automatically call a new, unmatched finding false: investigate and mark unresolved until adjudicated; update the oracle only with independent evidence and version the change.
+
+Use [scoreDetection](score.mjs) with expected IDs, the original findings' IDs/confidence and separate evidence-based adjudications. Record per-case detected/missed IDs, false positives, unresolved and unadjudicated findings, plus elapsed time and scope. Attach the actual reviewed evidence and impact justification; booleans in a scoring input are attestations, not proof. Report the control separately (zero expected defects means recall is unavailable, not 100%). Preserve failed, interrupted and empty runs in denominators. Test calibration deliberately includes misses and a false positive to check accounting, not to claim model performance.
+
+## Evidence and limits for 0.4.1
+
+Fixture development and oracle-aware inspection establish five reproducible defects and the bounded control contract. Scorer calibration verifies that three misses and one false positive remain visible in a constructed input; duplicate matches cannot inflate detected counts. This is runtime/oracle verification, not a blind review campaign. A [single independent review run](observed-0.4.1/README.md) confirmed 4/5 expected defects with no observed false positive; the timeout case remained unverified. No improvement over 0.4.0/BMAD or general detection rate is established. Written review guidance, valid JSON, report redaction and report opening prove none of those claims.
+
+Coverage is deliberately bounded: synthetic local functions with injected collaborators; no real providers, production telemetry settings, process-kill crash recovery, database isolation or complete contract migration matrix. Add relevant cases when actual changes expose those risks; do not require this entire suite for every small project edit.

package/evaluation/review-detection/fixtures/compatibility.mjs

@@ -0,0 +1,4 @@
+// Candidate change: renamed response field without adapting stored records/consumer.
+export function orderResponse(stored) {
+  return { id: stored.id, totalCents: stored.totalCents };
+}

package/evaluation/review-detection/fixtures/consumer.mjs

@@ -0,0 +1,3 @@
+// Unchanged existing consumer. Existing rows use amountCents, too.
+export function invoiceTotal(response) { return response.amountCents / 100; }
+export const existingOrder = { id: 'order-fixture', amountCents: 1250 };

package/evaluation/review-detection/fixtures/control.mjs

@@ -0,0 +1,5 @@
+// Accepted project contract: trim text; reject non-string values. No layering mandate.
+export function normalizeLabel(value) {
+  if (typeof value !== 'string') throw new TypeError('Expected text');
+  return value.trim();
+}

package/evaluation/review-detection/fixtures/sensitive.mjs

@@ -0,0 +1,11 @@
+// Deliberately defective evaluation input. Only synthetic values are used in tests.
+export async function connectAccount(input, provider, outputs) {
+  try {
+    return await provider(input.token);
+  } catch (error) {
+    const detail = { token: input.token, email: input.email, message: error.message };
+    outputs.log(detail);
+    outputs.telemetry({ event: 'connect-failed', detail });
+    return { status: 502, body: detail };
+  }
+}

package/evaluation/review-detection/fixtures/submission.mjs

@@ -0,0 +1,8 @@
+// Deliberately defective evaluation input: completion is recorded after all effects.
+export async function submit(key, state, charge, notify) {
+  if (state.has(key)) return state.get(key);
+  const receipt = await charge(key);
+  await notify(receipt);
+  state.set(key, receipt);
+  return receipt;
+}

package/evaluation/review-detection/observed-0.4.1/README.md

@@ -0,0 +1,16 @@
+# Observed bounded review, 0.4.1 candidate
+
+Date: 2026-09-13. One independent delegated Codex agent reviewed four isolated cases using the candidate installed skills. Its supplied context contained TASK.md, the five source modules and installed method resources, not the oracle, expected defect IDs or author reproduction tests. Deliberately-defective comments were removed from the supplied cases; the control's accepted contract was retained. The exact source bytes are included and hashed. All source hashes were unchanged after review.
+
+The evaluator produced [raw findings](raw-findings.md), [executable probes](review-probes.mjs) and [captured results](probe-results.json). Run `node review-probes.mjs` from this directory to reproduce those probes. The root agent subsequently inspected the artifacts against the oracle and recorded [adjudication](adjudication.json); [score.json](score.json) is derived with scoreDetection, not a keyword matcher. The adjudicator authored the oracle; this is disclosed, not an independent human judgment.
+
+| Case | Expected confirmed defects | Detected | Missed/unconfirmed | False positives |
+|---|---:|---:|---|---:|
+| Sensitive outputs | 1 | 1 | none | 0 |
+| Submission/recovery | 3 | 2 | TIMEOUT | 0 |
+| Compatibility | 1 | 1 | none | 0 |
+| Correct control | 0 | 0 | not applicable | 0 |
+
+Observed: 4/5 expected defects confirmed (80% on this tiny set); no false positive among the four confirmed findings. Charge-success-then-timeout was named as an unknown risk but not exercised, so TIMEOUT remains missed/unconfirmed rather than credited as a confirmed detection. The correct control received no invented architectural blocker. Application sink exposure was tested before any report masking.
+
+Limits: one run, five simple known defects, no matched earlier-version or BMAD baseline, no production systems, no human blind adjudication. This demonstrates bounded actual review behavior, not a general detection rate or an improvement over another version/method. Native autocomplete, graphical report opening, process-kill recovery and real provider/database behavior are not tested. The review was explicitly given a skill path; discovery was not measured. The raw narrative/probes are retained, not a complete host transport transcript. Model identifier, metered usage/cost and elapsed time were not independently captured and remain unavailable. Reviewer Node version was v23.10.0.

package/evaluation/review-detection/observed-0.4.1/TASK.md

@@ -0,0 +1 @@
+Review each case independently, without changing code. All files in case-a and case-b are the proposed implementation. In case-c, only compatibility.mjs changed; consumer.mjs is existing context. In case-d, control.mjs is the proposed implementation and its comment states the accepted contract. Report evidence-backed defects, impact and unverified risks. No report opening or product fixes are requested. Use only this directory and its installed skills. Do not inspect other temporary folders or repositories.

package/evaluation/review-detection/observed-0.4.1/adjudication.json

@@ -0,0 +1,65 @@
+{
+  "expected": [
+    "LEAK",
+    "RACE",
+    "PARTIAL",
+    "TIMEOUT",
+    "CONTRACT"
+  ],
+  "findings": [
+    {
+      "id": "DET-A-001",
+      "confidence": "confirmed"
+    },
+    {
+      "id": "DET-B-001",
+      "confidence": "confirmed"
+    },
+    {
+      "id": "DET-B-002",
+      "confidence": "confirmed"
+    },
+    {
+      "id": "DET-C-001",
+      "confidence": "confirmed"
+    }
+  ],
+  "adjudications": [
+    {
+      "findingId": "DET-A-001",
+      "verdict": "matched",
+      "defectIds": [
+        "LEAK"
+      ],
+      "evidenceReviewed": true,
+      "impactJustified": true
+    },
+    {
+      "findingId": "DET-B-001",
+      "verdict": "matched",
+      "defectIds": [
+        "RACE"
+      ],
+      "evidenceReviewed": true,
+      "impactJustified": true
+    },
+    {
+      "findingId": "DET-B-002",
+      "verdict": "matched",
+      "defectIds": [
+        "PARTIAL"
+      ],
+      "evidenceReviewed": true,
+      "impactJustified": true
+    },
+    {
+      "findingId": "DET-C-001",
+      "verdict": "matched",
+      "defectIds": [
+        "CONTRACT"
+      ],
+      "evidenceReviewed": true,
+      "impactJustified": true
+    }
+  ]
+}

package/evaluation/review-detection/observed-0.4.1/case-a/sensitive.mjs

@@ -0,0 +1,10 @@
+export async function connectAccount(input, provider, outputs) {
+  try {
+    return await provider(input.token);
+  } catch (error) {
+    const detail = { token: input.token, email: input.email, message: error.message };
+    outputs.log(detail);
+    outputs.telemetry({ event: 'connect-failed', detail });
+    return { status: 502, body: detail };
+  }
+}

package/evaluation/review-detection/observed-0.4.1/case-b/submission.mjs

@@ -0,0 +1,7 @@
+export async function submit(key, state, charge, notify) {
+  if (state.has(key)) return state.get(key);
+  const receipt = await charge(key);
+  await notify(receipt);
+  state.set(key, receipt);
+  return receipt;
+}

package/evaluation/review-detection/observed-0.4.1/case-c/compatibility.mjs

@@ -0,0 +1,3 @@
+export function orderResponse(stored) {
+  return { id: stored.id, totalCents: stored.totalCents };
+}

package/evaluation/review-detection/observed-0.4.1/case-c/consumer.mjs

@@ -0,0 +1,2 @@
+export function invoiceTotal(response) { return response.amountCents / 100; }
+export const existingOrder = { id: 'order-fixture', amountCents: 1250 };

package/evaluation/review-detection/observed-0.4.1/case-d/control.mjs

@@ -0,0 +1,5 @@
+// Accepted project contract: trim text; reject non-string values. No layering mandate.
+export function normalizeLabel(value) {
+  if (typeof value !== 'string') throw new TypeError('Expected text');
+  return value.trim();
+}

package/evaluation/review-detection/observed-0.4.1/input-hashes.json

@@ -0,0 +1,7 @@
+{
+  "case-d/control.mjs": "4e853b97ef8ca8976417d415c73954cf8d28d287fe933045fb4d4be787d2e607",
+  "case-c/compatibility.mjs": "b5ddd4fae3cae50b273c44311a2d238018def2f13019bc46f9098832d48ed08f",
+  "case-c/consumer.mjs": "fdd545577dcdd27331ed7cad4705ebdc916b59a429f46f1050e67d6fde4266ed",
+  "case-b/submission.mjs": "bae2ae0aee50ae04bd12ba7296b7f9ec86119a48dfd5b2ade1b7aa486ba6eb98",
+  "case-a/sensitive.mjs": "436f69d20aff30205560910622d0bfeac66de54aac6f4c2b519ccc69ed4a0420"
+}