Close the remaining number/string/id exact-cluster normalization residue

BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT

Author: ToolboxAid

docs/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -200,7 +200,7 @@
 - [x] Asteroids numeric sanitizers promoted into shared math
 - [x] duplicated `asObject` / `asArray` consumers moved to shared utils
 - [.] shared math is now a real active layer and should continue by exact-cluster extraction only
-- [ ] remaining number/string/id helpers still need exact-cluster normalization
+- [x] remaining number/string/id helpers still need exact-cluster normalization
 
 ---
 

docs/dev/CODEX_COMMANDS.md

@@ -2,32 +2,30 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP`.
+Create `BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT`.
 
-1. Locate these roadmap items:
-- no standalone showcase-only tool tracks
-- tools header accordion added to reduce vertical real-estate usage
-- tool-shell UI compaction is useful but does not replace tool-boundary normalization work
-- any follow-up tool UI cleanup should remain subordinate to shared-boundary and data-contract work
+Goal:
+Close the final remaining Shared Foundation checkpoint item:
+- remaining number/string/id helpers still need exact-cluster normalization
 
-2. Reclassify them as rules/instructions:
-- move them to the top roadmap rules/instructions area
-- remove checklist/status markers
-- preserve wording exactly
+Required work:
+1. Find the remaining duplicated or fragmented helper clusters in:
+   - number
+   - string
+   - id
+2. Normalize them using exact-cluster extraction only.
+3. Move them into the correct `src/shared` homes.
+4. Update consumers as needed.
+5. Do NOT perform a broad repo-wide cleanup pass.
+6. Do NOT do blind dedupe.
+7. Update roadmap status markers only.
+8. Report whether the item can now be truthfully marked complete.
 
-3. Do NOT:
-- delete content
-- rewrite wording
-- alter unrelated roadmap text
-
-4. Ensure the checklist/task area only contains actionable work after the move.
-
-5. Final packaging step is REQUIRED:
+Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP.zip`
+  `<project folder>/tmp/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.zip`
 
 Hard rules:
-- move, do not delete
-- no wording changes
+- exact-cluster work only
 - no unrelated repo changes
 - no missing ZIP

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Promote tool roadmap rules out of checklist tracking
-BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP
+Close the remaining number/string/id exact-cluster normalization residue
+BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT

docs/dev/reports/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT_report.md

@@ -0,0 +1,40 @@
+# BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT Report
+
+## Exact Clusters Normalized
+- `string` helpers:
+  - canonical home: `src/shared/string/stringHelpers.js`
+  - public surface: `src/shared/string/index.js`
+- `id` helpers:
+  - canonical home: `src/shared/id/idUtils.js`
+  - public surface: `src/shared/id/index.js`
+- `number` helpers:
+  - canonical home: `src/shared/number/numberUtils.js`
+  - public surface: `src/shared/number/index.js`
+
+## Compatibility Surfaces Kept
+- `src/shared/utils/stringUtils.js` now re-exports from `src/shared/string/stringHelpers.js`
+- `src/shared/utils/idUtils.js` now re-exports from `src/shared/id/idUtils.js`
+- `src/shared/utils/numberUtils.js` now re-exports from `src/shared/number/numberUtils.js`
+
+## Consumers Updated
+- `src/shared/utils/index.js` now routes string/id/number exports through canonical homes.
+- `samples/shared/numberUtils.js` now imports from `src/shared/number/index.js` (single clustered number source).
+- `tools/shared/debugInspectorData.js` now imports number helpers from `src/shared/number/index.js`.
+- `tools/Performance Profiler/main.js` now imports number helpers from `src/shared/number/index.js`.
+- `tools/Replay Visualizer/main.js` now imports number helpers from `src/shared/number/index.js`.
+- `tools/shared/stringUtils.js` now imports `trimSafe` from `src/shared/string/index.js`.
+
+## Focused Validation
+- `node --check` on all touched JS files: PASS
+- `node tests/shared/SharedNumberStringIdCloseout.test.mjs`: PASS
+- `node tests/shared/SharedFoundationCombinedPass.test.mjs`: PASS
+
+## Roadmap Marker
+- Updated to complete:
+  - `remaining number/string/id helpers still need exact-cluster normalization`
+  - in both roadmap copies:
+    - `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
+    - `docs/MASTER_ROADMAP_HIGH_LEVEL.md`
+
+## Completion Decision
+- The checkpoint item is now truthfully complete based on canonical `src/shared/{string,id,number}` cluster homes, compatibility-preserving wrappers, and passing focused validation.

docs/dev/reports/change_summary.txt

@@ -1,3 +1,2 @@
-- Added roadmap cleanup PR for tool-governance rules
-- Moves tool-governance items from checklist/status tracking to top-level roadmap instructions
-- Preserves wording and avoids deletion
+- Added final exact-cluster closeout PR for remaining number/string/id helper normalization
+- Intended to close the last open item in the recent Shared Foundation consolidation checkpoint

docs/dev/reports/validation_checklist.txt

@@ -1,6 +1,8 @@
-- all specified tool-governance items moved to top-level rules/instructions area
-- wording preserved exactly
-- checklist/status markers removed from those items
-- roadmap task areas left with actionable work only
+- remaining number helper residue addressed
+- remaining string helper residue addressed
+- remaining id helper residue addressed
+- only exact-cluster normalization used
+- roadmap updated by status markers only
+- final checkpoint item either marked complete or exact blockers reported
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_ROADMAP_TOOL_RULES_PROMOTION_AND_CLEANUP.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.zip

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -208,7 +208,7 @@
 - [x] duplicated `asNumber` consumers migrated to shared math
 - [x] Asteroids numeric sanitizers promoted into shared math
 - [x] duplicated `asObject` / `asArray` consumers moved to shared utils
-- [ ] remaining number/string/id helpers still need exact-cluster normalization
+- [x] remaining number/string/id helpers still need exact-cluster normalization
 
 ---
 

docs/pr/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.md

@@ -0,0 +1,36 @@
+# BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT
+
+## Purpose
+Close the final remaining item in the Shared Foundation consolidation checkpoint:
+
+- remaining number/string/id helpers still need exact-cluster normalization
+
+## Scope
+Finish exact-cluster normalization for the remaining reusable helper residue in:
+- number helpers
+- string helpers
+- id helpers
+
+## Rules
+- exact-cluster extraction only
+- no broad repo-wide cleanup pass
+- no blind dedupe
+- normalize only helpers that are clearly reusable and correctly owned by `src/shared`
+- preserve domain boundaries
+
+## Required work
+1. Identify the remaining duplicated or fragmented number/string/id helper clusters.
+2. Normalize those helpers into the correct `src/shared` homes.
+3. Update consumers as needed.
+4. Keep changes surgical.
+5. Mark the checkpoint item complete only if truthfully supported.
+
+## Validation
+Codex must report:
+- which exact clusters were normalized
+- where the helpers now live
+- what consumers were updated
+- whether the final checkpoint item can now be marked complete
+
+## Packaging
+`<project folder>/tmp/BUILD_PR_LEVEL_03_EXACT_CLUSTER_NUMBER_STRING_ID_CLOSEOUT.zip`

samples/shared/numberUtils.js

@@ -1,10 +1,7 @@
 export {
+  isFiniteNumber,
   toFiniteNumber,
   asFiniteNumber,
-  asPositiveInteger
-} from "../../src/shared/math/numberNormalization.js";
-
-export {
-  isFiniteNumber,
+  asPositiveInteger,
   asPositiveNumber
-} from "../../src/shared/utils/numberUtils.js";
+} from "../../src/shared/number/index.js";

src/shared/id/idUtils.js

@@ -0,0 +1,33 @@
+import { sanitizeText } from "../string/index.js";
+
+export function isValidId(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+export function normalizeId(value, fallback = "") {
+  const normalized = sanitizeText(value)
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return normalized || sanitizeText(fallback);
+}
+
+export function createId(prefix = "id", randomSource = Math.random) {
+  const safePrefix = normalizeId(prefix, "id");
+  const raw = typeof randomSource === "function" ? randomSource() : Math.random();
+  const token = Number(raw).toString(36).slice(2, 10);
+  return `${safePrefix}-${token || "00000000"}`;
+}
+
+export function createStableId(parts = [], fallback = "id") {
+  const normalized = (Array.isArray(parts) ? parts : [parts])
+    .map((part) => normalizeId(part))
+    .filter(Boolean);
+  const safeFallback = normalizeId(fallback, "id");
+  return normalized.length > 0 ? normalized.join(".") : safeFallback;
+}
+
+export function generateId(prefix = "id", randomSource = Math.random) {
+  return createId(prefix, randomSource);
+}