From 7990c5f8949af7f7c7a2bd860b34bc8c5ac96916 Mon Sep 17 00:00:00 2001 From: virtualian Date: Sun, 10 May 2026 21:52:23 +0100 Subject: [PATCH] Track #166 progress + audit pai-v5 overlay scaffold MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Backfill status into the design doc (Plans/v5-0-0-plus-port.md) covering issue #166 playbook completion, follow-up issue state on virtualian/pai-v5, and Phase B posture. Add overlay audit findings against the scaffold branch — one drift surfaced (SecurityValidator still present post-PR #170 demotion); flagged for separate cleanup gated on a Phase-B probe. --- Plans/v5-0-0-plus-port.md | 69 ++++++++++ reports/v5-comparison/v5-overlay-audit.md | 161 ++++++++++++++++++++++ 2 files changed, 230 insertions(+) create mode 100644 reports/v5-comparison/v5-overlay-audit.md diff --git a/Plans/v5-0-0-plus-port.md b/Plans/v5-0-0-plus-port.md index 36b0563..f47996e 100644 --- a/Plans/v5-0-0-plus-port.md +++ b/Plans/v5-0-0-plus-port.md @@ -418,6 +418,75 @@ Per parent plan's Step 11 sketch: - Did NOT touch marrair's PAI runtime (only read the snapshot) - Did NOT do personalisation transfer (Phase C) +## Progress / Status (as of 2026-05-10) + +Tracking what has actually landed versus what the doc *plans for*. Updated +on each `166-…` branch that revisits status; the design doc itself remains +the source of truth for *what should happen*. + +### Issue #166 playbook (this repo) + +All 12 playbook steps from the issue body are functionally complete. +Evidence: + +| Step | Status | Evidence | +|---|---|---| +| 1. Tag `pre-v5-baseline-shift` on marrair | ✅ | `git tag` shows `pre-v5-baseline-shift` | +| 2. Branch `sync/v5-baseline-shift` on marrair | ✅ | merged via PR #167 | +| 3. Snapshot marrair runtime | ✅ | `~/backups/pai/runtime-marrair-20260508-002618/` | +| 4. Secret-scan hygiene log | ✅ | `reports/v5-comparison/scan-log.txt` | +| 5. Prepare marrmini (decommission existing PAI) | ✅ | `~/backups/pai/marrmini-pre-v5-20260508-002618/` | +| 6. Clone fork, archive marrair clone | ✅ | `marrair-final` tag | +| 7. Clean v5.0.0 install on marrmini | ✅ | `~/backups/pai/marrmini-fresh-v5.0.0-20260508-021422/` | +| 8. Snapshot post-install marrmini | ✅ | snapshot above | +| 9. Freeze `Releases/v4.0.3+/` | ✅ | `v4.0.3+-final` tag | +| 10. Comparison report | ✅ | targeted diff used in lieu of multi-day prose (per "What This Session Did NOT Do") | +| 11. Design doc | ✅ | this file; landed via PR #167, refined via PR #170 | +| 12. Open PR `sync/v5-baseline-shift` → `main` | ✅ | PR #167 merged 2026-05-09, PR #170 merged 2026-05-10 | + +### Follow-up issues on `virtualian/pai-v5` + +| ID | Title | State | +|---|---|---| +| `virtualian/pai-v5#1` | Port AskUserQuestion ENUMERATE→OFFER phase-exit gate to Algorithm v6.3.0+local (HIGH#1) | OPEN — overlay file populated; wiring + verification pending | +| `virtualian/pai-v5#2` | Port AISTEERINGRULES.md base + `loadAtStartup` wiring (HIGH#2) | OPEN — overlay file + settings.json.overlay wiring populated; runtime verification pending | +| `virtualian/pai-v5#3` | Adopt two-root architecture | CLOSED won't-do — per Decisions Locked | + +### Related issues filed in `virtualian/pai` + +- `#168` — Curate `SKILL.md` descriptions to fit default skill-listing + budget (referenced from MED item #11) +- `#169` — Investigate v5 Learning Loop integration — port-side curation + layer + community research (referenced from MED item #10) + +### Overlay scaffold state on `virtualian/pai-v5:bootstrap/v5-overlay-and-tooling` + +Audited 2026-05-10. Findings detailed in +[`reports/v5-comparison/v5-overlay-audit.md`](../reports/v5-comparison/v5-overlay-audit.md). + +- **Matches design:** README, AISTEERINGRULES.md (95-line runtime), askuq-gate.md, repo-url.ts, WorkArchival.ts, preserve-claudemd{,.test}.ts, settings.json.overlay (partial), deploy-overlay.sh, check-overlay.sh. Seven two-root migrators correctly absent. +- **Drifts from design (PR #170 not yet applied to overlay):** + `hooks/SecurityValidator.hook.ts` (19.4 KB) still present; + `README.md` overlay-contents table still documents it Class A; + `settings.json.overlay` still wires it under `hooks.PreToolUse`. + Per PR #170 demotion these three sites need cleanup. Recommendation: + file a cleanup issue on `virtualian/pai-v5` against the scaffold + branch, gated on a Phase-B trial-session probe to confirm no + concrete destructive-pattern gap surfaces under v5's + SecurityPipeline + PatternInspector chain. +- **Not yet captured (by design, deferred):** MED-priority + `settings.json` keys (item #13 — `autoUpdatesChannel`, + `skillListingBudgetFraction`, etc.), Scope gate overlay file (HIGH#3 + in revised list), MED items 6–12. + +### Phase posture + +Currently mid-**Phase B** (per "Phased Move" table): design doc landed, +overlay scaffold populated for HIGH#1/#2, first daily-work port session +not yet started. Marrair remains primary. marrmini decommission criteria +(this doc, lines 358–377) are 0 of 5 satisfied — HIGH#1 and HIGH#2 still +need overlay-deploy + runtime validation on marrmini before Phase C cutover. + ## References - Parent plan: [`Plans/v5-0-0-is-a-major-keen-wall.md`](v5-0-0-is-a-major-keen-wall.md) diff --git a/reports/v5-comparison/v5-overlay-audit.md b/reports/v5-comparison/v5-overlay-audit.md new file mode 100644 index 0000000..742d459 --- /dev/null +++ b/reports/v5-comparison/v5-overlay-audit.md @@ -0,0 +1,161 @@ +# v5.0.0 Overlay Audit — `virtualian/pai-v5:bootstrap/v5-overlay-and-tooling` + +**Audited:** 2026-05-10 +**Against:** `Plans/v5-0-0-plus-port.md` (as of `f92eafe`, post-PR #170) +**Branch:** `virtualian/pai-v5:bootstrap/v5-overlay-and-tooling` +**Issue:** virtualian/pai#166 + +## Method + +Listed the overlay tree on the scaffold branch via `gh api` +(`/repos/virtualian/pai-v5/git/trees/bootstrap/v5-overlay-and-tooling?recursive=1`, +filtered to `Releases/v5.0.0-overlay/`), then read the `README.md`, +`settings.json.overlay`, and key prose files (`AISTEERINGRULES.md`, +`PAI/ALGORITHM/askuq-gate.md`). Compared file-by-file against the design +doc's "Overlay path strategy" (lines 82–137), "Drop List" (lines 268–278), +and "Decisions Locked" / two-root drop (lines 31, 215–222). Also checked +`Tools/{deploy,check}-overlay.sh` for presence and content. + +## Overlay tree (actual, on `bootstrap/v5-overlay-and-tooling`) + +``` +Releases/v5.0.0-overlay/ +├── README.md (6687 B) +├── settings.json.overlay (1119 B) +├── PAI/ +│ ├── AISTEERINGRULES.md (13334 B — 95-line runtime version) +│ ├── ALGORITHM/ +│ │ └── askuq-gate.md (populated; addendum to v6.3.0 OBSERVE) +│ ├── PAI-Install/ +│ │ └── engine/ +│ │ └── repo-url.ts +│ └── TOOLS/ +│ ├── WorkArchival.ts +│ ├── preserve-claudemd.ts +│ └── preserve-claudemd.test.ts +└── hooks/ + └── SecurityValidator.hook.ts (19441 B) +``` + +Tooling at repo root (`Tools/`): + +- `deploy-overlay.sh` (3217 B) — rsync + jq merge as designed +- `check-overlay.sh` (3590 B) — drift detector as designed +- `BackupRestore.ts`, `validate-protected.ts`, `utilities-icon.png` — pre-existing repo tooling, unrelated to overlay + +## Findings + +### GREEN — overlay matches design + +| Item | Design doc reference | Status | +|---|---|---| +| `README.md` documenting deploy classes A/B/C/D | lines 120–137 | ✅ present | +| `PAI/AISTEERINGRULES.md` (system, 95-line runtime) | line 91 + 134–137 | ✅ present, size consistent with 95 lines | +| `PAI/ALGORITHM/askuq-gate.md` (synthesised addendum) | line 92 | ✅ present, populated | +| `PAI/PAI-Install/engine/repo-url.ts` (v4-only, NOT in 7-helper drop set) | line 102 vs lines 218–221 | ✅ correctly kept | +| `PAI/TOOLS/WorkArchival.ts` (v4-only) | line 104 | ✅ present (MED-priority candidate) | +| `PAI/TOOLS/preserve-claudemd.ts` + test (v4-only) | line 105 | ✅ present (MED-priority candidate) | +| 7 two-root migration helpers absent | Decisions Locked line 31, drop note lines 215–222 | ✅ correctly absent (`pai-paths.ts`, `pai-runtime-migration.ts`, `memory-migration{,.test}.ts`, `skill-migration{,.test}.ts`, `command-migration.ts`, `exec.ts`) | +| `Tools/deploy-overlay.sh` (rsync + jq merge) | line 116 | ✅ present, functional | +| `Tools/check-overlay.sh` (drift detector) | line 117 | ✅ present, functional | +| `settings.json.overlay` wires `PAI/AISTEERINGRULES.md` into `loadAtStartup` | sequencing item #2 lines 342–344 | ✅ wired | +| `settings.json.overlay` sets `voiceEnabled: false` | drop-list line 272 | ✅ wired | + +### RED — overlay drifts from design (post-PR #170 demotion) + +PR #170 ("Refine v5.0.0+ port design: demote SecurityValidator, refresh +Learning scope") moved SecurityValidator from the HIGH-priority port list +to the **Drop List** (design doc lines 276–277). Rationale: + +> v5's `hooks/SecurityPipeline.hook.ts` self-documents (L4–L7) as +> replacing it with a composable `Pattern → Egress → Rules` inspector +> chain... PatternInspector is fail-closed on missing patterns where +> fork is fail-open. v5 ships `PATTERNS.yaml` (156 lines) in baseline. +> No documented residual gap. Verify-first probe deferred to Phase B +> trial sessions; promote back if a concrete gap surfaces. + +The overlay scaffold predates this demotion and still treats +SecurityValidator as an active Class-A port. Three drift sites: + +1. **`hooks/SecurityValidator.hook.ts`** — 19441-byte hook present in + overlay tree. Per design doc this should NOT be in overlay. + +2. **`README.md` overlay-contents table** — documents + `hooks/SecurityValidator.hook.ts` as Class A, citing "vanilla v5.0.0 + has SecurityPipeline + ContentScanner + PromptGuard + ContainmentGuard + but lacks the per-pattern destructive-intent gate." This rationale was + the basis on which PR #170 explicitly demoted the port (the gap is + not documented, v5's chain is held to be sufficient until a concrete + gap surfaces). + +3. **`settings.json.overlay` `hooks.PreToolUse[]` entry** — wires + `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/hooks/SecurityValidator.hook.ts` + under matcher `Bash|Edit|Write|Read`. With the hook dropped, this + entry has no target. + +Net: a follow-up commit on the `bootstrap/v5-overlay-and-tooling` branch +(or a per-issue branch cut from it) needs to: + +- Delete `hooks/SecurityValidator.hook.ts` +- Strip the SecurityValidator row from `README.md` +- Strip the `hooks.PreToolUse` entry from `settings.json.overlay` + +### AMBER — settings.json MED-priority keys not captured + +Design doc item #13 (lines 256–258) enumerates fork-side `settings.json` +customisations as a Class-B MED-priority merge: + +> `autoUpdatesChannel`, `effortLevel`, `enableAllProjectMcpServers`, +> `enabledMcpjsonServers`, `mcpServers`, `remoteControlAtStartup`, +> `showThinkingSummaries`, `skillListingBudgetFraction`, +> `skillListingMaxDescChars`, `verbose` + +Current `settings.json.overlay` carries only `loadAtStartup`, +`voiceEnabled`, and the (stale) `hooks.PreToolUse` entry. The +MED-priority keys are not yet present. This is consistent with their +MED priority — they're sequenced for later — but the overlay should +eventually capture them, and item #11 (skill-listing budget bump) lists +`skillListingBudgetFraction` / `skillListingMaxDescChars` as the +specific fix for the documented skill-budget overflow. + +Not a defect against the current state of the playbook; flagged here so +it doesn't disappear from view. + +### OPEN — by design + +These are absent because the design doc explicitly defers them: + +- **Scope gate overlay file** (HIGH#3 in revised priority list, + formerly HIGH#5) — design doc line 354 says "To file in subsequent + sessions"; no overlay file yet. +- **MED items 6–12** — AgentExecutionGuard hook, SkillGuard hook, + pre-read sweep gate, dependency-analysis micro-phase, Learning + standalone pack, skill-listing budget bump, SessionAutoName hook — + none yet in overlay; per sequencing principle, each becomes its own + per-issue branch when picked up. + +## Recommended follow-ups (NOT executed in this audit) + +1. **File a `bootstrap`-branch cleanup issue on `virtualian/pai-v5`** — + remove the three SecurityValidator drift sites from + `bootstrap/v5-overlay-and-tooling`. Title: "Remove SecurityValidator + from overlay scaffold (per PR #170 demotion)." +2. **Re-confirm the demotion empirically before cleanup** — design doc + says "promote back if a concrete gap surfaces." A Phase-B trial + session on marrmini exercising destructive bash patterns + (`rm -rf` near `$HOME`, broad chmod, etc.) under v5's + SecurityPipeline + PatternInspector chain should be the trigger for + keep-or-delete. +3. **Track skill-listing budget keys as the first MED-priority + `settings.json` candidate** when item #11 / #13 is picked up; the + marrmini-environment.txt evidence of overflow is already on file. + +## References + +- Design doc: [`Plans/v5-0-0-plus-port.md`](../../Plans/v5-0-0-plus-port.md) +- PR #167 (initial scaffold): +- PR #170 (SecurityValidator demotion): +- Bootstrap branch: +- Follow-up issues filed: `virtualian/pai-v5#1` (AskUQ gate, OPEN), + `virtualian/pai-v5#2` (AISTEERINGRULES + loadAtStartup, OPEN), + `virtualian/pai-v5#3` (two-root, CLOSED won't-do)