codex-genesis-harness 0.1.1 → 0.1.4

package/.codex/skills/genesis-harness/resources/post-implementation-guide.md

@@ -0,0 +1,347 @@
+# Post-Implementation Auto-Update Guide
+
+**Purpose**: Automated state synchronization and documentation updates after successful implementation.
+
+**Status**: REFERENCE - Use after implementation is verified and tests pass.
+
+## Quick Reference: What Updates Automatically
+
+After passing all tests and verification:
+
+| Change Type | File to Update | Update Trigger |
+|-------------|---|---|
+| Code implementation | `.codebase/MODULE_INDEX.md` | New module/export added |
+| API changes | `.codebase/API_CONTRACTS.md` | Endpoint behavior changed |
+| Database changes | `.codebase/DOMAIN_MODELS.md` | Schema or entity changed |
+| Route changes | `.codebase/UI_ROUTES.md` | Frontend route added/modified |
+| Test coverage | `.codebase/TEST_MATRIX.md` | New test files created |
+| Module dependencies | `.codebase/DEPENDENCY_GRAPH.md` | Import statements changed |
+| Architecture | `.codebase/ARCHITECTURE.md` | System design changed |
+| Status | `.codebase/CURRENT_STATE.md` | Any public-facing change |
+
+---
+
+## Automated Update Workflow
+
+### Phase 1: Detection (After Implementation Passes Tests)
+
+```
+Trigger: All tests pass + Manual review approved
+┌─────────────────────────────────────────────┐
+│ 1. Scan changed files                       │
+│ 2. Identify type of changes                 │
+│ 3. Check what docs need updating            │
+└─────────────────────────────────────────────┘
+```
+
+**Scan categories:**
+- New files created?
+- Public APIs modified?
+- Database queries changed?
+- Routes added/removed?
+- Configuration changes?
+
+### Phase 2: Analysis (Auto-Detect Impact)
+
+**For each changed file, check:**
+
+```javascript
+if (file in /api || /endpoint) {
+  → Update API_CONTRACTS.md
+  → Run api-contract-skill
+}
+
+if (file contains database/query) {
+  → Update DOMAIN_MODELS.md
+  → Validate schema compatibility
+}
+
+if (file is route/page) {
+  → Update UI_ROUTES.md
+  → Check navigation flow
+}
+
+if (test file added) {
+  → Update TEST_MATRIX.md
+  → Calculate coverage %
+}
+
+if (file in core module) {
+  → Update MODULE_INDEX.md
+  → Check import/export statements
+}
+```
+
+### Phase 3: Documentation Sync
+
+**AUTO-SYNC checklist:**
+
+- [ ] **Module Inventory** (`MODULE_INDEX.md`)
+  ```
+  When: New file/function/export added
+  Auto-Action:
+    - Extract new exports
+    - Document module purpose
+    - Update import paths
+  ```
+
+- [ ] **API Contracts** (`API_CONTRACTS.md`)
+  ```
+  When: API endpoint changed/added
+  Auto-Action:
+    - Extract request/response schemas
+    - Update endpoint paths
+    - Document breaking changes
+  ```
+
+- [ ] **Domain Models** (`DOMAIN_MODELS.md`)
+  ```
+  When: Database schema changed
+  Auto-Action:
+    - Extract new tables/fields
+    - Document relationships
+    - Note migration strategy
+  ```
+
+- [ ] **Test Matrix** (`TEST_MATRIX.md`)
+  ```
+  When: Test files added/removed
+  Auto-Action:
+    - Recalculate coverage %
+    - Update test counts
+    - Flag coverage gaps
+  ```
+
+- [ ] **UI Routes** (`UI_ROUTES.md`)
+  ```
+  When: Frontend routes changed
+  Auto-Action:
+    - Extract new routes
+    - Update navigation flow
+    - Document route params
+  ```
+
+- [ ] **Current State** (`CURRENT_STATE.md`)
+  ```
+  When: Any significant change
+  Auto-Action:
+    - Increment version/phase
+    - Record what changed
+    - Set "Last Updated"
+    - List next steps
+  ```
+
+### Phase 4: Verification
+
+```
+After Auto-Sync:
+
+✓ All updated docs compile without errors?
+✓ Internal links are valid?
+✓ Examples are still accurate?
+✓ Cross-references consistent?
+✓ No stale information?
+```
+
+---
+
+## Manual Post-Implementation Checklist
+
+**Use this AFTER implementation is complete and tests pass:**
+
+- [ ] **Read updated `.codebase/` files**
+  - [ ] CURRENT_STATE.md reflects implementation
+  - [ ] MODULE_INDEX.md includes new modules
+  - [ ] API_CONTRACTS.md has endpoint changes
+  - [ ] TEST_MATRIX.md shows new test coverage
+
+- [ ] **Verify documentation accuracy**
+  - [ ] README examples still work
+  - [ ] API docs match implementation
+  - [ ] Database docs match schema
+  - [ ] UI docs match routing
+
+- [ ] **Check for inconsistencies**
+  - [ ] API_CONTRACTS.md ← → actual endpoints
+  - [ ] DOMAIN_MODELS.md ← → database schema
+  - [ ] UI_ROUTES.md ← → frontend routes
+  - [ ] TEST_MATRIX.md ← → test files
+
+- [ ] **Update derived documents**
+  - [ ] EVOLUTION_PLAN.md (next phase?)
+  - [ ] DEPENDENCY_GRAPH.md (new deps?)
+  - [ ] ARCHITECTURE.md (design impact?)
+  - [ ] KNOWN_PROBLEMS.md (issues found?)
+
+- [ ] **Release documentation**
+  - [ ] Update VERSION file
+  - [ ] Add entry to CHANGELOG
+  - [ ] Update RELEASE_NOTES
+  - [ ] Tag commit appropriately
+
+---
+
+## Docs Skill Integration
+
+### When to invoke `docs-skill` explicitly:
+
+```
+AFTER implementation when:
+  ✓ All tests pass
+  ✓ Code review approved
+  ✓ No more changes expected
+
+RUN: Use docs-skill to:
+  - Sync all changed docs
+  - Update README examples
+  - Verify cross-references
+  - Generate changelog entry
+  - Validate installation docs
+```
+
+**Command reference:**
+```bash
+# After code implementation:
+invoke docs-skill
+
+# Parameters:
+- changed_files: [list of modified files]
+- public_behavior: [what changed from user perspective]
+- verification_results: [test results]
+- affected_users: [who needs to know about changes]
+```
+
+---
+
+## State Continuity: Handoff Document
+
+### Create after implementation for future resumption:
+
+```markdown
+## Implementation Handoff - [Feature/Bug Name]
+
+### What Was Done
+- Module X: Created new authentication handler
+- Module Y: Updated request validation
+- Tests: Added 15 new unit tests
+- Docs: Updated API_CONTRACTS.md
+
+### Files Changed
+- `src/auth/handler.ts` (new)
+- `src/middleware/validator.ts` (modified)
+- `tests/auth.test.ts` (new)
+- `.codebase/API_CONTRACTS.md` (updated)
+
+### Current State
+- All tests passing ✓
+- Code review approved ✓
+- Docs updated ✓
+- Ready for: deployment / next feature
+
+### For Continuation
+If this needs more work later:
+1. Start with `.codebase/CURRENT_STATE.md`
+2. Check KNOWN_PROBLEMS.md for blockers
+3. Review this handoff document
+4. Pick up from "Next Steps" below
+
+### Next Steps
+- [ ] Deploy to staging
+- [ ] Monitor performance metrics
+- [ ] Gather user feedback
+- [ ] Plan Phase 2 features
+```
+
+---
+
+## Auto-Update Triggers (Proposed Implementation)
+
+### Git Hook: Post-Merge / Post-Commit
+
+```bash
+# .git/hooks/post-commit
+if (tests pass) {
+  run-auto-update.sh
+}
+```
+
+### Build Integration: After Successful Build
+
+```bash
+# scripts/post-build.sh
+detect_changes.js \
+  | analyze_impact.js \
+  | update-docs.js
+```
+
+### CI/CD: After Successful Test Suite
+
+```yaml
+# .github/workflows/docs-sync.yml
+on: [push]
+jobs:
+  docs-sync:
+    if: tests passed
+    runs: docs-skill-sync.sh
+```
+
+---
+
+## Troubleshooting Auto-Updates
+
+### Issue: Docs not updating after implementation
+
+**Solution:**
+1. Check git has commit all changes
+2. Verify tests actually passing
+3. Run `scripts/detect-changes.sh` manually
+4. Check for errors in auto-update logs
+
+### Issue: Docs out of sync with code
+
+**Solution:**
+1. Read `.codebase/CURRENT_STATE.md`
+2. Identify what's stale (via TEST_MATRIX.md)
+3. Run `docs-skill` explicitly
+4. Verify all links/examples work
+
+### Issue: Can't understand what changed
+
+**Solution:**
+1. Read IMPLEMENTATION_HANDOFF.md (created after each feature)
+2. Check git diff with `.codebase/` baseline
+3. Review decision-logs in `observability/`
+4. Read PR description or commit messages
+
+---
+
+## Continuous State Tracking
+
+### Quick State Check Command
+
+```bash
+./scripts/state-check.sh
+# Output:
+# ✓ CURRENT_STATE.md is recent (updated 2 hrs ago)
+# ⚠ TEST_MATRIX.md is 3 days old - may need refresh
+# ✓ API_CONTRACTS.md matches current endpoints
+# ✗ DEPENDENCY_GRAPH.md - 5 new dependencies not documented
+```
+
+---
+
+## Next Phase: Full Automation
+
+When ready to implement:
+
+1. **Auto-Detection Script** (detect changes automatically)
+2. **Impact Analysis** (determine what docs to update)
+3. **Docs Regeneration** (auto-update specific sections)
+4. **Validation** (check all links/examples work)
+5. **Notification** (alert team of updates)
+
+---
+
+**Last Updated**: _2026-05-30_  
+**Owner**: _Genesis Harness Team_  
+**Status**: _Reference - Ready to implement automation_

package/.codex/skills/genesis-harness/scripts/check-architecture-boundaries.sh

@@ -1,23 +1,23 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="${1:-.}"
-cd "$root"
-
-status=0
-for file in .planning/ARCHITECTURE.md .planning/diagrams/system-context.mmd .planning/diagrams/container-architecture.mmd; do
-  if [ ! -s "$file" ]; then
-    echo "Missing or empty architecture source: $file"
-    status=1
-  fi
-done
-
-if [ -f .planning/ARCHITECTURE.md ]; then
-  if ! grep -Eiq 'boundary|boundaries|dependency|forbidden|data flow' .planning/ARCHITECTURE.md; then
-    echo "ARCHITECTURE.md should document boundaries, dependency direction, forbidden patterns, or data flow."
-    status=1
-  fi
-fi
-
-exit "$status"
-
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+status=0
+for file in .planning/ARCHITECTURE.md .planning/diagrams/system-context.mmd .planning/diagrams/container-architecture.mmd; do
+  if [ ! -s "$file" ]; then
+    echo "Missing or empty architecture source: $file"
+    status=1
+  fi
+done
+
+if [ -f .planning/ARCHITECTURE.md ]; then
+  if ! grep -Eiq 'boundary|boundaries|dependency|forbidden|data flow' .planning/ARCHITECTURE.md; then
+    echo "ARCHITECTURE.md should document boundaries, dependency direction, forbidden patterns, or data flow."
+    status=1
+  fi
+fi
+
+exit "$status"
+

package/.codex/skills/genesis-harness/scripts/check-docs-sync.sh

@@ -1,24 +1,24 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="${1:-.}"
-cd "$root"
-
-if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  echo "Not a git repository; docs sync check is limited to required files."
-  test -f .planning/SPEC_CHANGELOG.md
-  exit $?
-fi
-
-changed="$(git diff --name-only HEAD 2>/dev/null || git diff --name-only)"
-docs_changed="$(printf '%s\n' "$changed" | grep -E '^(\.planning/|docs/|README\.md|AGENTS\.md)' || true)"
-code_changed="$(printf '%s\n' "$changed" | grep -Ev '^(\.planning/|docs/|README\.md|AGENTS\.md)$' || true)"
-
-if [ -n "$code_changed" ] && [ -z "$docs_changed" ]; then
-  echo "Code changed but no planning/docs files changed."
-  echo "$code_changed"
-  exit 1
-fi
-
-echo "Docs sync check passed or no code changes detected."
-
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "Not a git repository; docs sync check is limited to required files."
+  test -f .planning/SPEC_CHANGELOG.md
+  exit $?
+fi
+
+changed="$(git diff --name-only HEAD 2>/dev/null || git diff --name-only)"
+docs_changed="$(printf '%s\n' "$changed" | grep -E '^(\.planning/|docs/|README\.md|AGENTS\.md)' || true)"
+code_changed="$(printf '%s\n' "$changed" | grep -Ev '^(\.planning/|docs/|README\.md|AGENTS\.md)$' || true)"
+
+if [ -n "$code_changed" ] && [ -z "$docs_changed" ]; then
+  echo "Code changed but no planning/docs files changed."
+  echo "$code_changed"
+  exit 1
+fi
+
+echo "Docs sync check passed or no code changes detected."
+

package/.codex/skills/genesis-harness/scripts/check-no-debug-logs.sh

@@ -1,21 +1,21 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="${1:-.}"
-cd "$root"
-
-exclude='\.planning/|\.codex/skills/|node_modules/|vendor/|\.git/|build/|dist/|coverage/'
-pattern='console\.log|debugger;|var_dump\(|dd\(|print_r\(|pdb\.set_trace\(|binding\.pry|puts\s+["'\'']DEBUG|System\.out\.println'
-
-if command -v rg >/dev/null 2>&1; then
-  matches="$(rg -n --hidden -g '!.planning' -g '!.codex/skills' -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!coverage' "$pattern" . || true)"
-else
-  matches="$(grep -RInE "$pattern" . 2>/dev/null | grep -Ev "$exclude" || true)"
-fi
-
-if [ -n "$matches" ]; then
-  echo "$matches"
-  exit 1
-fi
-
-echo "No obvious debug logs found."
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+exclude='\.planning/|\.codex/skills/|node_modules/|vendor/|\.git/|build/|dist/|coverage/'
+pattern='console\.log|debugger;|var_dump\(|dd\(|print_r\(|pdb\.set_trace\(|binding\.pry|puts\s+["'\'']DEBUG|System\.out\.println'
+
+if command -v rg >/dev/null 2>&1; then
+  matches="$(rg -n --hidden -g '!.planning' -g '!.codex/skills' -g '!node_modules' -g '!vendor' -g '!dist' -g '!build' -g '!coverage' "$pattern" . || true)"
+else
+  matches="$(grep -RInE "$pattern" . 2>/dev/null | grep -Ev "$exclude" || true)"
+fi
+
+if [ -n "$matches" ]; then
+  echo "$matches"
+  exit 1
+fi
+
+echo "No obvious debug logs found."

package/.codex/skills/genesis-harness/scripts/check-required-planning-files.sh

@@ -1,46 +1,46 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="${1:-.}"
-cd "$root"
-
-required=(
-  ".planning/PROJECT.md"
-  ".planning/REQUIREMENTS.md"
-  ".planning/ROADMAP.md"
-  ".planning/STATE.md"
-  ".planning/STACK.md"
-  ".planning/ARCHITECTURE.md"
-  ".planning/DESIGN.md"
-  ".planning/API_DOCS.md"
-  ".planning/INTEGRATIONS.md"
-  ".planning/CONVENTIONS.md"
-  ".planning/PITFALLS.md"
-  ".planning/LESSONS_LEARNED.md"
-  ".planning/SPEC_CHANGELOG.md"
-  ".planning/FEATURE_INDEX.md"
-  ".planning/CHANGE_IMPACT_MATRIX.md"
-  ".planning/QUALITY_SCORE.md"
-  ".planning/ESCALATION.md"
-  ".planning/OBSERVABILITY.md"
-  ".planning/SMOKE_TESTS.md"
-  ".planning/JOURNEYS.md"
-  ".planning/SUMMARY.md"
-  ".planning/config.json"
-  ".planning/diagrams/system-context.mmd"
-  ".planning/diagrams/container-architecture.mmd"
-  ".planning/diagrams/database-erd.mmd"
-  ".planning/diagrams/deployment-flow.mmd"
-  ".planning/diagrams/roadmap-flow.mmd"
-)
-
-missing=0
-for file in "${required[@]}"; do
-  if [ ! -f "$file" ]; then
-    echo "Missing: $file"
-    missing=1
-  fi
-done
-
-exit "$missing"
-
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+required=(
+  ".planning/PROJECT.md"
+  ".planning/REQUIREMENTS.md"
+  ".planning/ROADMAP.md"
+  ".planning/STATE.md"
+  ".planning/STACK.md"
+  ".planning/ARCHITECTURE.md"
+  ".planning/DESIGN.md"
+  ".planning/API_DOCS.md"
+  ".planning/INTEGRATIONS.md"
+  ".planning/CONVENTIONS.md"
+  ".planning/PITFALLS.md"
+  ".planning/LESSONS_LEARNED.md"
+  ".planning/SPEC_CHANGELOG.md"
+  ".planning/FEATURE_INDEX.md"
+  ".planning/CHANGE_IMPACT_MATRIX.md"
+  ".planning/QUALITY_SCORE.md"
+  ".planning/ESCALATION.md"
+  ".planning/OBSERVABILITY.md"
+  ".planning/SMOKE_TESTS.md"
+  ".planning/JOURNEYS.md"
+  ".planning/SUMMARY.md"
+  ".planning/config.json"
+  ".planning/diagrams/system-context.mmd"
+  ".planning/diagrams/container-architecture.mmd"
+  ".planning/diagrams/database-erd.mmd"
+  ".planning/diagrams/deployment-flow.mmd"
+  ".planning/diagrams/roadmap-flow.mmd"
+)
+
+missing=0
+for file in "${required[@]}"; do
+  if [ ! -f "$file" ]; then
+    echo "Missing: $file"
+    missing=1
+  fi
+done
+
+exit "$missing"
+

package/.codex/skills/genesis-harness/scripts/check-spec-changelog.sh

@@ -1,24 +1,24 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="${1:-.}"
-cd "$root"
-
-if [ ! -f .planning/SPEC_CHANGELOG.md ]; then
-  echo "Missing .planning/SPEC_CHANGELOG.md"
-  exit 1
-fi
-
-if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
-  changed="$(git diff --name-only HEAD 2>/dev/null || git diff --name-only)"
-  spec_affecting="$(printf '%s\n' "$changed" | grep -E 'api|route|schema|migration|model|ui|component|config|env|auth|security|integration' || true)"
-  changelog_changed="$(printf '%s\n' "$changed" | grep -x '.planning/SPEC_CHANGELOG.md' || true)"
-  if [ -n "$spec_affecting" ] && [ -z "$changelog_changed" ]; then
-    echo "Spec-affecting files changed but SPEC_CHANGELOG.md was not updated:"
-    echo "$spec_affecting"
-    exit 1
-  fi
-fi
-
-echo "Spec changelog check passed."
-
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+if [ ! -f .planning/SPEC_CHANGELOG.md ]; then
+  echo "Missing .planning/SPEC_CHANGELOG.md"
+  exit 1
+fi
+
+if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  changed="$(git diff --name-only HEAD 2>/dev/null || git diff --name-only)"
+  spec_affecting="$(printf '%s\n' "$changed" | grep -E 'api|route|schema|migration|model|ui|component|config|env|auth|security|integration' || true)"
+  changelog_changed="$(printf '%s\n' "$changed" | grep -x '.planning/SPEC_CHANGELOG.md' || true)"
+  if [ -n "$spec_affecting" ] && [ -z "$changelog_changed" ]; then
+    echo "Spec-affecting files changed but SPEC_CHANGELOG.md was not updated:"
+    echo "$spec_affecting"
+    exit 1
+  fi
+fi
+
+echo "Spec changelog check passed."
+

package/.codex/skills/genesis-harness/scripts/check-task-tracking.sh

@@ -1,25 +1,25 @@
-#!/usr/bin/env bash
-set -euo pipefail
-
-root="${1:-.}"
-cd "$root"
-
-if [ ! -d .planning ]; then
-  echo "Missing .planning directory."
-  exit 1
-fi
-
-status=0
-while IFS= read -r file; do
-  case "$file" in
-    *TASKS.md|*PLAN.md|*REVIEW.md|*VERIFICATION.md|.planning/ROADMAP.md|.planning/STATE.md|.planning/SUMMARY.md)
-      if ! grep -Eq '\[( |~|x|!)\]' "$file"; then
-        echo "No checkbox tracking found: $file"
-        status=1
-      fi
-      ;;
-  esac
-done < <(find .planning -type f -name '*.md' | sort)
-
-exit "$status"
-
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+if [ ! -d .planning ]; then
+  echo "Missing .planning directory."
+  exit 1
+fi
+
+status=0
+while IFS= read -r file; do
+  case "$file" in
+    *TASKS.md|*PLAN.md|*REVIEW.md|*VERIFICATION.md|.planning/ROADMAP.md|.planning/STATE.md|.planning/SUMMARY.md)
+      if ! grep -Eq '\[( |~|x|!)\]' "$file"; then
+        echo "No checkbox tracking found: $file"
+        status=1
+      fi
+      ;;
+  esac
+done < <(find .planning -type f -name '*.md' | sort)
+
+exit "$status"
+