BUILD PR: optional npm prehook for shared extraction guard.

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,8 +1,7 @@
 MODEL: GPT-5.3-codex
 REASONING: high
 COMMAND:
-Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_20_GUARD_SCRIPT_WIRING_PACKAGE_JSON.md exactly.
-Edit only:
-- package.json (only if it exists and has scripts)
-Fail fast if conditions are not met.
-Package delta to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_20_GUARD_SCRIPT_WIRING_PACKAGE_JSON_delta.zip
+Execute docs/pr/BUILD_PR_SHARED_EXTRACTION_21_OPTIONAL_NPM_PREHOOK_GUARD.md exactly.
+Edit only package.json under defined rules.
+Fail fast if conditions not met.
+Package delta to <project folder>/tmp/BUILD_PR_SHARED_EXTRACTION_21_OPTIONAL_NPM_PREHOOK_GUARD_delta.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-BUILD PR: wire shared extraction guard into package.json script.
+BUILD PR: optional npm prehook for shared extraction guard.

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-Next: continue executable BUILD chain.
+Next: continue BUILD chain.

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Add npm script for guard execution.
+Optional guard auto-run via npm prehooks.

docs/dev/reports/validation_checklist.txt

@@ -1 +1 @@
-package.json script added correctly
+prehook added correctly

docs/pr/BUILD_PR_SHARED_EXTRACTION_21_OPTIONAL_NPM_PREHOOK_GUARD.md

@@ -0,0 +1,55 @@
+# BUILD_PR_SHARED_EXTRACTION_21_OPTIONAL_NPM_PREHOOK_GUARD
+
+## Purpose
+Optionally enforce the shared-extraction guard automatically before existing npm workflows (test or start), without introducing CI or new tooling.
+
+## Single PR Purpose
+Add guard execution as a pre-hook ONLY IF matching scripts already exist.
+
+## Exact Files Allowed
+1. package.json (only if it exists AND already has scripts)
+
+## Fail-Fast Gate
+Before editing:
+1. package.json exists
+2. has scripts section
+3. already contains at least one of:
+   - "test"
+   - "start"
+
+If not:
+- stop
+- no changes
+- no ZIP
+
+## Exact Change
+
+If "test" exists and "pretest" does NOT exist:
+add:
+"pretest": "node tools/dev/checkSharedExtractionGuard.mjs"
+
+If "start" exists and "prestart" does NOT exist:
+add:
+"prestart": "node tools/dev/checkSharedExtractionGuard.mjs"
+
+Rules:
+- do not override existing pretest/prestart
+- do not modify existing scripts
+- minimal insertion only
+
+## Hard Constraints
+- only package.json
+- no new files
+- no logic changes
+- no CI
+- no lint
+
+## Validation Checklist
+1. Only package.json changed
+2. pretest/prestart added only if valid
+3. guard script path correct
+4. existing scripts unchanged
+
+## Non-Goals
+- no CI integration
+- no repo-wide changes

package.json

@@ -1,6 +1,7 @@
 {
   "type": "module",
   "scripts": {
+    "pretest": "node tools/dev/checkSharedExtractionGuard.mjs",
     "test": "node ./scripts/run-node-tests.mjs",
     "build:manifest": "node ./scripts/generate-sample-manifest.mjs",
     "check:shared-extraction-guard": "node tools/dev/checkSharedExtractionGuard.mjs"