From 3262cb3a873d4c2859ada4ff1703c471f3af4e22 Mon Sep 17 00:00:00 2001 From: YeonGyu-Kim Date: Wed, 22 Apr 2026 20:34:35 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20OPT=5FOUT=5FDEMAND=5FLOG.md=20=E2=80=94?= =?UTF-8?q?=20evidentiary=20base=20for=20governance=20decisions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 | 11 +++ OPT_OUT_AUDIT.md | 1 + OPT_OUT_DEMAND_LOG.md | 167 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 179 insertions(+) create mode 100644 OPT_OUT_DEMAND_LOG.md diff --git a/CLAUDE.md b/CLAUDE.md index f5277b7..ed4da10 100644 --- a/CLAUDE.md +++ b/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 diff --git a/OPT_OUT_AUDIT.md b/OPT_OUT_AUDIT.md index 5d63f5b..459b523 100644 --- a/OPT_OUT_AUDIT.md +++ b/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 diff --git a/OPT_OUT_DEMAND_LOG.md b/OPT_OUT_DEMAND_LOG.md new file mode 100644 index 0000000..06b2cf8 --- /dev/null +++ b/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 + +``` +### +**Signal received: [N]** + +Entry N (YYYY-MM-DD): +- Source: +- Use case: +- Markdown-alternative-checked: +- Follow-up: +``` + +--- + +## 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.