Docs/pr merge runbook

.agent-os/instructions/core/pr-merge-runbook.md

@@ -0,0 +1,84 @@
+# PR Merge Runbook — Truth Kernel Branches
+
+Purpose: deterministically open and merge our three current branches using either the GitHub UI or the repo’s helper script. This file is the canonical reference for future threads.
+
+## Branches
+1. **PR 1** (audit fix) → `fix/audit-hyphenated-identifiers` → `main`
+2. **PR 2** (node test runner) → `test/node-runner` → `main`
+3. **PR 3** (docs) → `docs/truthlens-readme-status` → `main` (after rebasing on merged PR1+PR2)
+
+---
+
+## Option A — GitHub UI (simplest)
+1. Open each “Compare & pull request” link for the three branches.
+2. Titles/Bodies:
+   - PR 1 — **Title:** `fix(audit): ignore code blocks; tighten pronoun detection`  
+     **Body:** Refines simulation detection to skip fenced/inline code and avoid hyphen/underscore-bound identifiers. Adds unit tests.
+   - PR 2 — **Title:** `test: switch to Node built-in runner; convert audit tests`  
+     **Body:** Replaces Mocha semantics with node:test. Updates package.json test script. Ensures zero-deps test execution in CI.
+   - PR 3 — **Title:** `docs: TruthLens runtime + audit; compliance quick checks; Codex workflow`  
+     **Body:** README adds TruthLens + CI gate overview; STATUS adds compliance quick checks; TruthLens policy page gains canonical pointers.
+3. Labels:
+   - PR 1: `truth-kernel`, `audit`
+   - PR 2: `tests`, `truth-kernel`
+   - PR 3: `docs`, `truth-kernel`
+4. Merge order:
+   - Merge PR 1 → Merge PR 2 → Rebase `docs/truthlens-readme-status` on `main`, then open & merge PR 3.
+
+---
+
+## Option B — Helper script (no gh CLI)
+**Prereq:** create a GitHub Personal Access Token (repo scope). Export it in your shell:
+```bash
+export GITHUB_TOKEN=<YOUR_REPO_SCOPED_TOKEN>
+```
+Run these commands from the repo root (Ubuntu).
+
+### 1) PR 1 — audit fix
+```bash
+node tools/gh-pr-open-and-merge.cjs \
+  --repo mrhpython/Soulfield \
+  --base main \
+  --head fix/audit-hyphenated-identifiers \
+  --title "fix(audit): ignore code blocks; tighten pronoun detection" \
+  --body "Refines simulation detection to skip fenced/inline code and avoid hyphen/underscore-bound identifiers. Adds unit tests." \
+  --labels "truth-kernel,audit"
+```
+### 2) PR 2 — node test runner
+```bash
+node tools/gh-pr-open-and-merge.cjs \
+  --repo mrhpython/Soulfield \
+  --base main \
+  --head test/node-runner \
+  --title "test: switch to Node built-in runner; convert audit tests" \
+  --body "Replaces Mocha semantics with node:test. Updates package.json test script. Ensures zero-deps test execution in CI." \
+  --labels "tests,truth-kernel"
+```
+### 3) Rebase docs branch after PR 1 & 2 merge
+```bash
+git switch docs/truthlens-readme-status
+git fetch origin
+git rebase origin/main
+npm ci && npm test && node backend/scripts/audit-truth.cjs
+```
+### 4) PR 3 — docs
+```bash
+node tools/gh-pr-open-and-merge.cjs \
+  --repo mrhpython/Soulfield \
+  --base main \
+  --head docs/truthlens-readme-status \
+  --title "docs: TruthLens runtime + audit; compliance quick checks; Codex workflow" \
+  --body "README adds TruthLens + CI gate overview; STATUS adds compliance quick checks; TruthLens policy page gains canonical pointers." \
+  --labels "docs,truth-kernel"
+```
+
+---
+
+## Notes
+- TruthLens is the governing policy; all outputs are wrapped at runtime:contentReference[oaicite:5]{index=5} and documented as OS intent:contentReference[oaicite:6]{index=6}.
+- Non-simulation contract applies to all agent outputs:contentReference[oaicite:7]{index=7}.
+- CI gate runs the Truth audit + tests on every push/PR.
+
+## Troubleshooting
+- If the helper reports “CI failed”, click into the PR checks to view logs. Fix locally, push to the branch, rerun the helper.
+- If `git rebase` reports conflicts, resolve locally, `git add <files> && git rebase --continue`, then rerun the PR 3 helper command.

.github/workflows/ci.yml

@@ -2,9 +2,11 @@ name: CI
 
 on:
   push:
+<<<<<<< HEAD
+=======
     branches: [ main, feat/**, fix/**, docs/**, chore/** ]
+>>>>>>> origin/main
   pull_request:
-    branches: [ main ]
 
 jobs:
   node:
@@ -19,8 +21,28 @@ jobs:
           cache: 'npm'
       - name: Install deps
         run: npm ci
+<<<<<<< HEAD
+      - name: API health (offline)
+        run: |
+          DEV_NO_API=1 node backend/index.cjs & echo $! > api.pid
+          for i in {1..20}; do
+            if curl -fsS http://127.0.0.1:8790/health >/dev/null; then
+              curl -fsS http://127.0.0.1:8790/health | tee health.json; break
+            fi
+            sleep 0.3
+          done
+          kill $(cat api.pid)
+      - name: Run ESLint (npx ESLint v8)
+        run: npx -y eslint@8 .
+        continue-on-error: true
+      - name: Lint (if present)
+        run: npm run -s lint --if-present
+      - name: Test (if present)
+        run: npm run -s test --if-present
+=======
       - name: Run tests (node:test)
         run: npm test
+>>>>>>> origin/main
 
   python:
     runs-on: ubuntu-latest
@@ -31,5 +53,22 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: '3.11'
+<<<<<<< HEAD
+      - name: Install deps (if requirements.txt)
+        run: |
+          if [ -f requirements.txt ]; then
+            python -m pip install --upgrade pip
+            pip install -r requirements.txt
+          fi
+      - name: Run pytest if tests are present
+        run: |
+          if ls -1 tests test_*.py 2>/dev/null | grep -q .; then
+            pip install pytest
+            PYTHONPATH=. pytest -q
+          else
+            echo "No python tests found; skipping"
+          fi
+=======
       - name: Sanity
         run: python --version
+>>>>>>> origin/main