mirror of
https://github.com/ultraworkers/claw-code.git
synced 2026-04-24 21:28:11 +08:00
3262cb3a87
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.
168 lines
5.0 KiB
Markdown
168 lines
5.0 KiB
Markdown
# 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.
|