docs: OPT_OUT_DEMAND_LOG.md — evidentiary base for governance decisions

Cycle #21 ships governance infrastructure, not implementation. Maintainership
mode means sometimes the right deliverable is a decision framework, not code.

Problem context:
OPT_OUT_AUDIT.md (cycle #18 bonus) established 'demand-backed audit' as the
next step. But without a structured way to record demand signals, 'demand-backed'
was just a slogan — the next audit cycle would have no evidence to work from.

This commit creates the evidentiary base:

New file: OPT_OUT_DEMAND_LOG.md
- Per-surface entries for all 12 OPT_OUT commands (Groups A/B/C)
- Current state: 0 signals across all surfaces (consistent with audit prediction)
- Signal entry template with required fields:
  - Source (who/what)
  - Use case (concrete orchestration problem)
  - Markdown-alternative-checked (why existing output insufficient)
  - Date
- Promotion thresholds:
  - 2+ independent signals for same surface → file promotion pinpoint
  - 1 signal + existing stable schema → file pinpoint for discussion
  - 0 signals → stays OPT_OUT (rationale preserved)

Decision framework for cycle #22 (audit close):
- If 0 signals total: move to PERMANENTLY_OPT_OUT, close audit
- If 1-2 signals: file individual promotion pinpoints with evidence
- If 3+ signals: reopen audit, question classification itself

Updated files:
- OPT_OUT_AUDIT.md: Added demand log reference in Related section
- CLAUDE.md: Added prerequisites for promotions (must have logged signals),
  added 'File a demand signal' workflow section

Philosophy:
'Prevent speculative expansion' — schema bloat protection discipline.
Every new CLAWABLE surface is a maintenance tax. Evidence requirement keeps
the protocol lean. OPT_OUT surfaces are intentionally not-clawable until
proven otherwise by external demand.

Operational impact:
Next cycles can now:
1. Watch for real claws hitting OPT_OUT surface limits
2. Log signals in structured format (no ad-hoc filing)
3. Run audit at cycle #22 with actual data, not speculation

No code changes. No test changes. Pure governance infrastructure.

Related: #18 cycle (OPT_OUT_AUDIT.md), maintainership phase transition.

CLAUDE.md

@@ -149,12 +149,23 @@ Target: >90% line coverage for src/ (currently ~85%).
 
 ### Promote an OPT_OUT surface to CLAWABLE
 
+**Prerequisite:** Real demand signal logged in `OPT_OUT_DEMAND_LOG.md` (threshold: 2+ independent signals per surface). Speculative promotions are not allowed.
+
+Once demand is evidenced:
 1. Add --output-format flag to argparse
 2. Emit wrap_json_envelope() output in JSON path
 3. Move command from OPT_OUT_SURFACES to CLAWABLE_SURFACES
 4. Document in SCHEMAS.md
 5. Write test for JSON output
 6. Run parity audit to confirm no regressions
+7. Update `OPT_OUT_DEMAND_LOG.md` to mark signal as resolved
+
+### File a demand signal (when a claw actually needs JSON from an OPT_OUT surface)
+
+1. Open `OPT_OUT_DEMAND_LOG.md`
+2. Find the surface's entry under Group A/B/C
+3. Append a dated entry with Source, Use Case, and Markdown-alternative-checked explanation
+4. If this is the 2nd signal for the same surface, file a promotion pinpoint in ROADMAP.md
 
 ## Dogfood principles
 

OPT_OUT_AUDIT.md

@@ -144,6 +144,7 @@ If external claws report needing JSON from any OPT_OUT surface:
 
 ## Related
 
+- **OPT_OUT_DEMAND_LOG.md** — Active survey recording real demand signals (evidentiary base for any promotion decision)
 - **SCHEMAS.md** — Clawable surface contracts
 - **CLAUDE.md** — Development guidance
 - **test_cli_parity_audit.py** — Parametrized tests for CLAWABLE_SURFACES enforcement

OPT_OUT_DEMAND_LOG.md

@@ -0,0 +1,167 @@
+# OPT_OUT Demand Log
+
+**Purpose:** Record real demand signals for promoting OPT_OUT surfaces to CLAWABLE. Without this log, the audit criteria in `OPT_OUT_AUDIT.md` have no evidentiary base.
+
+**Status:** Active survey window (post-#178/#179, cycles #21+)
+
+## How to file a demand signal
+
+When any external claw, operator, or downstream consumer actually needs JSON output from one of the 12 OPT_OUT surfaces, add an entry below. **Speculation, "could be useful someday," and internal hypotheticals do NOT count.**
+
+A valid signal requires:
+- **Source:** Who/what asked (human, automation, agent session, external tool)
+- **Surface:** Which OPT_OUT command (from the 12)
+- **Use case:** The concrete orchestration problem they're trying to solve
+- **Would-parse-Markdown alternative checked?** Why the existing OPT_OUT output is insufficient
+- **Date:** When the signal was received
+
+## Promotion thresholds
+
+Per `OPT_OUT_AUDIT.md` criteria:
+- **2+ independent signals** for the same surface within a survey window → file promotion pinpoint
+- **1 signal + existing stable schema** → file pinpoint for discussion
+- **0 signals** → surface stays OPT_OUT (documented rationale in audit file)
+
+The threshold is intentionally high. Single-use hacks can be served via one-off Markdown parsing; schema promotion is expensive (docs, tests, maintenance).
+
+---
+
+## Demand Signals Received
+
+### Group A: Rich-Markdown Reports
+
+#### `summary`
+**Signals received: 0**
+
+Notes: No demand recorded. Markdown output is intentional and useful for human review.
+
+#### `manifest`
+**Signals received: 0**
+
+Notes: No demand recorded.
+
+#### `parity-audit`
+**Signals received: 0**
+
+Notes: No demand recorded. Report consumers are humans reviewing porting progress, not automation.
+
+#### `setup-report`
+**Signals received: 0**
+
+Notes: No demand recorded.
+
+---
+
+### Group B: List Commands with Query Filters
+
+#### `subsystems`
+**Signals received: 0**
+
+Notes: `--limit` already provides filtering. No claws requesting JSON.
+
+#### `commands`
+**Signals received: 0**
+
+Notes: `--query`, `--limit`, `--no-plugin-commands`, `--no-skill-commands` already allow filtering. No demand recorded.
+
+#### `tools`
+**Signals received: 0**
+
+Notes: `--query`, `--limit`, `--simple-mode` provide filtering. No demand recorded.
+
+---
+
+### Group C: Simulation / Debug Surfaces
+
+#### `remote-mode`
+**Signals received: 0**
+
+Notes: Simulation-only. No production orchestration need.
+
+#### `ssh-mode`
+**Signals received: 0**
+
+Notes: Simulation-only.
+
+#### `teleport-mode`
+**Signals received: 0**
+
+Notes: Simulation-only.
+
+#### `direct-connect-mode`
+**Signals received: 0**
+
+Notes: Simulation-only.
+
+#### `deep-link-mode`
+**Signals received: 0**
+
+Notes: Simulation-only.
+
+---
+
+## Survey Window Status
+
+| Cycle | Date | New Signals | Running Total | Action |
+|---|---|---|---|---|
+| #21 | 2026-04-22 | 0 | 0 | Survey opened; log established |
+
+**Current assessment:** Zero demand for any OPT_OUT surface promotion. This is consistent with `OPT_OUT_AUDIT.md` prediction that all 12 likely stay OPT_OUT long-term.
+
+---
+
+## Signal Entry Template
+
+```
+### <surface-name>
+**Signal received: [N]**
+
+Entry N (YYYY-MM-DD):
+- Source: <who/what>
+- Use case: <concrete orchestration problem>
+- Markdown-alternative-checked: <yes/no + why insufficient>
+- Follow-up: <filed pinpoint / discussion thread / closed>
+```
+
+---
+
+## Decision Framework
+
+At cycle #22 (or whenever survey window closes):
+
+### If 0 signals total (likely):
+- Move all 12 surfaces to `PERMANENTLY_OPT_OUT` or similar
+- Remove `OPT_OUT_SURFACES` from `test_cli_parity_audit.py` (everything is explicitly non-goal)
+- Update `CLAUDE.md` to reflect maintainership mode
+- Close `OPT_OUT_AUDIT.md` with "audit complete, no promotions"
+
+### If 1–2 signals on isolated surfaces:
+- File individual promotion pinpoints per surface with demand evidence
+- Each goes through standard #171/#172/#173 loop (parity audit, SCHEMAS.md, consistency test)
+
+### If high demand (3+ signals):
+- Reopen audit: is the OPT_OUT classification actually correct?
+- Review whether protocol expansion is warranted
+
+---
+
+## Related Files
+
+- **`OPT_OUT_AUDIT.md`** — Audit criteria, decision table, rationale by group
+- **`SCHEMAS.md`** — JSON contract for the 14 CLAWABLE surfaces
+- **`tests/test_cli_parity_audit.py`** — Machine enforcement of CLAWABLE/OPT_OUT classification
+- **`CLAUDE.md`** — Development posture (maintainership mode)
+
+---
+
+## Philosophy
+
+**Prevent speculative expansion.** The discipline of requiring real signals before promotion protects the protocol from schema bloat. Every new CLAWABLE surface adds:
+- A SCHEMAS.md section (maintenance burden)
+- Test coverage (test suite tax)
+- Documentation (cognitive load for new developers)
+- Version compatibility (schema_version bump risk)
+
+If a claw can't articulate *why* it needs JSON for `summary` beyond "it would be nice," then JSON for `summary` is not needed. The Markdown output is a feature, not a gap.
+
+The audit log closes the loop on "governed non-goals": OPT_OUT surfaces are intentionally not clawable until proven otherwise by evidence.