gm-oc 2.0.402 → 2.0.404

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gm-oc",
-  "version": "2.0.402",
+  "version": "2.0.404",
   "description": "State machine agent with hooks, skills, and automated git enforcement",
   "author": "AnEntrypoint",
   "license": "MIT",

package/skills/gm/SKILL.md

@@ -126,6 +126,53 @@ Invoke `browser` skill. Escalation — exhaust each before advancing:
 
 Completing a phase is NOT stopping. After every phase: read .prd, check git, invoke next skill. Only when .prd is deleted AND git is clean AND all commits are pushed may you return a final response to the user.
 
+## MANDATORY DEV WORKFLOW — ABSOLUTE RULES
+
+These rules apply to ALL phases. Violations trigger immediate snake to planning.
+
+**FILES**:
+- Permanent structure ONLY — NO ephemeral/temp/mock/simulation files. Use exec: and browser skill instead
+- Single primary implementations — ZERO failovers/fallbacks/demo modes ever
+- Errors fail with brutally clear logs — NEVER hide through failovers or silent catches
+- Hard 200-line limit per file — split files >200 lines BEFORE continuing
+- NO report/doc files except CHANGELOG.md, CLAUDE.md, README.md, TODO.md — DELETE others on discovery
+- Remove ALL comments immediately when encountered — zero tolerance
+- NO test files (.test.js, .spec.js, __tests__/) — manual testing only via exec: and browser skill
+- Clean ALL files not required for the program to function
+
+**CODE QUALITY**:
+- ALWAYS scan codebase (exec:codesearch) before editing — find everything that touches the same concern
+- **Duplicate concern = snake to planning**: overlapping responsibility, similar logic in different places, parallel implementations, or code that could be consolidated. Snake to `planning` with consolidation instructions
+- After every file write: run exec:codesearch for the primary function/concern you just wrote. If ANY other code serves the same concern → snake to `planning` with consolidation instructions. This is not optional — it is a gate
+- When a native feature, stdlib function, or convention replaces custom code → delete the custom code. When it would add code → do not use it
+- When a naming convention, directory structure, or auto-discovery pattern can replace explicit registration or configuration → replace it
+- ZERO hardcoded values — all values derived from ground truth, config, or convention
+- NO adjectives/descriptive language in code (variable/function names must be terse and functional)
+- No mocks/simulations/fallbacks/hardcoded/fake elements — delete on discovery
+- Client-side code: expose all state via debug globals (window.__debug or similar)
+
+**ERROR HANDLING**:
+- Every error must throw and propagate with clear context
+- No `|| defaultValue`, no `catch { return null }`, no graceful degradation
+- The only acceptable error handling: catch → log the real error → re-throw or display to user
+
+**DEBUGGING**:
+- ALWAYS hypothesize/troubleshoot via execution BEFORE editing any files
+- Check git history (`git log`, `git diff`) for troubleshooting known regressions — never revert, use differential comparisons and edit new code manually
+- Keep execution logs concise (<4k chars ideal, 30k max)
+- Clear cache before playwright/browser debugging
+
+**DOCUMENTATION** (update at every phase transition, not at the end):
+- CLAUDE.md: after each structural change, update technical info. NO progress/changelogs
+- TODO.md: add items when discovered, remove when done. File must not exist at completion
+- CHANGELOG.md: append entry after each commit
+- After push: deploy if deployable, publish if npm package
+
+**PROCESS**:
+- Only persistent background shells for long-running CLI processes
+- Test via exec: and browser skill — NO test files ever
+- Test locally before live
+
 ## CONSTRAINTS
 
 **Tier 0**: no_crash, no_exit, ground_truth_only, real_execution, fail_loud
@@ -133,8 +180,6 @@ Completing a phase is NOT stopping. After every phase: read .prd, check git, inv
 **Tier 2**: no_duplication, no_hardcoded_values, modularity
 **Tier 3**: no_comments, convention_over_code
 
-**FAIL LOUD — NO FALLBACKS**: Never create fallback modes, demo modes, graceful degradation, silent error swallowing, or try/catch that returns a default value instead of propagating the error. Every error must throw and propagate. If something fails, the user must see exactly what failed and why. No `|| defaultValue`, no `catch { return null }`, no "demo mode", no "offline mode", no degraded functionality. The only acceptable error handling is: catch → log the real error → re-throw or display to user.
-
-**Never**: `Bash(node/npm/npx/bun)` | skip planning | sequential independent items | screenshot before JS exhausted | narrate past unresolved mutables | stop while .prd has items | ask the user what to do next while work remains | create fallback/demo modes | silently swallow errors
+**Never**: `Bash(node/npm/npx/bun)` | skip planning | sequential independent items | screenshot before JS exhausted | narrate past unresolved mutables | stop while .prd has items | ask the user what to do next while work remains | create fallback/demo modes | silently swallow errors | duplicate concern | leave comments | create test files | leave stale architecture when changes reveal restructuring opportunity
 
-**Always**: invoke named skill at every transition | snake to planning on any new unknown | witnessed execution only | keep going until .prd deleted and git clean
+**Always**: invoke named skill at every transition | snake to planning on any new unknown | snake to planning when duplicate concern or restructuring opportunity discovered | witnessed execution only | scan codebase before edits | keep going until .prd deleted and git clean

package/skills/gm-complete/SKILL.md

@@ -118,9 +118,28 @@ gh run list --repo AnEntrypoint/<downstream-repo> --limit 3 --json databaseId,na
 ```
 Monitor any cascade runs the same way — poll, diagnose failures, fix if the cause is in this repo.
 
+## CODEBASE HYGIENE SWEEP
+
+Before declaring complete, sweep the entire codebase for violations:
+
+1. **Files >200 lines** → split immediately
+2. **Comments in code** → remove all
+3. **Test files** (.test.js, .spec.js, __tests__/) → delete
+4. **Mock/stub/simulation files** → delete
+5. **Unnecessary doc files** (not CHANGELOG/CLAUDE/README/TODO.md) → delete
+6. **Duplicate concern** (overlapping responsibility, similar logic, parallel implementations, consolidatable code) → snake to `planning` with restructuring instructions — do not patch locally
+7. **Hardcoded values** → derive from ground truth, config, or convention
+8. **Fallback/demo modes** → remove, fail loud instead
+9. **TODO.md** → must be empty/deleted before completion
+10. **CHANGELOG.md** → must have entries for this session's changes
+11. **CLAUDE.md** → must reflect current technical state
+12. **Deploy/publish** → if deployable, deploy. If npm package, publish.
+
+Any violation found = fix immediately before advancing.
+
 ## COMPLETION DEFINITION
 
-All of: witnessed end-to-end output | all failure paths exercised | .prd empty | git clean and pushed | all CI runs green | `user_steps_remaining=0`
+All of: witnessed end-to-end output | all failure paths exercised | .prd empty | git clean and pushed | all CI runs green | codebase hygiene sweep clean | TODO.md empty/deleted | CHANGELOG.md updated | `user_steps_remaining=0`
 
 ## DO NOT STOP
 
@@ -128,9 +147,9 @@ After end-to-end verification passes: read .prd from disk. If any items remain,
 
 ## CONSTRAINTS
 
-**Never**: claim done without witnessed output | uncommitted changes | unpushed commits | failed CI runs | .prd items remaining | stop at first green | absorb surprises silently | respond to user while .prd has items
+**Never**: claim done without witnessed output | uncommitted changes | unpushed commits | failed CI runs | .prd items remaining | TODO.md with items remaining | stop at first green | absorb surprises silently | respond to user while .prd has items | skip hygiene sweep | leave comments/mocks/test files/fallbacks
 
-**Always**: triage failure before snaking | witness end-to-end | snake to planning on any new unknown | enumerate remaining after every success | check .prd after every verification pass
+**Always**: triage failure before snaking | witness end-to-end | snake to planning on any new unknown | enumerate remaining after every success | check .prd after every verification pass | run hygiene sweep before declaring complete | deploy/publish if applicable | update CHANGELOG.md
 
 ---
 

package/skills/gm-emit/SKILL.md

@@ -71,11 +71,18 @@ Pre-emit revealing unexpected behavior → new unknown → snake to `planning`.
 - Pre-emit debug passed with real inputs and error inputs
 - Post-emit verification matches pre-emit exactly
 - Hot reloadable: state outside reloadable modules, handlers swap atomically
-- Crash-proof: catch at every boundary, recovery hierarchy
-- No mocks/fakes/stubs anywhere
-- Files ≤200 lines, no duplicate code, no comments, no hardcoded values
-- No fallbacks, demo modes, or silent error swallowing — every error must throw and propagate
+- Errors throw with clear context — no fallbacks, demo modes, silent swallowing, `|| default`, `catch { return null }`
+- No mocks/fakes/stubs/simulations/test files anywhere — delete on discovery
+- Files ≤200 lines — split immediately if over, do not advance
+- No duplicate concern — after writing, run exec:codesearch for the primary concern. If ANY other code serves the same concern → do NOT advance, snake to `planning` with consolidation instructions
+- No comments — remove any found
+- No hardcoded values — dynamic/modular code using ground truth only
+- No adjectives/descriptive language in variable/function names
+- No unnecessary files — clean anything not required for the program to function
+- Client-side code exposes debug globals (window.__debug or similar)
 - CLAUDE.md reflects actual behavior
+- CHANGELOG.md updated with changes
+- TODO.md cleared or deleted
 
 ## CODEBASE EXPLORATION
 
@@ -92,7 +99,7 @@ Invoke `browser` skill. Escalation: (1) `exec:browser\n<js>` → (2) `browser` s
 
 ## SELF-CHECK (before and after each file)
 
-File ≤200 lines | No duplication | Pre-emit passed | No mocks | No comments | Docs match | All spotted issues fixed
+File ≤200 lines | No duplicate concern | Pre-emit passed | No mocks | No comments | Docs match | All spotted issues fixed
 
 ## DO NOT STOP
 

package/skills/gm-execute/SKILL.md

@@ -114,7 +114,11 @@ Invoke `browser` skill. Escalation — exhaust each before advancing:
 
 ## GROUND TRUTH
 
-Real services, real data, real timing. Mocks/fakes/stubs = delete immediately. No .test.js/.spec.js. Delete on discovery.
+Real services, real data, real timing. Mocks/fakes/stubs/simulations = delete immediately. No .test.js/.spec.js. Delete on discovery. No fallback/demo modes — errors must fail loud with clear logs.
+
+**SCAN BEFORE EDIT**: Before modifying or creating any file, search the codebase (exec:codesearch) for existing implementations of the same concern. "Duplicate" means overlapping responsibility, similar logic, or parallel implementations — not just identical files. If consolidation is possible, snake to `planning` with restructuring instructions instead of continuing.
+
+**HYPOTHESIZE VIA EXECUTION**: Always troubleshoot and validate hypotheses through witnessed execution BEFORE editing files. Never edit based on assumptions — run the code first, observe the actual behavior, then edit with ground truth.
 
 ## DO NOT STOP
 
@@ -122,9 +126,9 @@ Never respond to the user from this phase. When all mutables are KNOWN, immediat
 
 ## CONSTRAINTS
 
-**Never**: `Bash(node/npm/npx/bun)` | fake data | mock files | Glob/Grep/Read/Explore (hook-blocked — use exec:codesearch) | sequential independent items | absorb surprises silently | respond to user or pause for input
+**Never**: `Bash(node/npm/npx/bun)` | fake data | mock files | test files | fallback/demo modes | Glob/Grep/Read/Explore (hook-blocked — use exec:codesearch) | sequential independent items | absorb surprises silently | respond to user or pause for input | edit files before executing to understand current behavior | duplicate existing code
 
-**Always**: witness every hypothesis | import real modules | snake to planning on any new unknown | fix immediately on discovery | invoke next skill immediately when done
+**Always**: witness every hypothesis | import real modules | scan codebase before creating/editing files | snake to planning on any new unknown | fix immediately on discovery | delete mocks/stubs/comments/test files on discovery | invoke next skill immediately when done
 
 ---
 

package/skills/planning/SKILL.md

@@ -39,6 +39,8 @@ Planning = exhaustive mutable discovery. For every aspect of the task ask:
 
 Categories of unknowns to enumerate: file existence | API shape | data format | dependency versions | runtime behavior | environment differences | error conditions | concurrency | integration points | backwards compatibility | rollback paths | deployment steps | verification criteria
 
+**MANDATORY CODEBASE SCAN**: For every planned item, add `existingImpl=UNKNOWN` mutable. Resolve by running exec:codesearch for the concern (not the implementation). If existing code serves the same concern → the .prd item becomes a consolidation task, not an addition. The plan restructures existing code to absorb the new requirement — never bolt new code alongside existing code that does related work.
+
 ## .PRD FORMAT
 
 Path: exactly `./.prd` in current working directory. **JSON array** written via `exec:nodejs`.