feat(os): enrich instruction files with Phase 0 intake gate & sync upstream OS rules

.agent/rules/destructive-action-guard.md

@@ -54,51 +54,37 @@ This verification applies before:
 
 ### Verification Protocol
 
-### Step 1 — Extract the target from each file
-
+#### Step 1 — Extract the target from each file
 For a single-line text stand-in at path `P` containing relative path `T`:
 ```bash
 cat P  # confirm single line, relative path
 ```
 
-### Step 2 — Repo-wide target search
-
+#### Step 2 — Repo-wide target search
 ```bash
 git ls-files | grep -i "<filename>"
 ```
 - **Target found in repo** → classify as **MISLOCATED_REFERENCE** — do not delete; propose correct path
 - **Target not found** → proceed to Step 3
 
-**Decision:**
-- Target found in repo → classify as **MISLOCATED_REFERENCE** — do not delete; propose correct path
-- Target not found → proceed to Step 3
-
-### Step 3 — Git history check
-
+#### Step 3 — Git history check
 ```bash
 git log --all --oneline --full-history -- "**/filename"
 ```
 - **File existed and was recently deleted** → classify as **POSSIBLE_ACCIDENTAL_DELETION** — add to Map Debt; do not delete
 - **File only appears in consolidation/migration commits with no subsequent history** → likely safe, classify as **DEAD_CROSS_REPO_REFERENCE**
 
-**Decision:**
-- File existed and was recently deleted → classify as **POSSIBLE_ACCIDENTAL_DELETION** — add to Map Debt; do not delete
-- File only appears in consolidation/migration commits with no subsequent history → likely safe, classify as **DEAD_CROSS_REPO_REFERENCE**
-
-### Step 4 — SKILL_ALIAS check (commands/ and agents/)
-
+#### Step 4 — SKILL_ALIAS check (commands/ and agents/)
 If content matches `../skills/<name>/SKILL.md` pattern AND the target SKILL.md exists:
 - Classify as **SKILL_ALIAS** → convert to symlink via `symlink_manager create`, do not delete
 
-### Step 5 — Produce audit table before any change
-
-Output this table and wait for implicit confirmation (no new instruction = proceed, conflict = stop):
+#### Step 5 — Produce audit table before any change
+Output this table and wait for explicit confirmation:
 
 | File | Target | Exists in Repo | Classification | Action |
 |------|--------|----------------|----------------|--------|
 
-### Step 6 — Kill switch
-
+#### Step 6 — Kill switch
 **Stop and output the audit table only (no changes)** if any of the following:
 - 5+ files classified `POSSIBLE_ACCIDENTAL_DELETION`
 - Any ambiguity in target resolution
@@ -116,9 +102,6 @@ Output this table and wait for implicit confirmation (no new instruction = proce
 
 ---
 
-The consolidation from 26 → 11 plugins left pre-consolidation stand-ins with cross-repo paths
-that never existed post-merge. Blind deletion passes treat MISLOCATED and DEAD references
-identically — but only DEAD ones are safe to remove. The distinction requires a git search.
+## Why This Rule Exists
 
-This incident was caught during the dev-utils Opus review (2026-06-28): 19 stand-ins identified,
-repo search revealed MISLOCATED and SKILL_ALIAS cases that would have been incorrectly deleted.
+The consolidation of repository plugins left pre-consolidation stand-ins with cross-repo paths that never existed post-merge. Blind deletion passes treat MISLOCATED and DEAD references identically — but only DEAD ones are safe to remove. The distinction requires git verification. Similarly, agents routinely rationalize deleting functional skills under the guise of "cleanup" or "absorption". This rule unifies both protections under one strict gate.

.agent/rules/git-operations.md

@@ -110,30 +110,21 @@ Never skip hooks with `--no-verify` unless the user explicitly requests it.
 - Auto-modified files like `.DS_Store` or `uv.lock` should not be committed unless relevant.
 - When `skills-lock.json` or `symlinks.json` changes as a direct result of adding/modifying skills or plugins, commit them together with the changes.
 
-### 8. Mandatory Pre-Branch Fetch & Pull Gate
-Before executing `git worktree add` or `git checkout -b` for ANY feature or chore:
-1. Switch to `main`: `git checkout main`
-2. Fetch and pull latest remote: `git fetch origin main && git pull origin main`
-3. Verify local matches remote: `git rev-parse HEAD` equals `git rev-parse origin/main`.
-Branching from an un-pulled local state is strictly prohibited.
-
-### 9. Strict Working-Directory Confinement & Cross-Repo Protocol
-All commands, tool executions, and file edits MUST remain strictly within the current repository tree (`InvestmentToolkit`). Never pass `-C ../<dir>`, never reference files outside the workspace root, and never inspect or touch parallel repositories (such as `agent-plugins-skills`) unless explicitly reviewed, approved, or authorized by the user.
-
-When cross-repository ecosystem work in `agent-plugins-skills` is authorized:
-1. **Pre-Flight Baseline**: Run `git status --short` in target repo. If uncommitted changes exist, STOP immediately and consult user.
-2. **Remote Synchronization**: Run `git checkout main && git fetch origin main && git pull origin main`. Verify `HEAD == origin/main`.
-3. **Scope Approval & Worktree Isolation**: Confirm exact change approval, then create isolated worktree: `git worktree add -b <branch> .worktrees/<name> main`.
-4. **Implement, Test & PR**: Execute strictly within worktree, run tests, commit, push, open PR. Never self-merge.
-5. **Post-Merge Hygiene**: After user merges, `git fetch origin main`, verify ancestor (`git merge-base --is-ancestor`), fast-forward `main`, remove worktree (`git worktree remove --force`), delete local and remote feature branch, verify clean state (`git branch --list`, `git worktree list`).
-6. **Downstream Resync**: In `InvestmentToolkit`, run `sync_with_inventory.py` and `plugin_add.py plugins/ -y` to propagate updates.
-
-### 10. Git Worktree Hard Invariants
-- **Path Standard**: Always use `.worktrees/<branch-slug>` inside repository root; never `/tmp/`, home directories, or arbitrary locations.
-- **Main Checkout Cleanliness**: The main checkout remains untouched on `main` while a worktree is active.
-- **Never Raw `rm -rf`**: Always remove worktrees with `git worktree remove --force .worktrees/<name>`. Using raw `rm -rf` leaves stale administrative refs in `.git/worktrees/`.
-- **Data Isolation**: Gitignored data files (e.g. `domain_model.sqlite`) do not carry over to worktrees; always verify final database writes landed on the main checkout.
-- **Leak Verification**: Before opening a PR from a worktree, run `git status --short` on the main checkout to ensure no edits leaked outside the worktree.
+### 10. Evolution Integrity Gate — update map-debt BEFORE committing core logic
+Any commit that touches files under `plugins/`, `src/`, or `py_services/` **must** do one of the following before `git commit`:
+- Stage an update to `references/map-debt.md` recording the debt entry (RESOLVED or OPEN) for the change, **OR**
+- Stage an update to `references/evolution-log.md` if one exists, **OR**
+- Include `Evolution-Check: none` in the commit message body with a one-line justification.
+
+**Failure mode this prevents:** committing core logic changes and only discovering the missing map-debt entry when CI fails on the PR — forcing a follow-up commit and a broken CI run.
+
+**Correct sequence:**
+1. Make code changes
+2. Update `references/map-debt.md` (add or resolve the relevant DEBT entry)
+3. `git add <code files> references/map-debt.md`
+4. `git commit`
+
+The CI gate (`Verify Evolution & Map Debt Compliance`) enforces this post-hoc. The rule enforces it pre-emptively. Both must be respected.
 
 ## Approval Required
 

.agent/rules/graph-planning-superpowers-policy.md

@@ -33,10 +33,7 @@ Phase 3: Deterministic Exit Gates & Asymmetric Persistence (6-State Vocabulary +
 
 ## 2. Phase 0: Pre-Planning Intake Bookend & Socratic Gate
 
-### 2.1. Native Read-Only Plan Sandboxing
-- Before generating code, you MUST enter host-native Plan Mode (Claude Code `/plan` / `Shift+Tab` or Copilot `@plan`).
-- While in Plan Mode, filesystem mutations and write operations are **strictly prohibited**. Use only read-only search and AST analysis tools.
-- The output must be written to an immutable spec/plan contract (e.g., `docs/plans/<feature-id>.md` or `~/.claude/plans/`).
+Before Plan Mode can ever be entered, the task must be bounded:
 
 1. **Read-Only Exploration Cycle:**
    - Execute read-only codebase discovery via `exploration-cycle-plugin` (`technical_diagnostic_engine.py`).
@@ -56,17 +53,14 @@ Phase 3: Deterministic Exit Gates & Asymmetric Persistence (6-State Vocabulary +
 
 ## 3. Phase 1: Native Plan Mode & Adversarial Review
 
-### 3.1. Worktree State Isolation & Graph Execution
-- Execute implementation subagents strictly within dedicated `git worktree` branches (`../worktree-<feature-name>`).
-- Subagents must not execute in shared or dirty working trees.
-- High-assurance, multi-step tasks must execute as a deterministic Directed Acyclic Graph (DAG) state machine via [`agent-orchestration:graph-execution`](../plugins/agent-orchestration/skills/graph-execution/SKILL.md), enforcing Proposal Mode, Verifier Sovereignty, and Asymmetric Persistence.
-- Delegation between director and worker agents follows the [`agent-orchestration:dual-loop`](../plugins/agent-orchestration/skills/dual-loop/SKILL.md) pattern (or [`agent-orchestration:co-pilot-loop`](../plugins/agent-orchestration/skills/co-pilot-loop/SKILL.md) for fast-tier models).
-
-### 3.2. Strict Red-Green-Refactor Enforcement
-- Invoke `superpowers/test-driven-development` protocols:
-  1. **Red:** Author concrete unit/integration test cases against the contract. Verify they FAIL.
-  2. **Green:** Implement minimum functional code to make tests pass.
-  3. **Refactor:** Clean up code while maintaining green test status.
+1. **Native Plan Sandboxing:**
+   - Enforce host-native Plan Mode (Claude `/plan`, Copilot `@plan`, Antigravity plan mode) where available. Defer to Superpowers graph planning *only* when native host planning is absent or when executing complex multi-agent DAGs.
+   - While in Plan Mode, filesystem mutations outside plan artifacts are strictly prohibited.
+2. **Pre-Execution Critic Review:**
+   - Run clean-context adversarial review via `critical-auditor` (max 2–3 rounds) probing failure domains and cross-plugin boundaries before human presentation.
+3. **The Supreme Law Human Gate:**
+   - Present plan and require explicit user approval ("Proceed", "Go", "Execute").
+   - On approval, transition task to `APPROVED` in `context/control_plane.db`.
 
 ---
 
@@ -102,22 +96,7 @@ Phase 3: Deterministic Exit Gates & Asymmetric Persistence (6-State Vocabulary +
 
 ## 6. Git & Environment Invariants
 
-- **NEVER** commit directly to `main`. **ALWAYS** use a feature branch.
-- **NEVER** run `git push` without explicit, fresh approval.
-- **NEVER** "auto-fix" via git operations.
-- **HALT** immediately on any user "Stop/Wait" command.
-- Write descriptive commit messages in the imperative mood.
-- **NEVER** commit agent directories (`.agents/`, `.claude/`, `.gemini/`, `.codex/`) to version control. They contain session data and secrets.
-- Any planning artifacts created inside an isolated git worktree will be deleted when the worktree is removed. Sync these to the main checkout directory before merging.
-
----
-
-## 7. Context Management
-
-- **Build context, then maintain it.** Do not redundantly re-read unchanged artifacts in a single session.
-- **Never** use blind full-repo sweeps (`grep`, `find`, or `ls -R`); use targeted native `rg` / exact scoped file matches or structured directories. Zero background daemons required.
-
----
-**Renamed**: 2026-08-27 (from `spec-driven-development-policy.md` — dropped "Spec-Kit" branding; this repo does not use the spec-kitty tool)
-**Refactored**: 2026-08-27 — replaced with the three-phase Graph Planning, Superpowers, and Execution Discipline lifecycle (native Plan Mode sandboxing, context-bundler adversarial convergence capped at 2-3 rounds, worktree-isolated TDD, multi-stage verification)
-**Ratified**: 2026-05-22 | **Replaces**: `constitution.md`, `AGENTS.md`, legacy `spec_driven_development_policy.md`
+- **NEVER** commit directly to `main`. Always use isolated branches.
+- **NEVER** run `git push` without explicit approval.
+- **NEVER** commit transient agent directories (`.agents/`, `.claude/`, `.gemini/`, `.codex/`).
+- UTF-8 encoding only. No smart quotes or non-ASCII characters in manifests and rules.

.agent/rules/local-worktree-and-dual-repo-edit-protocol.md

@@ -0,0 +1,153 @@
+---
+description: Mandatory end-to-end protocol and checklist for authoring edits, worktrees, commits, PRs, user merge, branch cleanup, cross-repo plugin sync, and post-sync health checks.
+globs: ["**/*"]
+---
+
+# Dual-Repo & Worktree Edit Lifecycle Protocol
+
+## Purpose
+This rule formalizes the end-to-end execution protocol when modifying plugins, skills, or platform code—whether upstream in `agent-plugins-skills` or downstream in consumer repositories like `InvestmentToolkit`.
+
+It eliminates conversational friction and guessing by establishing an explicit, deterministic checklist: from branch creation to PR review, user merge, branch deletion, two-repo plugin reinstall, and final health check verification.
+
+---
+
+## The End-to-End Lifecycle Protocol
+
+```mermaid
+flowchart TD
+    A[Phase 0: Socratic Intake & Spec] --> B[Phase 1: Worktree / Feature Branch]
+    B --> C[Phase 2: TDD / Implementation]
+    C --> D[Phase 3: Pre-Push Quality Gates]
+    D --> E[Phase 4: Commit & Push to Feature Branch]
+    E --> F[Phase 5: Open PR & Notify User]
+    F --> G[Phase 6: User Merges PR on GitHub]
+    G --> H[Phase 7: Fetch & Fast-Forward Local Main]
+    H --> I[Phase 8: Branch & Worktree Cleanup]
+    I --> J[Phase 9: Dual-Repo Reinstall & Resync]
+    J --> K[Phase 10: Mandatory Post-Sync Health Check]
+```
+
+---
+
+## 10-Phase Lifecycle Checklist
+
+### Phase 0: Intake, Control Plane & Planning Gate
+- [ ] Task registered in `context/control_plane.db` (`python3 scripts/agent_control.py init` or kernel event).
+- [ ] Read-only discovery conducted; 1–3 Socratic scoping questions presented with `[Recommended]` answers.
+- [ ] Implementation plan approved by the user before creating branches or modifying code.
+
+### Phase 1: Worktree / Branch Creation
+- [ ] In downstream repo (`InvestmentToolkit`), use a git worktree:
+  ```bash
+  git worktree add -b feat/<branch-name> ../InvestmentToolkit-<branch-name> main
+  ```
+- [ ] In upstream repo (`agent-plugins-skills`), checkout a dedicated feature branch:
+  ```bash
+  git checkout -b feat/<branch-name>
+  ```
+- [ ] Ensure gitignored files / dependencies required for tests are initialized or linked.
+
+### Phase 2: TDD & Implementation
+- [ ] Follow Test-Driven Development (failing test or verification contract first).
+- [ ] Implement required changes; refactor at 50+ lines or 3+ nesting levels.
+- [ ] Adhere to coding conventions and standard file headers.
+
+### Phase 3: Pre-Push Quality & Regression Gates
+- [ ] Run test suite:
+  - Upstream (`agent-plugins-skills`): `pytest plugins/agent-agentic-os/tests/`
+  - Downstream (`InvestmentToolkit`): `python3 run_tests.py`
+- [ ] Run compliance & convention audits:
+  ```bash
+  python3 plugins/dev-utils/scripts/workspace_conventions_auditor.py  # if present
+  python3 .agents/skills/symlink-manager/scripts/symlink_manager.py diagnose
+  ```
+- [ ] Confirm clean working state without stray diffs (`git status --short`).
+
+### Phase 4: Commit & Push
+- [ ] Stage required files explicitly (`git add <files>`).
+- [ ] Commit with conventional commit message (`feat(...)`, `fix(...)`, `refactor(...)`).
+- [ ] Push directly to remote feature branch:
+  ```bash
+  git push -u origin feat/<branch-name>
+  ```
+
+### Phase 5: Open PR & Hand Off to User (DO NOT AUTO-MERGE)
+- [ ] Open Pull Request via GitHub CLI:
+  ```bash
+  gh pr create --repo <owner/repo> --title "feat: ..." --body "## Summary..."
+  ```
+- [ ] Report PR link and state to user ("Pushed to origin, PR link below, awaiting user merge").
+- [ ] **STOP AND WAIT**: The user MUST review and merge the PR on GitHub. Never merge the PR autonomously.
+
+### Phase 6: User Merge Signal
+- [ ] The user reviews and merges the PR on GitHub, then informs the agent ("merged", "PR merged", etc.).
+
+### Phase 7: Fetch & Fast-Forward Local Main
+- [ ] Switch to root repository on `main`:
+  ```bash
+  git checkout main
+  git fetch origin
+  git pull origin main
+  ```
+- [ ] Verify the merge commit is an ancestor of `main`:
+  ```bash
+  git merge-base --is-ancestor <branch-tip> main
+  ```
+
+### Phase 8: Branch & Worktree Cleanup (Mandatory Loop Closure)
+- [ ] In downstream repo (`InvestmentToolkit`), remove the merged worktree:
+  ```bash
+  git worktree remove ../InvestmentToolkit-<branch-name>
+  ```
+- [ ] Delete local feature branch:
+  ```bash
+  git branch -d feat/<branch-name>
+  ```
+- [ ] Delete remote feature branch:
+  ```bash
+  git push origin --delete feat/<branch-name>
+  ```
+- [ ] Confirm clean worktree list and branch list:
+  ```bash
+  git worktree list
+  git branch --list
+  ```
+
+### Phase 9: Dual-Repo Reinstall & Resync
+- [ ] **Step 9A: Upstream (`agent-plugins-skills`)**:
+  - Re-run OS initialization/retrofit:
+    ```bash
+    python3 plugins/agent-agentic-os/scripts/init_agentic_os.py --target . --retrofit
+    ```
+  - Reinstall universal plugin copies:
+    ```bash
+    python3 plugins/plugin-manager/scripts/plugin_add.py --all -y
+    ```
+- [ ] **Step 9B: Downstream (`InvestmentToolkit`)**:
+  - Resync plugins from inventory:
+    ```bash
+    python3 .agents/skills/plugin-syncer/scripts/sync_with_inventory.py
+    ```
+  - Re-run OS initialization/retrofit to align instruction mirrors (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) and rules:
+    ```bash
+    python3 .agents/skills/os-init/scripts/init_agentic_os.py --target . --retrofit
+    ```
+
+### Phase 10: Mandatory Post-Sync Health Check
+- [ ] Deterministically verify all OS substrates are active:
+  ```bash
+  test -f context/control_plane.db && echo "OK control_plane.db" || echo "MISSING control_plane.db"
+  test -f .claude/hooks/hooks.json && echo "OK hooks.json" || echo "MISSING hooks.json"
+  test -f .git/hooks/pre-commit-evolution-guard && echo "OK pre-commit-guard" || echo "MISSING pre-commit-guard"
+  test -f .github/workflows/verify-evolution-integrity.yml && echo "OK verify-evolution-integrity.yml" || echo "MISSING verify-evolution-integrity.yml"
+  ```
+- [ ] Run canonical tests in downstream repo:
+  ```bash
+  python3 run_tests.py
+  ```
+- [ ] Verify symlink integrity:
+  ```bash
+  python3 .agents/skills/symlink-manager/scripts/symlink_manager.py diagnose
+  ```
+- [ ] Present final health check summary to user.