Move tool planning fields to DB-backed planning ownership - PR_26160_071-tool-planning-db-ownership

Author: ToolboxAid

docs_build/dev/reports/coverage_changed_js_guardrail.txt

@@ -6,18 +6,11 @@ Missing changed runtime JS files are WARN, not FAIL.
 Source: Playwright/Chromium built-in V8 coverage from the active Playwright run.
 
 Changed runtime JS files considered:
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/shared/toolbox/platformShell.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/toolRegistry.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(92%) admin/tool-votes.js - executed lines 383/383; executed functions 46/50
 
 Guardrail warnings:
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file missing from coverage; advisory only
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file missing from coverage; advisory only
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file missing from coverage; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) src/shared/toolbox/platformShell.js - WARNING: changed runtime JS file missing from coverage; advisory only
-(0%) toolbox/toolRegistry.js - WARNING: changed runtime JS file missing from coverage; advisory only

docs_build/dev/reports/playwright_v8_coverage_report.txt

@@ -17,13 +17,9 @@ Exercised tool entry points detected:
 (74%) Theme V2 Shared JS - exercised 2 runtime JS files
 
 Changed runtime JS files covered:
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) src/shared/toolbox/platformShell.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(0%) toolbox/toolRegistry.js - WARNING: changed runtime JS file was not collected by Playwright V8 coverage; advisory only
-(92%) admin/tool-votes.js - executed lines 383/383; executed functions 46/50
 
 Files with executed line/function counts where available:
 (38%) src/engine/api/session-api-client.js - executed lines 34/34; executed functions 3/8
@@ -43,21 +39,12 @@ Files with executed line/function counts where available:
 (100%) toolbox/project-workspace/project-workspace-api-client.js - executed lines 12/12; executed functions 2/2
 
 Uncovered or low-coverage changed JS files:
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - WARNING: uncovered changed runtime JS file; advisory only
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - WARNING: uncovered changed runtime JS file; advisory only
 (0%) src/dev-runtime/persistence/mock-db-store.js - WARNING: uncovered changed runtime JS file; advisory only
 (0%) src/dev-runtime/server/mock-api-router.mjs - WARNING: uncovered changed runtime JS file; advisory only
-(0%) src/shared/toolbox/platformShell.js - WARNING: uncovered changed runtime JS file; advisory only
-(0%) toolbox/toolRegistry.js - WARNING: uncovered changed runtime JS file; advisory only
 
 Changed JS files considered:
-(0%) src/dev-runtime/guest-seeds/tool-metadata-inventory.js - changed JS file not collected as browser runtime coverage
 (0%) src/dev-runtime/guest-seeds/tool-state-samples.js - changed JS file not collected as browser runtime coverage
 (0%) src/dev-runtime/persistence/mock-db-store.js - changed JS file not collected as browser runtime coverage
 (0%) src/dev-runtime/server/mock-api-router.mjs - changed JS file not collected as browser runtime coverage
-(0%) src/shared/toolbox/platformShell.js - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/BuildPathProgressSimplification.spec.mjs - changed JS file not collected as browser runtime coverage
 (0%) tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) tests/playwright/tools/ToolboxRoutePages.spec.mjs - changed JS file not collected as browser runtime coverage
-(0%) toolbox/toolRegistry.js - changed JS file not collected as browser runtime coverage
-(92%) admin/tool-votes.js - changed JS file with browser V8 coverage

docs_build/dev/reports/tool-planning-db-ownership-report.md

@@ -0,0 +1,92 @@
+# PR_26160_071 Tool Planning DB Ownership Report
+
+## Branch Validation
+
+| Check | Expected | Actual | Status |
+| --- | --- | --- | --- |
+| Current git branch | `main` | `main` | PASS |
+
+## Ownership Summary
+
+| Data Area | DB Table / Contract | Owned Fields |
+| --- | --- | --- |
+| Tool Metadata | `toolbox_tool_metadata` via `/api/toolbox/registry/snapshot` and `/api/toolbox/votes/snapshot` | Identity, display, routing, grouping, state, and order: `toolKey`, `toolName`, labels/descriptions, `group`, `category`, `colorGroup`, `toolboxGroup`, `path`, `order`, `status`, images, visibility/access fields. |
+| Tool Planning | `toolbox_tool_planning`, merged into `/api/toolbox/registry/snapshot` | Readiness/dependency/checklist data: `readiness`, `requiredForPlayable`, `requiredForTestable`, `requiredForPublish`, `requires`, `progressChecklist`. |
+| Tool Voting | `toolbox_votes` via `/api/toolbox/votes/snapshot` | Vote totals and current-user vote state: `toolId`, `userKey`, `direction`, computed up/down/total/percent/current vote. |
+
+## Implementation Notes
+
+- Added DB-backed `toolbox_tool_planning` schema in `src/dev-runtime/persistence/mock-db-store.js`.
+- Seeded one planning row per active tool in `src/dev-runtime/guest-seeds/tool-state-samples.js`.
+- Removed planning fields from `toolbox_tool_metadata` schema and seed rows.
+- Updated `src/dev-runtime/server/mock-api-router.mjs` to:
+  - populate/sync planning rows from the dev inventory;
+  - migrate old planning values out of existing metadata rows when present;
+  - strip planning fields from active metadata rows after planning rows are populated;
+  - merge planning rows into the existing registry snapshot API so Toolbox behavior remains unchanged.
+- Kept Admin Tool Votes unchanged for users: order/group/path/status/votes still come from metadata/vote contracts.
+
+## API / DB Probe Evidence
+
+```json
+{
+  "activeTools": 43,
+  "voteRows": 43,
+  "metadataRows": 43,
+  "planningRows": 43,
+  "metadataHasPlanning": false,
+  "planningSchemaHasFields": true,
+  "metadataSchemaHasPlanning": false,
+  "colorsPlanningSource": "toolbox_tool_planning",
+  "colorsRequiredForPublish": true,
+  "hasMidi": true,
+  "hasMusic": true,
+  "platformToolboxGroup": "Admin"
+}
+```
+
+## Requirement Checklist
+
+| Requirement | Status | Evidence |
+| --- | --- | --- |
+| Create DB-backed Tool Planning ownership for `requiredForTestable`. | PASS | `toolbox_tool_planning` schema/seed/API merge owns `requiredForTestable`; Playwright asserts registry values merge from planning. |
+| Create DB-backed Tool Planning ownership for `requiredForPublish`. | PASS | `toolbox_tool_planning` schema/seed/API merge owns `requiredForPublish`; Colors registry snapshot still exposes `requiredForPublish: true`. |
+| Create DB-backed Tool Planning ownership for `requires`. | PASS | `toolbox_tool_planning` schema/seed/API merge owns `requires`; registry snapshot keeps an array for existing UI behavior. |
+| Create DB-backed Tool Planning ownership for `progressChecklist`. | PASS | `toolbox_tool_planning` schema/seed/API merge owns `progressChecklist`; registry snapshot keeps an array for existing UI behavior. |
+| Keep Tool Metadata limited to identity, display, routing, grouping, state, and order. | PASS | `toolbox_tool_metadata` schema no longer includes planning fields; API probe reports `metadataHasPlanning: false`. |
+| Add/update API service contract so Tool Planning data is read through Web UI -> API/Service Contract -> DB Adapter. | PASS | Existing `/api/toolbox/registry/snapshot` now merges DB-backed `toolbox_tool_planning` rows into tool records consumed by Toolbox. |
+| Remove planning fields from active Tool Metadata rows after Tool Planning is populated. | PASS | Server sync migrates planning fields first and then strips `progressChecklist`, `readiness`, `requiredForPlayable`, `requiredForPublish`, `requiredForTestable`, and `requires` from metadata rows. |
+| Keep Toolbox and Admin Tool Votes behavior unchanged. | PASS | Targeted Playwright lanes passed; Admin edits still update Toolbox after reload. |
+| Do not use page-local arrays, hardcoded counts, or duplicated planning metadata. | PASS | Planning ownership is DB-backed; Toolbox still reads through API clients. Existing UI constants are display maps, not duplicated planning records. |
+| Preserve 43-tool inventory, MIDI/Music separation, and Platform Settings Admin placement. | PASS | API probe confirms 43/43 rows, `hasMidi: true`, `hasMusic: true`, and `platformToolboxGroup: "Admin"`. |
+| No inline script/style/event handlers. | PASS | No HTML was changed; JS remains external. |
+
+## Validation
+
+| Lane | Command | Result |
+| --- | --- | --- |
+| Changed-file syntax | `node --check` on changed JS/MJS files | PASS |
+| Static diff whitespace | `git diff --check` | PASS |
+| DB adapter/API probe | Node probe against `/api/toolbox/registry/snapshot`, `/api/toolbox/votes/snapshot`, and `/api/mock-db/snapshot` | PASS |
+| Admin Tool Votes / Toolbox SSoT Playwright | `npx playwright test tests/playwright/tools/ToolboxAdminMetadataSsot.spec.mjs --reporter=line` | PASS: 4/4 |
+| Toolbox route/Admin menu Playwright | `npx playwright test tests/playwright/tools/ToolboxRoutePages.spec.mjs --reporter=line` | PASS: 8/8 on rerun |
+
+Validation note: the first `ToolboxRoutePages.spec.mjs` attempt encountered Playwright artifact zip `ENOENT` errors under `tmp/test-results` while writing trace artifacts. The clean rerun passed 8/8 without product-code changes.
+
+## Impacted Lane
+
+DB adapter/API, Toolbox, and Admin Tool Votes.
+
+## Skipped Lanes
+
+| Lane | Reason |
+| --- | --- |
+| Full samples validation | Safe to skip per request; this PR did not touch samples or shared sample loader/framework code. |
+| Unrelated tool runtime lanes | Safe to skip; Toolbox consumes the same registry snapshot shape and targeted Toolbox/Admin validation passed. |
+
+## Manual Test Notes
+
+- Confirmed current branch was `main` before changes.
+- Confirmed Tool Metadata rows no longer carry planning fields after registry snapshot sync.
+- Confirmed Tool Planning rows preserve the planning fields and are merged into the Toolbox registry snapshot.
+- Confirmed Admin Tool Votes still shows the 43 DB-backed tools and metadata edits still flow to Toolbox.

src/dev-runtime/guest-seeds/tool-state-samples.js

@@ -132,12 +132,6 @@ function toolboxToolMetadataRows() {
         capabilityLabel: tool.capabilityLabel || "",
         childCapabilities: Array.isArray(tool.childCapabilities) ? [...tool.childCapabilities] : [],
         requiredRole: typeof tool.requiredRole === "string" ? tool.requiredRole : "",
-        requires: Array.isArray(tool.requires) ? [...tool.requires] : [],
-        requiredForPlayable: tool.requiredForPlayable === true,
-        requiredForTestable: tool.requiredForTestable === true,
-        requiredForPublish: tool.requiredForPublish === true,
-        progressChecklist: Array.isArray(tool.progressChecklist) ? [...tool.progressChecklist] : [],
-        readiness: tool.readiness || "",
         statusDiagnostic: tool.statusDiagnostic || "",
         toolId: toolKey,
         releaseChannel,
@@ -147,9 +141,28 @@ function toolboxToolMetadataRows() {
     });
 }
 
+function toolboxToolPlanningRows() {
+  return getActiveToolRegistry()
+    .map((tool, index) => {
+      const toolKey = tool.id;
+      return {
+        key: serverSeedUlid(8_801 + index),
+        toolKey,
+        readiness: tool.readiness || "",
+        requiredForPlayable: tool.requiredForPlayable === true,
+        requiredForTestable: tool.requiredForTestable === true,
+        requiredForPublish: tool.requiredForPublish === true,
+        requires: Array.isArray(tool.requires) ? [...tool.requires] : [],
+        progressChecklist: Array.isArray(tool.progressChecklist) ? [...tool.progressChecklist] : [],
+        ...serverSeedAuditFields(90 + index, MOCK_DB_KEYS.users.forgeBot),
+      };
+    });
+}
+
 export function createServerSeedTables() {
   const tables = getStandaloneMockDbSeedTables();
   tables.toolbox_tool_metadata = toolboxToolMetadataRows();
+  tables.toolbox_tool_planning = toolboxToolPlanningRows();
   tables.toolbox_votes = [];
   tables.tool_state_samples = [
     ...guestToolStateSampleRows(),

src/dev-runtime/persistence/mock-db-store.js

@@ -118,7 +118,8 @@ const MOCK_DB_TABLE_SCHEMAS = Object.freeze({
   users: Object.freeze(["key", "displayName", "email", "authProvider", "authProviderUserId", "isActive", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
   roles: Object.freeze(["key", "roleSlug", "name", "description", "isSystemRole", "isActive", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
   user_roles: Object.freeze(["key", "userKey", "roleKey", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
-  toolbox_tool_metadata: Object.freeze(["key", "toolKey", "toolName", "shortLabel", "shortDescription", "description", "group", "category", "colorGroup", "toolboxGroup", "subgroup", "path", "order", "status", "badge", "toolImage", "active", "adminOnly", "hidden", "deferred", "visibleInToolsList", "capabilityLabel", "childCapabilities", "requiredRole", "requires", "requiredForPlayable", "requiredForTestable", "requiredForPublish", "progressChecklist", "readiness", "statusDiagnostic", "toolId", "releaseChannel", "releaseChannelLabel", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
+  toolbox_tool_metadata: Object.freeze(["key", "toolKey", "toolName", "shortLabel", "shortDescription", "description", "group", "category", "colorGroup", "toolboxGroup", "subgroup", "path", "order", "status", "badge", "toolImage", "active", "adminOnly", "hidden", "deferred", "visibleInToolsList", "capabilityLabel", "childCapabilities", "requiredRole", "statusDiagnostic", "toolId", "releaseChannel", "releaseChannelLabel", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
+  toolbox_tool_planning: Object.freeze(["key", "toolKey", "readiness", "requiredForPlayable", "requiredForTestable", "requiredForPublish", "requires", "progressChecklist", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
   toolbox_votes: Object.freeze(["key", "toolId", "userKey", "direction", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
   workspace_projects: Object.freeze(["key", "name", "status", "ownerKey", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
   workspace_progress: Object.freeze(["key", "projectKey", "currentFocus", "projectProgress", "publishingProgress", "recommendedNextTool", "createdAt", "updatedAt", "createdBy", "updatedBy"]),
@@ -148,6 +149,7 @@ const DEFAULT_TABLE_OWNERS = Object.freeze(Object.fromEntries([
   ["roles", "standalone"],
   ["user_roles", "standalone"],
   ["toolbox_tool_metadata", "standalone"],
+  ["toolbox_tool_planning", "standalone"],
   ["toolbox_votes", "standalone"],
   ["tool_state_samples", "standalone"],
   ...Object.entries(MOCK_DB_TOOL_GROUPS).flatMap(([ownerId, group]) =>