@event4u/agent-config 1.34.0 → 1.35.0

package/docs/guidelines/cross-role-handoff.md

@@ -0,0 +1,127 @@
+# Cross-Role Handoff
+
+Wing-specific prose for senior-tier skills handing off across role
+boundaries. The mechanical contract — initiator → delegated(input) →
+output, lint rules, worktree boundary — lives in
+[`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md).
+This guideline covers **when a role hands off to another role**,
+**how to phrase the routing**, and the **L4 / C8 boundary**.
+
+## Wings at a glance
+
+The senior catalog spans four wings. Each wing owns a cognition
+cluster and emits artifacts the other wings can consume.
+
+| Wing | Cluster | Senior skills (anchor examples) |
+|---|---|---|
+| **1. Engineering** | Code, architecture, debugging, review | `architecture-review-lens`, `bug-analyzer`, `judge-bug-hunter`, `blast-radius-analyzer` |
+| **2. Product + Foundation** | Discovery, refinement, decisions | `po-discovery`, `refine-ticket`, `decision-record`, `rice-prioritization` |
+| **3. GTM + Growth** | Customers, comms, funnel, channels | `customer-research` (L1), `release-comms` (L2), `funnel-analysis` |
+| **4. Money + Strategy + Ops** | Unit economics, OKRs, capacity, risk | `unit-economics-modeling`, `okr-tree-modeling`, `dcf-modeling`, `risk-officer` |
+
+A handoff is **cross-role** when the initiator and the delegate live
+in different wings (or in different cognition clusters within the
+same wing). Same-cluster delegation is normal composition and does
+not need this guideline.
+
+## When to hand off
+
+A senior skill SHOULD hand off — not absorb — when any of the four
+fires:
+
+1. **Different cognition cluster.** The downstream step needs a
+   different mode of thinking (numbers vs. narrative; user vs.
+   system; risk vs. design). Absorbing it dilutes the skill.
+2. **Different artifact owner.** The output naturally lives under a
+   different role's catalog (e.g. `forecast-band.json` belongs to
+   Wing-4, not Wing-2).
+3. **Tier-mismatch risk.** Inlining the step would require
+   downgrading to a non-senior delegate; the cross-wing-handoff
+   linter blocks tier mismatches.
+4. **Re-use evidence.** The step is already cited by ≥ 2 other
+   senior skills; absorbing it duplicates cognition.
+
+If none fire, keep the step inline. Cross-role plumbing is not free.
+
+## How to phrase the handoff
+
+Two surfaces in the senior-skill template carry routing:
+
+- **`## Related Skills` § *WHEN NOT to use this*** — the routing
+  list. One bullet per peer that owns the cognition the user might
+  expect from this skill but is wrong to ask here. Format:
+  *"X is the actual question — route to [`<peer>`](../<peer>/SKILL.md)"*.
+- **`## Procedure` Composes line** — when the skill **does** call
+  another skill mid-procedure, declare it on a line beginning with
+  `Composes [`<peer>`](...)` so the linter can match the call site
+  to the delegate's `## Input` block.
+
+The delegated skill's `## Input` block names the fields the initiator
+must pass. Drift between the two is the failure the contract catches.
+
+## Decision tree
+
+```
+Need a downstream cognition step?
+├── Same wing + same cluster? → keep inline (normal composition).
+├── Different cluster, but no shipped senior peer?
+│   └── Implement inline; flag for next plate's audit (the cluster
+│       might need its own senior).
+├── Different cluster + shipped senior peer + ≥ 2 reuse citations?
+│   └── HAND OFF: declare in WHEN NOT block + Composes line.
+└── Cross-wing chain (≥ 3 senior steps, ≥ 30 min each)?
+    └── Use `subagent-orchestration` mode 6 (worktrees) per
+        cross-wing-handoff.md § 3.
+```
+
+## L4 / C8 composition boundary
+
+Council Q3 (2026-05-05) locks the disambiguation between L4
+`stakeholder-tradeoff` and the sibling C8 `code-review-multi-lens`:
+
+- **L4 fires** when a request crosses two stakeholder lenses
+  (engineering ↔ PO, PO ↔ ops, ops ↔ infra) and the trade-off is
+  **not yet code**. Output is a trade-off matrix + recommendation +
+  dissent log; the artifact is consumable by a roadmap or PR
+  description, not by a diff.
+- **C8 fires** when the request **is already code** — PR open, draft
+  branch under review, or a diff supplied as input. Output is a
+  multi-lens code review (security · architecture · tests · quality)
+  bound to file:line spans.
+- **C8 → L4 escalation.** A C8 verdict that surfaces a stakeholder
+  conflict — e.g. test-coverage judge fails but PO insists on
+  shipping — becomes **input to L4**. The escalation is one-way:
+  L4 produces the dissent log that decides whether C8's verdict
+  is overridden, with the override recorded in
+  [`decision-record`](../../.agent-src.uncompressed/skills/decision-record/SKILL.md).
+
+The boundary keeps the two skills sharp — neither absorbs the other —
+and gives the agent a deterministic rule for which one to load when
+both look applicable.
+
+## Worked example
+
+A PO refining a ticket (Wing-2) hits a sentence like *"the cheapest
+acquisition channel is paid search, but only if CAC payback < 6 months"*:
+
+1. Wing-2 is the initiator (`refine-ticket`).
+2. The CAC question is Wing-4 cognition — `unit-economics-modeling`.
+3. `refine-ticket` hands off via:
+   - WHEN NOT entry: *"CAC / payback questions — route to
+     [`unit-economics-modeling`](../unit-economics-modeling/SKILL.md)"*.
+   - Composes line in the procedure step that needs the answer.
+4. The delegate's `## Input` block lists the fields (channel,
+   cohort, time horizon); `refine-ticket` passes them.
+5. The output (`payback-band.md`) feeds the AC of the original ticket.
+
+No cluster collision, no tier mismatch, no untyped drift.
+
+## See also
+
+- [`docs/contracts/cross-wing-handoff.md`](../contracts/cross-wing-handoff.md)
+  — the mechanical contract this guideline cites.
+- [`docs/contracts/context-spine.md`](../contracts/context-spine.md)
+  — orthogonal context-slot mechanism, often used together with a
+  handoff (e.g. delegate reads `team` slot the initiator opted in to).
+- `.agent-src.uncompressed/skills/subagent-orchestration/SKILL.md` § mode 6
+  — when the chain runs in fresh worktrees.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@event4u/agent-config",
-    "version": "1.34.0",
+    "version": "1.35.0",
     "description": "Shared agent configuration \u2014 skills, rules, commands, guidelines, and templates for AI coding tools",
     "license": "MIT",
     "private": false,

package/scripts/lint_context_spine_usage.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""Context-spine usage linter.
+
+Closes the lint gap left after `scripts/schemas/skill.schema.json`
+gained the `context_spine` enum: a skill can declare
+`context_spine: [product]` in frontmatter without ever citing the
+slot in its body, and the schema check will not catch it.
+
+This linter enforces the author checklist in
+`docs/contracts/context-spine.md` § 6: for every slot declared in
+frontmatter, the skill body MUST cite the slot at least once.
+A citation is any of these tokens:
+
+  - the literal path `agents/context-spine/<slot>.md`
+  - the slot name in bold: ``**<slot>**``
+  - the slot name in inline code: `` `<slot>` ``
+
+Cap: ≤ 150 LOC, stdlib only. Hooked into `task ci` via
+`task lint-context-spine-usage`.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+QUIET = "--quiet" in sys.argv
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILL_GLOBS = (
+    ".agent-src.uncompressed/skills/**/SKILL.md",
+    ".agent-src/skills/**/SKILL.md",
+)
+VALID_SLOTS = ("product", "team", "repo")
+
+CONTEXT_SPINE_PAT = re.compile(
+    r"^context_spine:\s*\[([^\]]*)\]\s*$", re.MULTILINE
+)
+
+
+def _frontmatter_and_body(text: str) -> tuple[str, str]:
+    if not text.startswith("---\n"):
+        return "", text
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        return "", text
+    return text[4:end], text[end + 5 :]
+
+
+def _read_spine(fm: str) -> list[str] | None:
+    m = CONTEXT_SPINE_PAT.search(fm)
+    if m is None:
+        return None
+    raw = m.group(1).strip()
+    if not raw:
+        return []
+    return [s.strip().strip("'\"") for s in raw.split(",") if s.strip()]
+
+
+def _slot_cited(body: str, slot: str) -> bool:
+    """A slot is cited if any of three forms appears in the body."""
+    forms = (
+        f"agents/context-spine/{slot}.md",
+        f"**{slot}**",
+        f"`{slot}`",
+    )
+    return any(form in body for form in forms)
+
+
+def lint_skill(path: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    fm, body = _frontmatter_and_body(text)
+    if not fm:
+        return []
+    slots = _read_spine(fm)
+    if slots is None:
+        return []
+    problems: list[str] = []
+    for slot in slots:
+        if slot not in VALID_SLOTS:
+            problems.append(
+                f"unknown_context_spine_slot: '{slot}' "
+                f"(valid: {', '.join(VALID_SLOTS)})"
+            )
+            continue
+        if not _slot_cited(body, slot):
+            problems.append(
+                f"declared context_spine slot '{slot}' is never cited "
+                f"in the skill body — add `**{slot}**`, `` `{slot}` ``, "
+                f"or a link to `agents/context-spine/{slot}.md` "
+                f"(see docs/contracts/context-spine.md § 6)"
+            )
+    return problems
+
+
+def main() -> int:
+    skills: list[Path] = []
+    for pattern in SKILL_GLOBS:
+        skills.extend(sorted(REPO_ROOT.glob(pattern)))
+    if not skills:
+        print("❌  no SKILL.md files matched", file=sys.stderr)
+        return 1
+    failed = 0
+    declared = 0
+    for skill in skills:
+        rel = skill.relative_to(REPO_ROOT)
+        problems = lint_skill(skill)
+        text = skill.read_text(encoding="utf-8")
+        fm, _ = _frontmatter_and_body(text)
+        if fm and CONTEXT_SPINE_PAT.search(fm):
+            declared += 1
+        if problems:
+            failed += 1
+            print(f"❌  {rel}", file=sys.stderr)
+            for p in problems:
+                print(f"    - {p}", file=sys.stderr)
+    if failed:
+        print(
+            f"\n❌  {failed} skill(s) failed context-spine usage lint "
+            f"({declared} skill(s) declare a spine)",
+            file=sys.stderr,
+        )
+        return 1
+    if not QUIET:
+        print(
+            f"✅  {declared} skill(s) declare context_spine; "
+            f"all declared slots are cited in the body"
+        )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/lint_roadmap_complexity.py

@@ -35,6 +35,29 @@ COMPLEXITY_PAT = re.compile(
     r"^complexity:\s*(lightweight|structural)\s*$", re.MULTILINE
 )
 
+# Plate / horizon detection — template rule 16 forbids time-boxed plates
+# in roadmaps. Patterns match the authoring devices we are retiring.
+PLATE_PATS: tuple[tuple[re.Pattern[str], str], ...] = (
+    (re.compile(r"^##\s+Horizon\b", re.MULTILINE | re.IGNORECASE),
+     "'## Horizon' section header"),
+    (re.compile(r"\b\d+-week\s+(visible\s+)?plate\b", re.IGNORECASE),
+     "'N-week (visible) plate' phrasing"),
+    (re.compile(r"\bvisible\s+plate\b", re.IGNORECASE),
+     "'visible plate' phrasing"),
+    (re.compile(r"\b(in|out)-of-plate\b", re.IGNORECASE),
+     "'in-of-plate' / 'out-of-plate' marker"),
+    (re.compile(r"\bout-of-horizon\b", re.IGNORECASE),
+     "'out-of-horizon' marker"),
+    (re.compile(r"\bIn-plate\??\b"),
+     "'In-plate' / 'In-plate?' label"),
+    (re.compile(r"\bOut-of-plate\b"),
+     "'Out-of-plate' label"),
+    (re.compile(r"inside\s+(the\s+|\d+-week\s+)?plate", re.IGNORECASE),
+     "'inside the plate' phrasing"),
+    (re.compile(r"outside\s+(the\s+|\d+-week\s+)?plate", re.IGNORECASE),
+     "'outside the plate' phrasing"),
+)
+
 
 def _frontmatter(text: str) -> str:
     if not text.startswith("---\n"):
@@ -73,6 +96,19 @@ def _check_lightweight(text: str, line_count: int, problems: list[str]) -> None:
         )
 
 
+def _check_no_plate(text: str, problems: list[str]) -> None:
+    """Detect time-boxed plate / horizon framing forbidden by template rule 16."""
+    for pat, label in PLATE_PATS:
+        m = pat.search(text)
+        if m is None:
+            continue
+        line = text.count("\n", 0, m.start()) + 1
+        problems.append(
+            f"plate/horizon convention detected ({label}) at line {line} — "
+            f"forbidden by templates/roadmaps.md rule 16"
+        )
+
+
 def lint_roadmap(path: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     line_count = text.count("\n") + (1 if text and not text.endswith("\n") else 0)
@@ -87,6 +123,7 @@ def lint_roadmap(path: Path) -> list[str]:
         return problems
     if complexity == "lightweight":
         _check_lightweight(text, line_count, problems)
+    _check_no_plate(text, problems)
     return problems
 
 

package/scripts/schemas/skill.schema.json

@@ -67,6 +67,15 @@
       "enum": ["deep"],
       "description": "Optional reasoning-depth marker for AI Council invocations triggered by this skill. The only accepted value is 'deep'; omit the key for default depth (setting 'standard' is rejected — every frontmatter byte counts against the context window, and 'standard' is the implicit default). 'deep' instructs the host agent to pass --depth deep to council_cli, which floors rounds at max(ai_council.deep_min_rounds, ai_council.min_rounds). Use for architecture, refactoring, or bug-diagnosis skills. See .agent-src.uncompressed/skills/ai-council/SKILL.md."
     },
+    "context_spine": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": ["product", "team", "repo"]
+      },
+      "description": "Senior-skill opt-in for the tri-slot context spine. Declares which slots under agents/context-spine/ the skill expects to read (product, team, repo). Council Q1 (KEEP-3) locks the slot count at 3; additions require ≥ 2 citing skills + ADR per docs/contracts/context-spine.md § 5."
+    },
     "execution": {
       "type": "object",
       "additionalProperties": false,