cohorte 1.2.5 → 1.3.0

package/core/hooks/gate.py

@@ -16,6 +16,23 @@ A pattern matches a command segment when the segment *contains* the pattern
 (after normalizing whitespace). `deny` wins over `ask`. If the config is missing
 or unreadable, the hook stays silent (exit 0) and lets settings.json decide.
 
+The hook fires for EVERY agent in the session — the lead, /build's implementers,
+and subagents spawned by the Workflow runtime alike. Workflow subagents run in
+acceptEdits regardless of the session's permission mode (their Write/Edit calls
+are auto-approved), but acceptEdits does NOT auto-approve Bash or Task, so this
+gate still sees and can block them. In bypassPermissions (headless `claude -p`,
+dashboard actions) there is no human to answer a prompt, so every `ask` match is
+escalated to a hard deny with the reason attached — a clear refusal beats a
+prompt that can never be answered.
+
+Two extra duties beyond Bash patterns:
+
+- Phase gate (`preflight` block in gate-config.json): a Task dispatch of a
+  listed subagent_type (default review/smoke) requires a fresh
+  `.claude/preflight.ok` stamp, written by pipeline/scripts/preflight.sh when
+  typecheck+lint+tests are green. Stale/missing stamp => "ask" — dispatching
+  reviewers onto code that doesn't compile burns their whole run.
+
 Protocol: reads the PreToolUse payload on stdin; emits a JSON permissionDecision
 of "deny" or "ask" on a match; otherwise exits 0 silently.
 """
@@ -25,6 +42,7 @@ import os
 import re
 import subprocess
 import sys
+import time
 
 SPLIT = re.compile(r"&&|\|\||[;|\n]")
 WS = re.compile(r"\s+")
@@ -33,18 +51,24 @@ WS = re.compile(r"\s+")
 def load_config() -> dict:
     root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
     path = os.path.join(root, ".claude", "gate-config.json")
-    empty = {"deny": [], "ask": [], "ask_on_default_branch": [], "default_branch": "main"}
+    empty = {"deny": [], "ask": [], "ask_on_default_branch": [], "default_branch": "main",
+             "preflight": {}}
     try:
         with open(path, "r", encoding="utf-8") as fh:
             cfg = json.load(fh)
     except Exception:
         return empty
+    preflight = cfg.get("preflight")
+    if not isinstance(preflight, dict):
+        preflight = {}
     return {
         "deny": list(cfg.get("deny", [])),
         "ask": list(cfg.get("ask", [])),
         # Patterns gated ONLY on the default branch — allowed freely on feature branches.
         "ask_on_default_branch": list(cfg.get("ask_on_default_branch", [])),
         "default_branch": cfg.get("default_branch", "main") or "main",
+        # Phase gate: {"enabled": true, "agents": ["review","smoke"], "max_age_minutes": 30}
+        "preflight": preflight,
     }
 
 
@@ -67,22 +91,83 @@ def current_branch():
     return None
 
 
+def current_head():
+    """HEAD sha of CLAUDE_PROJECT_DIR, or None."""
+    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=root, capture_output=True, text=True, timeout=3,
+        )
+        if out.returncode == 0:
+            return out.stdout.strip() or None
+    except Exception:
+        pass
+    return None
+
+
+def check_preflight(payload: dict, cfg: dict) -> int:
+    """Phase gate on Task dispatches: review/smoke agents need a green preflight stamp."""
+    pf = cfg.get("preflight") or {}
+    if not pf.get("enabled"):
+        return 0
+    agents = pf.get("agents") or ["review", "smoke"]
+    subagent = (payload.get("tool_input") or {}).get("subagent_type", "") or ""
+    if subagent not in agents:
+        return 0
+
+    root = os.environ.get("CLAUDE_PROJECT_DIR", ".")
+    stamp = os.path.join(root, ".claude", "preflight.ok")
+    why = None
+    try:
+        with open(stamp, "r", encoding="utf-8") as fh:
+            epoch_s, _, sha = fh.read().strip().partition(" ")
+        age_min = (time.time() - float(epoch_s)) / 60
+        max_age = float(pf.get("max_age_minutes", 30) or 30)
+        if age_min > max_age:
+            why = f"the preflight stamp is {age_min:.0f} min old (max {max_age:.0f})"
+        else:
+            head = current_head()
+            if head and sha not in ("", "none") and head != sha:
+                why = "HEAD moved since the preflight ran"
+    except Exception:
+        why = "no preflight stamp found"
+    if why is None:
+        return 0
+    return decide(
+        "ask",
+        f"Phase gate: dispatching `{subagent}` but {why}. Run the deterministic pre-flight first "
+        f"(pipeline/scripts/preflight.sh — typecheck + lint + tests) so agents never review red code; "
+        f"or confirm to dispatch anyway (PIPELINE.md gate.preflight).",
+    )
+
+
 def main() -> int:
     try:
         payload = json.load(sys.stdin)
     except Exception:
         return 0  # malformed input → don't block
 
-    if payload.get("tool_name") != "Bash":
+    tool = payload.get("tool_name")
+    cfg = load_config()
+
+    if tool == "Task":
+        return check_preflight(payload, cfg)
+    if tool != "Bash":
         return 0
 
     command = (payload.get("tool_input") or {}).get("command", "") or ""
-    cfg = load_config()
     deny, ask, branch_gated = cfg["deny"], cfg["ask"], cfg["ask_on_default_branch"]
     default = cfg["default_branch"]
     if not deny and not ask and not branch_gated:
         return 0
 
+    # No human can answer a prompt in bypassPermissions (headless runs) — an "ask"
+    # there either hangs or silently auto-resolves, so escalate it to a clear deny.
+    unattended = payload.get("permission_mode") == "bypassPermissions"
+    ask_decision = "deny" if unattended else "ask"
+    ask_suffix = " (denied outright: unattended run, nobody to confirm)" if unattended else ""
+
     # Branch-conditional patterns (e.g. git/docker) are gated only on the default branch;
     # on a feature branch they run freely. Unknown branch (no repo / detached / no git) ⇒
     # be conservative and gate. Resolve the branch once, lazily.
@@ -100,12 +185,16 @@ def main() -> int:
                 return decide("deny", f"`{pat}` is forbidden by the project's PIPELINE.md gate.")
         for pat in ask:
             if norm(pat) in seg:
-                return decide("ask", f"`{pat}` is a gated command — confirm first (PIPELINE.md gate).")
+                return decide(ask_decision,
+                              f"`{pat}` is a gated command — confirm first (PIPELINE.md gate)."
+                              f"{ask_suffix}")
         if on_default:
             for pat in branch_gated:
                 if norm(pat) in seg:
-                    return decide("ask", f"`{pat}` is gated on the default branch `{default}` — confirm "
-                                         f"(PIPELINE.md gate). It runs freely on feature branches.")
+                    return decide(ask_decision,
+                                  f"`{pat}` is gated on the default branch `{default}` — confirm "
+                                  f"(PIPELINE.md gate). It runs freely on feature branches."
+                                  f"{ask_suffix}")
 
     return 0
 

package/core/templates/agent-handoff.md

@@ -1,7 +1,8 @@
 # HANDOFF — <surface> · `<feature_id>`
 
 <!-- Keep it tight: the lead only acts on mismatches, test failures, remediation ticks, and TODOs.
-     Never list files one by one — the lead has `git diff --stat`. -->
+     Never list files one by one — the lead has `git diff --stat`. Never paste code excerpts —
+     a file:line reference is enough, the code is on disk. One line per item. -->
 
 ## Summary
 

package/core/templates/review-feedback.md

@@ -2,7 +2,10 @@
 
 <!-- Emitted-report shape. Everything in an HTML comment is guidance — do NOT emit it.
      Verdict rules live in the review agent's instructions (SHIP = no CRITICAL/security;
-     REVISE = ≥1 CRITICAL; BLOCK = security vulnerability). -->
+     REVISE = ≥1 CRITICAL; BLOCK = security vulnerability).
+     CAPPED: max 20 findings, ONE line each (severity · file:line · type · concrete fix),
+     ZERO code excerpts — file:line is enough, the source is on disk. Overflow ⇒ keep all
+     CRITICAL/HIGH/security, fill by severity, close with one `+<n> more …` line. -->
 
 feature_id: <feature_id>
 Feature branch: <feature_branch_prefix><feature_id>

package/core/templates/steps/init-pipeline/02-interview-gaps.md

@@ -15,6 +15,13 @@ Ask ONLY what you couldn't confidently detect. Batch related questions. Cover:
   per SCHEMA.md §Specialization. If the human accepts, apply the rules: **shared code (routing, global
   state, DS kit/tokens) becomes its own single-owner surface**, and cross-slice shapes go through the
   contract. Default to NOT splitting when boundaries are tangled or slices are tiny — coarse is fine.
+- **Quiet commands** (never store a bare `pnpm test` as what agents execute) — for each noisy command
+  (tests, lint; per surface AND repo-wide), propose the detected **bridled variant** as the
+  Recommended option: dot/failures-only reporter (`--reporter=dot` vitest/playwright, `--silent`
+  jest, `-q` pytest, `--quiet` eslint/ruff — whatever the detected runner supports). These land in
+  `test_quiet_cmd`/`lint_quiet_cmd` + `commands.test_quiet`/`lint_quiet` and are what agents and the
+  `/review`·`/smoke` pre-flight actually run (SCHEMA.md §Output discipline). If the human declines or
+  the runner has no such flag, leave `""` — consumers then fall back to `<cmd> 2>&1 | tail -40`.
 - **Contract** — mechanism (`shared-types-zod` / `openapi` / `protobuf` / `json-schema` / `none`) and
   where feature contracts are authored. If `none`, surfaces sync by the spec prose alone.
 - **UI language** — language of all user-facing copy.

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -9,18 +9,26 @@
 3. **Render one agent per surface** — for each surface, follow SCHEMA.md §"Rendering / reconciling a
    surface agent" (steps 2–3): render `.claude/agents/<agent>.md` from the installer's
    `pipeline/implementer.template.md`, substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`, `<SURFACE_PATH>`,
-   `<SURFACE_TOOLS>`, `<SURFACE_MODEL>`, `<PROJECT_NAME>`, and the surface-specific blocks
+   `<SURFACE_TOOLS>`, `<SURFACE_MODEL>`, `<PROJECT_NAME>`, `<SURFACE_CONVENTIONS>` (the surface's
+   baked convention slice — §Shared + its `### Surface:` stanza + its §Testing lines from the
+   PIPELINE.md you just wrote), and the surface-specific blocks
    (`<SURFACE_EXTRA_NEVER>`, `<SURFACE_DESIGN_INPUT>`, `<SURFACE_TDD_STEP1>` — fill design-related ones
    only when `uses_design`).
-   Leave `review.md` + `release.md` as-is (generic).
-4. **Generate `.claude/gate-config.json`** from the `gate` block — copy all four keys verbatim:
-   `{"deny": [...], "ask": [...], "ask_on_default_branch": [...], "default_branch": "<vcs.default_branch>"}`.
+   Leave `review.md` + `release.md` + `profile-reader.md` as-is (generic).
+4. **Generate `.claude/gate-config.json`** from the `gate` block — copy all five keys verbatim:
+   `{"deny": [...], "ask": [...], "ask_on_default_branch": [...], "default_branch": "<vcs.default_branch>",
+   "preflight": {"enabled": <gate.preflight.enabled>, "agents": [...], "max_age_minutes": <n>}}`
+   (profile has no `preflight` block ⇒ omit the key — the hook then skips the phase gate).
 5. **Write `.claude/settings.json`** permissions (`ask`/`deny` lists mirroring the gate, **plus an
    `allow` list of the project's read-only / verification commands** so agents don't stall on
-   permission prompts: the detected per-surface `test_cmd`/`lint_cmd`/`typecheck_cmd`/`build_cmd`
-   and repo-wide `commands.*` equivalents as `Bash(<cmd>:*)` rules, plus read-only git —
-   `Bash(git status:*)`, `Bash(git diff:*)`, `Bash(git log:*)`. Never allowlist anything matching a
-   `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
+   permission prompts — including mid-workflow, where nobody is watching a prompt: the detected
+   per-surface `test_cmd`/`lint_cmd`/`typecheck_cmd`/`build_cmd` **and their `*_quiet_cmd`
+   variants** and repo-wide `commands.*` equivalents as `Bash(<cmd>:*)` rules, plus read-only git —
+   `Bash(git status:*)`, `Bash(git diff:*)`, `Bash(git log:*)`, `Bash(git rev-parse:*)` — plus the
+   shipped pipeline scripts for BOTH cores (`Bash(.claude/pipeline/scripts/:*)` and
+   `Bash(~/.claude/pipeline/scripts/:*)` — preflight, kanban-move, telemetry-send), and the
+   retrieval provider's MCP tools when wired (e.g. `mcp__serena`). Never allowlist anything matching
+   a `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
    `/fewer-permission-prompts`) + the hooks, **conditioned on the install mode:**
    - **bundled:** register the PreToolUse `Bash` hook `.claude/hooks/gate.py` and the PostToolUse
      formatter (detected formatter).

package/core/workflows/audit.js

@@ -0,0 +1,144 @@
+// cohorte — /audit as a deterministic workflow (opt-in; the conversational
+// /audit command remains the default path and the fallback).
+//
+// Invoke with args = {target: "<path or domain>"} (optional — default whole repo).
+//
+// Shape (SCHEMA.md §Workflows): profile via profile-reader (phase 0), the
+// mechanical gates staged to disk by one haiku agent, then ONE auditor per
+// domain (each surface + `shared`) running concurrently — the runtime caps
+// concurrency at ~16, extra domains queue — and a merge phase that writes the
+// prioritized specs/refactor-backlog.md. Only the summary comes back.
+
+export const meta = {
+  name: 'cohorte-audit',
+  description: 'Audit the codebase against PIPELINE.md: mechanical gates, one auditor per domain in parallel, prioritized refactor backlog',
+  whenToUse: 'Only when the human explicitly asks for the audit workflow. args = {target: "<path or domain>"} — omit for the whole repo.',
+  phases: [
+    { title: 'Profile', detail: 'PIPELINE.md → JSON via profile-reader', model: 'haiku' },
+    { title: 'Gates', detail: 'format/lint/typecheck/tests → specs/reports/audit-gates.txt', model: 'haiku' },
+    { title: 'Audit', detail: 'one review-in-audit-mode agent per domain (concurrent, runtime-capped ~16)' },
+    { title: 'Backlog', detail: 'merge + write specs/refactor-backlog.md', model: 'haiku' },
+  ],
+}
+
+const target = (typeof args === 'string' ? args.trim() : args && args.target) || ''
+
+const PROFILE = { type: 'object', additionalProperties: true }
+
+const GATES = {
+  type: 'object', required: ['failures'], additionalProperties: false,
+  properties: {
+    failures: {
+      type: 'array', maxItems: 40,
+      items: {
+        type: 'object', required: ['file', 'line', 'kind', 'summary'], additionalProperties: false,
+        properties: {
+          file: { type: 'string' }, line: { type: 'integer' },
+          kind: { enum: ['lint', 'format', 'type', 'test'] },
+          summary: { type: 'string', description: 'one line, no output excerpts' },
+        },
+      },
+    },
+    overflow: { type: 'integer', description: 'failures beyond the 40-item cap' },
+  },
+}
+
+const BACKLOG = {
+  type: 'object', required: ['items'], additionalProperties: false,
+  properties: {
+    items: {
+      type: 'array', maxItems: 30,
+      items: {
+        type: 'object', required: ['severity', 'file', 'line', 'kind', 'fix'], additionalProperties: false,
+        properties: {
+          severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
+          file: { type: 'string' }, line: { type: 'integer' },
+          kind: { enum: ['rule', 'tdd', 'lint', 'format', 'type', 'security'] },
+          fix: { type: 'string', description: 'one concrete change, one line, no code excerpts' },
+        },
+      },
+    },
+    overflow: { type: 'integer' },
+  },
+}
+
+// ── Phase 0 — profile ────────────────────────────────────────────────────────
+phase('Profile')
+const profile = await agent(
+  'Return this project\'s PIPELINE.md `yaml pipeline-profile` block as JSON, per your instructions.',
+  { agentType: 'profile-reader', label: 'profile', schema: PROFILE, effort: 'low' },
+)
+if (!profile || profile.error) {
+  return { error: `profile unreadable: ${(profile && profile.error) || 'profile-reader returned nothing'}` }
+}
+const cmds = profile.commands || {}
+const surfaces = Array.isArray(profile.surfaces) ? profile.surfaces : []
+const quiet = (q, full) => (q && !String(q).startsWith('<') ? q : full ? `${full} 2>&1 | tail -40` : '')
+const scope = target || 'the whole repo'
+
+// ── Phase 1 — mechanical gates, staged to disk ───────────────────────────────
+phase('Gates')
+const gateCmds = [
+  cmds.format ? `${cmds.format} --check` : '',
+  quiet(cmds.lint_quiet, cmds.lint),
+  cmds.typecheck,
+  quiet(cmds.test_quiet, cmds.test),
+].filter(c => c && !String(c).startsWith('<'))
+const gates = await agent(
+  `Run the cohorte audit's mechanical gates, scoped to ${scope}. Commands (adapt the format one to the ` +
+  `project's check mode if --check is wrong): ${gateCmds.map(c => JSON.stringify(c)).join(' · ')}.\n` +
+  'Redirect EVERY command\'s output into specs/reports/audit-gates.txt (append, `cmd >> file 2>&1`) — ' +
+  'never print it — and keep going after failures (this is an inventory, not a gate to pass). Then grep ' +
+  'the file and return each failure as file/line/kind/one-line summary, capped at 40 (set overflow for the rest).',
+  { model: 'haiku', label: 'gates', schema: GATES, effort: 'low' },
+)
+const mech = (gates && gates.failures) || []
+log(`Mechanical failures: ${mech.length}${gates && gates.overflow ? ` (+${gates.overflow} overflow)` : ''}`)
+
+// ── Phase 2 — one auditor per domain, concurrent ─────────────────────────────
+// Domains = every surface + `shared` (contract package + anything outside the
+// surface trees). The runtime caps concurrent agents (~16); more domains queue.
+phase('Audit')
+const domains = surfaces.map(s => ({ key: s.key, path: s.path }))
+  .concat([{ key: 'shared', path: (profile.contract && profile.contract.path) || '(everything outside the surface trees)' }])
+  .filter(d => !target || target === d.key || String(d.path).startsWith(target) || target.startsWith(String(d.path)))
+if (!domains.length) return { error: `target "${target}" matches no surface/domain` }
+
+const audited = await parallel(domains.map(d => () => agent(
+  'Audit a target against PIPELINE.md (no spec — audit mode, per your agent instructions). Check ' +
+  'conventions for the domain\'s surface, TDD coverage (untested entry points / modules), and — if the ' +
+  'profile enables them — mobile-first + design-system usage. Mechanical findings are already staged: ' +
+  'read specs/reports/audit-gates.txt and fold the ones in your domain in. Return the prioritized items, ' +
+  'capped at 30, one line each, no code excerpts. — Variable slots: domain: ' +
+  `${d.key} · tree: ${d.path}${target ? ` · human-requested target: ${target}` : ''}`,
+  { agentType: 'review', label: `audit:${d.key}`, schema: BACKLOG },
+).then(r => r && { key: d.key, items: r.items, overflow: r.overflow || 0 })))
+const perDomain = audited.filter(Boolean)
+
+// ── Phase 3 — merge + write the backlog ──────────────────────────────────────
+phase('Backlog')
+const SEV = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 }
+const body = ['# Refactor backlog', '', `> Generated by the cohorte-audit workflow (scope: ${scope}).`]
+let total = 0
+for (const d of perDomain) {
+  const items = [...d.items].sort((a, b) => SEV[a.severity] - SEV[b.severity])
+  total += items.length
+  body.push('', `## ${d.key}`, '')
+  for (const it of items) body.push(`- [ ] ${it.severity} · ${it.file}:${it.line} · ${it.kind} · ${it.fix}`)
+  if (d.overflow) body.push(`- [ ] (+${d.overflow} more beyond the cap — re-audit ${d.key} after this pass)`)
+}
+await agent(
+  `Write EXACTLY this content to specs/refactor-backlog.md (overwrite), then return the single word done:\n<<<BACKLOG\n${body.join('\n')}\nBACKLOG`,
+  { model: 'haiku', label: 'write-backlog', effort: 'low' },
+)
+
+return {
+  backlog: 'specs/refactor-backlog.md',
+  mechanicalFailures: mech.length,
+  domains: Object.fromEntries(perDomain.map(d => [d.key, d.items.length + (d.overflow || 0)])),
+  total,
+  top: perDomain.flatMap(d => d.items.map(it => ({ ...it, domain: d.key })))
+    .sort((a, b) => SEV[a.severity] - SEV[b.severity]).slice(0, 10)
+    .map(it => `[${it.severity}] ${it.domain} · ${it.file}:${it.line} — ${it.fix}`),
+  next: 'refactor a domain with /refactor <domain> (or the refactor workflow for big domains)',
+}