---
phase: 23-commune-signoff-project-root-head-sha-stamping
plan: 05
subsystem: messaging
tags: [suppress-drift, suppression-marker, d-09, resume-delta-05, cli, t-23-15, phase23, rust]

requires:
  - phase: 23-commune-signoff-project-root-head-sha-stamping
    plan: 04
    provides: "is_suppressed + suppression_marker_path + suppression_dir + SAME_PROJECT_DRIFT_DIRECTIVE (src/live/context.rs) — Plan 05 reuses the path computation verbatim."
provides:
  - "`$LIVE suppress-drift <self_id> <project>` CLI subcommand (LiveCommands::SuppressDrift variant) — write-side counterpart of Plan 04's read-side is_suppressed gate."
  - "pub fn suppress_drift_result(self_id, project) -> Result<(), String> — Result-returning handler in src/live/context.rs that validates inputs via id_validate::validate_agent_id, then writes an empty marker file at the path locked by Plan 04."
  - "pub fn run_suppress_drift(self_id, project) — CLI wrapper that prints SUPPRESSED:{self_id}__{project} on success or INVALID_ID:{...} on rejection + exits 1."
  - "End-to-end round-trip closure of RESUME-DELTA-05 — `save → drift directive present → suppress-drift → directive absent` verified by an in-process test."
affects: [23-06-skill-docs]

tech-stack:
  added: []  # zero new external crates per CLAUDE.md "no runtime deps" — implementation is std + reuses crate::common::id_validate
  patterns:
    - "Reader/writer pairing locked on Plan 04's path helper: suppress_drift_result calls the same suppression_marker_path / suppression_dir as is_suppressed."
    - "Result-returning *_result handler + CLI wrapper that translates Ok/Err to live_status / owl_err + process::exit (matches the existing context_save_result / signoff_result / amend_signoff_result / commune_result convention in this codebase)."
    - "Belt-and-braces validation: suppress_drift_result validates inputs FIRST, before any FS touch (T-23-15 mitigation) — even though Plan 04's suppression_marker_path has a debug_assert! guard, production input validation lives at the handler boundary so the assertion is defense-in-depth, not the primary gate."

key-files:
  created: []
  modified:
    - "src/cli.rs (added LiveCommands::SuppressDrift { self_id, project } variant with doc comment)"
    - "src/live/mod.rs (added dispatch arm for LiveCommands::SuppressDrift, placed after ClearPsyche for logical grouping)"
    - "src/live/context.rs (added pub fn suppress_drift_result + pub fn run_suppress_drift handlers with Phase-24-migration doc comment; added 8 new tests under the existing #[cfg(test)] mod tests block — net +112 lines including 5 lines of impl + 5 lines of CLI wrapper + 8 test functions + module-level reuse of ENV_LOCK / SptHomeGuard / unique_id / write_context_files / make_stamped_content helpers)"

key-decisions:
  - "Reused the canonical crate::common::id_validate::validate_agent_id helper (Phase 19) for both self_id AND project inputs — no new private validate_simple_id was needed despite the plan's hedge wording. validate_agent_id matches /^[A-Za-z0-9_-]{1,64}$/ exactly, which covers all hostile-input categories the plan enumerated (path traversal, separators, shell metachars, whitespace, control chars, empty strings, length cap)."
  - "Hostile-input tests verify NO marker was written by filesystem scan of $SPT_HOME/suppressions/ rather than by calling is_suppressed(hostile_id, ...) — the latter would trip Plan 04's debug_assert! defense inside suppression_marker_path and panic the test under cargo's debug build. The fs scan is the authoritative no-write check."
  - "The round-trip integration test uses synthetic stamped content (mirroring download_directive_suppressed_by_marker's setup from Plan 04 line 2207) rather than spawning `git init` + `git commit --allow-empty` inside a tempdir. Rationale: spawning git in a tempdir requires set_current_dir, which races against every other test in the lib suite under cargo's parallel runner (see Plan 01 Deviation 1 — 8 false failures were induced by exactly this pattern before stamp_at was added). The synthetic-content approach exercises the same code path with deterministic input and zero global mutation."
  - "Used `fs::File::create(&path)` (not OpenOptions::new().create(true).write(true).open(&path)) for the empty marker — the simpler form is sufficient because existence is the signal (Plan 04's is_suppressed only .exists()-checks the path) and File::create unconditionally truncates which gives the idempotent-empty-file behavior the plan specifies."

patterns-established:
  - "End-to-end round-trip integration test in src/live/context.rs proves save → drift → suppress → no-drift in a single test function (suppress_drift_then_psyche_download_skips_directive). Pattern is reusable for any future suppression-style feature (e.g. an eventual `$LIVE unsuppress-drift` per T-23-17)."

requirements-completed: [RESUME-DELTA-05]

duration: ~5 min
completed: 2026-05-20
---

# Phase 23 Plan 05: $LIVE suppress-drift write-side Summary

**Shipped the write-side counterpart of Plan 04's `is_suppressed` read gate: a new `$LIVE suppress-drift <self_id> <project>` CLI subcommand that validates inputs via `id_validate::validate_agent_id` (T-23-15 mitigation), reuses Plan 04's locked `suppression_marker_path` helper for path computation, and writes an empty marker file. This closes RESUME-DELTA-05 — the D-09 "Don't ask again" option in Plan 04's drift directive is now end-to-end functional, proven by an in-process round-trip test that exercises `save → drift directive present → suppress-drift → directive absent`.**

## Performance

- **Duration:** ~5 min
- **Started:** 2026-05-20T06:16:29Z
- **Completed:** 2026-05-20T06:21:53Z
- **Tasks:** 1 (TDD: 2 commits — RED + GREEN)
- **Files modified:** 3 (src/cli.rs, src/live/mod.rs, src/live/context.rs)
- **Tests added:** 8 (all under live::context::tests)
- **Full lib suite runtime:** 8.11s for 551 tests under `--test-threads=1`

## Existing id_validate Helper Reused (Decision)

The plan hedged between reusing an existing helper vs. defining a private `validate_simple_id`. The grep `fn id_validate|fn validate_id` surfaced one canonical helper at `src/common/id_validate.rs::validate_agent_id` (Phase 19, ASVS V5). This is the same helper used by `src/live/fork.rs::fork_files_only` for the symmetric `INVALID_SRC:` / `INVALID_NEW_ID:` validation pattern.

`validate_agent_id` matches `/^[A-Za-z0-9_-]{1,64}$/`, which covers ALL hostile-input categories the plan enumerated:
- empty strings → rejected (`is_empty()` check)
- path-traversal segments (`..`, `/`, `\`) → rejected (`.` and slashes not in the allowed class)
- shell metachars (`;`, `|`, `&`, `$`, backtick, quotes, comma) → rejected (none in the allowed class)
- whitespace → rejected (space, tab, newline not in the allowed class)
- control chars (`\0`, `\n`) → rejected
- length > 64 → rejected (explicit `len() > 64` check)

Both `self_id` AND `project` are validated through the same helper. The `project` field has the same character class as `self_id` in Phase 23 — both are filesystem-component-safe strings. The handler doc comment notes that Phase 24 may relax the `project` rule when it owns the migration into `tracked/{agent_id}/suppressions/`.

No new private `validate_simple_id` was created — the canonical helper covers the surface exactly.

## Round-Trip Integration Test Setup Steps

`suppress_drift_then_psyche_download_skips_directive` is the critical RESUME-DELTA-05 closure. Its setup avoids the cwd-mutation pitfall that Plan 01 Deviation 1 documented; the steps are:

1. **`ENV_LOCK + SptHomeGuard + tempdir`** — standard setup pattern used by all tests in this module. Serializes the SPT_HOME env-var window against other tests in the same module.
2. **Synthesize stamped content** — call `crate::common::git::stamp()` once to capture the live `(machine, project)` pair, then `make_stamped_content(live.machine, live.project, "old-branch", "0000000000", "stale", "body\n")` produces a context file with a stamp that MATCHES the live machine+project but has a stale branch/head_sha. This is exactly the same setup `download_directive_suppressed_by_marker` (Plan 04) uses — the drift comparison fires because `stored.branch != current.branch && stored.head_sha != current.head_sha`, with same project (D-09 path).
3. **Write stamped file** — `write_context_files(&id, Some(&content), None)` drops the file at `$SPT_HOME/psyches/tracked/{id}.md`.
4. **Pre-suppress assertion** — `download_payload(&id)` MUST contain `<!-- ATTENTION SELF` (the locked drift directive opener).
5. **Invoke `suppress_drift_result(&id, &live.project)`** — the write-side under test.
6. **Post-suppress assertion** — re-run `download_payload(&id)`; MUST contain `<psyche-stamp` and `<current ` (blocks still emit per Plan 04's always-emit policy), MUST NOT contain `<!-- ATTENTION SELF` (directive gone because marker now exists).

Importantly, the test does NOT spawn `git init` / `git commit --allow-empty` inside the tempdir. Doing so would require `std::env::set_current_dir(tempdir)` — the cwd window races against every other lib-suite test that reads cwd-relative paths under cargo's parallel runner (Plan 01 Deviation 1 documented exactly this — 8 false failures were induced by chdir-based tests before `stamp_at` was added). The synthetic-content approach exercises the same `download_payload` drift-detection code path with deterministic inputs and zero global mutation.

## Hostile Input Rejection — Verified Before Filesystem Touch

| Input | self_id | project | Outcome | Reason |
|-------|---------|---------|---------|--------|
| path-traversal | `"../etc"` | `"myproject"` | `Err("INVALID_ID:../etc")` | `.` not in `[A-Za-z0-9_-]` |
| slash in project | valid | `"foo/bar"` | `Err("INVALID_ID:foo/bar")` | `/` not in `[A-Za-z0-9_-]` |
| empty self_id | `""` | `"p"` | `Err("INVALID_ID:")` | `is_empty()` check |
| empty project | valid | `""` | `Err("INVALID_ID:")` | `is_empty()` check |
| whitespace in project | valid | `"a b"` | `Err("INVALID_ID:a b")` | space not in `[A-Za-z0-9_-]` |

For each hostile input the test ALSO scans `$SPT_HOME/suppressions/` after the rejection and asserts the directory is either absent or empty — proving NO marker was written. The validation step runs BEFORE `fs::create_dir_all` and BEFORE `fs::File::create`, so the rejection precedes any filesystem touch.

Hostile-input tests verify "no marker written" via filesystem scan rather than `is_suppressed(hostile, ...)`. Plan 04's `suppression_marker_path` has a `debug_assert!` defense that panics under cargo's debug build when passed hostile inputs — calling `is_suppressed` from a test with hostile inputs would mask the rejection logic behind a debug-only panic. The filesystem scan is the authoritative no-write check.

## SUPPRESSED Status Tag — Relationship to CONVENTIONS.md

The new `SUPPRESSED:{self_id}__{project}` status tag follows the existing CONVENTIONS.md status-tag pattern documented in CLAUDE.md and the project conventions doc:

- **Existing tags:** `READY:id`, `SENT:id`, `STOPPED:id`, `CLEANED:id` (success), `NO_PERCH:id`, `STALE:id`, `DUPLICATE:id`, `COLLISION:id`, `INVALID_ID:id` (error)
- **New (this plan):** `SUPPRESSED:{self_id}__{project}` — success tag emitted via `output::live_status(output::S_READY, ...)` so it gets the orange `✓` prefix (live/psyche/context-related operations use the orange `live_status` channel).
- **The `__` separator inside the tag** mirrors the marker file naming (`{self_id}__{project}.marker`) so a user grepping logs sees the same shape as the file on disk. This is an intentional symmetry with Plan 04's lock — a Phase 24 migration that changes the separator MUST update both surfaces in lockstep.
- **Error tag:** `INVALID_ID:{value}` reuses the existing pattern from `src/live/fork.rs` (which emits `INVALID_SRC:` and `INVALID_NEW_ID:`). The bare `INVALID_ID:` shape is more general because the handler validates both args identically.

## Task Commits

This is a 1-task TDD plan — RED + GREEN:

1. **Task 1 RED** — `927c2ba` — `test(23-05): add failing tests for suppress-drift write-side` (8 tests + unimplemented! stub + CLI variant + dispatch arm)
2. **Task 1 GREEN** — `1d3d2fb` — `feat(23-05): implement suppress-drift write-side (RESUME-DELTA-05)` (validate_agent_id wiring + create_dir_all + File::create + 3 test-rewrite adjustments for the debug_assert! interaction)

## Files Modified

- **`src/cli.rs`** — added `LiveCommands::SuppressDrift { self_id: String, project: String }` variant with a `///` doc comment locking the relationship to D-09. Placed after `ClearPsyche` per the file's convention of grouping context-management subcommands together. +9 lines.
- **`src/live/mod.rs`** — added dispatch arm `LiveCommands::SuppressDrift { self_id, project } => { context::run_suppress_drift(&self_id, &project); }` after the `ClearPsyche` arm. +3 lines.
- **`src/live/context.rs`** — added `pub fn suppress_drift_result(self_id, project) -> Result<(), String>` (real impl: 32 lines incl. doc comment) and `pub fn run_suppress_drift(self_id, project)` (CLI wrapper: 13 lines incl. doc comment) before `run_clear`. Added 8 new tests under the existing `#[cfg(test)] mod tests` block. Tests reuse the module-level `ENV_LOCK`, `SptHomeGuard`, `unique_id`, `write_context_files`, and `make_stamped_content` helpers — no new test-infra was created. Net +178 lines.

## RESEARCH §Code Examples Consulted

- **§Open Question 1: subcommand vs. teaching Claude a path literal** — followed: a dedicated `LiveCommands::SuppressDrift` clap variant is the audit-friendly choice.
- **§Pitfall 6: Suppression marker location** — followed Plan 04's locked layout exactly: `$SPT_HOME/suppressions/{self_id}__{project}.marker` with `__` separator. The write side reuses `suppression_marker_path` so any future migration is a single-site change.
- **Plan 01 Deviation 1 (cross-module test interference via set_current_dir)** — applied lesson: round-trip test uses synthetic stamped content, NOT `git init` + `git commit --allow-empty` inside a tempdir.

## Verification Gate Results

| Gate | Command | Result |
|------|---------|--------|
| Plan 05 new tests | `cargo test --lib live::context::tests::suppress_drift -- --test-threads=1` | 8/8 pass in 0.33s |
| Full live::context module | `cargo test --lib live::context -- --test-threads=1` | 60/60 pass / 1 ignored in 6.11s |
| Full lib suite | `cargo test --lib -- --test-threads=1` | 551/551 pass / 2 ignored in 8.11s |
| Release build | `cargo build --release` | green (3 pre-existing dead_code warnings unrelated to Plan 05) |
| Clippy on touched files | `cargo clippy --lib 2>&1 \| grep -E "(suppress\|context\.rs:\|cli\.rs:\|mod\.rs:)"` | 3 hits — ALL pre-existing (common/mod.rs:21, live/context.rs:605 Phase-30 redundant_closure, live/wrapper/mod.rs:704) — zero new |
| SuppressDrift wiring | `grep -rn "SuppressDrift" src/` | 4 hits: cli.rs:310 (variant), live/mod.rs:71 (dispatch arm), live/mod.rs:72 (handler call), live/context.rs:906 (doc comment) ✓ |
| suppress_drift wiring | `grep -rn "suppress_drift" src/` | 30+ hits: handlers + 8 tests + reuse of Plan 04's helpers ✓ |
| Cargo.toml unchanged | `git diff HEAD~2 Cargo.toml` | empty (zero new external crates) ✓ |

## Manual Smoke Commands & Observed Output

```bash
$ target/release/owl.exe live suppress-drift --help
HANDOFF: trampoline -> C:\Users\decid\.claude\plugins\cache\cplugs\spt\1.10.14\owl.exe
error: unrecognized subcommand 'suppress-drift'
```

**Expected outcome — same trampoline-routing pattern Plans 03 and 04 documented.** The Phase 18.4/18.5 binary handoff trampoline intercepts `target/release/owl.exe` invocations and forwards them to the deployed plugin-cache binary at `~/.claude/plugins/cache/cplugs/spt/1.10.14/owl.exe`. That deployed binary is pre-Plan-05 (and pre-Plans 03 & 04), so the manual smoke does NOT exercise the freshly-built code path.

**In-process verification via the 8 new suppress_drift tests + the 1 Plan 04 read-side suppression test (`download_directive_suppressed_by_marker`) is authoritative.** These tests link the freshly-compiled lib crate directly and exercise `suppress_drift_result` + `run_suppress_drift`'s validation path + `is_suppressed`'s read path without any subprocess or handoff. All pass under `--test-threads=1`. The round-trip integration test (`suppress_drift_then_psyche_download_skips_directive`) is the end-to-end seal: it proves the write-side and read-side compose correctly through the production `download_payload` function.

Real deployment validation will land via `docs/DEPLOY.ps1` when Phase 23 ships.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 — Bug] Three hostile-input tests initially called `is_suppressed(hostile, ...)` and tripped Plan 04's debug_assert! defense**
- **Found during:** Task 1 GREEN — first cargo test run on the real implementation
- **Issue:** The plan's `<behavior>` for `suppress_drift_rejects_path_traversal_in_self_id` / `_slash_in_project` / `_whitespace_in_project` specified `assert!(!is_suppressed(hostile, ...))` as the no-write check. But Plan 04's `suppression_marker_path` carries a `debug_assert!` that panics in debug builds when passed inputs containing characters outside `[A-Za-z0-9_-]` (T-23-13 mitigation, file line 118). `is_suppressed` calls `suppression_marker_path`, so calling `is_suppressed("../etc", ...)` panicked the test BEFORE the assertion could run.
- **Fix:** Replaced the `!is_suppressed(hostile, ...)` assertions with a filesystem scan of `$SPT_HOME/suppressions/` that verifies the directory is either absent or empty after the rejection. The filesystem scan is the authoritative no-write check (and is what the plan actually wanted to prove). The `suppress_drift_rejects_path_traversal_in_self_id` test already had this fs scan; the other two tests needed it added. A short comment in each test documents why we're not using `is_suppressed`.
- **Files modified:** `src/live/context.rs` (tests only)
- **Verification:** All 8 Plan 05 tests pass; full live::context module 60/60 passes; full lib suite 551/551 passes.
- **Committed in:** `1d3d2fb` (Task 1 GREEN — alongside the real impl)

### Plan-Hedge Resolutions (Not Deviations)

**Existing id_validate helper reused.** The plan's `<action>` step 3 hedged: "Identify the existing input-validation helper. ... If no helper exists, define a private `fn validate_simple_id(s: &str) -> bool`." The grep showed `src/common/id_validate.rs::validate_agent_id` is the canonical helper (used by `src/live/fork.rs`), so no new private helper was needed. Documented in "Existing id_validate Helper Reused" section above.

**Round-trip test setup approach.** The plan's `<behavior>` for the round-trip test described using `Command::new("git") commit --allow-empty` inside a fresh `git init` tempdir setup. The plan's setup pattern required `set_current_dir` to make git operate inside the tempdir — exactly the cwd-mutation pattern Plan 01 Deviation 1 documented as causing 8 false failures in other modules' tests. Resolved by using synthetic stamped content (Plan 04's `download_directive_suppressed_by_marker` pattern) which exercises the same `download_payload` drift-detection code path with zero global mutation. Documented in "Round-Trip Integration Test Setup Steps" section above.

---

**Total deviations:** 1 auto-fixed (Rule 1 bug: test-side adjustments for Plan 04's debug_assert! interaction). No production-behavior deviations. No architectural changes (no Rule 4 STOP needed).

**Impact on plan:** All deviations are test-side. The production behavior (subcommand wiring, input validation via `validate_agent_id`, marker write via Plan 04's locked path, SUPPRESSED status tag) matches the plan verbatim. The plan's two hedges (existing id_validate helper vs. private one; git-init tempdir vs. synthetic content) were resolved by picking the option that minimized new code and avoided known test-isolation pitfalls.

## Issues Encountered

### Trampoline rerouted the manual smoke test (same as Plans 03 & 04)

Per Plans 03 and 04 SUMMARYs: `target/release/owl.exe` execution is intercepted by the Phase-18.4/18.5 binary handoff trampoline, which forwards to the deployed plugin-cache binary at `~/.claude/plugins/cache/cplugs/spt/1.10.14/owl.exe`. That deployed binary is pre-Plan-05, so the manual smoke does NOT exercise the freshly-built code path.

**In-process verification via the 8 new tests is authoritative.** They exercise `suppress_drift_result`, `run_suppress_drift`'s validation path, and the round-trip through `download_payload` directly from the lib crate (no subprocess, no handoff), and all pass. Real deployment validation will land via the regular `docs/DEPLOY.ps1` flow when Phase 23 ships.

## TDD Gate Compliance

- **RED commit:** `927c2ba` — `test(23-05): add failing tests for suppress-drift write-side` ✓ (8 tests, all panic with `unimplemented!()` against the stub)
- **GREEN commit:** `1d3d2fb` — `feat(23-05): implement suppress-drift write-side (RESUME-DELTA-05)` ✓ (after RED; all 8 tests pass; full lib suite green)
- **REFACTOR commits:** N/A — Deviation 1 (test-side debug_assert! adjustments) resolved inline in the GREEN commit per Rule 1.

## Self-Check: PASSED

- `src/cli.rs` declares `LiveCommands::SuppressDrift { self_id, project }` variant ✓
- `src/live/mod.rs` dispatches `SuppressDrift` to `context::run_suppress_drift` ✓
- `src/live/context.rs` defines `pub fn suppress_drift_result` + `pub fn run_suppress_drift` ✓
- 8/8 new tests pass ✓
- 60/60 live::context module tests pass under --test-threads=1 ✓
- 551/551 lib tests pass under --test-threads=1 ✓
- Both task commits (`927c2ba` test, `1d3d2fb` feat) present in `git log` ✓
- Zero new external crates ✓
- Hostile inputs rejected with `INVALID_ID:` before any FS touch ✓
- Forward-compat doc comment for Phase 24 migration present ✓
- Manual smoke attempted; trampoline routed to deployed binary as expected (issue inherited from Plans 03 & 04) ✓

## Next Phase Readiness

Plan 23-05 delivers the write side that closes RESUME-DELTA-05 — the D-09 "Don't ask again" option in Plan 04's drift directive is now end-to-end functional. Ready for:

- **Plan 23-06 (skill / plugin doc updates):** update `plugin/spt/skills/spt-commune/SKILL.md`, `plugin/spt/skills/spt-signoff/SKILL.md`, `plugin/spt/skills/spt-live/SKILL.md` to teach the new `$LIVE suppress-drift <self_id> <project>` subcommand and document its role as the write-side counterpart of Plan 04's drift directive. Suggested skill snippet: "When AskUserQuestion returns `Don't ask again` for the same-project drift directive, invoke `$LIVE suppress-drift {your-id} {project}` — the next psyche-download will skip the directive for this (self_id, project) pair until the marker is manually removed (or Phase 24 migration kicks in)."

No blockers. No `Cargo.toml` changes propagate downstream.

---
*Phase: 23-commune-signoff-project-root-head-sha-stamping*
*Plan: 05*
*Completed: 2026-05-20*