Adopt the hwp-editor bridge, and land Phase 2 + Phase 3 planning

.planning/PROJECT.md

@@ -43,17 +43,21 @@ real files the user owns, and nothing is lost if Maru is uninstalled.
   auto-update via minisign-verified `latest.json`
 - ✓ Measured and gated startup/bundle budgets (320 KiB gzip initial JS, 70 KiB
   CSS, lazy GraphView/RichMarkdownEditor/i18n chunks)
+- ✓ `make verify` is a signal a refactor can be trusted against — Phase 1
+  (pinned rust-toolchain 1.98.0, fmt-check + clippy gates, ESLint four-rule
+  gate wired into verify, `e2e/`+`scripts/` typechecked, CI trace on e2e
+  failure with no retries; UAT 24/24)
+- ✓ One shared generated-directory prune list replaces the diverged copies —
+  Phase 2 (`crate::paths::GENERATED_DIRS`, 14-entry union, six consumers)
+- ✓ One shared path-containment helper is the canonical one for new commands —
+  Phase 2 (`crate::paths::ensure_within`, lexical, plus `require_absolute`
+  guarding `maru_home()`/`install_root_base()`)
 
 ### Active
 
 <!-- Milestone 1: structural debt paydown. Scoped to the Tech Debt section of
      .planning/codebase/CONCERNS.md. -->
 
-- [ ] `make verify` is a signal a refactor can be trusted against (Rust lint
-      gate, hook-dependency gate, `e2e/`+`scripts/` typechecked, CI traces on
-      e2e failure, pinned Rust toolchain)
-- [ ] One shared generated-directory prune list replaces the five diverged copies
-- [ ] One shared path-containment helper is the canonical one for new commands
 - [ ] Errors the frontend branches on carry a typed `code`, not a string prefix
 - [ ] `src/App.tsx` no longer owns pane state - `OutlinePane`, `EditorPane`,
       `DocumentList`, and `TerminalPanel` read module stores instead of 71/55/40/25-prop
@@ -62,7 +66,9 @@ real files the user owns, and nothing is lost if Maru is uninstalled.
 ### Out of Scope
 
 - **New product features of any kind** - this milestone preserves behavior; a
-  feature landing mid-refactor makes every regression ambiguous
+  feature landing mid-refactor makes every regression ambiguous. One recorded
+  exception: the `hwped_*` hwp-editor bridge, written by a parallel track and
+  adopted here rather than built (STATE.md "Scope Exceptions")
 - **Converting all 1,118 `Result<T, String>` signatures** - CONCERNS.md rejects
   it explicitly; only the errors the frontend actually branches on move
 - **Retrofitting all ~20 existing path-traversal validators** - the existing
@@ -173,12 +179,12 @@ ones this milestone can actually break are listed here.
 |----------|-----------|---------|
 | Milestone 1 = structural debt paydown, no features | Behavior-preserving work is only verifiable if behavior is not also changing | - Pending |
 | Scope drawn from CONCERNS.md Tech Debt, not from the SPECs | 18 ingested docs describe shipped behavior; inventing forward work from them would be fabrication | - Pending |
-| Verification gates land before the decomposition (Phase 1) | Moving 68 `useState` / 50 `useEffect` without a hook-dependency gate reproduces #260/#262/#264 | - Pending |
+| Verification gates land before the decomposition (Phase 1) | Moving 68 `useState` / 50 `useEffect` without a hook-dependency gate reproduces #260/#262/#264 | ✓ Phase 1 — 7 gates live, deliberate-break proofs red-then-green, UAT 24/24 |
 | Continue the module-store precedent instead of adding a state library | `errorStore`/`workspaceStore`/`editorTabsStore` already prove the pattern here | - Pending |
 | Typed error contract covers only branched-on errors | Converting 1,118 signatures is cost without benefit; display-only errors read fine as strings | - Pending |
-| Promote `ensure_within`, do not retrofit all ~20 callers | Existing checks are individually sound; the problem is that a new author has no canonical example | - Pending |
+| Promote `ensure_within`, do not retrofit all ~20 callers | Existing checks are individually sound; the problem is that a new author has no canonical example | ✓ Phase 2 — promoted to `crate::paths`, doc + tests as the example, zero retrofits |
 | Phases 4-5 get no `UI hint` annotation | They refactor UI state plumbing with pixel-identical output as the success criterion; a UI design spec would be the wrong downstream suggestion | - Pending |
 | 64 SPEC constraints recorded as invariants, not decisions | 0 ADRs in the set - nothing is decision-locked, so a future ADR can override any of them | - Pending |
 
 ---
-*Last updated: 2026-08-22 after initial project definition from /gsd-ingest-docs + /gsd-map-codebase*
+*Last updated: 2026-08-23 after Phase 2*

.planning/REQUIREMENTS.md

@@ -23,11 +23,11 @@ milestone with no end-user-visible surface.
 
 ### Scanner and Path Invariants
 
-- [ ] **SCAN-01**: Adding a generated directory to the prune list is a one-line edit in one place, and all five scanners pick it up
-- [ ] **SCAN-02**: Workspace and vault scans no longer descend into `.git` or `.venv`
-- [ ] **SCAN-03**: A canonical path-containment helper is importable outside `maru_dir.rs`, and a new path-accepting command author has one obvious example to copy
-- [ ] **SCAN-04**: Joining a home-rooted path against a non-absolute base fails loudly instead of materializing a directory tree inside the repo
-- [ ] **SCAN-05**: The stray `Users/yj.lee/.maru/env/` tree is gone from the repo root
+- [x] **SCAN-01**: Adding a generated directory to the prune list is a one-line edit in one place, and all five scanners pick it up
+- [x] **SCAN-02**: Workspace and vault scans no longer descend into `.git` or `.venv`
+- [x] **SCAN-03**: A canonical path-containment helper is importable outside `maru_dir.rs`, and a new path-accepting command author has one obvious example to copy
+- [x] **SCAN-04**: Joining a home-rooted path against a non-absolute base fails loudly instead of materializing a directory tree inside the repo
+- [x] **SCAN-05**: The stray `Users/yj.lee/.maru/env/` tree is gone from the repo root
 
 ### Typed IPC Errors
 
@@ -102,7 +102,7 @@ not compete with the structural work. Not in the current roadmap.
 
 | Feature | Reason |
 |---------|--------|
-| Any new product feature | Behavior-preserving work is only verifiable if behavior is not also changing |
+| Any new product feature | Behavior-preserving work is only verifiable if behavior is not also changing. **Exception, 2026-08-23:** the `hwped_*` hwp-editor bridge landed from a parallel track and is adopted, not built, by this milestone - see STATE.md "Scope Exceptions" |
 | Converting all 1,118 `Result<T, String>` signatures | Explicitly rejected in the CONCERNS.md fix approach; cost without benefit for display-only errors |
 | Retrofitting all ~20 existing path-traversal validators | The existing checks are individually sound; the problem is the absence of a canonical example, not the callers |
 | Changing `.maruignore` defaults | It is a user-facing file format, not a scanner constant |
@@ -122,11 +122,11 @@ not compete with the structural work. Not in the current roadmap.
 | GATE-05 | Phase 1 | Complete |
 | GATE-06 | Phase 1 | Complete |
 | GATE-07 | Phase 1 | Complete |
-| SCAN-01 | Phase 2 | Pending |
-| SCAN-02 | Phase 2 | Pending |
-| SCAN-03 | Phase 2 | Pending |
-| SCAN-04 | Phase 2 | Pending |
-| SCAN-05 | Phase 2 | Pending |
+| SCAN-01 | Phase 2 | Complete |
+| SCAN-02 | Phase 2 | Complete |
+| SCAN-03 | Phase 2 | Complete |
+| SCAN-04 | Phase 2 | Complete |
+| SCAN-05 | Phase 2 | Complete |
 | ERR-01 | Phase 3 | Pending |
 | ERR-02 | Phase 3 | Pending |
 | ERR-03 | Phase 3 | Pending |

.planning/ROADMAP.md

@@ -21,8 +21,8 @@ mode-routing chain. Nothing user-visible changes in any phase; that is the point
 
 Decimal phases appear between their surrounding integers in numeric order.
 
-- [ ] **Phase 1: Trustworthy Verify Signal** - Make `make verify` and CI tell the truth about a behavior-preserving change
-- [ ] **Phase 2: Shared Scanner and Path Invariants** - Collapse five prune lists and ~20 containment checks into one of each
+- [x] **Phase 1: Trustworthy Verify Signal** - Make `make verify` and CI tell the truth about a behavior-preserving change (completed 2026-08-23)
+- [x] **Phase 2: Shared Scanner and Path Invariants** - Collapse five prune lists and ~20 containment checks into one of each (completed 2026-08-23)
 - [ ] **Phase 3: Typed IPC Error Contract** - Give the errors the frontend branches on a machine-readable code
 - [ ] **Phase 4: Editor Surface State Extraction** - Move `OutlinePane` and `EditorPane` off their prop bundles onto module stores
 - [ ] **Phase 5: Shell Decomposition Completion** - Move the remaining panes and mode routing out of `MainApp`
@@ -87,7 +87,17 @@ Notes for planning:
   4. A test proves that joining a `maru_home()`/`env_root()` result against a non-absolute base panics or errors rather than creating a tree in the working directory
   5. `Users/yj.lee/.maru/env/` no longer exists at the repo root
 
-**Plans**: TBD
+**Plans**: 3/3 plans executed
+
+Plans:
+**Wave 1**
+
+- [x] 02-01-PLAN.md - Tracer: create `src-tauri/src/paths.rs` (GENERATED_DIRS union + ensure_within + require_absolute), register it, rewire workspace_files/content_search, promote ensure_within into maru_dir (SCAN-01, SCAN-02, SCAN-03)
+
+**Wave 2** *(blocked on Wave 1 completion)*
+
+- [x] 02-02-PLAN.md - Rewire vault/secrets/project_activity/evidence_binder to the union; red-then-green SCAN-02 union-proof test; .maru retained module-locally (SCAN-01, SCAN-02)
+- [x] 02-03-PLAN.md - SCAN-04 absolute-base guard inside maru_home()/install_root_base() + regression test + delete stray Users/ tree (SCAN-04, SCAN-05)
 
 Notes for planning:
 
@@ -109,7 +119,21 @@ Notes for planning:
   3. No `message.includes("<error_code>")` matcher remains in `src/` for a code that moved to the contract
   4. The `Result<T, String>` count in `src-tauri/src/` is essentially unchanged from today's 1,118 - display-only errors were not touched
 
-**Plans**: TBD
+**Plans**: 0/4 plans executed
+
+Plans:
+**Wave 1**
+
+- [ ] 03-01-PLAN.md - Tracer: IpcError struct + TS mirror + normalizer, proven end-to-end on evidence_binder_revision_conflict; real-app smoke checkpoint ratifying the 7-command scope (ERR-01, ERR-02)
+
+**Wave 2** *(blocked on Wave 1 completion)*
+
+- [ ] 03-02-PLAN.md - Migrate the today and document Rust domains to IpcError; map_err adapter for today_ai; record the ERR-04 count (ERR-01, ERR-04)
+- [ ] 03-03-PLAN.md - Normalize the today/save funnels, migrate all five branch sites to err.code, retire todayErrorCode, align e2e fixtures (ERR-01, ERR-03)
+
+**Wave 3** *(blocked on Wave 2 completion)*
+
+- [ ] 03-04-PLAN.md - ERR-02 rename drill (red-then-revert both sides), ERR-04 count guard, ERR-03 residual grep, full make verify (ERR-02, ERR-03, ERR-04)
 
 Notes for planning:
 
@@ -169,9 +193,9 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Trustworthy Verify Signal | 7/7 | In Progress|  |
-| 2. Shared Scanner and Path Invariants | 0/TBD | Not started | - |
-| 3. Typed IPC Error Contract | 0/TBD | Not started | - |
+| 1. Trustworthy Verify Signal | 7/7 | Complete    | 2026-08-23 |
+| 2. Shared Scanner and Path Invariants | 3/3 | Complete    | 2026-08-23 |
+| 3. Typed IPC Error Contract | 0/4 | Not started | - |
 | 4. Editor Surface State Extraction | 0/TBD | Not started | - |
 | 5. Shell Decomposition Completion | 0/TBD | Not started | - |
 

.planning/STATE.md

@@ -2,51 +2,52 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
-current_phase: 1
-current_phase_name: Trustworthy Verify Signal
+current_phase: 3
+current_phase_name: Typed IPC Error Contract
 status: executing
-stopped_at: Completed 01-07-PLAN.md - Phase 1 fully executed, GATE-02 flipped, all 7 plans done
-last_updated: "2026-08-22T10:12:57.572Z"
-last_activity: 2026-08-22
-last_activity_desc: Roadmap created from /gsd-ingest-docs intel + /gsd-map-codebase
+stopped_at: Phase 3 context gathered
+last_updated: "2026-08-22T23:53:08.966Z"
+last_activity: 2026-08-23
+last_activity_desc: Phase 1 complete, transitioned to Phase 2
 progress:
-  total_phases: 1
-  completed_phases: 1
-  total_plans: 7
-  completed_plans: 7
+  total_phases: 3
+  completed_phases: 2
+  total_plans: 14
+  completed_plans: 10
 ---
 
 # Project State
 
 ## Project Reference
 
-See: .planning/PROJECT.md (updated 2026-08-22)
+See: .planning/PROJECT.md (updated 2026-08-23)
 
 **Core value:** The filesystem stays the source of truth - everything Maru shows is derived from real files the user owns, and nothing is lost if Maru is uninstalled.
-**Current focus:** Phase 1 - Trustworthy Verify Signal
+**Current focus:** Phase 02 — Shared Scanner and Path Invariants
 
 ## Current Position
 
-Phase: 1 of 5 (Trustworthy Verify Signal)
-Plan: 7 of 7 in current phase
+Phase: 3 — Typed IPC Error Contract
+Plan: Not started
 Status: Ready to execute
-Last activity: 2026-08-22 - Completed 01-01 (rust-toolchain.toml pin + fmt-check gate)
+Last activity: 2026-08-23 — Phase 2 complete, transitioned to Phase 3
 
 Progress: [██████████] 100%
 
 ## Performance Metrics
 
 **Velocity:**
 
-- Total plans completed: 0
+- Total plans completed: 10
 - Average duration: -
 - Total execution time: -
 
 **By Phase:**
 
 | Phase | Plans | Total | Avg/Plan |
 |-------|-------|-------|----------|
-| - | - | - | - |
+| 1 | 7 | - | - |
+| 2 | 3 | - | - |
 
 **Recent Trend:**
 
@@ -65,6 +66,9 @@ Progress: [██████████] 100%
 | Phase 01 P05 | 15min | 3 tasks | 8 files |
 | Phase 01-trustworthy-verify-signal P06 | 20min | 3 tasks | 4 files |
 | Phase 01-trustworthy-verify-signal P07 | 70min | 3 tasks | 30 files |
+| Phase 02 P01 | 9min | 3 tasks | 6 files |
+| Phase 02 P02 | 5min | 3 tasks | 4 files |
+| Phase 02 P03 | 7min | 2 tasks | 3 files |
 
 ## Accumulated Context
 
@@ -96,18 +100,45 @@ Recent decisions affecting current work:
 - [Phase 1]: Positional/required-interface unused args (favoriteIds, settings, warnings, hdbg, headerBg) renamed with a leading underscore rather than deleted, since deletion would have required touching call sites or type signatures outside this plan's fix-not-rewrite mandate
 - [Phase 1]: GATE-02 flipped - make lint added to the verify prerequisite list immediately after typecheck, proven red-then-green on both react-hooks/exhaustive-deps and no-unused-vars via deliberate break-and-revert on src/components/today/useTodayTasks.ts
 - [Phase 1]: Full make verify could not be proven green on the shared checkout - test-rust failed on 12 outlook_mso timeout tests racing a concurrent session's own cargo test --workspace process, and cargo clippy/fmt-check both fail solely inside the concurrent session's uncommitted src-tauri/src/hwped.rs; neither traces to this plan's diff (zero Rust files touched). Each gate this plan owns was verified individually instead (make lint both directions, pnpm typecheck, pnpm test, make test-e2e, all green); CI is the authoritative composite check, to be triggered by the team lead
+- [Phase ?]: [Phase 2]: mod paths; registered between outlook_mso and project_activity (true alphabetical, rustfmt-verified) - plan-stated ops_catalog/outlook_mso slot violates the strictly-alphabetical registry convention
+- [Phase ?]: [Phase 2]: vault.rs could_include_dot_folder_named deleted (lost its only caller when rg_visibility went unconditional) rather than kept as dead code under the clippy gate
+- [Phase ?]: [Phase 2]: ensure_within error message kept byte-identical (Path escapes the .maru directory) - live user-visible string in a behavior-preserving phase (RESEARCH Pitfall 4)
+- [Phase ?]: [Phase 2]: 02-02 union-proof fixture leaves written as .md documents instead of the plan's literal .pyc/extensionless/.py leaves - scan_vault only collects md/markdown/html/htm, so the literal fixture could never go red and the SCAN-02 proof required the change
+- [Phase ?]: [Phase 2]: 02-03 guard shape - maru_home()/install_root_base() restructured to a single exit wrapped in require_absolute, so a future early-return cannot bypass the check without restructuring the exit
+- [Phase ?]: [Phase 2]: 02-03 env_root()/skills_root() get no separate guard - they derive from maru_home() and are covered transitively; duplicating the check would re-fragment the invariant
+- [Phase ?]: [Phase 2]: 02-03 require_absolute's temporary allow(dead_code) removed in the same commit the first consumer landed - closes WINDOWS.md ledger entry 1
+
+### Scope Exceptions
+
+- **hwp-editor bridge (`hwped_*`), recorded 2026-08-23.** Six Tauri commands
+  (`src-tauri/src/hwped.rs`, wrappers in `src/lib/hwped.ts`) spawning the `hwp`
+  binary landed from a parallel track while this milestone was running. They are a
+  new product feature, which the milestone charter excludes, so they are recorded
+  here as an adopted exception rather than milestone work: this milestone owns the
+  gate signal, not the feature. Phases 1 and 2 each reported `make verify` as
+  unprovable locally because this file failed `clippy` and `fmt-check` while
+  untracked (`01-06-SUMMARY.md`, `01-07-SUMMARY.md`, `02-02-SUMMARY.md`); those two
+  clippy findings and the formatting diffs are fixed in the same commit that adopts
+  it, so the composite gate runs against the same tree CI sees.
+- The bridge's error strings (`cli_missing:`, `hwp_timeout:`, `hwp_failed:`,
+  `hwp_parse_failed:`, `hwped_bad_request:`) stay `Result<T, String>` and are
+  **exempt from the Phase 3 typed contract**. `src/lib/hwped.ts` contains no error
+  branching at all, so they are display-only - exactly the class ERR-04 protects
+  from migration.
+- Still owed, deliberately deferred until the hwp-editor implementation track
+  reports complete: the Phase 2.1 planning artifacts, the HWPE-01..03 requirement
+  registration, and the Semantica Phases 6-9 roadmap entries drawn from
+  `docs/semantica-adoption-plan.md`.
 
 ### Pending Todos
 
 None yet.
 
 ### Blockers/Concerns
 
-- No `.planning/config.json` exists; defaults assumed - granularity `standard`, `phase_id_convention` sequential, `project_code` null. Regenerate phase IDs if a config lands with different values.
+- **Phase 3's ERR-04 count band is coupled to `hwped.rs`.** The pinned command reports 1,138 on the tree that adopts the bridge, and `hwped.rs` contributes 19 of those matches; without it the tree reads 1,119 and the post-migration count lands at 1,109, below `03-04-PLAN.md`'s `[1118, 1138]` band. Re-measure the baseline before Phase 3 executes and write the new number into `03-02-PLAN.md` and `03-04-PLAN.md` - continued hwp-editor work keeps moving it.
 - `src/App.tsx` has no test of any kind. Phases 4-5 depend on Phase 1's hook-dependency gate plus the per-pane tests written during extraction; there is no existing safety net for the decomposition.
 - `make verify` runs on ubuntu-22.04 only and e2e runs Chromium against Vite with mocked IPC. Nothing in CI exercises WKWebView, the real PTY, IME input, or the macOS menu - macOS-affecting changes need a real-app run.
-- make verify's fmt-check/clippy/build-frontend steps unverified end-to-end pending a concurrent session's hwped.rs/lib.rs work landing in this shared checkout; not caused by 01-06
-- make verify's test-rust/fmt-check/clippy steps unverified end-to-end on this shared checkout pending the concurrent hwped session's work landing; not caused by 01-07. CI run on the committed tree is the authoritative composite check and is pending from the team lead
 
 ## Deferred Items
 
@@ -121,6 +152,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-08-22T10:12:57.566Z
-Stopped at: Completed 01-07-PLAN.md - Phase 1 fully executed, GATE-02 flipped, all 7 plans done
-Resume file: None
+Last session: 2026-08-22T22:29:59.605Z
+Stopped at: Phase 3 context gathered
+Resume file: .planning/phases/03-typed-ipc-error-contract/03-CONTEXT.md