carthagent 0.0.0-stage → 1.0.7

package/server.mjs

@@ -0,0 +1,341 @@
+import express from 'express';
+import { planningView } from './lib/planning-view.mjs';
+import { validatePlanning, inspectPlanning, recordPlanReview, approvePlanning, planningStatus, startImplementation } from './lib/planning.mjs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import {
+  fingerprint,
+  evidenceIdentity,
+  validatePlan,
+  planD2,
+  bindRequiredChecks,
+  pendingChecks,
+  runCommand,
+  createSerialQueue,
+  revisePlan,
+  completionIssues,
+  verificationMode
+} from './lib/delivery.mjs';
+import { captureDeliveryReview, recordDeliveryReview } from './lib/delivery-review.mjs';
+import { mergePlanPatch } from './lib/delivery.mjs';
+import { compareVersions, latestReleaseCached, packageVersion, updateCheckEnabled } from './lib/update.mjs';
+import { lockWorkspace, selectReport } from './lib/workspace.mjs';
+import { createReport, latestReport, saveReport } from './lib/reports.mjs';
+
+const root = dirname(fileURLToPath(import.meta.url));
+const cwd = resolve(process.env.CARTHAGENT_WORKSPACE || process.cwd());
+const port = Number(process.env.CARTHAGENT_PORT) || 3000;
+const token = process.env.CARTHAGENT_SERVER_TOKEN || randomBytes(24).toString('hex');
+const app = express();
+const enqueue = createSerialQueue();
+// Include queued requests: their check definitions belong to the active plan.
+let pendingRuns = 0;
+let active = latestReport(cwd);
+let currentState = active?.state || { version: 1, status: 'idle', plan: null, evidence: {}, review: '', launch: '', limitations: [] };
+
+// Resolved once at startup (the shared cache throttles fetches to ~1/day) and
+// surfaced on /api/status so the dashboard can badge an available update.
+let updateState = null;
+if (updateCheckEnabled()) {
+  latestReleaseCached().then(({ release }) => {
+    const installed = packageVersion();
+    let available = false;
+    try { available = Boolean(installed && release && compareVersions(installed, release.version) < 0); }
+    catch { /* non-semver comparison input */ }
+    updateState = { installed, latest: release?.version || installed, available, tag: release?.tag, note: release?.note };
+  }).catch(() => { /* update check is best-effort */ });
+}
+
+app.disable('x-powered-by');
+app.use((req, res, next) => {
+  res.setHeader('content-security-policy', "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'");
+  res.setHeader('referrer-policy', 'no-referrer');
+  res.setHeader('x-content-type-options', 'nosniff');
+  if (req.path.startsWith('/api/')) res.setHeader('cache-control', 'no-store');
+  next();
+});
+app.use(express.json({ limit: '1mb' }));
+app.use('/api', (req, res, next) => {
+  const supplied = req.get('x-carthagent-token') || '';
+  const expected = Buffer.from(token);
+  const received = Buffer.from(supplied);
+  if (expected.length !== received.length || !timingSafeEqual(expected, received)) return res.status(401).json({ error: 'Unauthorized' });
+  const origin = req.get('origin');
+  if (origin && !new Set([`http://127.0.0.1:${port}`, `http://localhost:${port}`]).has(origin)) return res.status(403).json({ error: 'Origin not allowed' });
+  next();
+});
+
+function refresh() {
+  if (pendingRuns) return;
+  const found = latestReport(cwd);
+  if (found) {
+    active = found;
+    currentState = found.state;
+  }
+}
+
+function persist() {
+  if (!active) active = createReport(cwd, currentState);
+  else saveReport(active.path, currentState);
+  active = { ...active, state: currentState, mtimeMs: Date.now() };
+}
+
+app.get('/api/status', (req, res) => {
+  try {
+    refresh();
+    const currentFingerprint = fingerprint(cwd, ['.']);
+    const pending = currentState.plan ? pendingChecks(currentState, currentFingerprint) : [];
+    res.json({
+      status: currentState.status,
+      runId: currentState.runId,
+      revision: currentState.revision,
+      completionIssues: currentState.plan ? completionIssues(currentState, cwd, currentFingerprint) : null,
+      plan: currentState.plan,
+      evidence: currentState.evidence || {},
+      stepStatus: currentState.stepStatus || {},
+      requirementRevisions: currentState.requirementRevisions || {},
+      reviewEvidence: currentState.reviewEvidence || null,
+      review: currentState.review || currentState.handoff?.review || '',
+      launch: currentState.launch || currentState.handoff?.launch || '',
+      limitations: currentState.limitations || currentState.handoff?.limitations || [],
+      currentFingerprint,
+      planningStatus: planningStatus(currentState, currentFingerprint),
+      planning: currentState.planning || null,
+      planningView: planningView(currentState, currentFingerprint),
+      pendingChecks: pending,
+      workspace: cwd,
+      report: active?.path || null,
+      update: updateState
+    });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  }
+});
+
+app.post('/api/plan/validate', (req, res) => {
+  try {
+    const plan = validatePlan(req.body.plan, cwd);
+    res.json({ valid: true, plan, d2: planD2(plan) });
+  } catch (error) {
+    res.status(400).json({ valid: false, error: error.message });
+  }
+});
+
+app.post('/api/plan/d2', (req, res) => {
+  try { res.json({ d2: planD2(req.body.plan) }); }
+  catch (error) { res.status(400).json({ error: error.message }); }
+});
+
+// Mutating endpoints share a cross-process lease for the entire response.
+app.use(['/api/design', '/api/plan/set', '/api/plan/revise', '/api/checks/run', '/api/review', '/api/finish'], (req, res, next) => {
+  if (req.method !== 'POST') return next();
+  let release;
+  try { release = lockWorkspace(cwd); refresh(); }
+  catch (error) { release?.(); return res.status(409).json({ error: error.message }); }
+  let done = false;
+  const finish = () => { if (!done) { done = true; release(); } };
+  // Mutations are persisted before handlers serialize their response. Release
+  // at that boundary rather than waiting for the socket's `finish` event: a
+  // client that has received the response must not race the still-held lease.
+  const json = res.json.bind(res);
+  res.json = body => { finish(); return json(body); };
+  // Do not release on socket close: a disconnected request may still run checks.
+  res.once('finish', finish);
+  res.locals.releaseWorkspace = finish;
+  next();
+});
+
+app.post('/api/plan/set', (req, res) => {
+  if (pendingRuns) return res.status(409).json({ error: 'Checks are running or queued; wait before replacing the plan' });
+  try {
+    const ongoing = currentState.plan && !['verified', 'blocked'].includes(currentState.status);
+    const required = ongoing ? currentState.plan.checks.filter(c => c.id.startsWith('required_')) : [];
+    const plan = validatePlan(bindRequiredChecks({ ...req.body.plan, verification: req.body.plan?.verification ?? 'required' }, required), cwd);
+    if (ongoing) {
+      currentState = revisePlan(currentState, plan, { cwd, hash: fingerprint(cwd, ['.']), reason: 'Active plan replaced via dashboard' });
+      persist();
+    } else {
+      currentState = {
+        version: 1,
+        runId: randomUUID(),
+        revision: (currentState.revision || 0) + 1,
+        status: 'implementing',
+        plan,
+        evidence: {},
+        stepStatus: {},
+        createdAt: new Date().toISOString()
+      };
+      active = createReport(cwd, currentState);
+      currentState = active.state;
+    }
+    selectReport(cwd, active.path);
+    res.json({ success: true, plan, d2: planD2(plan), report: active.path });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.post('/api/plan/revise', (req, res) => {
+  try {
+    if (!currentState.plan) throw Error('No active plan');
+    const required = currentState.plan.checks.filter(c => c.id.startsWith('required_'));
+    const plan = bindRequiredChecks(mergePlanPatch(currentState.plan, req.body.patch), required);
+    currentState = revisePlan(currentState, plan, { cwd, hash: fingerprint(cwd, ['.']), reason: req.body.reason });
+    persist();
+    res.json({ success: true, revision: currentState.revision, report: active.path });
+  } catch (error) { res.status(400).json({ error: error.message }); }
+});
+
+app.post('/api/plan/bind-required', (req, res) => {
+  try {
+    const plan = validatePlan(bindRequiredChecks(req.body.plan, req.body.required), cwd);
+    res.json({ success: true, plan, d2: planD2(plan) });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.post('/api/design', (req, res) => {
+  try {
+    if (!currentState.plan) throw Error('No active plan');
+    const hash = fingerprint(cwd, ['.']);
+    let result;
+    if (req.body.action === 'validate') result = validatePlanning(currentState, hash);
+    else if (req.body.action === 'inspect') result = inspectPlanning(currentState, hash);
+    else if (req.body.action === 'review') {
+      const review = req.body.review && typeof req.body.review === 'object' ? req.body.review : {};
+      for (const field of ['captureId', 'challenges', 'walkthroughs', 'findings', 'limitations', 'resolutions']) {
+        if (review[field] == null && req.body[field] !== undefined) review[field] = req.body[field];
+      }
+      if (review.captureId == null && typeof review.id === 'string' && review.id) review.captureId = review.id;
+      result = recordPlanReview(currentState, hash, review);
+    }
+    else if (req.body.action === 'approve') result = approvePlanning(currentState, hash);
+    else throw Error('Unknown design action');
+    persist();
+    res.json({ result, planningStatus: planningStatus(currentState, hash) });
+  } catch (error) { res.status(400).json({ error: error.message }); }
+});
+
+app.post('/api/checks/run', async (req, res) => {
+  refresh();
+  if (!currentState.plan?.checks?.length) return res.status(400).json({ error: 'No active plan' });
+  const checks = req.body.id === 'all' ? currentState.plan.checks : currentState.plan.checks.filter(check => check.id === req.body.id);
+  if (!checks.length) return res.status(404).json({ error: `Unknown check ID: ${req.body.id}` });
+  pendingRuns++;
+  try {
+    startImplementation(currentState, fingerprint(cwd, ['.']));
+    persist();
+    selectReport(cwd, active.path);
+    const results = await enqueue(async () => {
+      const runResults = [];
+      const priorStatus = currentState.status;
+      currentState.status = 'verifying';
+      currentState.verificationStarted = true;
+      persist();
+      for (const check of checks) {
+        const before = fingerprint(cwd, ['.']);
+        const result = await runCommand(check.argv, {
+          cwd,
+          timeoutSeconds: check.timeoutSeconds,
+          logPath: join(active.dir, `${check.id}-${randomUUID()}.log`)
+        });
+        const after = fingerprint(cwd, ['.']);
+        const evidence = {
+          passed: result.code === 0 && !result.timedOut && !result.cancelled && !result.outputLimit && before === after,
+          fingerprint: after,
+          ...evidenceIdentity(currentState, check),
+          executedRevision: currentState.revision,
+          durationMs: result.durationMs,
+          code: result.code,
+          timedOut: result.timedOut,
+          cancelled: result.cancelled,
+          outputLimit: result.outputLimit,
+          changedDuringCheck: before !== after,
+          outputTail: result.output.slice(-1200),
+          logPath: result.logPath,
+          timestamp: new Date().toISOString()
+        };
+        currentState.evidence[check.id] = evidence;
+        persist();
+        runResults.push({ id: check.id, ...evidence, output: result.output });
+      }
+      const complete = Object.values(completionIssues(currentState, cwd, fingerprint(cwd, ['.']))).every(items => items.length === 0);
+      currentState.status = priorStatus === 'verified' && complete ? 'verified' : 'implementing';
+      persist();
+      return runResults;
+    });
+    const currentFingerprint = fingerprint(cwd, ['.']);
+    res.json({ results, pendingChecks: pendingChecks(currentState, currentFingerprint), currentFingerprint });
+  } catch (error) {
+    res.status(500).json({ error: error.message });
+  } finally {
+    pendingRuns--;
+    res.locals.releaseWorkspace?.();
+  }
+});
+
+app.post('/api/review', async (req, res) => {
+  try {
+    if (!currentState.plan) throw Error('No active plan');
+    let result;
+    if (req.body.action === 'inspect') result = await captureDeliveryReview(currentState, cwd, active.dir);
+    else if (req.body.action === 'record') result = recordDeliveryReview(currentState, cwd, req.body);
+    else throw Error('Review action must be inspect or record');
+    persist();
+    res.json({ success: true, result });
+  } catch (error) { res.status(400).json({ error: error.message }); }
+  finally { res.locals.releaseWorkspace?.(); }
+});
+
+app.post('/api/finish', (req, res) => {
+  if (pendingRuns) return res.status(409).json({ error: 'Checks are running or queued; wait before finishing' });
+  try {
+    refresh();
+    const { status, review, launch, limitations } = req.body;
+    if (!['verified', 'blocked'].includes(status)) return res.status(400).json({ error: 'Status must be verified or blocked' });
+    if (!currentState.plan) return res.status(400).json({ error: 'No active plan' });
+    if (status === 'verified') {
+      const issues = completionIssues(currentState, cwd, fingerprint(cwd, ['.']));
+      if (Object.values(issues).some(items => items.length)) return res.status(400).json({ error: `Cannot verify: ${JSON.stringify(issues)}` });
+    } else if (!Array.isArray(limitations) || !limitations.length) {
+      return res.status(400).json({ error: 'Blocked status requires a reason' });
+    }
+    currentState.status = status;
+    currentState.review = review || '';
+    currentState.launch = launch || '';
+    currentState.limitations = Array.isArray(limitations) ? limitations : [];
+    currentState.handoff = { status, review: currentState.review, launch: currentState.launch, limitations: currentState.limitations, verification: verificationMode(currentState.plan), fingerprint: fingerprint(cwd, ['.']), at: new Date().toISOString(), evidence: structuredClone(currentState.evidence), reviewEvidence: currentState.reviewEvidence ? structuredClone(currentState.reviewEvidence) : null };
+    persist();
+    res.json({ success: true, state: currentState });
+  } catch (error) {
+    res.status(400).json({ error: error.message });
+  }
+});
+
+app.get('/api/docs/:name', (req, res) => {
+  const paths = {
+    readme: join(root, 'README.md'),
+    evaluation: join(root, 'docs', 'evaluation.md'),
+    delivery: join(root, 'prompts', 'delivery.md'),
+    'game-development': join(root, 'skills', 'game-development', 'SKILL.md'),
+    'software-delivery': join(root, 'skills', 'software-delivery', 'SKILL.md'),
+    'typescript-delivery': join(root, 'skills', 'typescript-delivery', 'SKILL.md')
+  };
+  const path = paths[req.params.name];
+  if (!path || !existsSync(path)) return res.status(404).json({ error: 'Document not found' });
+  res.json({ content: readFileSync(path, 'utf8'), path });
+});
+
+app.use(express.static(join(root, 'public')));
+app.use((req, res, next) => {
+  if (req.method === 'GET') return res.sendFile(join(root, 'public', 'index.html'));
+  next();
+});
+
+app.listen(port, '127.0.0.1', () => {
+  console.log(`carthagent dashboard: http://127.0.0.1:${port}/?token=${token}`);
+  console.log(`workspace: ${cwd}`);
+});

package/skills/game-development/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: game-development
+description: Build or repair games, simulations, and interactive visual applications through phased delivery. Covers engine API probes, asset completeness, frame budgets, deterministic logic tests, real input smoke tests, screenshots, and packaging. Read before implementing a Minecraft/voxel clone or other GUI game.
+---
+# Phased game delivery
+
+## First 10%: discover and de-risk
+- Inspect entry point, installed engine version/source, assets, platform, and run instructions. Preserve the user's original before a major rewrite; do not overwrite unrelated work.
+- Translate the prompt into 5–10 observable acceptance criteria. Choose a small complete scope, not a long list of half-implemented features. State ordinary assumptions and proceed; ask only if a consequential ambiguity blocks implementation.
+- Create a `delivery_plan` with source + tests + dependency files + docs in artifact roots, acceptance-to-check mappings, and a short vertical-slice sequence. Map every explicit prompt requirement to an acceptance criterion with a real check: a renderer-only contract does not verify a game whose prompt requires movement, collision, mining and saving. It emits D2. Use D2, never Mermaid, for additional flowcharts.
+- Probe uncertain methods/signatures before relying on them. An import test is not a gameplay test. In Ursina, `FirstPersonController.camera_raycast()` is not a supported API; inspect installed code and use supported raycasting or tested grid traversal.
+- In Ursina, callbacks nested inside `main()` are not automatically dispatched. Put `input`/`update` on a live `Entity` or at module scope, and use the same handlers for keyboard input and smoke checks. A correct dispatch shape is `class Runtime(Entity): def input(self, key): ...; def update(self): ...; runtime = Runtime()`.
+- Normal-window movement, mouselook, jump/gravity, and targeting need per-frame runtime behavior, not one-time camera offsets inside `input()`. Prefer the installed `FirstPersonController` for locomotion and use supported `raycast()` from its camera. Lock and read the mouse only in normal-window mode—the offscreen smoke buffer has no pointer API. For a custom controller, consume `mouse.velocity` during `update()`. Spawn at terrain eye height with a clear forward approach and an exposed block still inside interaction reach after moving, so movement is visible and the center-screen public path can then break and place. The controller initially faces positive Z: for terrain centered around zero, start near its negative-Z edge and remain inside its bounds.
+
+## Implement a vertical slice, then deepen it
+1. Window, camera, one visible surface, one actual input action, bounded automated launch. For Ursina 7, read `assets/ursina_starter.py` beside this skill: it is an executable, API-verified starting slice with real offscreen rendering. Adapt its lifecycle/capture pattern before implementing more systems; do not leave the starter as the finished game. Graphics feasibility is step zero: make the adapted slice render a nonblank frame and pass the external probe **before** writing gameplay code, and re-run the probe after renderer changes — never defer render verification to the end where repair budgets run out.
+2. Keep pure world/state/physics/persistence logic importable without constructing a window. Avoid module-level `app.run()`; use a main guard and lazy graphical imports.
+3. Finish the core loop: spawn safely, move, jump, collide, select, interact, pause/resume, recover from falling, quit. Avoid placing blocks inside the player or overlapping occupied cells; limit reach; address negative coordinates and boundary hits.
+4. Budget rendering: a world dictionary for O(1) lookup; chunk/batched geometry; remove hidden faces; rebuild only affected chunks including neighbors at boundaries. Do not create thousands of UI Buttons or colliders. Measure startup and report real counters; do not claim FPS you didn't measure.
+5. Supply all assets, generate deterministic assets, or use verified engine resources. Missing texture warnings are defects. Prefer a coherent palette, readable hierarchy, clear selection/target feedback, and a pause overlay over decorative feature sprawl.
+6. Handle data honestly: atomic saves, schema/version validation, bounded input size, corrupted-save errors without destroying existing data, deterministic seed, round-trip tests.
+
+## Last 25%: verification and repair
+- Pure tests: world invariants, seeded generation, hit/miss/reach, placement rejection, collision and jump/ceiling, persistence round-trip and malformed files, mesh face/winding/count invariants.
+- Integration smoke: instantiate the REAL app, step frames, invoke the SAME input handlers used by keyboard/mouse, assert the resulting world/UI state, close automatically, return nonzero on failure. Exercise break/place, selection, pause/resume, save/load when present and print one line beginning `GAME_SMOKE_RESULT ` followed by JSON containing the observed booleans/counters. An offscreen graphics context still needs a working graphics driver. Never implement --smoke as a separate pure-logic demonstration or draw a substitute screenshot with PIL.
+- A saved PNG's existence is NOT render evidence: smoke must sample the saved image's pixels and require several distinct colors (the starter's `assert_nonblank` is the tested pattern). A smoke that passes while the framebuffer is blank is a defect, not a probe limitation.
+- Diagnose blank frames from evidence, not excuses. A flat window-color frame with one oversized bar means the offscreen UI lens was not sized or the camera is inside/away from geometry: compare your init order with the starter, fix, re-capture. The probe reports real framebuffer dimensions and sampled color counts; "headless environment limitations" is a rationalization those numbers already disprove.
+- For Ursina, declare an additional runtime check using the bundled `scripts/verify_ursina.py` (resolve relative to this SKILL.md): `PYTHON /absolute/skill/path/scripts/verify_ursina.py minecraft.py --screenshot artifacts/probe.png`. This independently requires actual Panda3D startup and a nonblank framebuffer; it rejects fake smoke paths. It is not a full gameplay oracle.
+- Ursina 7 pitfalls confirmed by executable probes: use `color.rgb32` for 0–255 channels (`color.rgb` expects normalized floats); initialize `camera.ui_lens` film size for offscreen buffers; don't set mouse lock/visibility on a GraphicsBuffer; `Entity.material` is a reserved property, not a safe name for a Text label. Ursina mesh winding is opposite mathematical right-handed outward normals. Inspect a rendered frame, not only cross-product unit tests.
+- Capture a deterministic screenshot to `artifacts/`. If image-capable, read it and inspect terrain visibility, composition, text clipping, contrast, overlays, and blank/missing assets. Non-vision models must not claim visual inspection: record the image path and limitation. Screenshot existence is not evidence of good UX.
+- Run checks with `delivery_check`; repair the root cause, add a regression test, and rerun all stale checks after final edits. A timeout, skipped graphics check, empty test suite, or syntax-only check is not a pass.
+- Review adversarially: fresh install, default launch, alternate cwd, boundary input, unavailable assets, failure recovery, and performance. Call `delivery_finish` only with genuine evidence (or explicit blocked status).
+- Deliver: what works, exact setup/run/test commands, controls, evidence paths, and remaining limitations. Never label a prototype a complete Minecraft clone. A renderer-only verified slice with unimplemented prompt gameplay is an incomplete delivery: with budget remaining, finish the required behavior and its checks before delivery_finish.
+
+## Port this to other large software tasks
+Use the same vertical-slice/evidence approach: for web apps, browser interaction tests + screenshots + accessibility; for services, boot/readiness + API/error-path tests; for CLIs, subprocess tests + exit codes + filesystem side effects. Prefer the project's existing stack and tooling. Preserve acceptance state across compaction using the delivery tools, not a long narrative transcript.

package/skills/game-development/assets/ursina_starter.py

@@ -0,0 +1,98 @@
+"""Known-working Ursina 7 vertical slice. Extend it; this is NOT a complete game.
+Run: python ursina_starter.py --smoke --screenshot artifacts/starter.png
+"""
+import argparse
+from pathlib import Path
+
+
+def assert_nonblank(image_path, min_colors=3):
+    """A saved PNG's existence is NOT render evidence: verify pixel variety.
+
+    Smoke paths that only assert the file exists pass while the framebuffer is
+    blank (flat window color, empty UI). Sample a grid and require distinct colors.
+    """
+    from PIL import Image
+    with Image.open(image_path) as frame:
+        rgb = frame.convert('RGB')
+        width, height = rgb.size
+        colors = {rgb.getpixel((x, y))
+                  for x in range(0, width, max(1, width // 32))
+                  for y in range(0, height, max(1, height // 32))}
+    if len(colors) < min_colors:
+        raise AssertionError(
+            f'Framebuffer looks blank: {len(colors)} sampled colors in {image_path} '
+            f'(need {min_colors}). The render is defective; do not blame the probe or environment.')
+    return len(colors)
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--smoke', action='store_true')
+    parser.add_argument('--screenshot', default='artifacts/starter.png')
+    args = parser.parse_args()
+    # All graphical imports and construction are behind the main guard.
+    from panda3d.core import Filename, loadPrcFileData
+    from ursina import Ursina, Entity, Text, camera, window, color, mouse
+    if args.smoke:
+        loadPrcFileData('', 'audio-library-name null\nsync-video false')
+    app = Ursina(window_type='offscreen' if args.smoke else 'onscreen',
+                 size=(960, 600), development_mode=False, editor_ui_enabled=False)
+    # Offscreen GraphicsBuffer has no requestProperties(): do not set mouse.locked.
+    if not args.smoke:
+        from ursina.prefabs.first_person_controller import FirstPersonController
+        window.fullscreen = False
+        mouse.locked = True
+    aspect = app.win.getXSize() / app.win.getYSize()
+    camera.ui_lens.set_film_size(camera.ui_size * .5 * aspect, camera.ui_size * .5)
+    camera.perspective_lens.set_aspect_ratio(aspect)
+    window.color = color.rgb32(174, 207, 220)
+    ground = Entity(
+        model='cube',
+        scale=(12, 1, 12),
+        y=-1,
+        collider='box',
+        color=color.rgb32(93, 141, 73),
+    )
+    Entity(
+        model='cube',
+        position=(0, 1, 2),
+        collider='box',
+        color=color.rgb32(178, 124, 76),
+    )
+    if args.smoke:
+        camera.position = (5, 5, -8)
+        camera.look_at((0, 0, 0))
+    else:
+        FirstPersonController(position=(0, 1, -4), speed=5, gravity=.5, jump_height=1.5)
+
+    class Slice(Entity):
+        def __init__(self):
+            super().__init__(model='cube', color=color.rgb32(178, 124, 76))
+            self.actions = 0
+            Text(parent=camera.ui, text='A RUNNABLE SLICE / press 1', x=-.7, y=.43, scale=1)
+
+        def input(self, key):
+            if key == '1':
+                self.actions += 1
+                self.color = color.rgb32(100, 160, 210)
+
+    game = Slice()
+    if not args.smoke:
+        app.run()
+        return
+    game.input('1')
+    assert game.actions == 1
+    for _ in range(4):
+        app.taskMgr.step()
+        app.graphicsEngine.renderFrame()
+    screenshot = Path(args.screenshot).resolve()
+    screenshot.parent.mkdir(parents=True, exist_ok=True)
+    assert app.win.saveScreenshot(Filename.fromOsSpecific(str(screenshot)))
+    # Verify the actual pixels, not just that a file was written.
+    colors = assert_nonblank(screenshot)
+    print(f'NONBLANK_OK {colors} sampled colors in {screenshot}')
+    app.destroy()
+
+
+if __name__ == '__main__':
+    main()

package/skills/game-development/scripts/verify_ursina.py

@@ -0,0 +1,80 @@
+"""External smoke credibility check: require a real renderer and nonblank framebuffer.
+
+Usage: python verify_ursina.py minecraft.py --screenshot artifacts/probe.png
+Runs the candidate's --smoke path. This is NOT a sandbox or a gameplay/UX oracle.
+"""
+import argparse
+import json
+from pathlib import Path
+import runpy
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('entry')
+    parser.add_argument('--screenshot', default='artifacts/probe.png')
+    options = parser.parse_args()
+    entry = Path(options.entry).resolve()
+    screenshot = Path(options.screenshot).resolve()
+    from direct.showbase.ShowBase import ShowBase
+    from panda3d.core import PNMImage, Filename
+    original_init, original_destroy = ShowBase.__init__, ShowBase.destroy
+    instances, captures = [], []
+
+    def capture(app):
+        if getattr(app, 'win', None) is None:
+            return
+        app.graphicsEngine.renderFrame()
+        app.graphicsEngine.renderFrame()
+        image = PNMImage()
+        if not app.win.getScreenshot(image):
+            return
+        colors = set()
+        for x in range(0, image.getXSize(), max(1, image.getXSize() // 32)):
+            for y in range(0, image.getYSize(), max(1, image.getYSize() // 32)):
+                pixel = image.getXel(x, y)
+                colors.add(tuple(round(float(c) * 255) for c in pixel))
+        proof = screenshot.with_name(screenshot.stem + '-framebuffer.png')
+        proof.parent.mkdir(parents=True, exist_ok=True)
+        image.write(Filename.fromOsSpecific(str(proof)))
+        captures.append({'width': image.getXSize(), 'height': image.getYSize(), 'sampled_colors': len(colors), 'framebuffer': str(proof)})
+
+    def tracked_init(self, *args, **kwargs):
+        original_init(self, *args, **kwargs)
+        instances.append(self)
+
+    def tracked_destroy(self, *args, **kwargs):
+        capture(self)
+        return original_destroy(self, *args, **kwargs)
+
+    ShowBase.__init__, ShowBase.destroy = tracked_init, tracked_destroy
+    sys.path.insert(0, str(entry.parent))
+    old_argv = sys.argv
+    sys.argv = [str(entry), '--smoke', '--screenshot', str(screenshot)]
+    try:
+        try:
+            runpy.run_path(str(entry), run_name='__main__')
+        except SystemExit as error:
+            if error.code not in (None, 0):
+                raise RuntimeError(f'Candidate smoke failed: {error.code}') from error
+        for app in instances:
+            capture(app)
+        if not instances:
+            raise AssertionError('Smoke never instantiated Panda3D ShowBase: fake/headless-only smoke is not renderer evidence')
+        if not captures or not any(c['width'] >= 320 and c['height'] >= 200 and c['sampled_colors'] >= 3 for c in captures):
+            raise AssertionError(f'No sufficiently sized, nonblank real framebuffer captured. Renderers={len(instances)}, captures={captures}. Step/render frames before destroying the app; smoke must draw the actual game, not an empty window.')
+        if not screenshot.is_file():
+            raise AssertionError('Candidate did not save the requested screenshot')
+        print('URSINA_PROBE_RESULT ' + json.dumps({'status': 'passed', 'renderers': len(instances), 'captures': captures}))
+    finally:
+        ShowBase.__init__, ShowBase.destroy = original_init, original_destroy
+        sys.argv = old_argv
+        sys.path.pop(0)
+        for app in instances:
+            if getattr(app, 'win', None):
+                original_destroy(app)
+
+
+if __name__ == '__main__':
+    main()

package/skills/software-delivery/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: software-delivery
+description: Complete substantial software implementation from one prompt: CLIs, services, web apps and multi-file refactors. Use for acceptance contracts, vertical slices, process-level integration tests, platform/encoding failures, and evidence-backed handoff.
+---
+# Large-task delivery
+
+One user prompt can require many small implementation and verification turns. Prefer complete, testable behavior over generating a large code dump.
+
+## Pipeline
+
+1. **Inspect & identify knowledge.** For structural questions, use `code_nav` definition/symbols/outline, then callers/importers, then targeted source reads. Inspect graph coverage and nextOffset; name-based call matches are candidates, not runtime binding proof. Filter by path/container or paginate. Use grep for strings, routes, SQL and unsupported languages. Inspect nearby tests and dependency manifests, read applicable domain skills, and preserve every observable requirement. Do not exhaustively read the repository before proposing a contract.
+
+2. **Plan.** Use `delivery_plan` before implementation: a few steps, explicit assumptions, source/test/config/documentation roots (usually `["."]`), and 2–4 check suites. Reuse a check suite across acceptance criteria. D2 is emitted automatically; use D2 for other flowcharts.
+
+3. **Pressure-test proportionally.** Follow the selected workflow. Standard mode permits implementation after a valid complete contract; challenge requirements and checks without mandatory architecture paperwork. Strict mode requires `delivery_design` validate → inspect → review → approve with architecture, ports and scenarios; revisions relock it. Bounded Node/npm versions are available through delivery_probe; other APIs can be read. Revisions preserve omitted fields, merge design/workflow object fields and replace supplied arrays. Changed checks require new evidence; never remove obligations to manufacture success.
+
+4. **Develop.** Get one vertical slice running early: CLI command -> output/file; request -> handler -> response; UI action -> state -> visible feedback. Keep logic separable from infrastructure. Mark progress with `delivery_progress` as each step finishes so the plan panel stays current. If development reveals a wrong assumption or a step can't be completed as planned, call `delivery_revise` to adjust — update steps and checks to match reality, but never silently drop original acceptance criteria. Implement remaining requirements, failure behavior, dependency pins, and README commands. Check uncertain APIs by reading installed implementations or running a tiny probe. Don't add tests requiring an uninstalled framework; use the existing framework or standard-library tools.
+
+5. **Verify.** Verify like a user, in a **fresh process with the normal environment**, not just by calling internal functions. Use `delivery_check` with `id="all"`. Keep generated output under `artifacts/` so it doesn't invalidate source fingerprints. Do not edit while checks run. If checks fail, read the quoted output, repair the root cause, and rerun. If a check failure reveals the plan was wrong, adjust the plan first, then re-verify.
+
+6. **Deliver.** Review behavior, failure paths, data integrity, usability, performance and scope. Repair root causes, add regression tests, rerun stale checks, then `delivery_finish`. A blocked report is preferable to a false verified report.
+
+## Adaptive planning across packages
+
+Map affected callers, package boundaries, shared configuration and baseline test failures before changing code. Record compatibility invariants, uncertain assumptions and rollback strategy. Keep near-term slices detailed and later work coarse; expand milestones after discoveries rather than predicting every edit up front.
+
+Use structured steps `{id,title,dependsOn:[],checks:[]}` when order or evidence matters. Independent branches can proceed separately; dependent steps cannot start before prerequisites finish. Mark steps done only after mapped checks pass on current source. Reopening a prerequisite resets downstream progress. Stable IDs preserve unambiguous progress during revisions; all structured steps must be done before finish.
+
+For an intentionally failing regression milestone, use `kind:"regression",checks:[]`; run the focused probe via bash and record its behavioral assertion failure in progress notes. Import/syntax failures are not sufficient. Retain green suites on acceptance and the integration milestone. New/remapped acceptance needs new assertions and new check executions, not just retained old command evidence. Add a regression that fails before the fix. Run focused tests while iterating, then public-path integration tests and existing repository quality gates. `delivery_check id="all"` collects ordinary failures across all requested suites. Use `delivery_review action="inspect"` to capture the real final diff, read it and all listed new files, and inspect unrelated edits and missing consumers. Run additional boundary/metamorphic probes: vary magnitudes, signs, extremes, equivalent representations and order where relevant. After repairs and fresh checks, inspect again and `delivery_review action="record"` with the capture ID, per-criterion concrete assertions, probe commands/results, empty unresolved findings and honest limitations. Structured required plans cannot finish without this snapshot-bound receipt. Claimed review content remains model-authored, not independent proof. See [adaptive planning scenarios](../../docs/planning.md) for examples and assurance limits.
+
+## General pitfalls
+
+- Reuse the installed test runner. For isolated TypeScript/framework routes, consider node:test + existing TypeScript transpilation + explicit mocked imports before inventing ESM loaders. Prove one minimal import first. After two failed infrastructure probes, inspect full stderr and change one hypothesis. Run tests directly: output pipelines must not mask the original exit code. Do not upgrade unrelated dependencies or manufacture ambient types merely to obtain a green typecheck.
+
+- Test exit codes, stdout/stderr separation, filesystem side effects, paths with spaces, alternate cwd, and repeat invocations. Use subprocess argument arrays; shell quoting is platform-specific.
+- Test non-ASCII text (not just accented Latin) through the actual command with captured stdout. On Windows, stdout may use a legacy code page even when files are UTF-8. Don't make only the test environment UTF-8 and claim the default executable works — either emit ASCII-safe output or configure the application's UTF-8 output explicitly.
+- Reject malformed schema as well as malformed syntax. Avoid coercing booleans to integer IDs. Test duplicate records, missing files, invalid identifiers, whitespace-only values, and idempotency where relevant.
+- Write to a temporary file in the destination directory, flush, then atomically replace. On failure leave the previous bytes untouched and clean up temporary files. Never discard corrupt user data to make a test pass.
+- Import safety: a subprocess should import the module without starting a service/window, parsing unrelated argv, writing files, or printing output. Guard entry points so importing the module doesn't execute the main logic.
+
+## Other task types
+
+- Games/GUI: read the game-development skill for real-renderer verification and input smoke tests. Never substitute a hand-drawn image for a renderer screenshot.
+- Web: test real browser actions, empty/loading/error states, keyboard focus and screenshots; do not mistake a dev server's readiness for correct UI.
+- Services: boot/readiness, schema validation, failure status codes, persistence and shutdown; avoid unauthorized live integrations.
+- Refactors: preserve the public contract and existing tests, add a failing regression first, keep changes scoped, examine the final diff.
+
+## Evidence discipline
+
+Checks written by the same model can share its blind spots. External behavioral tests and visual inspection are separate evidence. A passing gate proves recorded commands passed on the current project, not that all requirements are objectively satisfied. Never remove assertions, relabel runtime work as static checks, or narrow the contract to achieve a green status. If context compacts, retrieve `delivery_status` and continue from the durable contract.