|
| 1 | +# Red-Line Framework (attribute-triggered mandatory constraints) |
| 2 | + |
| 3 | +This file owns the **red-line framework**: a proactive conformance gate that runs while |
| 4 | +improving a Skill. Unlike evidence-gated optimization (fix what a run observed breaking), a |
| 5 | +red line is a **design invariant** — its violation is a defect by definition, whether or not |
| 6 | +any execution crashed. The executable half is `${SKILL_HOME}/scripts/redline-check.py`; this |
| 7 | +file owns the methodology, the registry catalogue, and the admission rigor. |
| 8 | + |
| 9 | +## Why this exists |
| 10 | + |
| 11 | +The improvement loop was purely reactive: it optimized from observed execution evidence and |
| 12 | +user direction. That misses invariants whose breach produces no error — a browser-automation |
| 13 | +Skill that steals system focus "works" (the run completes) while silently disrupting the |
| 14 | +user's real work. Such invariants must be checked **proactively, keyed on what the Skill is**, |
| 15 | +and remediated **mandatorily**, not recommended. |
| 16 | + |
| 17 | +## The generic 4-step flow |
| 18 | + |
| 19 | +``` |
| 20 | +1. attribute collection classify the target Skill from its own text/scripts |
| 21 | + (automation? sensitive-info? … — extensible) |
| 22 | +2. red-line selection map each present attribute to the red lines it fires |
| 23 | + (attribute present ≠ red line fires; only bound red lines run) |
| 24 | +3. trigger judgment evaluate compliance -> PASS (not-applicable / compliant) |
| 25 | + or TRIGGERED (gap / review) |
| 26 | +4. remediation TRIGGERED => MUST fix (or prove each signal a sanctioned, |
| 27 | + announced exception). Red-line remediation is never optional. |
| 28 | +``` |
| 29 | + |
| 30 | +Steps 1–3 are deterministic and run in `redline-check.py`. Step 4 is judgment + MUST-DO and |
| 31 | +stays with the improver. Run it in **workflow step 4** (before acting) and re-run it in |
| 32 | +**step 8** (must exit `0` before finishing). |
| 33 | + |
| 34 | +```bash |
| 35 | +python3 ${SKILL_HOME}/scripts/redline-check.py <target/SKILL.md> # gate: exit 0 pass / 1 triggered |
| 36 | +python3 ${SKILL_HOME}/scripts/redline-check.py <target/SKILL.md> --json # machine verdict + evidence |
| 37 | +python3 ${SKILL_HOME}/scripts/redline-check.py <target/SKILL.md> --scan-all # deeper audit incl. references/ |
| 38 | +``` |
| 39 | + |
| 40 | +## What the probe decides vs what stays judgment |
| 41 | + |
| 42 | +| Deterministic (the probe) | Judgment (the improver) | |
| 43 | +|---------------------------|-------------------------| |
| 44 | +| which attributes are present | whether a flagged signal is a *sanctioned, announced exception* (e.g. a human-in-the-loop SSO login window) or a real violation | |
| 45 | +| which red lines therefore apply | the concrete remediation edit that satisfies the invariant | |
| 46 | +| where violation / compliance signals appear (file:line) | whether a `review` verdict's hard signals are all legitimately documented | |
| 47 | + |
| 48 | +The probe never auto-convicts: a `review` verdict means "remediate **unless** you can point at |
| 49 | +why each signal is sanctioned". This division follows the skill's own principle — deterministic |
| 50 | +logic to code, judgment to the LLM. |
| 51 | + |
| 52 | +### Verdict model (exit code driven by *mitigation presence*, not raw signal count) |
| 53 | + |
| 54 | +| Verdict | Condition | Meaning | |
| 55 | +|---------|-----------|---------| |
| 56 | +| `not-applicable` | trigger attribute absent | red line does not fire → PASS | |
| 57 | +| `gap` | attribute present, **zero** focus-safe vocabulary | drives automation with no mitigation → MANDATORY remediation | |
| 58 | +| `review` | attribute present, mitigation present, un-negated **hard** signal remains | verify each is sanctioned, else fix → MANDATORY | |
| 59 | +| `compliant` | attribute present, mitigation present, no un-negated hard signal | PASS | |
| 60 | + |
| 61 | +Why mitigation-presence and not signal-count: a reference implementation documents the |
| 62 | +*banned* mechanisms (in "rejected" tables, API listings, `never call X` prohibitions). Counting |
| 63 | +raw greps would flag the most-compliant skills — the calibration trap `skill-shape.py` warns |
| 64 | +about. So the probe (a) excludes `references/` from the default gate scope, (b) applies a ±2-line |
| 65 | +**negation guard** (a wrapped `never call\n bringToFront()` is a prohibition, not a violation), |
| 66 | +(c) splits **hard** signals (always worth judgment) from **soft** context signals (only matter |
| 67 | +when no mitigation exists), and (d) skips its own framework files. `--scan-all` opts into the |
| 68 | +deeper, knowingly-noisier reference audit. |
| 69 | + |
| 70 | +## Red-line catalogue |
| 71 | + |
| 72 | +The executable registry (detection patterns, compliance markers, remediation text) lives in |
| 73 | +`redline-check.py` `RED_LINES` — that is the SSOT for *detection*. This table is the |
| 74 | +human-facing index; keep ids in sync. |
| 75 | + |
| 76 | +| id | trigger attribute | invariant (absolute) | mandatory remediation | |
| 77 | +|----|-------------------|----------------------|-----------------------| |
| 78 | +| `RL-FOCUS-01` | `automation` (drives a GUI/browser/desktop surface that maps real windows) | No automation method may steal the user's system focus or pop a window/tab in front of their work. | Route every launch/attach through a focus-safe path: background `open -g` (macOS) or headless / virtual display; attach to a running instance instead of relaunching; reuse background tabs; never `bringToFront()`; any genuinely-headed window is announced, small and fixed. Foreground/direct-binary launch only as an announced human-in-the-loop exception, gated + documented. See browser-utils `focus-safe-launch.md`, profiles-browsers SKILL.md § 焦点红线. | |
| 79 | + |
| 80 | +Collected attributes with **no** red line bound yet (framework is extensible; binding one |
| 81 | +requires passing admission below): `sensitive-info` (handles credentials/tokens/cookies/PII). |
| 82 | + |
| 83 | +## Admission criteria — what qualifies as a red line (rigor gate) |
| 84 | + |
| 85 | +The remediation for a red line is **MUST**, so the bar for calling something a red line is high. |
| 86 | +A candidate qualifies **only if all** hold — otherwise it is a normal constraint (recommended, |
| 87 | +evidence-gated), and MUST NOT be added to `RED_LINES`: |
| 88 | + |
| 89 | +1. **Protects an irreversible or user-harming invariant** — data loss, security/credential |
| 90 | + breach, destructive/irreversible action, or disruption of the user's own work (focus theft). |
| 91 | + Not efficiency, structure, style, or a preference. |
| 92 | +2. **Objectively detectable** — a static signal decides it (presence of a pattern / absence of |
| 93 | + required mitigation), not taste. If two competent reviewers would disagree on whether it was |
| 94 | + violated, it is not a red line. |
| 95 | +3. **Has one required alternative** — remediation is a single unambiguous MUST-DO, not a menu of |
| 96 | + acceptable options. Pair the prohibition with the required alternative (avoids negation-priming). |
| 97 | +4. **Universal within its trigger attribute** — it binds *every* Skill with the attribute, with |
| 98 | + at most narrow, nameable, announced exceptions (e.g. human-in-the-loop login). A rule with |
| 99 | + broad case-by-case discretion is a guideline, not a red line. |
| 100 | +5. **Worth blocking a loop over** — breaching it must be severe enough that finishing the |
| 101 | + improvement without fixing it is unacceptable. |
| 102 | + |
| 103 | +Anti-pattern: promoting a general best practice ("prefer headless", "announce long runs", |
| 104 | +"keep scripts idempotent") to a red line. Those are constraints/recommendations; making them |
| 105 | +`MUST` devalues the real red lines and trains people to ignore the gate. |
| 106 | + |
| 107 | +## Reconciliation with "Evidence before defect" (Hard Constraint 5) |
| 108 | + |
| 109 | +HC5 forbids labeling something a defect without an observed symptom. A red-line violation does |
| 110 | +not contradict it: **the violating pattern's presence in the Skill's own instructions/scripts is |
| 111 | +the observed symptom** (a static artifact), exactly like a runtime stack trace is evidence. The |
| 112 | +probe surfaces that artifact; the improver still must not invent violations the probe did not |
| 113 | +find. `not-applicable` and `compliant` verdicts are never defects. |
| 114 | + |
| 115 | +## Extending the framework |
| 116 | + |
| 117 | +To add a red line: (1) confirm the candidate passes **all** admission criteria above; (2) add its |
| 118 | +trigger attribute signals to `ATTRIBUTES` (or reuse an existing attribute); (3) add a `RED_LINES` |
| 119 | +entry — `id`, `attribute`, `invariant`, `violation` patterns tagged `hard`/`soft`, `compliance` |
| 120 | +markers, `remediation` (the required alternative), `refs`; (4) add its row to the catalogue table |
| 121 | +here; (5) validate per the reverse-case discipline — run the probe against a compliant Skill |
| 122 | +(must NOT trigger) and a genuinely-violating sample (must trigger) before wiring it as a gate. |
0 commit comments