super-ux 0.66.3 → 0.67.0

package/CHANGELOG.md

@@ -1,3 +1,58 @@
+## 0.67.0 (2026-11-09): contract v5, agents and capabilities (opt-in)
+
+Packet P-SU of the family run `2026-11-09-ai-native` (hub plan and design:
+`docs/evidence/plans/2026-11-09-ai-native.md`,
+`docs/evidence/specs/2026-11-09-ai-native-pipeline.md` in ssheleg/sshlg-skills).
+
+- **Contract v5, opt-in by marker.** `scenario-format.md` gains *Contract v5:
+  agents and capabilities*, the home of AN-1 (parity by story) and AN-4 (why a
+  person: gates and serving reasons, each with evidence): actors `A-NN` under
+  `## Actors`, persona `Agent use`, a journey `Performed by` column,
+  `docs/ux/capabilities.md` with one `CAP-NN` per effect set (`Traces`,
+  `Actors`, `Agent excluded`, `Roles`, `Gate`, `Tools`, `Emits`, `Data`,
+  `Automation`, `Human surface`, `Since`, `Status`), scenario `Channel`, screen
+  `Fronts` and `Why human`, and `docs/ux/agent-panel.md`. A chain is on v5 when
+  its headers carry `ux-contract v5`; the lowest marker decides, so a v4 chain
+  with one v5 seed stays on v4. v4 chains lint exactly as before.
+- **Nine lint codes, warnings, v5 only:** `U087` (a CAP field missing), `U088`
+  (a v5 value outside its enum), `U089` (a must/should story with no CAP),
+  `U090` (an agent CAP with no tools), `U091` (an agent-channel scenario citing
+  no CAP), `U092` (agents left out with no evidenced reason, or debt with no
+  board row), `U093` (a gate or serving reason with no evidence), `U094` (a
+  screen with no `Fronts` or `Why human`, or fronting an unknown CAP), `U095` (a
+  no-agent persona's must story served only by agent scenarios). Under v5 a
+  chain with no `screens.md` is not asked `U050`. Each code is planted both
+  ways in `test/ux_lint_test.py`; `test/fixtures/contract-v4` exits 0 under
+  `--strict` and `test/fixtures/contract-v5` is clean too. `validate.py`
+  compares the linter's `V5_ENUMS` with the contract's v5 declarations.
+- **Doctor:** `CURRENT = 5`, `HISTORY[5]`; v4 is supported (no problem
+  counted) and is offered the v4 to v5 migration: add actors, capabilities and
+  channels, then the marker; nothing else is required.
+- **Doctrine:** `system-map.md` carries AN-2 (the design order: stories,
+  capabilities, contract, logic, automation, human surfaces) and AN-6
+  (automation by default); `ux-design-principles.md` reorders the pipeline
+  (jobs, capabilities, contract, then flows and screens for the human lanes)
+  and is the home of AN-5 (the attention budget). The agent surface itself is
+  cited by raw URL to agent-stack's `agent-surface.md` and `operability.md`,
+  not restated.
+- **Templates:** the seeds `/ux init` writes carry `ux-contract v5`;
+  `foundation.md` gains `## Actors`, `Agent use` and `Performed by`; new
+  `capabilities.md` and `agent-panel.md`; `scenarios.md` gains `Channel`;
+  `screens.md` gains `Fronts`, `Why human` and the missing `blocked` status.
+- **Skills:** `ux-foundation` owns the capabilities layer (description 267 to
+  264 characters); `ux-scenarios` writes agent-channel steps; `ux-flows` designs
+  the human lanes and asks the Figma question at the first human surface;
+  `ux-audit` accepts an MCP or CLI call receipt as runtime evidence and checks
+  the one-contract proxy; `vision` §4 and §9 guidance ask what an agent can do
+  without a screen (nine sections unchanged); `copywriting` separates
+  agent-facing text from the `human_steps` a person reads. `/ux` routes agent
+  requests to the capabilities layer. The hard rule in `templates/claude-rule.md`
+  and `/ux-rule` (byte-equal) becomes foundation, capabilities, contract,
+  flows, screens, scenarios for human lanes.
+- **Drift fixed on the way (BN-22):** the screens template lacked `blocked`;
+  the linter's no-docs message named only `scenarios.md` although it accepts
+  `foundation.md` or `vision.md`.
+
 ## 0.66.3 (2026-10-27): route misses in Triggers, ux-scenarios names its subject first
 
 - **Route misses join ux-flows' `## Triggers`** (hub board row B-267): "users drop off" /

package/README.md

@@ -184,8 +184,9 @@ Installed into your project's `CLAUDE.md` (and as the always-on Cursor rule):
   Code that diverges from a screen's record, or a stale Figma link, is drift
   the audit flags.
 - Any new feature or project **starts** with the chain: which job, which
-  journey stage, which story, then flows, screens, and scenarios, validated
-  against the existing base and approved.
+  journey stage, which story, which capability and who performs it (a person,
+  an agent, an automation), then flows, screens, and scenarios for the human
+  lanes, validated against the existing base and approved.
 - **Do not write interface code until that workflow is done.** Chain designed
   and approved, and (Figma on, the default) the UI mocked up with every screen
   linked to its frame. Building UI before this is the mistake super-ux exists
@@ -253,13 +254,13 @@ to is a skill nobody runs.
 | `/vision` `/ux-init` `/ux-foundation` `/ux-flows` `/ux-update` `/ux-audit` `/ux-rule` `/ux-lint` `/ux-doctor` · `/brand` `/brand-init` `/brand-update` `/brand-lint` `/copy` | Direct controls for when you know exactly what you want; `/ux-rule` installs both hard rules and seeds `lint.py` + `doctor.py`; `/brand-init` seeds `docs/brand/` and its linter |
 | `docs/ux/lint.py` + `/ux-lint` | The deterministic half: missing Figma frames, a screen with no states or no render axes, a built state with no story, more than one onboarding screen before the first value with no reason on file, art direction approved with no critique cited, unresolved SCR/story traces, orphans, built screens without coverage, index desync, ID gaps, broken links. Stdlib-only, exit 1 on problems, so wire it into CI and drift can't merge |
 | `cursor/rules/*.mdc` | The same methodology for Cursor: one always-on hard rule + seven agent-requested rules (vision, foundation, flows, scenarios, audit, brand voice, copywriting) |
-| `templates/` | Seeds for `docs/ux/`: the vision skeleton, foundation, flows, screens, scenario base, the folder README, and the audit-report skeleton. Both hard-rule snippets live here as their single source, `claude-rule.md` (scenario-first) and `vision-rule.md` (vision alignment), and the validator fails if a command's embedded copy drifts from them. Seeds for `docs/brand/`: voice, terminology, facts, channels, the string registry, a locale delta, and its folder README. The tree is mirrored into `plugins/super-ux/templates/` (and the seeds each skill names into that skill's own directory) by `test/sync_references.py`, so installed channels carry the seeds their texts point at; the validator refuses drift between the copies |
+| `templates/` | Seeds for `docs/ux/`: the vision skeleton, foundation, capabilities, flows, screens, scenario base, the agent test panel, the folder README, and the audit-report skeleton. Both hard-rule snippets live here as their single source, `claude-rule.md` (scenario-first) and `vision-rule.md` (vision alignment), and the validator fails if a command's embedded copy drifts from them. Seeds for `docs/brand/`: voice, terminology, facts, channels, the string registry, a locale delta, and its folder README. The tree is mirrored into `plugins/super-ux/templates/` (and the seeds each skill names into that skill's own directory) by `test/sync_references.py`, so installed channels carry the seeds their texts point at; the validator refuses drift between the copies |
 
 The contracts every skill reads:
 
 | Reference | Holds |
 |---|---|
-| [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md) | **The contract (ux-contract v4).** File layout, every field name, stable IDs (`P` `JTBD` `JRN` `ST` `FLW` `SCR` `SCN`), completeness checklists, the `draft → validated → implemented` lifecycle, audit verdicts and severities, the UX-plan format |
+| [scenario-format.md](plugins/super-ux/skills/references/scenario-format.md) | **The contract (ux-contract v5; v4 chains stay valid).** File layout, every field name, stable IDs (`P` `A` `JTBD` `JRN` `ST` `CAP` `FLW` `SCR` `SCN`), the opt-in v5 layer for agents (actors, capabilities, channels, why a person is needed), completeness checklists, the `draft → validated → implemented` lifecycle, audit verdicts and severities, the UX-plan format |
 | [system-map.md](plugins/super-ux/skills/references/system-map.md) | The whole system on one page: pipeline, files, skills, companions, and the four sync rules; every skill points here |
 | [ux_doctor.py](plugins/super-ux/scripts/ux_doctor.py) | Contract doctor. It reports mixed or stale contract versions across a project's artifacts, files the tooling cannot find under their contract names, and audits produced against a base that is not there. `/ux-lint` checks a chain against itself; this checks it against the contract. Installed as `docs/ux/doctor.py`, read-only unless `--fix` |
 | [best-practices-index.md](plugins/super-ux/skills/references/best-practices-index.md) | Generated tag index over the catalog: tag → ids, id → title. Read it to decide which entries to open; regenerated by `plugins/super-ux/scripts/bp_index.py` and checked for drift by the validator |

package/cursor/rules/super-ux.mdc

@@ -6,10 +6,11 @@ alwaysApply: true
 # UX scenarios — hard rule (super-ux)
 
 - `docs/ux/scenarios.md` is the source of truth for all user-facing behavior;
-  `docs/ux/foundation.md` (personas, JTBD, journeys, stories) and
-  `docs/ux/flows.md` (user flows) are the WHY and HOW layers scenarios trace
-  to. Above all three sits `docs/ux/vision.md` — what the product is and
-  refuses to become — when the project has written one.
+  `docs/ux/foundation.md` (personas, actors, JTBD, journeys, stories),
+  `docs/ux/capabilities.md` (what people and agents can do, contract v5) and
+  `docs/ux/flows.md` (user flows) are the layers scenarios trace to. Above
+  them sits `docs/ux/vision.md` (what the product is and refuses to
+  become), when the project has written one.
 - Any change that touches user-facing behavior or interface MUST update, in
   the same change: `docs/ux/scenarios.md`; affected flows; the affected
   screens in `docs/ux/screens.md` (the UI map — states, elements, coverage);
@@ -20,14 +21,17 @@ alwaysApply: true
   path must exist and the line range must be inside the file. Seven of this
   pack's own citations were pre-shift ranges nothing re-resolved.
 - Any new feature or project STARTS with the chain: which job does it serve,
-  which journey stage, which story — then flows and scenarios, validated
+  which journey stage, which story, which capability and who performs it (a
+  person, an agent, an automation); then flows and scenarios, validated
   against the existing base, approved. An idea serving no job is challenged,
   not silently accepted.
-- **Do NOT write interface code until the UX workflow is done first:** the
-  foundation → flows → screens → scenarios chain is designed and approved,
-  and — when Figma is enabled (default) — the UI is mocked up in Figma with
-  every screen linked to its frame. Building UI before this is the exact
-  mistake super-ux exists to prevent.
+- **Do NOT write interface code until the UX workflow is done first:**
+  foundation → capabilities → contract → flows → screens → scenarios for
+  human lanes, designed and approved (capabilities and contract under
+  contract v5), and, when Figma is enabled (default), the UI mocked up in
+  Figma with every screen linked to its frame. A screen is designed where a
+  person is needed; every other capability stays reachable by agents.
+  Building UI before this is the exact mistake super-ux exists to prevent.
 - Visual identity is ONE locked style pack, recorded in `docs/ux/screens.md`
   → Design system and obeyed by every Figma frame and every built screen —
   picked with the **sheleg-design** companion skill when the project has no

package/cursor/rules/ux-flows.mdc

@@ -14,7 +14,7 @@ reused. Any interface change updates `screens.md` (and the Figma frame when
 enabled) in the same change — a screen whose code diverges from its record
 is `drifted`.
 
-## Flow entry (ux-contract v4)
+## Flow entry (ux-contract v5; a v4 chain stays valid)
 
 Fields: `Traces` (story/job IDs), `Goal` (observable end state), `Entry
 points` (ALL of them), `Success exit`, `Task analysis` (numbered
@@ -29,7 +29,10 @@ Story | Behavior |` — a row per default/loading/empty/error/offline/
 long-content/keyboard-up/first-run state that applies), `Axes`
 (viewport; theme; text; locale — or the Design system default),
 `Wireframe`, `Coverage` (file:line), `Scenarios`, `Resources`, `Status`
-(designed|blocked|built|drifted|retired). A flow that onboards records
+(designed|blocked|built|drifted|retired); under v5 also `Fronts` (the
+`CAP-NN` it fronts, or none) and `Why human` (a serving reason with
+evidence), because flows and screens are drawn for the human lanes only.
+A flow that onboards records
 `Onboarding:` and `First value:`; the budget is one screen before the first
 value unless the director record says why.
 

package/cursor/rules/ux-foundation.mdc

@@ -10,7 +10,7 @@ alwaysApply: false
 stories (ST-NNN)**. IDs sequential, never reused; dropped entries kept, not
 deleted.
 
-## Formats (ux-contract v4)
+## Formats (ux-contract v5; a v4 chain stays valid)
 
 - **Persona `P-NN`:** 1–3 sentences, grounded in data/observation,
   recognizable by a real user.
@@ -26,6 +26,14 @@ deleted.
   <benefit>` + Traces (JTBD, JRN/stage) + Given/When/Then acceptance
   criteria + priority (must|should|could) + status
   (proposed|validated|delivered|dropped). Quality bar: INVEST.
+- **v5 (opt-in; new projects):** persona `Agent use: none|some|most` with
+  evidence; actors `A-NN` under `## Actors` (`Kind: agent|system`, `Acts
+  for: P-NN`, `Grant`); a journey `Performed by` column; and
+  `docs/ux/capabilities.md`, one `CAP-NN` per must/should story with
+  `Traces, Actors, Agent excluded, Roles, Gate, Tools, Emits, Data,
+  Automation, Human surface, Since, Status`. A person enters at a gate
+  (`body|approval|legal`) or for a serving reason, each with evidence;
+  everything else stays reachable by agents.
 
 ## Workflows
 

package/cursor/rules/ux-scenarios.mdc

@@ -8,7 +8,7 @@ alwaysApply: false
 `docs/ux/scenarios.md` describes everything the user can do, see, and hit —
 every feature, button, state, error, result. Keep it true.
 
-## File structure (ux-contract v4)
+## File structure (ux-contract v5; a v4 chain stays valid)
 
 Title, then header comment, then: **Index** table
 (`| ID | Title | Feature | Persona | Traces | Status | Last audit |`),
@@ -28,7 +28,10 @@ when none exist), `UI elements` (every button/field/link/dialog/toast involved
 this is what audits check), `States covered` (loading|empty|error|success),
 `Errors & recovery` (each failure: what the user sees, how they recover),
 `Status` (draft|validated|implemented|retired), `Coverage` (file:line or
-`none yet`).
+`none yet`). Under v5, `Channel` (human|agent|both; absent reads human): an
+agent step is `A-NN -> tool -> observable response`, the scenario cites the
+`CAP-NN` it exercises, and `UI elements` is required on the human channel
+only.
 
 Rules: IDs `SCN-NNN`, sequential, never reused; retired entries are kept,
 never deleted. Lifecycle: draft → validated (human approval) → implemented

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "super-ux",
-  "version": "0.66.3",
+  "version": "0.67.0",
   "scripts": {
     "test": "python3 test/validate.py && python3 test/family_gate.py && python3 test/family_gate.py --self-test && python3 test/brand_lint_test.py && python3 test/display_copy_test.py && python3 test/ux_lint_test.py && python3 docs/ux/lint.py && python3 docs/brand/lint.py && node test/installer_test.js && npm run test:audit",
     "test:audit": "for t in test/audit_regressions/*.py; do python3 \"$t\" || exit 1; done"

package/plugins/super-ux/scripts/ux_doctor.py

@@ -21,7 +21,11 @@ import re
 import sys
 from pathlib import Path
 
-CURRENT = 4
+CURRENT = 5
+# The oldest contract still read as current work rather than as debt. v5 is
+# opt-in (agents and capabilities), so a v4 chain is supported, not behind:
+# the doctor names the migration and counts no problem for it.
+SUPPORTED = 4
 
 # What each contract version introduced, so a report can say what is missing
 # rather than only that something is old.
@@ -29,8 +33,19 @@ HISTORY = {
     2: "`Traces:` on every scenario + traceability rules; `foundation.md` (personas, JTBD, journeys, stories)",
     3: "scenarios become use cases (`user action -> system response`), `Alt paths`, `Traces` includes `FLW-NN`; `flows.md`; `plans/`",
     4: "`screens.md` — one `SCR-NN` entry per screen with per-state Figma frames; flows reference screens by id instead of respecifying them",
+    5: "agents and capabilities, opt-in: actors (`A-NN`) and `Agent use` in `foundation.md`, `capabilities.md` (`CAP-NN`), `Channel` on scenarios, `Fronts` and `Why human` on screens, `agent-panel.md`",
 }
 
+# The v4 -> v5 step, named so a v4 chain is told what opting in costs. Nothing
+# else is required: every v5 lint rule is a warning, and only under the marker.
+V5_MIGRATION = (
+    "v4 -> v5 is opt-in, best taken on the first capability task: add "
+    "`## Actors` (`A-NN`) and `Agent use` to foundation.md, write "
+    "capabilities.md with one `CAP-NN` per must/should story, add `Channel` "
+    "to scenarios and `Fronts` with `Why human` to screens, then change every "
+    "header marker to `ux-contract v5`. Nothing else is required."
+)
+
 # Additive since v4 — absence is not a version problem, but it is worth naming.
 ADDITIVE = [
     ("foundation.md", "## Product mechanics", "Product mechanics section (personalization, engagement, a11y regime) — 0.26.1"),
@@ -39,6 +54,8 @@ ADDITIVE = [
 ]
 
 ARTIFACTS = ["vision.md", "foundation.md", "flows.md", "screens.md", "scenarios.md"]
+# v5 files: their markers count, and their absence is reported only on v5.
+V5_ARTIFACTS = ["capabilities.md", "agent-panel.md"]
 
 # `screens.md` format 2 (0.58.0): the screen matrix — a state list and render
 # axes per screen, a frame for every declared state, a story per state once
@@ -82,6 +99,7 @@ def marker(path: Path) -> int | None:
 def diagnose(ux: Path) -> dict:
     present = {a: (ux / a).exists() for a in ARTIFACTS}
     markers = {a: marker(ux / a) for a in ARTIFACTS if present[a]}
+    markers.update({a: marker(ux / a) for a in V5_ARTIFACTS if (ux / a).exists()})
     known = [v for v in markers.values() if v is not None]
 
     misnamed = {
@@ -135,9 +153,13 @@ def report(ux: Path, d: dict) -> int:
     elif eff is None:
         problems += 1
         print("  NO CONTRACT MARKER on any artifact — the chain is unmanaged.")
-    elif eff < CURRENT:
+    elif eff < SUPPORTED:
         problems += 1
         print(f"  BEHIND: contract v{eff}, current v{CURRENT}")
+    elif eff < CURRENT:
+        print(f"  contract v{eff}, supported; current v{CURRENT} is opt-in")
+    else:
+        print(f"  contract v{eff}")
 
     if unmarked and not d["mixed"]:
         problems += 1
@@ -153,6 +175,8 @@ def report(ux: Path, d: dict) -> int:
         print(f"  MISNAMED: {wrong} -> {right}  (the tooling looks for the contract name and finds nothing)")
 
     missing_core = [a for a, ok in d["present"].items() if not ok]
+    if eff is not None and eff >= 5 and "capabilities.md" not in markers:
+        missing_core.append("capabilities.md")
     if missing_core:
         print(f"  ABSENT: {', '.join(missing_core)}")
 
@@ -170,7 +194,15 @@ def report(ux: Path, d: dict) -> int:
     if d.get("screens_format") == 1:
         print(f"  migration offered: {SCREENS_MIGRATION}")
 
-    print("  OK — on the current contract" if problems == 0 else f"  {problems} problem(s)")
+    if eff == 4 and not d["mixed"]:
+        print(f"  migration offered: {V5_MIGRATION}")
+
+    if problems:
+        print(f"  {problems} problem(s)")
+    elif eff is not None and eff < CURRENT:
+        print("  OK: on a supported contract")
+    else:
+        print("  OK: on the current contract")
     return problems
 
 

package/plugins/super-ux/scripts/ux_lint.py

@@ -1038,6 +1038,265 @@ def check_vision(ux: Path, vision: str) -> None:
                  f"the `vision` skill's step 4, or keep the edit deliberately")
 
 
+# --- Contract v5: agents and capabilities (opt-in) -------------------------
+#
+# v5 models who performs a story (a person, an agent acting for one, an
+# automation), the capabilities a story needs, and why a person is needed
+# where a screen exists. Every v4 chain stays valid: nothing below runs unless
+# the chain declares `ux-contract v5`, the marker form `doctor.py` already
+# reads. The LOWEST marker decides, as the doctor's `effective` does, so one
+# v5 seed dropped into a v4 chain does not switch it onto rules it never
+# opted into. Every finding here is a warning: the layer is new, and a gate
+# that failed builds on day one is the gate that gets switched off.
+CONTRACT_MARKER = re.compile(r"ux-contract v(\d+)")
+CONTRACT_FILES = ("vision.md", "foundation.md", "flows.md", "screens.md",
+                  "scenarios.md", "capabilities.md", "agent-panel.md")
+V5 = 5
+
+# The capability row, in the contract's order. One row is one effect set.
+CAP_FIELDS = ("Traces", "Actors", "Agent excluded", "Roles", "Gate", "Tools",
+              "Emits", "Data", "Automation", "Human surface", "Since", "Status")
+
+# Every v5 enum, keyed by (layer, field). `validate.py` compares this table
+# with the contract's v5 declarations, the same parity `STATUS_ENUMS` has.
+V5_ENUMS = {
+    ("CAP", "Actors"): ("human", "agent", "automation"),
+    ("CAP", "Agent excluded"): ("presence", "legal", "debt"),
+    ("CAP", "Gate"): ("none", "body", "approval", "legal"),
+    ("CAP", "Data"): ("public", "internal", "personal", "payment", "secret"),
+    ("CAP", "Status"): ("proposed", "specified", "exposed", "deprecated", "retired"),
+    ("A", "Kind"): ("agent", "system"),
+    ("P", "Agent use"): ("none", "some", "most"),
+    ("SCN", "Channel"): ("agent", "human", "both"),
+    ("SCR", "Why human"): ("oversight", "exception-queue", "trust", "presence",
+                           "audience", "manual", "taste"),
+}
+BOARD_ID = re.compile(r"\b[A-Z][A-Z0-9]*-\d+\b")
+
+
+def contract_version(ux: Path) -> int | None:
+    """The lowest `ux-contract vN` among the chain's files, read raw.
+
+    The marker lives in an HTML comment and `read()` strips comments, so the
+    head of each file is read here directly, as `doctor.py` reads it.
+    """
+    found = []
+    for name in CONTRACT_FILES:
+        try:
+            head = (ux / name).read_text(encoding="utf-8", errors="ignore")[:2000]
+        except OSError:
+            continue
+        m = CONTRACT_MARKER.search(head)
+        if m:
+            found.append(int(m.group(1)))
+    return min(found) if found else None
+
+
+def v5_field(body: str, name: str) -> str | None:
+    """A v5 field's value on one line; None when the field is absent."""
+    m = re.search(rf"\*\*{re.escape(name)}:\*\*[ \t]*([^\n]*)", body)
+    return None if m is None else m.group(1).strip()
+
+
+def v5_token(value: str) -> tuple[str, str]:
+    """`(first word, the rest)`: the enum value and the evidence beside it."""
+    m = re.match(r"\s*([A-Za-z][\w-]*)\s*(.*)$", value or "", re.DOTALL)
+    if m is None:
+        return ("", "")
+    return (m.group(1).lower(), m.group(2).strip())
+
+
+def evidenced(rest: str) -> bool:
+    """Does the text beside an enum value say anything? Brackets and
+    separators alone are not evidence."""
+    return stated(re.sub(r"[()\[\];:,.\s]+", " ", rest or "").strip() or None)
+
+
+def v5_enum(name: str, sid: str, field: str, value: str,
+            allowed: tuple[str, ...]) -> bool:
+    """Warn U088 on a value outside its enum; True when the value is legal."""
+    if value in allowed:
+        return True
+    warn(f"[U088] {name}: {sid} declares {field} '{value or '(nothing)'}', "
+         f"which is not one of {' | '.join(allowed)}. An unrecognised value "
+         f"reads as no value, and every v5 rule keyed on it stops applying")
+    return False
+
+
+def actors_of(value: str) -> list[str]:
+    """The actor kinds a CAP names, before any bracketed note."""
+    head = re.split(r"[(;]", value or "", maxsplit=1)[0]
+    return [a.strip().lower() for a in head.split(",") if a.strip()]
+
+
+def check_v5(foundation: str, scenarios: str, screens: str,
+             capabilities: str) -> None:
+    """The v5 layers: actors, capabilities, channels, and why a person.
+
+    The doctrine of each rule lives in `scenario-format.md`, section
+    "Contract v5: agents and capabilities"; this function only checks it.
+    """
+    caps = entry_blocks(capabilities, "CAP")
+    cap_ids = set(caps)
+    for prefix, name, text in (("CAP", "capabilities.md", capabilities),
+                               ("A", "foundation.md/actors", foundation)):
+        entry_ids = ids(text, prefix)
+        if entry_ids:
+            check_unique_and_gaps(entry_ids, name)
+        for sid, colon, title in entry_names(text, prefix):
+            if not (colon and title):
+                err(f"[U073] {name}: `### {sid}` carries no name: the contract's "
+                    f"header is `### {sid}: <short name>`")
+    if cap_ids:
+        idx = index_ids(capabilities, "CAP")
+        for missing in sorted(cap_ids - idx):
+            warn(f"[U003] capabilities.md: {missing} has no index row")
+        for ghost in sorted(idx - cap_ids):
+            err(f"[U004] capabilities.md: index lists {ghost} but no entry exists")
+
+    traced_by_caps: set[str] = set()
+    for cid, body in sorted(caps.items()):
+        status, _ = v5_token(v5_field(body, "Status") or "")
+        if status == "retired":
+            continue
+        for field in CAP_FIELDS:
+            if v5_field(body, field) is None:
+                warn(f"[U087] capabilities.md: {cid} is missing **{field}:**. The "
+                     f"row is {', '.join(CAP_FIELDS)}; `none` is a value, an "
+                     f"absent field is not")
+        traced_by_caps |= refs(v5_field(body, "Traces") or "", "ST")
+        if status:
+            v5_enum("capabilities.md", cid, "Status", status, V5_ENUMS[("CAP", "Status")])
+        actors = actors_of(v5_field(body, "Actors") or "")
+        for actor in actors:
+            v5_enum("capabilities.md", cid, "Actors", actor, V5_ENUMS[("CAP", "Actors")])
+        data, _ = v5_token(v5_field(body, "Data") or "")
+        if data:
+            v5_enum("capabilities.md", cid, "Data", data, V5_ENUMS[("CAP", "Data")])
+
+        tools = v5_field(body, "Tools")
+        if "agent" in actors and (not stated(tools) or v5_token(tools or "")[0] == "none"):
+            warn(f"[U090] capabilities.md: {cid} names agent among its Actors and no "
+                 f"**Tools:**. An agent reaches a capability through a tool id, and "
+                 f"one with none listed is a capability only a screen can reach")
+
+        excluded, why = v5_token(v5_field(body, "Agent excluded") or "")
+        if actors and "agent" not in actors:
+            if excluded in ("", "none"):
+                warn(f"[U092] capabilities.md: {cid} leaves agents out and names no "
+                     f"**Agent excluded:** reason (presence | legal | debt, with "
+                     f"evidence). Parity is by story: an exception is named per "
+                     f"capability or it is a gap")
+            elif v5_enum("capabilities.md", cid, "Agent excluded", excluded,
+                         V5_ENUMS[("CAP", "Agent excluded")]):
+                if excluded == "debt" and not BOARD_ID.search(why):
+                    warn(f"[U092] capabilities.md: {cid} records parity debt with "
+                         f"no board row. Debt is listed and on the board "
+                         f"(`debt (B-nnn)`), never hidden")
+                elif excluded != "debt" and not evidenced(why):
+                    warn(f"[U092] capabilities.md: {cid} excludes agents for "
+                         f"'{excluded}' and cites no evidence: a JTBD-, ST- or "
+                         f"RE- id, a policy or a decision")
+
+        gate, gate_why = v5_token(v5_field(body, "Gate") or "")
+        if gate and v5_enum("capabilities.md", cid, "Gate", gate,
+                            V5_ENUMS[("CAP", "Gate")]):
+            if gate != "none" and not evidenced(gate_why):
+                warn(f"[U093] capabilities.md: {cid} is gated '{gate}' and cites no "
+                     f"evidence: the policy, the decision or the law that puts a "
+                     f"person there. No product-level waiver exists")
+
+        reason_m = re.search(r"Why human:\s*(.*)", v5_field(body, "Human surface") or "")
+        if reason_m:
+            reason, reason_why = v5_token(reason_m.group(1))
+            if v5_enum("capabilities.md", cid, "Why human", reason,
+                       V5_ENUMS[("SCR", "Why human")]) and not evidenced(reason_why):
+                warn(f"[U093] capabilities.md: {cid} serves a person for "
+                     f"'{reason}' and cites no evidence beside it")
+
+    # AN-1, structurally: every must/should story has a capability tracing to
+    # it, and the capability's row names any exclusion.
+    for sid, body in sorted(entry_blocks(foundation, "ST").items()):
+        if declared_status(body) == "dropped":
+            continue
+        if not re.search(r"\*\*Priority:\*\*\s*(must|should)", body, re.IGNORECASE):
+            continue
+        if sid not in traced_by_caps:
+            warn(f"[U089] foundation.md: {sid} (must/should) has no capability "
+                 f"tracing to it in capabilities.md. Parity is by story: name the "
+                 f"CAP that serves it, and any exclusion in that CAP's row")
+
+    for aid, body in sorted(entry_blocks(foundation, "A").items()):
+        kind, _ = v5_token(v5_field(body, "Kind") or "")
+        if kind:
+            v5_enum("foundation.md", aid, "Kind", kind, V5_ENUMS[("A", "Kind")])
+
+    # Channel: an absent field reads as `human`, the scenario every v4 chain
+    # already wrote. An agent-channel scenario is the contract's acceptance
+    # test, so it names the capability it accepts.
+    scn_channel: dict[str, str] = {}
+    scn_traces: dict[str, set[str]] = {}
+    for sid, body in sorted(entry_blocks(scenarios, "SCN").items()):
+        channel, _ = v5_token(v5_field(body, "Channel") or "human")
+        scn_traces[sid] = refs(v5_field(body, "Traces") or body, "ST")
+        if not v5_enum("scenarios.md", sid, "Channel", channel,
+                       V5_ENUMS[("SCN", "Channel")]):
+            continue
+        scn_channel[sid] = channel
+        if declared_status(body) == "retired":
+            continue
+        if channel in ("agent", "both") and not refs(body, "CAP"):
+            warn(f"[U091] scenarios.md: {sid} is an {channel}-channel scenario and "
+                 f"cites no CAP in its Traces. An agent step calls a capability, "
+                 f"and the scenario is that capability's acceptance test")
+
+    for sid, body in sorted(screen_blocks(screens).items()):
+        if declared_status(body) == "retired":
+            continue
+        fronts = v5_field(body, "Fronts")
+        why_value = v5_field(body, "Why human")
+        missing = [f for f, v in (("Fronts", fronts), ("Why human", why_value))
+                   if not stated(v)]
+        if missing:
+            warn(f"[U094] screens.md: {sid} has no **{':** or **'.join(missing)}:**. "
+                 f"A screen fronts capabilities (`Fronts: CAP-NN`, or `none`) and "
+                 f"says why a person is needed there")
+        for ghost in sorted(refs(fronts or "", "CAP") - cap_ids):
+            warn(f"[U094] screens.md: {sid} fronts {ghost}, which capabilities.md "
+                 f"does not define")
+        if stated(why_value):
+            reason, reason_why = v5_token(why_value)
+            if v5_enum("screens.md", sid, "Why human", reason,
+                       V5_ENUMS[("SCR", "Why human")]) and not evidenced(reason_why):
+                warn(f"[U093] screens.md: {sid} serves a person for '{reason}' and "
+                     f"cites no evidence beside it: a JTBD-, ST- or RE- id, a "
+                     f"policy, a decision or the typed error that routes here")
+
+    # A persona whose people use no agent still gets a whole human path for
+    # every must story: the audience decides the human path's size.
+    jobs = entry_blocks(foundation, "JTBD")
+    for pid, body in sorted(entry_blocks(foundation, "P").items()):
+        use_value = v5_field(body, "Agent use")
+        if use_value is None:
+            continue
+        use, _ = v5_token(use_value)
+        if not v5_enum("foundation.md", pid, "Agent use", use,
+                       V5_ENUMS[("P", "Agent use")]) or use != "none":
+            continue
+        for st, sbody in sorted(entry_blocks(foundation, "ST").items()):
+            if not re.search(r"\*\*Priority:\*\*\s*must", sbody, re.IGNORECASE):
+                continue
+            via_jobs = any(pid in refs(v5_field(jobs.get(j, ""), "Personas") or "", "P")
+                           for j in refs(sbody, "JTBD"))
+            if pid not in refs(sbody, "P") and not via_jobs:
+                continue
+            serving = [s for s, t in scn_traces.items() if st in t and s in scn_channel]
+            if serving and not any(scn_channel[s] in ("human", "both") for s in serving):
+                warn(f"[U095] foundation.md: {pid} declares Agent use: none and "
+                     f"must story {st} has only agent-channel scenarios. People "
+                     f"who use no agent need the whole human path for it")
+
+
 def check_links(ux: Path) -> None:
     link_re = re.compile(r"\[[^\]]*\]\(([^)\s]+)\)")
     for md in sorted(ux.rglob("*.md")):
@@ -1055,7 +1314,8 @@ def main() -> int:
     strict = "--strict" in sys.argv[1:]
     ux = find_ux_dir(args[0] if args else None)
     if ux is None:
-        print("no UX docs found (docs/ux/scenarios.md). Run /ux to set up.")
+        print("no UX docs found (docs/ux/ with scenarios.md, foundation.md or "
+              "vision.md). Run /ux to set up.")
         return 2
 
     vision = read(ux / "vision.md")
@@ -1063,6 +1323,8 @@ def main() -> int:
     flows = read(ux / "flows.md")
     screens = read(ux / "screens.md")
     scenarios = read(ux / "scenarios.md")
+    capabilities = read(ux / "capabilities.md")
+    v5 = (contract_version(ux) or 0) >= V5
 
     # Cited paths are project-relative, so they resolve against the tree the
     # ux directory sits in — the same derivation `check_links` already uses.
@@ -1263,9 +1525,14 @@ def main() -> int:
     check_jobs(foundation, scenarios, flows, screens)
     check_journey_owners(foundation)
     check_vision(ux, vision)
-    check_web_surface(screens, flows)
+    # Under v5 a product may have no human surface at all, so a chain with no
+    # `screens.md` has no screen to ask the web question about.
+    if not (v5 and not (ux / "screens.md").exists()):
+        check_web_surface(screens, flows)
     check_onboarding(flows, ux, project_root)
     check_art_direction(flows, ux, project_root)
+    if v5:
+        check_v5(foundation, scenarios, screens, capabilities)
     check_links(ux)
 
     # --- Report ---

package/templates/README.md

@@ -6,14 +6,19 @@ sync with the code on every interface change.
 ## The pipeline
 
 ```
-Vision  →  Personas · JTBD · Journeys · Stories  →  Flows  →  Screens  →  Scenarios  →  Audits  →  Plans
-vision.md           foundation.md                  flows.md  screens.md  scenarios.md   audits/    plans/
+Vision  →  Personas · Actors · JTBD · Journeys · Stories  →  Capabilities  →  Flows  →  Screens  →  Scenarios  →  Audits  →  Plans
+vision.md           foundation.md                           capabilities.md  flows.md  screens.md  scenarios.md   audits/    plans/
 ```
 
+Flows and screens are drawn for the human lanes: a capability an agent or an
+automation performs needs no screen unless a person is needed there.
+
 | File | Holds |
 |------|-------|
 | `vision.md` | WHAT IT IS: essence, core idea, principles, the anti-vision, the alignment test. Optional layer; when present, new features are checked against it before anything is designed |
-| `foundation.md` | WHO & WHY: personas, jobs-to-be-done, journeys, user stories, monetization, Figma on/off + file URL |
+| `foundation.md` | WHO & WHY: personas, actors (the agents and systems acting for them), jobs-to-be-done, journeys, user stories, monetization, Figma on/off + file URL |
+| `capabilities.md` | WHAT PEOPLE AND AGENTS CAN DO: one `CAP-NN` per effect set, with its actors, gate, tools and the human surface that fronts it |
+| `agent-panel.md` | optional: the agents an agent-tester walks the agent-channel scenarios as |
 | `flows.md` | HOW: user-flow diagrams (screens, branches, error paths), referencing screens by `SCR-ID` |
 | `screens.md` | THE UI MAP: every screen and state with its Figma frame link, wireframe, code coverage, scenarios, resources |
 | `scenarios.md` | WHAT IT DOES: use-case scenarios — the source of truth for behavior |

package/templates/agent-panel.md

@@ -0,0 +1,40 @@
+# Agent test panel
+
+<!-- Managed with super-ux (ux-contract v5). The agents an agent-tester walks
+the agent-channel scenarios as (task-pipeline reads this file). Separate from
+test-panel.md, the human panel, on purpose. Five agents, each with its grant,
+its model class and the scenarios it walks. A grant here is a test-tenant
+grant: the credential comes from the project's secret store, never this file. -->
+
+## Panel
+
+<!-- ### AG-01: Full-grant agent
+- **Acts for:** P-01
+- **Grant:** <every scope its principal holds>
+- **Model class:** <the verification model the project uses>
+- **Walks:** <SCN-… agent-channel scenarios>
+
+### AG-02: Narrowly delegated agent
+- **Acts for:** P-01
+- **Grant:** <one scope, e.g. read-only billing>
+- **Model class:** <…>
+- **Walks:** <SCN-…: expects a typed refusal where its grant ends>
+
+### AG-03: Automation with no conversation
+- **Acts for:** <A-…, Kind: system>
+- **Grant:** <the automation's own scope>
+- **Model class:** none
+- **Walks:** <SCN-… for CAP rows with an Automation trigger>
+
+### AG-04: Cheap model
+- **Acts for:** P-01
+- **Grant:** <as AG-01>
+- **Model class:** <a small, inexpensive model; advisory>
+- **Walks:** <SCN-…: can the tool descriptions alone guide it>
+
+### AG-05: Adversarial agent
+- **Acts for:** P-01
+- **Grant:** <as AG-02>
+- **Model class:** <…>
+- **Walks:** <SCN-… with injected content in what it reads; owed on a public surface>
+-->

package/templates/capabilities.md

@@ -0,0 +1,29 @@
+# Capabilities
+
+<!-- Managed with super-ux (ux-contract v5). What people and agents can do:
+one CAP-NN per effect set. Between the stories (foundation.md) and the flows
+(flows.md): every must/should story has a capability tracing to it, and a
+capability found while designing a later layer comes back here in the same
+change. Field rules: the contract's "Contract v5: agents and capabilities". -->
+
+## Index
+
+| ID | Capability | Actors | Gate | Status |
+|----|------------|--------|------|--------|
+
+## Capabilities
+
+<!-- ### CAP-01: <verb + object, e.g. Cancel a subscription>
+- **Traces:** <ST-…>
+- **Actors:** <human, agent, automation: who performs it>
+- **Agent excluded:** none | presence (<evidence>) | legal (<evidence>) | debt (<board id>)
+- **Roles:** <principal roles allowed to invoke it; an agent never exceeds its principal>
+- **Gate:** none | body | approval | legal (<policy, decision or law>)
+- **Tools:** <tool ids an agent calls, as the contract source names them>
+- **Emits:** <events or notifications an agent can subscribe to, or none>
+- **Data:** public | internal | personal | payment | secret
+- **Automation:** none | <trigger; schedule; kill switch>
+- **Human surface:** none | <SCR-…>; Why human: <serving reason> (<evidence>)
+- **Since:** <contract version that introduced it>
+- **Status:** proposed | specified | exposed | deprecated | retired
+-->

package/templates/claude-rule.md

@@ -1,8 +1,9 @@
 ## UX scenarios — hard rule (super-ux)
 
 - `docs/ux/scenarios.md` is the source of truth for all user-facing
-  behavior; `docs/ux/foundation.md` (personas, JTBD, journeys, stories) and
-  `docs/ux/flows.md` (user flows) are the WHY and HOW layers scenarios
+  behavior; `docs/ux/foundation.md` (personas, actors, JTBD, journeys,
+  stories), `docs/ux/capabilities.md` (what people and agents can do,
+  contract v5) and `docs/ux/flows.md` (user flows) are the layers scenarios
   trace to.
 - Any change that touches user-facing behavior or interface MUST update, in
   the same change: `docs/ux/scenarios.md`; affected flows; the affected
@@ -11,13 +12,16 @@
   links in `screens.md`. A screen whose code diverges from its record, or a
   stale Figma link, is drift — the exact thing this system prevents.
 - Any new feature or project STARTS with the chain: which job does it
-  serve, which journey stage, which story — then flows and scenarios,
-  validated against the existing base, approved.
-- **Do NOT write interface code until the UX workflow is done first:** the
-  foundation → flows → screens → scenarios chain is designed and approved,
-  and — when Figma is enabled (default) — the UI is mocked up in Figma with
-  every screen linked to its frame. Building UI before this is the exact
-  mistake super-ux exists to prevent.
+  serve, which journey stage, which story, which capability and who
+  performs it (a person, an agent, an automation); then flows and
+  scenarios, validated against the existing base, approved.
+- **Do NOT write interface code until the UX workflow is done first:**
+  foundation → capabilities → contract → flows → screens → scenarios for
+  human lanes, designed and approved (capabilities and contract under
+  contract v5), and, when Figma is enabled (default), the UI mocked up in
+  Figma with every screen linked to its frame. A screen is designed where a
+  person is needed; every other capability stays reachable by agents.
+  Building UI before this is the exact mistake super-ux exists to prevent.
 - Visual identity is ONE locked style pack, recorded in `docs/ux/screens.md`
   → Design system and obeyed by every Figma frame and every built screen —
   picked with the **sheleg-design** companion skill when the project has no

package/templates/flows.md

@@ -1,7 +1,7 @@
 # User Flows
 
-<!-- Managed with super-ux (ux-contract v4). The HOW layer: task analysis
-and user flows. Flows reference screens by SCR-ID (full specs live in
+<!-- Managed with super-ux (ux-contract v5). The HOW layer: task analysis
+and user flows for the human lanes. Flows reference screens by SCR-ID (full specs live in
 screens.md). Scenarios in scenarios.md trace to FLW-IDs and must cover every
 node and edge. -->
 

package/templates/foundation.md

@@ -1,14 +1,27 @@
 # UX Foundation
 
-<!-- Managed with super-ux (ux-contract v4). The WHY layer: personas, jobs
-to be done, customer journeys, user stories. Update when the understanding
-of users changes; scenarios in scenarios.md trace to the IDs defined here. -->
+<!-- Managed with super-ux (ux-contract v5). The WHY layer: personas, actors,
+jobs to be done, customer journeys, user stories. Update when the understanding
+of users changes; capabilities.md and scenarios.md trace to the IDs defined
+here. -->
 
 ## Personas
 
 <!-- ### P-01: <name>
 1-3 sentences: who they are, what they know, what they want. Grounded in
-data/observation, recognizable by a real user. -->
+data/observation, recognizable by a real user.
+- **Agent use:** none | some | most (<evidence: RE-NN, the brief, an interview>)
+-->
+
+## Actors
+
+<!-- The non-human performers: agents acting for a persona, automations and
+outside systems. People stay in Personas.
+### A-01: <name>
+- **Kind:** agent | system
+- **Acts for:** P-01
+- **Grant:** <the scope it holds; never wider than its principal's role>
+-->
 
 ## Jobs to Be Done
 
@@ -24,8 +37,9 @@ data/observation, recognizable by a real user. -->
 
 <!-- ### JRN-01: <persona> — <job> (JTBD-01)
 - **Owner:** unknown
-| # | Stage | User action | Touchpoint | Emotion (1-5) | Pain | Opportunity |
-|---|-------|------------|------------|---------------|------|-------------|
+| # | Stage | User action | Performed by | Touchpoint | Emotion (1-5) | Pain | Opportunity |
+|---|-------|------------|--------------|------------|---------------|------|-------------|
+Performed by: the P- and A- ids that do this stage.
 -->
 
 ## Monetization

package/templates/scenarios.md

@@ -1,6 +1,6 @@
 # UX Scenarios
 
-<!-- Managed with super-ux (ux-contract v4). Update in the same change as any user-facing behavior change. -->
+<!-- Managed with super-ux (ux-contract v5). Update in the same change as any user-facing behavior change. -->
 
 ## Index
 
@@ -16,20 +16,23 @@ know, what they want. -->
 ## Scenarios
 
 <!-- Group scenarios by feature under "## <feature>" headings. Entry shape
-(see ux-contract v4 for field rules); steps are use-case style — one user
-action per step paired with the observable system response:
+(see ux-contract v5 for field rules); steps are use-case style: one user
+action per step paired with the observable system response. An agent-channel
+step is `A-NN -> tool -> observable response`, and its scenario cites the
+CAP-NN it exercises in Traces:
 
 ### SCN-001: <Title>
 - **Persona:** <persona-id>
 - **Feature:** <feature>
 - **Traces:** <ST-…, FLW-… (JTBD-…, JRN-…/#stage) — required when those layers exist>
+- **Channel:** human | agent | both
 - **Entry point:** <where the user starts>
 - **Preconditions:** <state required, or "none">
 - **Steps:**
   1. <user action> -> <observable system response>
 - **Expected result:** <what the user observes on success>
 - **Alt paths:** <meaningful non-error deviations and system responses, or omit>
-- **UI elements:** <every button, field, link, dialog, toast involved>
+- **UI elements:** <every button, field, link, dialog, toast involved; human channel only>
 - **States covered:** <loading | empty | error | success>
 - **Errors & recovery:** <each failure: what the user sees, how they recover>
 - **Telemetry:** <`object_action` event + params, or omit if none>

package/templates/screens.md

@@ -4,7 +4,7 @@
 <!-- The line above puts this registry on format 2: the screen matrix
 (states, axes, a frame per state, a story per built state) is a lint gate.
 Keep it. -->
-<!-- Managed with super-ux (ux-contract v4). The design map: every screen and
+<!-- Managed with super-ux (ux-contract v5). The design map: every screen and
 state with its Figma frame, wireframe, code coverage, and related UX/UI
 resources. Update in the same change as any interface change; when Figma is
 enabled, update the frame and re-verify its link in the same change. A screen
@@ -44,11 +44,13 @@ the problem it can no longer fix. -->
 
 ## Screens
 
-<!-- One entry per screen (see ux-contract v4 for field rules):
+<!-- One entry per screen (see ux-contract v5 for field rules):
 
 ### SCR-01: <name>
 - **Used by:** <FLW-… and the step(s)>
 - **Purpose:** <the job step this screen serves>
+- **Fronts:** <CAP-… this screen fronts, or none>
+- **Why human:** <oversight | exception-queue | trust | presence | audience | manual | taste> (<evidence>)
 - **Elements:** <each element; mark the ONE primary action>
 - **States:** (every one that applies: default, loading, empty, error,
   offline, long-content, keyboard-up, first-run, product-specific ones)
@@ -69,5 +71,5 @@ the problem it can no longer fix. -->
 - **Coverage:** <file:line, or "none yet">
 - **Scenarios:** <SCN-… touching this screen>
 - **Resources:** <related components, shared assets, API/data deps, links>
-- **Status:** designed | built | drifted | retired
+- **Status:** designed | blocked | built | drifted | retired
 -->

package/templates/vision.md

@@ -1,6 +1,6 @@
 # <Product> — Vision
 
-<!-- Managed with super-ux (ux-contract v4). The layer above the chain. -->
+<!-- Managed with super-ux (ux-contract v5). The layer above the chain. -->
 
 <!--
   Owned by the `vision` skill (super-ux). Nine sections, these headings, in
@@ -39,8 +39,10 @@
 
 ## 4. The user's role
 
-<!-- What the user becomes. Not "the user clicks" — the user directs, judges,
-     decides. If it reads like operating any other tool, go deeper. -->
+<!-- What the user becomes. Not "the user clicks": the user directs, judges,
+     decides. If it reads like operating any other tool, go deeper. Say
+     which work the person keeps and which their agent or an automation does
+     for them; the person is where a gate or a decision needs them. -->
 
 ## 5. Principles
 
@@ -67,7 +69,9 @@
 
 <!-- Three to five questions any proposed feature must pass. These are what
      the hard rule in the instruction file actually runs. A stranger should be
-     able to reject a plausible feature with them. -->
+     able to reject a plausible feature with them. Include one for agents:
+     can an agent do this without a screen, and if a person must, which gate
+     or serving reason says so? -->
 
 1. <question>
 2. <question>