devmethod-ai 0.1.0-rc.2 → 0.2.0

package/examples/fullstack/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "devmethod-fullstack-fixture",
+  "private": true,
+  "version": "0.1.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build:api": "tsc -p api/tsconfig.json",
+    "build:web": "next build web --webpack",
+    "build": "npm run build:api && npm run build:web",
+    "test": "npm run build:api && node --test tests/unit.test.cjs tests/http.test.cjs tests/web-model.test.cjs",
+    "test:db": "npm run build:api && node --test tests/postgres.test.cjs",
+    "db:migrate": "npm run build:api && node build/infrastructure/migrate.js",
+    "start:api": "node build/main.js",
+    "dev:web": "next dev web -p 3100 --hostname 127.0.0.1",
+    "start:web": "next start web -p 3100 --hostname 127.0.0.1",
+    "test:e2e": "npm run build && node --test tests/e2e.test.cjs"
+  },
+  "dependencies": {
+    "@nestjs/common": "12.0.1",
+    "@nestjs/core": "12.0.1",
+    "@nestjs/platform-express": "12.0.1",
+    "drizzle-orm": "0.45.2",
+    "next": "16.3.5",
+    "pg": "8.23.0",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "server-only": "0.0.1"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "22.20.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.2.3",
+    "@types/pg": "8.16.0"
+  },
+  "overrides": {
+    "@nestjs/platform-express": {
+      "multer": "2.3.0"
+    }
+  }
+}

package/examples/fullstack/tests/e2e.test.cjs

@@ -0,0 +1,54 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { spawn } = require('node:child_process');
+const { once } = require('node:events');
+const { Pool } = require('pg');
+const { createApp } = require('../build/http');
+const { PostgresTasks } = require('../build/infrastructure/postgres');
+const { migrateDatabase } = require('../build/infrastructure/migrate');
+if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL is required; use an isolated fixture database.');
+test('Next production HTML renders a task created through Nest and PostgreSQL', { timeout: 30000 }, async (t) => {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+  let app;
+  let task;
+  let web;
+  t.after(async () => {
+    if (web && web.exitCode === null) { const exited = once(web, 'exit'); web.kill('SIGTERM'); await exited; }
+    if (app) await app.close();
+    if (task) await pool.query('delete from tasks where id=$1', [task.id]);
+    await pool.end();
+  });
+  await migrateDatabase(pool);
+  app = await createApp(new PostgresTasks(pool));
+  await app.listen(0, '127.0.0.1');
+  const api = await app.getUrl();
+  const rejected = await fetch(`${api}/tasks`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ title: 'before\u0000after' }) });
+  assert.equal(rejected.status, 400);
+  const created = await fetch(`${api}/tasks`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ title: 'Verify the full stack' }) });
+  assert.equal(created.status, 201);
+  task = await created.json();
+  web = spawn(process.execPath, [require.resolve('next/dist/bin/next'), 'start', 'web', '--port', '0', '--hostname', '127.0.0.1'], {
+    cwd: require('node:path').resolve(__dirname, '..'),
+    env: { ...process.env, TASKS_API_URL: api, NEXT_TELEMETRY_DISABLED: '1' }, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const url = await new Promise((resolve, reject) => {
+    let output = '';
+    const timer = setTimeout(() => reject(new Error('Next did not become ready.')), 15000);
+    web.once('error', (error) => { clearTimeout(timer); reject(error); });
+    web.once('exit', (code) => { clearTimeout(timer); reject(new Error(`Next exited before readiness: ${code}`)); });
+    const read = (chunk) => {
+      output += chunk.toString();
+      const match = output.match(/http:\/\/127\.0\.0\.1:\d+/);
+      if (match && /Ready in/.test(output)) { clearTimeout(timer); resolve(match[0]); }
+    };
+    web.stdout.on('data', read); web.stderr.on('data', read);
+  });
+  const page = await fetch(url);
+  assert.equal(page.status, 200);
+  const html = await page.text();
+  assert.match(html, /Verify the full stack/);
+  assert.match(html, /Filter tasks/);
+  await app.close();
+  const unavailable = await fetch(url);
+  assert.match(await unavailable.text(), /Tasks are unavailable/);
+});

package/examples/fullstack/tests/http.test.cjs

@@ -0,0 +1,33 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { createApp } = require('../build/http');
+test('Nest HTTP contract validates input and exposes created tasks', async (t) => {
+  const rows = [];
+  const app = await createApp({ list: async () => rows, insert: async (row) => { rows.push(row); return row; } });
+  await app.listen(0, '127.0.0.1');
+  t.after(() => app.close());
+  const url = await app.getUrl();
+  const post = (body) => fetch(`${url}/tasks`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+  for (const body of [{ title: '' }, { title: 42 }, { title: 'before\u0000after' }, { title: 'x'.repeat(121) }, { title: 'ok', admin: true }, []]) {
+    assert.equal((await post(body)).status, 400);
+  }
+  const multipart = new FormData();
+  multipart.set('title', 'Do not accept uploads');
+  assert.equal((await fetch(`${url}/tasks`, { method: 'POST', body: multipart })).status, 400);
+  assert.equal(rows.length, 0);
+  const response = await post({ title: '  Publish evidence  ' });
+  assert.equal(response.status, 201);
+  const task = await response.json();
+  assert.equal(task.title, 'Publish evidence');
+  const listed = await fetch(`${url}/tasks`);
+  assert.equal(listed.status, 200);
+  assert.deepEqual(await listed.json(), [task]);
+});
+test('infrastructure failure returns 500 without exposing driver secrets', async (t) => {
+  const app = await createApp({ list: async () => { throw new Error('private-db-credential'); }, insert: async () => { throw new Error('private-db-credential'); } });
+  await app.listen(0, '127.0.0.1');
+  t.after(() => app.close());
+  const response = await fetch(`${await app.getUrl()}/tasks`);
+  assert.equal(response.status, 500);
+  assert.doesNotMatch(await response.text(), /private-db-credential/);
+});

package/examples/fullstack/tests/postgres.test.cjs

@@ -0,0 +1,29 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Pool } = require('pg');
+const { randomUUID } = require('node:crypto');
+const { migrateDatabase } = require('../build/infrastructure/migrate');
+const { PostgresTasks } = require('../build/infrastructure/postgres');
+// Refuse to silently pass when a database was not configured.
+if (!process.env.DATABASE_URL) throw new Error('DATABASE_URL is required; use an isolated fixture database.');
+test('real PostgreSQL migration replay, durability and constraints', async (t) => {
+  const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+  const ids = [randomUUID(), randomUUID(), randomUUID()];
+  t.after(async () => {
+    try { await pool.query('delete from tasks where id = ANY($1::uuid[])', [ids]); }
+    catch (error) { if (error.code !== '42P01') throw error; }
+    finally { await pool.end(); }
+  });
+  await migrateDatabase(pool);
+  await migrateDatabase(pool);
+  const task = { id: ids[0], title: 'Verify persistence' };
+  await new PostgresTasks(pool).insert(task);
+  const secondPool = new Pool({ connectionString: process.env.DATABASE_URL });
+  try {
+    const result = await secondPool.query('select id, title from tasks where id = $1', [task.id]);
+    assert.deepEqual(result.rows, [task]);
+  } finally { await secondPool.end(); }
+  await assert.rejects(pool.query('insert into tasks (id,title) values ($1,$2)', [ids[1], '  ']), { code: '23514' });
+  await assert.rejects(pool.query('insert into tasks (id,title) values ($1,$2)', [ids[2], 'x'.repeat(121)]), { code: '22001' });
+  await assert.rejects(new PostgresTasks(pool).insert(task), (error) => error.cause?.code === '23505');
+});

package/examples/fullstack/tests/unit.test.cjs

@@ -0,0 +1,20 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { taskTitle, InvalidTitle } = require('../build/domain/task');
+const { Tasks } = require('../build/application/tasks');
+test('title normalization and boundaries are authoritative', () => {
+  assert.equal(taskTitle('  Review contract  '), 'Review contract');
+  assert.equal(taskTitle('x'.repeat(120)).length, 120);
+  for (const value of [null, 12, '', '   ', 'x'.repeat(121), '\u0000', 'before\u0000after']) assert.throws(() => taskTitle(value), InvalidTitle);
+});
+test('invalid input never reaches persistence and valid creation returns its durable identifier', async () => {
+  const writes = [];
+  const service = new Tasks({ list: async () => writes, insert: async (task) => { writes.push(task); return task; } });
+  assert.throws(() => service.create(' '), InvalidTitle);
+  assert.throws(() => service.create('before\u0000after'), InvalidTitle);
+  assert.equal(writes.length, 0);
+  const created = await service.create('  Read ADR  ');
+  assert.equal(created.title, 'Read ADR');
+  assert.match(created.id, /^[0-9a-f-]{36}$/);
+  assert.deepEqual(await service.list(), [created]);
+});

package/examples/fullstack/tests/web-model.test.cjs

@@ -0,0 +1,23 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { readFileSync } = require('node:fs');
+const { resolve } = require('node:path');
+const ts = require('typescript');
+const moduleObject = { exports: {} };
+const code = ts.transpileModule(readFileSync(resolve(__dirname, '../web/features/tasks/model/tasks.ts'), 'utf8'), {
+  compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+}).outputText;
+new Function('exports', 'module', code)(moduleObject.exports, moduleObject);
+const { filterTasks, parseTasks } = moduleObject.exports;
+test('filtering is normalized and does not mutate server data', () => {
+  const tasks = Object.freeze([Object.freeze({ id: '1', title: 'Review ADR' }), Object.freeze({ id: '2', title: 'Ship fixture' })]);
+  assert.deepEqual(filterTasks(tasks, '  REVIEW  '), [tasks[0]]);
+  assert.deepEqual(filterTasks(tasks, 'missing'), []);
+  assert.deepEqual(filterTasks(tasks, ''), tasks);
+});
+test('the server boundary rejects malformed data and strips unknown fields', () => {
+  for (const value of [null, {}, [{ id: 12, title: 'wrong' }], new Array(101).fill({ id: '1', title: 'x' })]) {
+    assert.throws(() => parseTasks(value), /Unexpected tasks response/);
+  }
+  assert.deepEqual(parseTasks([{ id: '1', title: 'Read ADR', secret: 'never serialize' }]), [{ id: '1', title: 'Read ADR' }]);
+});

package/examples/fullstack/web/app/layout.tsx

@@ -0,0 +1,4 @@
+import type { ReactNode } from 'react';
+export default function Layout({ children }: { children: ReactNode }) {
+  return <html lang="en"><body style={{ fontFamily: 'sans-serif', maxWidth: 720, margin: '3rem auto', padding: '1rem' }}>{children}</body></html>;
+}

package/examples/fullstack/web/app/page.tsx

@@ -0,0 +1,11 @@
+import { listTasks } from '../features/tasks/server/list-tasks';
+import { TaskList } from '../features/tasks/components/task-list';
+export const dynamic = 'force-dynamic';
+export default async function Page() {
+  try {
+    const tasks = await listTasks();
+    return <main><h1>Team tasks</h1><p>Local DevMethod fixture. Showing up to 100 tasks.</p><TaskList tasks={tasks} /></main>;
+  } catch {
+    return <main><h1>Team tasks</h1><p role="alert">Tasks are unavailable. Start the local API and database, then reload.</p></main>;
+  }
+}

package/examples/fullstack/web/features/tasks/components/task-list.tsx

@@ -0,0 +1,11 @@
+"use client";
+import { Task } from '../model/tasks';
+import { useTaskFilter } from '../hooks/use-task-filter';
+export function TaskList({ tasks }: { tasks: Task[] }) {
+  const { query, setQuery, visibleTasks } = useTaskFilter(tasks);
+  return <section aria-label="Tasks">
+    <label htmlFor="task-filter">Filter tasks</label>{' '}
+    <input id="task-filter" value={query} onChange={(event) => setQuery(event.target.value)} />
+    {visibleTasks.length ? <ul>{visibleTasks.map((task) => <li key={task.id}>{task.title}</li>)}</ul> : <p>No matching tasks.</p>}
+  </section>;
+}

package/examples/fullstack/web/features/tasks/hooks/use-task-filter.ts

@@ -0,0 +1,7 @@
+"use client";
+import { useState } from 'react';
+import { filterTasks, Task } from '../model/tasks';
+export function useTaskFilter(tasks: readonly Task[]) {
+  const [query, setQuery] = useState('');
+  return { query, setQuery, visibleTasks: filterTasks(tasks, query) };
+}

package/examples/fullstack/web/features/tasks/model/tasks.ts

@@ -0,0 +1,12 @@
+export interface Task { id: string; title: string }
+export function filterTasks(tasks: readonly Task[], query: string): Task[] {
+  const search = query.trim().toLowerCase();
+  return tasks.filter((task) => task.title.toLowerCase().includes(search));
+}
+export function parseTasks(value: unknown): Task[] {
+  if (!Array.isArray(value) || value.length > 100 || value.some((task) =>
+    !task || typeof task !== 'object' || typeof task.id !== 'string' || typeof task.title !== 'string')) {
+    throw new Error('Unexpected tasks response.');
+  }
+  return value.map(({ id, title }) => ({ id, title }));
+}

package/examples/fullstack/web/features/tasks/server/list-tasks.ts

@@ -0,0 +1,8 @@
+import 'server-only';
+import { parseTasks } from '../model/tasks';
+export async function listTasks() {
+  const base = process.env.TASKS_API_URL ?? 'http://127.0.0.1:3101';
+  const response = await fetch(new URL('/tasks', base), { cache: 'no-store', signal: AbortSignal.timeout(3000) });
+  if (!response.ok) throw new Error('Tasks API unavailable.');
+  return parseTasks(await response.json());
+}

package/examples/fullstack/web/next.config.mjs

@@ -0,0 +1,2 @@
+import { fileURLToPath } from 'node:url';
+export default { outputFileTracingRoot: fileURLToPath(new URL('..', import.meta.url)) };

package/examples/fullstack/web/tsconfig.json

@@ -0,0 +1,36 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "isolatedModules": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "allowJs": true,
+    "incremental": true
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

package/examples/mission/CONTRACT.md

@@ -0,0 +1,3 @@
+# Task title contract
+
+A title must contain 1–120 characters after trimming. Preserve the API and persistence boundaries. This fictional contract is a fixture decision, not project-wide policy.

package/examples/mission/mission.json

@@ -0,0 +1,18 @@
+{
+  "format": 1,
+  "id": "TASK-TITLE",
+  "path": "quick",
+  "outcome": "Reject empty task titles while preserving valid titles.",
+  "scope": ["Task title validation"],
+  "exclusions": ["API redesign", "Publication"],
+  "invariants": ["Preserve the existing task API"],
+  "uncertainties": [],
+  "owner": "mission-owner",
+  "status": "active",
+  "nextAction": "Inspect the title implementation and run its acceptance check.",
+  "stopConditions": ["Acceptance verified and diff reviewed", "A required contract is unresolved"],
+  "acceptance": [{"id": "AC1", "description": "Whitespace-only titles are rejected", "changes": ["examples/mission/CONTRACT.md"], "verification": "Inspect the fictional title contract; this template does not claim an executed application test.", "kind": "design-review"}],
+  "sources": [{"id": "title-contract", "path": "examples/mission/CONTRACT.md", "level": "domain", "reason": "Defines accepted title validation", "authority": "Authority for this fictional exercise's title semantics only", "kind": "accepted-decision", "revision": "working-tree; captured bytes are pinned by context"}],
+  "dependencies": [],
+  "contradictions": []
+}

package/examples/mission/plan.json

@@ -0,0 +1,11 @@
+{
+  "format": 1,
+  "status": "active",
+  "concurrency": 1,
+  "contractOwner": "supervisor",
+  "sharedContracts": ["contracts"],
+  "tasks": [
+    {"id": "api", "owner": "api-worker", "worktree": "worktrees/api", "owns": ["src/api"], "dependsOn": [], "status": "pending", "attempts": 0, "maxAttempts": 2, "checkpoint": "checkpoint.json", "evidence": "missing", "acceptance": ["API tests pass"]},
+    {"id": "web", "owner": "web-worker", "worktree": "worktrees/web", "owns": ["src/web"], "dependsOn": ["api"], "status": "pending", "attempts": 0, "maxAttempts": 2, "checkpoint": "checkpoint.json", "evidence": "missing", "acceptance": ["Web contract matches API"]}
+  ]
+}

package/examples/pocket-tasks/BRIEF.md

@@ -0,0 +1,21 @@
+# Pocket Tasks — greenfield acceptance contract
+
+Build a complete local task manager from this empty project. The owner delegates routine implementation decisions within this contract. Use the installed DevMethod skills to frame, plan, implement, verify, review and hand off. Scope is Standard. No deployment, external services, purchases or authentication.
+
+A user can add a task, edit its title, complete/reopen it, filter all/active/completed, delete it, and retain tasks across application restart. Interface: responsive light layout, labeled task input, readable list, visible empty/loading/error states, keyboard-operable buttons, clear active filter and status announcements. Render user text safely, including HTML-looking strings.
+
+Implementation constraints: Node.js >=22 built-ins, no runtime npm dependencies; ordinary HTML/CSS/browser JavaScript. Keep domain validation, durable storage, HTTP and UI responsibilities separate. Bind only 127.0.0.1. JSON file persistence is sufficient for this single-process fictional application; atomic replacement, no silent data reset if storage is malformed. No databases or cloud providers are needed for this bounded test.
+
+Export createTaskServer({dataFile}) from server.mjs, returning an unstarted Node HTTP server. A direct node server.mjs invocation starts on process.env.PORT or 4318, with process.env.DATA_FILE or data/tasks.json. npm start invokes server.mjs; npm test executes meaningful node:test checks authored with the application.
+
+HTTP contract:
+- GET /api/tasks -> 200 {tasks:[{id,title,done}]}
+- POST /api/tasks JSON {title} -> 201 {task:{id,title,done:false}}
+- PATCH /api/tasks/:id JSON {title? ,done?} -> 200 {task}; at least one supported field required
+- DELETE /api/tasks/:id -> 204; unknown ID -> 404
+- Trim title, require string length 1..120, reject invalid types; done must be boolean. Invalid input and malformed JSON -> 400, JSON error body. Invalid body container (null, array) -> 400. Request body >16KiB -> 413.
+- Unsupported routes -> 404; never serve files outside the public asset directory.
+
+AC1 CRUD and filtering usable in browser. AC2 invalid input rejected without changing state. AC3 persistence survives close/restart. AC4 no HTML injection through titles. AC5 keyboard and narrow viewport usable. AC6 automated tests and README startup/recovery instructions. AC7 DevMethod context, decisions, verification and resumable handoff reflect actual work.
+
+Do not edit BRIEF.md or installed method sources. Fill PROJECT_PROFILE.md with actual project context. Create lightweight mission/decision/verification records; no empty template-only claim counts as completion. No Git commits by implementation worker. The owner supplies a separate acceptance harness and browser checks after implementation.

package/examples/pocket-tasks/PROJECT_PROFILE.md

@@ -0,0 +1,19 @@
+# Pocket Tasks — project profile
+
+- Objective: complete the fictional local task-manager contract AC1–AC7 in BRIEF.md.
+- Phase and scope: Standard greenfield implementation; no deployment, authentication, external services, purchases or worker commits.
+- Sources and decisions: BRIEF.md and CONTRIBUTING.md supplied by owner, inspected 2026-09-13; docs/ADR-001.md records delegated implementation choice.
+- Readiness: contract complete, no unresolved dependency; pre-implementation assessment retained in docs/MISSION.md.
+- UI direction: light responsive local task workspace; no approved visual artifact supplied. Owner browser acceptance pending.
+- Canonical code: this isolated `greenfield-v1/project` repository/worktree; working tree implementation, uncommitted by instruction.
+- Stack: Node.js >=22 built-ins; npm scripts; HTML/CSS/browser JavaScript; zero dependencies and no lockfile needed.
+- Boundaries: pure validation, serialized file storage, HTTP composition, browser UI. Single process owns the chosen task JSON file.
+- Commands: `npm start`, `npm test`; PORT and DATA_FILE optional for startup.
+- Risks: invalid input must not mutate state; persistence and failure recovery; HTML-looking titles; keyboard/narrow rendering; concurrent writes in one process.
+- Data: fictional user-entered titles stored locally until deletion; no secrets used, retention/backups controlled by local operator.
+- Integrations: loopback HTTP API defined in BRIEF.md; no cloud integration.
+- Rendering: static public assets with interactive client; fixed allowlist, textContent title rendering.
+- Policy and budget: no model child runs, no remote CI, no publication or commits by implementation worker. Loopback execution authorized for checks; no financial spend.
+- Skills loaded: installed `.agents/skills/project-foundation`, `decision-architecture`, `scoped-delivery`; installer provenance and integrity in local DevMethod manifest. Other modules not relevant to this vanilla local app.
+- Assumptions: single-user/process filesystem is sufficient as explicitly permitted; revisit for multiple concurrent server processes.
+- Next independent action: owner acceptance/browser verification of PT-1; no unrelated feature backlog.

package/examples/pocket-tasks/README.md

@@ -0,0 +1,43 @@
+# Pocket Tasks
+
+A fictional, local single-user task manager built from BRIEF.md using installed DevMethod 0.1.0 skills. Add, rename, complete/reopen, filter and delete tasks. Titles are rendered as text, including HTML-looking input.
+
+## Run
+
+Requires Node.js 22 or newer and npm. There are no runtime or development npm dependencies; no install step is needed.
+
+```sh
+npm start
+```
+
+Open http://127.0.0.1:4318. The direct startup command always binds to loopback. Stop with Ctrl+C. Optional shell variables:
+
+```sh
+PORT=4320 DATA_FILE=/absolute/path/tasks.json npm start
+```
+
+The default data file is `data/tasks.json` beneath this project. It is created on the first successful mutation. Use one server process per file. No cloud service, account or authentication is involved; anyone with local access to the app can change its tasks. Do not expose it using a proxy or public bind.
+
+## Use
+
+Type a task and choose Add task. Use its checkbox to complete/reopen, Edit to change its title, Save or Cancel to finish editing (Escape also cancels), and Delete to remove it. All/Active/Completed filters affect the displayed list. Deletion is immediate. The interface supports keyboard navigation and small screens; status and error messages are announced. If a change fails over the network, use Reload tasks to reconcile saved state before retrying; the server may have already saved it.
+
+## Test
+
+```sh
+npm test
+```
+
+Node's test runner exercises domain boundaries, actual loopback HTTP CRUD, invalid and oversized input, restart persistence, concurrent writes, malformed-storage protection and static-file restrictions. HTTP tests need permission to bind ephemeral loopback ports. No remote requests are made. Browser interaction and narrow viewport checks are separate acceptance work; see `docs/VERIFICATION.md` for current evidence.
+
+## Data, backups and recovery
+
+Tasks persist as a JSON array of `{id,title,done}` records. Mutations serialize in this process, fsync a sibling temporary file, then atomically rename it over the live file. This is not a multi-process database or a universal power-loss durability guarantee.
+
+Back up the data file while the app is stopped, and keep backups private. A missing file represents a new empty collection; an unreadable, malformed, or invalid existing file causes a JSON 500 error without silently resetting or replacing it. To recover: stop the server, copy the affected file to a safe backup, inspect it and restore a known-good backup or repair the JSON/schema, ensure the file and parent directory are readable/writable, then restart. Only deliberately replace it with `[]` when loss of all current tasks is intended. Stale `.tmp` siblings from an interrupted write are not loaded; inspect and remove those only while the server is stopped. If the port is occupied, stop the other process or select a different PORT.
+
+## Boundaries and API
+
+`src/domain.mjs` validates titles and input shapes; `src/store.mjs` serializes persistence; `server.mjs` maps HTTP and explicitly allowlists three static assets; `public/` contains presentation and interaction. Exported `createTaskServer({dataFile})` returns an unstarted server for embedding/tests; callers choose their listener. Direct CLI startup binds 127.0.0.1.
+
+The canonical route/status/validation contract remains `BRIEF.md`. GET/POST `/api/tasks`, PATCH/DELETE `/api/tasks/:id`; errors use `{error:string}`. Body limit is 16 KiB. POST/PATCH require `Content-Type: application/json` (optional charset allowed); other media types receive JSON 415. Every request must use Host `127.0.0.1:<actual server port>`; other hosts receive JSON 403. Mutations reject external or null Origin and `Sec-Fetch-Site: cross-site` with JSON 403. Same-origin browser requests and CLI requests without Origin remain supported. These browser-boundary checks do not authenticate local clients. Unsupported routes/methods return 404. No authentication, deployment, external integration, telemetry or dependency updates are included.

package/examples/pocket-tasks/docs/ADR-001.md

@@ -0,0 +1,7 @@
+# ADR-001 — Local serialized JSON persistence
+
+Date: 2026-09-13. Status: implementation decision under owner delegation in BRIEF.md.
+
+Node built-ins and single-process JSON persistence are contract constraints. Domain validation is pure, a storage adapter serializes read-modify-write transactions, HTTP maps statuses, and browser code owns interaction only. Atomic sibling temporary file replacement prevents partially written live JSON. Each mutation rereads current data and validates persisted records; malformed data fails closed without overwriting it. A failed transaction does not poison subsequent operations. fsync the temporary file before rename; no claim of power-loss durability on every filesystem. No multi-process writer support.
+
+Alternative in-memory cache with delayed writes risks loss on restart; database would violate the bounded dependency scope. Revisit the storage choice for multi-user or multi-process operation. Local files contain user-entered titles, retained until deletion; backups remain the operator’s responsibility. API and mutation ambiguity: clients do not blindly retry writes after network failures, since operation may already have persisted.

package/examples/pocket-tasks/docs/HANDOFF.md

@@ -0,0 +1,16 @@
+# PT-1 — resumable handoff
+
+Archived worker record at handoff. Subsequent coordinator acceptance, browser checks and final review are recorded in [the consolidated validation](../../../docs/GREENFIELD-VALIDATION.md). “Outstanding” below describes the worker handoff, not current release status.
+
+
+Done: local app implemented; nine automated tests pass with loopback permission. Method sources and BRIEF were preserved. No commit, publication, purchase, deployment or extra worker was performed. Source hashes, actual runtime and limitations are in VERIFICATION.md; baseline commit is `0cf3474bfd777299873e51a2789829692c648130`.
+
+Dirty state: PROJECT_PROFILE.md updated; README.md, package.json, server.mjs, src/, public/, tests/ and docs/ created. Owner may be running a separate browser instance with its own data file; coordinate before restarting or changing these frozen source files. Worker never read or edited the sibling independent verification directory.
+
+Outstanding: owner independent API/browser acceptance including real keyboard, filtering, injection and narrow viewport. Independent review found missing local HTTP browser boundaries; worker corrected Host/Origin/MIME checks and added a non-mutation regression test. Evidence is in VERIFICATION.md. The coordinator owns any resulting method guidance evolution. This single fictional project cannot establish superiority over another method, universal reliability, or production readiness.
+
+Resumption: inspect actual source/hash and owner acceptance results; fix specific findings within BRIEF if any, invalidate/re-run affected evidence, then record acceptance. Work beyond this app or integration remains owned by the coordinating agent. Single-process file storage and lack of auth/deployment are explicit scope boundaries.
+
+Next command: `$project-foundation verify PT-1`.
+
+Latest correction: owner browser observation of misleading HTTP 400 feedback resolved. Client preserves input and permits immediate correction for 4xx; network/5xx retain reconciliation. Two VM-based UI regression tests added; browser confirmation belongs to the owner. Source app.js hash updated in VERIFICATION.md.

package/examples/pocket-tasks/docs/MISSION.md

@@ -0,0 +1,15 @@
+# PT-1 — Pocket Tasks
+
+## Foundation / frame / design / architecture / plan / ready — recorded before implementation
+
+Inputs: BRIEF.md, CONTRIBUTING.md, installed project-foundation, decision-architecture and scoped-delivery skills and their work-sizing, operating commands, backend boundaries, HTTP contracts, verification references. Standard scope is explicit in BRIEF.
+
+Outcome: a local single-user task manager implementing AC1–AC7. Exclusions: authentication, deployment, external services, multi-process storage, arbitrary files. The owner has delegated routine choices within the contract.
+
+Design: light responsive centered workspace, add form, three pressed-state filter buttons, task checkboxes and explicit Edit/Delete actions, inline edit form, live status and alert errors. No external fonts or assets. No approved image reference exists; this direction is an implementation choice within the brief.
+
+Plan: (1) validate task invariants and serialize atomic file transactions; (2) map HTTP contract and safe static allowlist; (3) implement accessible UI; (4) run domain/HTTP/persistence/failure tests and self-review; (5) hand off for independent acceptance and browser checks.
+
+Ready assessment: contract, constraints, permission and test strategy are sufficient. No unresolved dependency. ADR-001 records persistence boundary. Done requires real automated evidence and owner browser acceptance; implementation worker cannot claim independent acceptance.
+
+Next command at readiness: `$project-foundation implement PT-1`.

package/examples/pocket-tasks/docs/VERIFICATION.md

@@ -0,0 +1,58 @@
+# PT-1 — implementation verification
+
+Archived worker record at handoff. Subsequent coordinator acceptance, browser checks and final review are recorded in [the consolidated validation](../../../docs/GREENFIELD-VALIDATION.md). “Outstanding” below describes the worker handoff, not current release status.
+
+
+2026-09-13. Worker-authored checks; not an independent review. Inspected baseline commit `0cf3474bfd777299873e51a2789829692c648130` plus uncommitted files below. Runtime actually used: Node v23.10.0 on macOS; Node 22 was specified as minimum but not separately executed here.
+
+## Execution and correction
+
+The pre-code readiness/design/plan outputs were recorded in MISSION.md before source creation. Implementation followed the domain/store/HTTP/UI slice. Self-review found that invalid persisted titles could leak the domain's HTTP 400 error classification; changed stored-record validation to throw a storage error (500) and added an empty persisted-title fixture. No contract weakening.
+
+First `npm test`: 1 domain test passed, 5 HTTP tests could not bind because the outer sandbox denied loopback (EPERM). Second run with authorized loopback: 6/6 passed. After the stored-title correction, final `npm test` with loopback permission: 6/6 passed, 0 skipped/failed, 300 ms reported duration. No tests were disabled. The SHA utility failed due to host locale configuration; Node crypto computed the hashes below instead.
+
+## Acceptance evidence
+
+| Criterion | Worker evidence | Remaining acceptance |
+|---|---|---|
+| AC1 CRUD/filtering | HTTP CRUD/reopen/delete tests pass; client filter implementation inspected | Owner real browser actions and filters |
+| AC2 invalid input | Bad types, null/array, empty/overlong title, empty patch, malformed JSON, >16 KiB rejected; stored bytes unchanged | Independent harness |
+| AC3 restart persistence | Close/recreate server sees saved record; deletion persists; 20 concurrent creates retained | Independent restart check |
+| AC4 safe title rendering | HTML-looking string round-trip; title uses textContent, no innerHTML; CSP | Owner real browser injection check |
+| AC5 keyboard/narrow | Semantic forms/buttons/labels, checkbox labels, pressed filters, live status, responsive CSS inspected | Owner keyboard/narrow browser check |
+| AC6 tests/recovery | Six Node tests executed; README commands and explicit backup/repair instructions | Owner startup acceptance |
+| AC7 context/handoff | Filled profile, mission readiness, ADR, this evidence and HANDOFF | Owner method-path assessment |
+
+The reviewer is the implementation worker here; no independent review is claimed. Native browser evidence belongs to the owner and is not reconstructed into worker evidence. No deployment or production use was tested.
+
+## Evidence identity (SHA-256)
+
+- BRIEF.md: `574ff435d8ac66f39cad76d0318c6476afea061737b0c217599c0e401c541125`
+- server.mjs: `9791de6e7c63790ce837ed9ddd80f6f50edfc3465bc553621aaf8e529cd19ecd`
+- src/domain.mjs: `0a65f1775d4de877985730a344857e84d359d4a9259c29cd43e5e3c991b606db`
+- src/store.mjs: `abf87b665bbe34dca33dff02acdca4389d2a32063dfb55d61cbe9b6b6ae36208`
+- public/index.html: `420e4d1cf29535298196a5da2ee43603662c7189908be9fed01a1e068d4316e9`
+- public/styles.css: `a3868709460fb1cf522a56a65e8bcf132074c2fb8ed65ac5384d134bd5cde251`
+- public/app.js: `38b2ad64ac707c94856f0808db11e96f0fb86f71a8bb888c2a97f1b82423eef0`
+- tests/app.test.mjs: `c08c030b2232e2f6139f10db505e8fc089102a2cf7156a35c937cfa27aba7703`
+- package.json: `92dd7058064ae4b18c0cfcabcb7585c526e50bf1bccd5e3e706cbf302878f1e3`
+
+## Independent review correction — local browser boundary
+
+The coordinator's independent review identified a real omission: loopback binding alone did not stop cross-origin simple requests or untrusted Host values. The original version accepted JSON-shaped bodies with text/plain and had no Host/Origin validation. This finding invalidates the original HTTP-boundary sufficiency claim; it does not change BRIEF or installed skills.
+
+Correction: require the exact `127.0.0.1:<effective local port>` Host, reject duplicate Host; reject external/null Origin, duplicate Origin or Sec-Fetch-Site cross-site on POST/PATCH/DELETE; require application/json for POST/PATCH (415), preserve same-origin and Origin-free CLI clients. No authentication guarantee is claimed.
+
+Added real HTTP test verifies 24 hostile Origin/Host mutation combinations, eight unsupported-MIME writes, a hostile read, unchanged persisted bytes, a valid same-origin update with charset, and an Origin-free CLI update. Its first run failed because the raw test client omitted Content-Length for DELETE/GET bodies (socket hang-up); corrected the test transport framing, without weakening assertions. Final `npm test`: **7/7 pass**, 0 failed/skipped, 1221 ms reported duration. Current source hashes above reflect this correction. UI sources remain unchanged. Owner independent harness/browser rerun remains separate.
+
+Next command: `$project-foundation verify PT-1` for independent owner acceptance.
+
+## Browser-found validation feedback correction
+
+The owner browser check found that a whitespace title received HTTP 400 but the UI described it as an ambiguous save and requested reload. Updated the client to distinguish definitive 4xx rejection from network/5xx ambiguity. Validation now preserves add/edit input, restores an unsuccessfully toggled checkbox, focuses the editable input and permits immediate correction without reload. Network/5xx failures still offer reconciliation.
+
+Added two tests executing the real client script in Node VM with a minimal DOM substitute: validation input preservation/immediate second submission, and network/server reconciliation messaging. These check control flow, not rendered browser accessibility. Final npm test: **9/9 pass**, 0 failed/skipped, 340 ms. Owner browser recheck remains separate.
+
+- tests/ui-errors.test.mjs SHA-256: cb70e0628dfa78c33bd02b6d799bf533dfb0217cc009760d4f5ec24d63cdc70d
+
+Next command: `$project-foundation verify PT-1` (owner browser check).

package/examples/pocket-tasks/package.json

@@ -0,0 +1 @@
+{"name":"pocket-tasks-greenfield","version":"1.0.0","private":true,"type":"module","engines":{"node":">=22"},"scripts":{"start":"node server.mjs","test":"node --test"}}