@bongos/core 1.19.31 → 1.19.33

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.31",
-  "core_contract": "1.19.31",
-  "source_commit": "2e9b2abd8b182334b2eeb52e9815f499f340a3e3",
+  "core_version": "1.19.33",
+  "core_contract": "1.19.33",
+  "source_commit": "53e6567ae132484c597ea9f16ed141b3f38c4d98",
   "source_ref": "HEAD",
-  "built_at": "2026-08-11T14:47:58.633Z",
+  "built_at": "2026-08-11T15:10:31.561Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 286,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1207,
+    "functional_verbatim": 1208,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1514,
-  "tree_sha256": "46bd790b34d0d3e1c2884f43eecf20fa747ddd57fb76ad0331f24dfb362fc6a2",
+  "file_count": 1515,
+  "tree_sha256": "c4eb5d8939b2cfefc3bddc6b97e016418d2fd5a7c99a9090116183a407bfc937",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -87,7 +87,7 @@
     {
       "path": ".claude/skills/builder-sequence/SKILL.md",
       "mode": "0000644",
-      "sha256": "7772f3a12d76e6872ae4ae7b6cd16e9af839a0698b6ca89769429b38363157b2"
+      "sha256": "4284bc0184dd27752202ce02974fa8909fc462f546ee3cae38fa26b4ca071f81"
     },
     {
       "path": ".claude/skills/builder-setup/SKILL.md",
@@ -97,7 +97,7 @@
     {
       "path": ".claude/skills/builder-ship/SKILL.md",
       "mode": "0000644",
-      "sha256": "c9ad7867f8cb4be347dde8b33ff5f3ae64ac6812a06209205f2d0c98fc16374d"
+      "sha256": "b21b28bc173431adbaf8c98faec0d32c84808258099a35c346b2cff6612f9f51"
     },
     {
       "path": ".claude/skills/builder-stage/SKILL.md",
@@ -142,7 +142,7 @@
     {
       "path": ".claude/skills/fix-task/SKILL.md",
       "mode": "0000644",
-      "sha256": "ffae88604d885ab93557d315f82351c737df831e790cf4084c695172a73f0106"
+      "sha256": "1cb690260144b33fe2c149348d5f048454a90c525285aa768de326cf097a7be9"
     },
     {
       "path": ".claude/skills/goal-create/SKILL.md",
@@ -352,7 +352,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "7e6732aedaf7aaa3c657fc05e2dfd1dcc63e0fb06586d4077248d79d6198297e"
+      "sha256": "649065862779b6a9b871607debfee5ca18bde8cccbde4d00ea42b0d175938c9d"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -1282,12 +1282,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "e28575936d1cb0cce684b20723743fd0d801ccd0a7ec58fff5360e160b23b5e7"
+      "sha256": "8f83ea78edb348688196414bf2fb7352df3de0ded6abbbe44f2371c099431016"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "b232ca69ae97842be312b76f6ac49ca66090c5c8fef392f609bb857e5f5c2979"
+      "sha256": "27cf9c2b8548168f13dd2add1633bc9b3ca57f2fd5aa3b42ac8dbfb5cf60c41f"
     },
     {
       "path": "docs/architecture.md",
@@ -3362,7 +3362,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "85c856016e548399538734098d2f08d3920fb52814759ffa314ed26d98bf32eb"
+      "sha256": "b2927d0be39718b274dda102c0d9d9035d323d1c60937ea7cd7a216315d5dc64"
     },
     {
       "path": "modules/lifecycle/done-when.js",
@@ -3467,7 +3467,7 @@
     {
       "path": "modules/lifecycle/routes/tasks.js",
       "mode": "0000644",
-      "sha256": "aa179ab79508a002e8f580fb839767d8aaa8b6f02a46d021bb61633dd9f8f9a4"
+      "sha256": "8a6ecd6c7ecadcbec79483a589fef11957d13e2c94b569a9ff9da97f2908b713"
     },
     {
       "path": "modules/lifecycle/routes/versions.js",
@@ -4012,12 +4012,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "bb741853a2f1a9a62c27bfa769492a653a975103458dd872c4e51f7a7e4e6b9a"
+      "sha256": "3b7b3283efe27724944d786e894dffd69731c4aca5f10c72c4dd318f2e05e1bf"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "1d0695ec7d2636aab3ca123aff5dfb89e5ccc6ddfd3cb3692b4570fd114e4f97"
+      "sha256": "854d15e8cf4e81bf848db848280b88dfc40a3836858a0ad1ab008f808f96677b"
     },
     {
       "path": "public-docs/index.html",
@@ -5637,7 +5637,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "1b4208d337a8dd0b88ba82cb42f5685537be1e4d12824c4972564cecbf84ce32"
+      "sha256": "229087cbc698ed7d1a71aa3cea5b210528e2d5d1fcc7232ee6a536e9a2ca2010"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6832,7 +6832,7 @@
     {
       "path": "tests/migration_allocation.mjs",
       "mode": "0000644",
-      "sha256": "f014dee000483e41d01d41bc53361b81deba8ff1b21e5810aaf9200d65b8f366"
+      "sha256": "10b1faf40cef2a3872c44109b63680e79922446b573bb476c79540d44a5622ac"
     },
     {
       "path": "tests/migration_namespace.mjs",
@@ -7439,6 +7439,11 @@
       "mode": "0000644",
       "sha256": "7e4f4270188771f1fc1fa7d68e9730b4562fb772ee9ecbd04b65fd1738ee9795"
     },
+    {
+      "path": "tests/skill_docs_unavailable_regrade.mjs",
+      "mode": "0000644",
+      "sha256": "0eeccae9320f419667cf9ede3c13671a5b03571f7f2f17067bff1857234ddf91"
+    },
     {
       "path": "tests/skill_prefs.mjs",
       "mode": "0000644",

package/.claude/skills/builder-sequence/SKILL.md

@@ -60,7 +60,7 @@ Between passes, report progress in one line — which task landed, what is next,
 
 Two more halts are yours to detect, not the script's:
 
-- **`ship_failed`** — the ship bounced, the grade failed, or the task did not reach `shipped`.
+- **`ship_failed`** — the ship bounced, the grade failed, or the task did not reach `shipped`. Tell the two non-pass grade shapes apart first: **`GRADER UNAVAILABLE`** (`panel_outcome='unavailable'`) is **not a quality rejection** — the panel could not run, there is nothing to fix, and `node scripts/gds/ship.js <id> --regrade` re-runs the grade once the grader is reachable (a recoverable pause, not a halt). A genuine **`FAIL`** has findings: fix, commit, re-run `node scripts/gds/ship.js <id> --regrade`; if it still will not land, halt and report.
 - **`scope_surprise`** — the task turns out to need work outside its `touches[]`, or its premise is wrong (the thing it describes is already done, or no longer true). Do not quietly widen the scope; that is a new task.
 
 **On any halt:** leave the current task claimed, stop, and report — what you hit, which task, and what it needs from a human. Then say plainly what already landed. Everything shipped stays shipped; a halt costs the rest of the run, not the work done.

package/.claude/skills/builder-ship/SKILL.md

@@ -19,6 +19,11 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
 
 `/builder-ship` runs steps 1 + 2 inline; on auto-confirm it chains into step 3 (push, merge on main, smoke, deploy).
 
+**Two non-pass grade shapes — tell them apart before reacting:**
+
+- **`GRADER UNAVAILABLE`** (`panel_outcome='unavailable'`) — the grading panel could not run (worker infra outage or a pre-spawn bypass). This is **not a quality rejection**: no quality signal was produced, there are no findings to fix, and the task parks at `completed` ungraded (aggregates exclude these rounds as `n_unavailable` — an outage never counts as a zero). Recovery: when the grader is reachable again, re-run just the grade step — `node scripts/gds/ship.js <id> --regrade`.
+- **A genuine `FAIL`** — the panel ran and returned findings. Fix the real issues, commit on the claim branch (the grader reads committed history, not the working tree), then re-grade with the same command: `node scripts/gds/ship.js <id> --regrade`.
+
 (Dev-box game changes, `--approved`) Persists the builder's sandbox self-approval to `tasks.sandbox_review` — `{ by, at, stamp, url, method }`, with `by`/`at` stamped server-side ([#1048](https://example.com/builders#/task/1048), ADR 0046).
 
 ## How to use

package/.claude/skills/fix-task/SKILL.md

@@ -48,7 +48,9 @@ Runs the recurring "claim, fix, and ship task NNNN" macro end to end. Its own va
    node scripts/gds/api.js GET /api/gds/tasks/<id>
    ```
    - `shipped` (or `confirmed`, awaiting `/merge-mode`) → done; relay the completion card per `/builder-ship`.
-   - Still `completed` → the grader bounced it. **Surface its feedback verbatim** — don't paraphrase or summarize away the specifics — then loop back to step 4 with that feedback in hand.
+   - Still `completed` → read the grade shape before reacting; two distinct outcomes park a task here:
+     - **`GRADER UNAVAILABLE`** (`panel_outcome='unavailable'`) — the panel could not run (infra outage/bypass). **Not a quality rejection**: there are no findings to fix. Re-run the grade when the grader is reachable: `node scripts/gds/ship.js <id> --regrade`.
+     - **A genuine `FAIL`** — the grader bounced it with findings. **Surface its feedback verbatim** — don't paraphrase or summarize away the specifics — then loop back to step 4 with that feedback in hand; fix, commit, and re-grade: `node scripts/gds/ship.js <id> --regrade`.
 
 ## Constraints
 

package/clients/bongos-client/index.d.ts

@@ -131,7 +131,7 @@ export interface PatchMeSkillPrefsResponse { prefs: unknown; effective: unknown;
 export interface PatchMeSoundPrefsResponse { prefs: unknown; effective: unknown; effective_map: unknown; volume: unknown; defaults: unknown; known_sounds: unknown }
 export interface PatchProjectsIdFeaturedRequest { featured: boolean }
 export interface PatchProjectsIdFeaturedResponse { project: unknown }
-export interface PatchTasksIdRequest { kind?: string; discipline?: string; requires_rank?: string; module_key?: string; goal_id?: number; parent_task_id?: StringifiableId; parallel_safe?: unknown; newcomer_friendly?: boolean; xenos_claimable?: boolean; security_sensitive?: boolean; automation_tag?: string; status?: unknown }
+export interface PatchTasksIdRequest { kind?: string; discipline?: string; requires_rank?: string; module_key?: string; goal_id?: number; parent_task_id?: StringifiableId; parallel_safe?: unknown; newcomer_friendly?: boolean; xenos_claimable?: boolean; security_sensitive?: boolean; automation_tag?: string; needs_migration?: boolean; status?: unknown }
 export interface PostAccessRequestsRequest { github_login: string; display_name?: string; note?: string }
 export interface PostAccessRequestsResponse { ok: boolean; request?: unknown; already_pending?: boolean }
 export interface PostAuthAppPairApproveRequest { pair_code: string }

package/docs/api/openapi.json

@@ -13789,6 +13789,9 @@
             "type": "string",
             "maxLength": 64
           },
+          "needs_migration": {
+            "type": "boolean"
+          },
           "status": {}
         },
         "additionalProperties": false

package/docs/api-reference.md

@@ -463,7 +463,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/tasks` | `any-builder` | — | reads (filtered task list); preserved per CRITICAL §4. |
 | POST | `/api/bongos/tasks` | `metic+archon` | `version_id`, `title`, `description`, `status`, `touches`, `est_minutes`, `est_cost_usd`, `manual_degree`, `priority`, `automation_tag`, `credits_reward`, `source`, `source_ref`, `value_summary`, `kind`, `discipline`, `parallel_safe`, `newcomer_friendly`, `security_sensitive`, `requires_rank`, `auto_detect_touches`, `criterion_ids`, `module_key`, `goal_id` | Task create/promote/edit (plan/scope mutation) is Metic+ as of ADR 0090 (owner decision 2026-06-26): a Metic who can run idea-triage may … |
 | GET | `/api/bongos/tasks/:id` | `any-builder` | — | single-task read; preserved per CRITICAL §4 (supervisor hot path). |
-| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
+| PATCH | `/api/bongos/tasks/:id` | `metic+archon` | `kind`, `discipline`, `requires_rank`, `module_key`, `goal_id`, `parent_task_id`, `parallel_safe`, `newcomer_friendly`, `xenos_claimable`, `security_sensitive`, `automation_tag`, `needs_migration`, `status` | PATCH /tasks/:id — supports body.parent_task_id (V2 C2), body.kind (V2 B1), body.discipline (mig 014), body.parallel_safe (mig 028), and … |
 | POST | `/api/bongos/tasks/:id/abandon` | `metic+archon` | `reason` | POST /tasks/:id/abandon — terminal "retire this task" transition (task 987). |
 | POST | `/api/bongos/tasks/:id/attest-gate` | `any-builder` | `head_sha` | POST /tasks/:id/attest-gate — body: { head_sha }. |
 | POST | `/api/bongos/tasks/:id/confirm` | `any-builder` | `verified` |  |

package/modules/lifecycle/db.js

@@ -1686,6 +1686,11 @@ async function updateTaskParallelSafe(id, parallelSafe) { return updateTaskColum
 
 async function updateTaskAutomationTag(id, automationTag) { return updateTaskColumn(id, 'automation_tag', automationTag); }
 
+// task 1002648: correct the create-time migration heuristic's verdict — a false
+// flag makes claiming reserve a migration number that goes unused (task 1002614
+// burned 213 that way). Boolean only; the route validates.
+async function updateTaskNeedsMigration(id, needsMigration) { return updateTaskColumn(id, 'needs_migration', needsMigration === true); }
+
 // BV1.R53 (task 1422): assign (or clear) the module_key that declares which
 // module this task's work belongs to. Drives module-disjointness at claim time
 // and diff⊆module enforcement at ship time. Accepts any key in MODULE_SCOPE_MAP,
@@ -5441,6 +5446,7 @@ module.exports = {
   updateTaskParallelSafe,
   updateTaskSecuritySensitive,
   updateTaskAutomationTag,
+  updateTaskNeedsMigration,
   updateTaskModuleKey,
   listClaimableTasks,
   capNewcomerTasks,

package/modules/lifecycle/routes/tasks.js

@@ -69,8 +69,27 @@ const VALID_FITS = new Set(['autonomous', 'parallel']);
 const MIGRATION_KEYWORD_RE =
   /\bmigrations?\b|\bschema\b|\balter\s+table\b|\bcreate\s+table\b/i;
 
+// task 1002648 (idea 1000642): compounds where the keyword is qualified by a
+// NON-database noun are refactor/API language, not schema work, and are blanked
+// before the keyword test. Two families surfaced in the wild: "gate/route/code
+// migration" (code-migration phrasing) and "request/PATCH/:NNN schema"
+// (API-shape phrasing — the task-1002614 false positive, which reserved
+// migration 213 for zero schema change). Bare "migration"/"schema" and every
+// DB-shaped compound ("schema migration", "DB schema") still flag.
+const NON_DB_COMPOUND_RE = new RegExp(
+  [
+    /\b(?:gate|route|code)s?[-\s]+migrations?\b/.source,
+    /\bmigrations?\s+of\s+(?:gate|route|code)s?\b/.source,
+    /\b(?:request|response|body|validation|patch|post|put|delete|json|openapi|api|error)[-\s]+schemas?\b/.source,
+    /:\d+[-\s]+schemas?\b/.source,
+  ].join('|'),
+  'gi'
+);
+
 function detectsMigration(...texts) {
-  return texts.some((t) => typeof t === 'string' && MIGRATION_KEYWORD_RE.test(t));
+  return texts.some(
+    (t) => typeof t === 'string' && MIGRATION_KEYWORD_RE.test(t.replace(NON_DB_COMPOUND_RE, ' '))
+  );
 }
 
 // ---- peer votes (V3.R25 #245) ---------------------------------------------
@@ -773,6 +792,7 @@ module.exports = function buildTasksRouter() {
       xenos_claimable: { type: 'boolean' },              // pre-rename alias for newcomer_friendly
       security_sensitive: { type: 'boolean' },           // task 990 — Archon-only ship broadcast
       automation_tag: { type: 'string', maxLength: 64 },
+      needs_migration: { type: 'boolean' },              // task 1002648 — correct the create-time heuristic's flag (the claim-time allocator keys off it)
       // task 1002614 (map D-18): DECLARED so strict-mode admits the request far
       // enough to reach the deliberate status_not_patchable hint below (#514) —
       // the hint had been unreachable dead code behind unknown_field since the
@@ -794,6 +814,7 @@ module.exports = function buildTasksRouter() {
     const hasParallelSafe = Object.prototype.hasOwnProperty.call(body, 'parallel_safe');
     const hasSecuritySensitive = Object.prototype.hasOwnProperty.call(body, 'security_sensitive');
     const hasAutomationTag = Object.prototype.hasOwnProperty.call(body, 'automation_tag');
+    const hasNeedsMigration = Object.prototype.hasOwnProperty.call(body, 'needs_migration');
     const hasRequiresRank = Object.prototype.hasOwnProperty.call(body, 'requires_rank');
     const hasModuleKey = Object.prototype.hasOwnProperty.call(body, 'module_key');
     const hasGoalId = Object.prototype.hasOwnProperty.call(body, 'goal_id');
@@ -808,8 +829,8 @@ module.exports = function buildTasksRouter() {
     if (Object.prototype.hasOwnProperty.call(body, 'status')) {
       return res.fail('status_not_patchable', { status: 400, message: STATUS_HINT });
     }
-    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasRequiresRank && !hasModuleKey && !hasGoalId) {
-      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, parallel_safe, security_sensitive, automation_tag, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
+    if (!hasParent && !hasKind && !hasDiscipline && !hasNewcomerOrXenos && !hasParallelSafe && !hasSecuritySensitive && !hasAutomationTag && !hasNeedsMigration && !hasRequiresRank && !hasModuleKey && !hasGoalId) {
+      return res.fail('no_supported_fields', { status: 400, message: 'PATCH /tasks/:id supports parent_task_id, kind, discipline, parallel_safe, security_sensitive, automation_tag, needs_migration, requires_rank, module_key, goal_id, and newcomer_friendly (alias: xenos_claimable). ' + STATUS_HINT });
     }
     // ---- task 1002609 (G-22): settle EVERY gate and validation before the ----
     // ---- FIRST write. The previous shape validated-and-wrote per field in ----
@@ -937,6 +958,15 @@ module.exports = function buildTasksRouter() {
         return res.fail('patch_failed', { status: 500, message: 'internal error' });
       }
     }
+    if (hasNeedsMigration) {
+      try {
+        updated = await db.updateTaskNeedsMigration(id, body.needs_migration);
+        if (!updated) return res.fail('task_not_found', 404);
+      } catch (err) {
+        console.error('[gds] PATCH /tasks/:id needs_migration', err);
+        return res.fail('patch_failed', { status: 500, message: 'internal error' });
+      }
+    }
     if (hasModuleKey) {
       try {
         updated = await db.updateTaskModuleKey(id, body.module_key ?? null);

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.31",
+  "version": "1.19.33",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.31",
+      "version": "1.19.33",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.31",
+  "version": "1.19.33",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -489,8 +489,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.29 with no explicit bump. run 31502880105. (task 1002620)
 //   1.19.31 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.30 with no explicit bump. run 31503461332. (task 1002620)
+//   1.19.32 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.31 with no explicit bump. run 31504858325. (task 1002620)
+//   1.19.33 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.32 with no explicit bump. run 31505528205. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.31'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.33'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/migration_allocation.mjs

@@ -27,6 +27,7 @@ import { strict as assert } from 'node:assert';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
+import { createRequire } from 'node:module';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const repoRoot = join(__dirname, '..');
@@ -141,6 +142,56 @@ function shouldReserveMigrationNumber(task) {
     );
   });
 
+  // ---- task 1002648 (idea 1000642): the classifier must not flag non-DB ----
+  // "migration"/"schema" compounds, and a wrong verdict must be correctable
+  // via PATCH. Behavioral tests use the real exported detectsMigration.
+  const require = createRequire(import.meta.url);
+  const { detectsMigration } = require('../modules/lifecycle/routes/tasks.js');
+
+  await test('classifier ignores code-migration and API-schema phrasing (task 1002648)', () => {
+    const falsePositives = [
+      'gate migration cleanup across the router',
+      'finish the route-migration started in R86',
+      'the migration of gates to the new catalog',
+      // the task-1002614 repro — reserved migration 213 for zero schema change:
+      'the PATCH schema declares 11 keys and description is not among them',
+      'status is undeclared in the :751 schema, so strict-mode validation returns unknown_field first',
+      'align the request schema with the response schema',
+    ];
+    for (const text of falsePositives) {
+      assert.equal(detectsMigration(text), false, `must NOT flag: ${JSON.stringify(text)}`);
+    }
+  });
+
+  await test('classifier still flags real schema work (regression)', () => {
+    const truePositives = [
+      'add a migration to backfill the marker',
+      'ALTER TABLE builders add a column',
+      'create table for the new ledger',
+      'schema change on tasks',
+      'a schema migration for the counter floor',
+      'apply migrations/ before deploy',
+    ];
+    for (const text of truePositives) {
+      assert.equal(detectsMigration(text), true, `must flag: ${JSON.stringify(text)}`);
+    }
+  });
+
+  await test('PATCH /tasks/:id accepts needs_migration so a wrong flag is correctable', () => {
+    assert.ok(
+      /needs_migration: \{ type: 'boolean' \}/.test(routesSrc),
+      'the PATCH schema must declare needs_migration as a boolean'
+    );
+    assert.ok(
+      /db\.updateTaskNeedsMigration\(id, body\.needs_migration\)/.test(routesSrc),
+      'the PATCH handler must write via db.updateTaskNeedsMigration'
+    );
+    assert.ok(
+      /async function updateTaskNeedsMigration/.test(dbSrc) && /updateTaskNeedsMigration,/.test(dbSrc),
+      'db.js must define and export updateTaskNeedsMigration'
+    );
+  });
+
   console.log(`\n${passed} passed, ${failed} failed`);
   if (failed > 0) process.exit(1);
 })();

package/tests/skill_docs_unavailable_regrade.mjs

@@ -0,0 +1,35 @@
+// tests/skill_docs_unavailable_regrade.mjs — the builder-facing skills teach
+// unavailable-vs-fail + the --regrade recovery command (task 1002654, Wave 2 of
+// the grader-hardening evaluation). A GRADER UNAVAILABLE outcome
+// (panel_outcome='unavailable', R01/R02) is not a quality rejection, and every
+// skill that walks a builder through shipping must say so and name the recovery:
+//   node scripts/gds/ship.js <id> --regrade
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILLS = ['builder-ship', 'fix-task', 'builder-sequence'];
+
+// .claude/skills is INSTANCE-materialized; a neutral core checkout carries none
+// (task 1002470) — check what exists, with a non-vacuity guard like file_map.mjs.
+const present = SKILLS
+  .map((name) => ({ name, file: path.join(ROOT, '.claude', 'skills', name, 'SKILL.md') }))
+  .filter(({ file }) => existsSync(file));
+
+test('ship-path skills name the unavailable-vs-fail distinction and the --regrade recovery', () => {
+  for (const { name, file } of present) {
+    const md = readFileSync(file, 'utf8');
+    assert.ok(md.includes("panel_outcome='unavailable'"),
+      `${name}: must name the grader-outage outcome (panel_outcome='unavailable')`);
+    assert.match(md, /not a quality rejection/i,
+      `${name}: must say an unavailable grade is NOT a quality rejection`);
+    assert.match(md, /node scripts\/gds\/ship\.js <(?:task-)?id> --regrade/,
+      `${name}: must name the recovery command: node scripts/gds/ship.js <id> --regrade`);
+  }
+  if (existsSync(path.join(ROOT, '.claude', 'skills'))) {
+    assert.ok(present.length > 0, '.claude/skills exists but none of the ship-path skills were found — the check went vacuous');
+  }
+});