claude-company 0.1.1 → 0.2.0

package/.claude/agents/architect.md

@@ -38,6 +38,16 @@ yourself - it is frozen; hand the CEO the JSON to apply):
 5. **The gate ladder.** Propose `company/gates.config` entries per
    `company/GATES.md`, including the negative-space tests (generated
    complement of any allow-table) and the integrator-owned golden-path e2e.
+6. **Architecture decision records.** For every boundary-shaping decision in
+   Phase 0 or program planning - the narrow waist, a single-writer surface, a
+   kernel extension point, a frozen path - write a proposed ADR with
+   `company/templates/ADR-TEMPLATE.md` (`Status: proposed`, one decision per
+   record) under `company/adr/`, and keep `company/adr/README.md` index and
+   next-free number honest. The CEO accepts by setting `Status: accepted`;
+   from that moment the ADR is immutable (a guard blocks edits) and changes
+   only through a superseding ADR. Precedence: an accepted ADR wins on
+   architecture (how), the spec wins on scope (what) - so never propose an ADR
+   that fights an accepted one; supersede it instead.
 
 ## The solutioning gate (mandatory before any program)
 

package/.claude/agents/devops-engineer.md

@@ -24,6 +24,16 @@ anticlimax.
   fires on merge, never wrap deploy in a make target an agent could run.
   Deploys are manual, owner-only, forever. If asked to automate one, decline
   in your report and say why.
+- **Release preparation is yours; the ship is not.** When the CEO invokes
+  `/release`, you assemble the release per `company/RELEASE.md` from integrated
+  `main` (never a worktree): the changelog derived from conventional commits and
+  their `Task:` trailers since the last tag, a semver bump proposal with its
+  one-line reasoning, release notes written as an evidence report (what shipped,
+  the gate ladder, known limits), and the filled `RELEASE-TEMPLATE.md`
+  checklist. You prepare only from a green readiness board; a red criterion is a
+  stop, not a footnote. Your output ends at material the CEO turns into a
+  proposal on `DECISIONS.md` - you never tag, push a tag, publish, or deploy,
+  and never write a step that does.
 - **Migrations are forward-only and immutable once shipped.** Your release
   notes state the migration order and the rollback story explicitly.
 - **Secrets never enter the repo.** Env templates (`.env.example`) yes,

package/.claude/agents/docs-librarian.md

@@ -30,6 +30,14 @@ code itself is a finding for the CEO, not a judgment call for you.
    accurate, `MODULE.md` tables current.
 5. Archive: shipped specs to `company/specs/shipped/`, their briefs to
    `company/briefs/shipped/`.
+6. Keep the ADR index true. After a merge, reconcile `company/adr/README.md`
+   with the ADRs on disk: every record indexed, every row's title and scope
+   accurate, the next-free number correct. Verify each accepted ADR's `Scope`
+   paths still exist; a scope pointing at a path the merge deleted or moved is a
+   finding for the CEO. You NEVER change an ADR's `Status` and never edit an
+   accepted ADR - both are CEO actions applied through a CR, and the guard will
+   block you anyway. Index and cross-references are yours; the records
+   themselves are not.
 
 Report: docs touched (paths), statements corrected (before -> after, the
 load-bearing ones), conflicts you could not resolve, indexes updated. Facts,

package/.claude/agents/tech-lead.md

@@ -56,8 +56,10 @@ only by CR - for you and your whole team.
   explicit paths only - never `git add -A`.
 - QA evidence is committed at `company/evidence/<task-slug>/` - it ships
   with the task.
-- You never merge to main; the CEO integrates after verifying. Your branch
-  green and your evidence report complete IS your handoff.
+- You never merge to main and never push anything; the CEO integrates after
+  verifying (via a PR carrying your evidence report when the project has a
+  remote, via a local --no-ff merge when it does not). Your branch green and
+  your evidence report complete IS your handoff.
 
 ## Boundaries
 

package/.claude/hooks/context_pin.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+"""UserPromptSubmit hook: inject a one-line claude-company execution pin.
+
+Every user turn gets a compact status line drawn from the active task and the
+provenance ledger - for a feature/program task: execution mode, dispatch
+count, self-authored count, and (in PR mode with no tracking issues) an iss=0
+drift flag; for any other type: just the counts. A second line fires only when
+a feature/program task has an idle team (no execution decision, or a decision
+with zero dispatches), nudging a decision or a dispatch.
+
+Pure read: never blocks, always exits 0, fails open on any internal error. The
+roster and the doctrine already live in the system prompt, so this stays
+deliberately under a tight token budget - nothing beyond the pin is injected.
+Python 3.8 stdlib only.
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _common as c  # noqa: E402
+import guard_provenance as gp  # noqa: E402
+
+PREFIX = "[company]"
+FEATURE_TYPES = ("feature", "program")
+UNDECIDED = "undecided"
+DRIFT_SEGMENT = " iss=0"
+IDLE_LINE = "[company] team idle - decide execution / dispatch a tech-lead"
+
+
+def emit(text):
+    # OQ-DE-01 assumption: plain stdout + exit 0 is the documented injection
+    # contract; a schema change is then a one-function edit.
+    print(text)
+    sys.exit(0)
+
+
+def main():
+    payload = c.read_stdin_json()
+    try:
+        root = c.project_root(payload)
+        task = c.active_task(root)
+        if not isinstance(task, dict):
+            sys.exit(0)  # no active task -> nothing to pin
+
+        slug = task.get("task")
+        ttype = task.get("type")
+        ledger = gp.read_ledger(root)
+        disp = len(ledger["dispatches"])
+        selfn = len(ledger["self_authored"])
+
+        if ttype in FEATURE_TYPES:
+            decision = gp.execution_decision(task)
+            line1 = "{} {} {} exec={} disp={} self={}".format(
+                PREFIX, slug, ttype, decision or UNDECIDED, disp, selfn
+            )
+            # FR-DE-15 drift signal: the tracking gate is armed and nothing is
+            # recorded (PR mode, feature/program, no valid issues).
+            if gp.tracking_untracked(root, task):
+                line1 += DRIFT_SEGMENT
+            drifty = decision is None or disp == 0
+        else:
+            # OQ-DE-04 assumption: ideation treated like quick - no exec, no
+            # iss, no idle line.
+            line1 = "{} {} {} disp={} self={}".format(
+                PREFIX, slug, ttype, disp, selfn
+            )
+            drifty = False
+
+        lines = [line1]
+        if drifty:
+            lines.append(IDLE_LINE)
+        emit("\n".join(lines))
+    except SystemExit:
+        raise
+    except Exception:
+        pass
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/cost_capture.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Stop/SubagentStop hook: log per-invocation token usage and an estimated cost.
+
+Registered on both Stop and SubagentStop. On each invocation it reads the
+session transcript (JSONL), computes the token DELTA since the last time this
+session was seen (via a per-session byte-offset cursor), and appends one
+greppable line to company/state/costs.log. It NEVER blocks and ALWAYS exits 0:
+this is passive accounting, not enforcement. Everything fails open - on any
+error the hook exits 0 silently rather than disturbing a stop.
+
+The delta cursor is the hard invariant: tokens already attributed to a session
+are never counted twice, including after a transcript compaction shrinks the
+file (OQ-W1-03). Cost is an estimate only, not billing (OQ-W1-01).
+"""
+
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+import _common as c  # noqa: E402
+
+HOOK = "cost_capture"
+
+_ZEROS = {"in": 0, "out": 0, "cache_r": 0, "cache_w": 0}
+
+
+def _event_kind(payload):
+    """Map the hook event name to the log column. Defaults to stop (OQ-W1-04)."""
+    event = payload.get("hook_event_name") or ""
+    if event == "SubagentStop":
+        return "subagent_stop"
+    # "Stop" and anything unexpected/missing fall through to stop.
+    return "stop"
+
+
+def _sum_assistant(lines):
+    """Aggregate token usage across assistant lines in an iterable of raw bytes-decoded strings.
+
+    Returns (totals_dict, last_model). Non-parsing lines and lines lacking the
+    assistant message/usage shape are skipped silently (read defensively,
+    OQ-W1-04). A transcript is JSONL: whole objects appended one per line, so a
+    byte range that starts at a prior EOF only ever contains whole lines.
+    """
+    import json
+
+    totals = dict(_ZEROS)
+    last_model = None
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except Exception:
+            continue
+        if not isinstance(obj, dict) or obj.get("type") != "assistant":
+            continue
+        message = obj.get("message")
+        if not isinstance(message, dict):
+            continue
+        model = message.get("model")
+        usage = message.get("usage")
+        if not isinstance(usage, dict):
+            continue
+
+        def _n(key):
+            v = usage.get(key, 0)
+            return v if isinstance(v, int) else 0
+
+        totals["in"] += _n("input_tokens")
+        totals["out"] += _n("output_tokens")
+        totals["cache_w"] += _n("cache_creation_input_tokens")
+        totals["cache_r"] += _n("cache_read_input_tokens")
+        if isinstance(model, str) and model:
+            last_model = model
+    return totals, last_model
+
+
+def _read_range(path, start, end):
+    """Decode transcript bytes [start, end) into text (utf-8, replace errors)."""
+    with open(path, "rb") as f:
+        f.seek(start)
+        data = f.read(end - start)
+    return data.decode("utf-8", "replace")
+
+
+def _estimate(models_path, model, delta):
+    """Return an 'est=$X.XX' string, or None when no pricing applies.
+
+    Reads company/models.json 'pricing' defensively. USD per MTok. Missing rate
+    sub-keys default to 0. OQ-W1-01: estimate only, not billing.
+    """
+    if not model:
+        return None
+    models = c.read_json_file(models_path)
+    pricing = models.get("pricing") if isinstance(models, dict) else None
+    if not isinstance(pricing, dict):
+        return None
+    rate = None
+    for key, value in pricing.items():
+        if key == "$comment":
+            continue
+        if isinstance(key, str) and key.lower() in model.lower():
+            rate = value
+            break
+    if not isinstance(rate, dict):
+        return None
+
+    def _r(name):
+        v = rate.get(name, 0)
+        return v if isinstance(v, (int, float)) else 0
+
+    est = (
+        delta["in"] * _r("input")
+        + delta["out"] * _r("output")
+        + delta["cache_w"] * _r("cache_write")
+        + delta["cache_r"] * _r("cache_read")
+    ) / 1000000.0
+    return "est=$%.2f" % est
+
+
+def main():
+    payload = c.read_stdin_json()
+    if payload is None:
+        sys.exit(0)
+
+    try:
+        import json
+
+        root = c.project_root(payload)
+        kind = _event_kind(payload)
+
+        transcript_path = payload.get("transcript_path")
+        session_id = payload.get("session_id")
+        # OQ-W1-03 fail open: no transcript or session, no unreadable file -> no line.
+        if not transcript_path or not session_id:
+            sys.exit(0)
+        if not os.path.isfile(transcript_path):
+            sys.exit(0)
+
+        session8 = session_id[:8]
+
+        state_dir = os.path.join(root, "company", "state")
+        cursor_path = os.path.join(state_dir, ".cost-cursor.json")
+        costs_path = os.path.join(state_dir, "costs.log")
+        models_path = os.path.join(root, "company", "models.json")
+
+        cursor = c.read_json_file(cursor_path)
+        if not isinstance(cursor, dict):
+            cursor = {}
+        entry = cursor.get(session_id)
+        if not isinstance(entry, dict):
+            entry = {"offset": 0, "cum": dict(_ZEROS)}
+        prev_offset = entry.get("offset", 0)
+        if not isinstance(prev_offset, int) or prev_offset < 0:
+            prev_offset = 0
+        prev_cum = entry.get("cum")
+        if not isinstance(prev_cum, dict):
+            prev_cum = dict(_ZEROS)
+        prev_cum = {k: (prev_cum.get(k, 0) if isinstance(prev_cum.get(k, 0), int)
+                        else 0) for k in _ZEROS}
+
+        size = os.path.getsize(transcript_path)
+
+        if size >= prev_offset:
+            # NORMAL: only the freshly-appended byte range is new.
+            text = _read_range(transcript_path, prev_offset, size)
+            totals, model = _sum_assistant(text.splitlines())
+            delta = dict(totals)
+            new_offset = size
+            new_cum = {k: prev_cum[k] + delta[k] for k in _ZEROS}
+        else:
+            # COMPACTION: the transcript shrank. Re-read the whole file and take
+            # per-key max(0, file_total - cum). Surviving lines were already
+            # counted, so this delta is ~0 - the guard against double-counting.
+            text = _read_range(transcript_path, 0, size)
+            file_total, model = _sum_assistant(text.splitlines())
+            delta = {k: max(0, file_total[k] - prev_cum[k]) for k in _ZEROS}
+            new_offset = size
+            new_cum = {k: max(prev_cum[k], file_total[k]) for k in _ZEROS}
+
+        cursor[session_id] = {"offset": new_offset, "cum": new_cum}
+
+        os.makedirs(state_dir, exist_ok=True)
+        with open(cursor_path, "w") as f:
+            json.dump(cursor, f)
+
+        total_delta = delta["in"] + delta["out"] + delta["cache_r"] + delta["cache_w"]
+        # Log only genuine assistant activity: a model was found and the delta
+        # carries tokens. Empty deltas (no new assistant messages, or a
+        # compaction that added nothing) persist the cursor but write no line.
+        if model is None or total_delta <= 0:
+            sys.exit(0)
+
+        task = (c.active_task(root) or {})
+        task_slug = task.get("task") if isinstance(task, dict) else None
+        task_slug = task_slug or "-"
+
+        tokens = "in=%d out=%d cache_r=%d cache_w=%d" % (
+            delta["in"], delta["out"], delta["cache_r"], delta["cache_w"]
+        )
+        line = "%s | %s | %s | %s | %s | %s" % (
+            c.iso_now(), session8, kind, task_slug, model, tokens
+        )
+        est = _estimate(models_path, model, delta)
+        if est is not None:
+            line += " | " + est
+        line += "\n"
+
+        with open(costs_path, "a") as f:
+            f.write(line)
+    except SystemExit:
+        raise
+    except Exception:
+        sys.exit(0)
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/.claude/hooks/gates_detect.py

@@ -35,6 +35,48 @@ ORDER = {"lint": 0, "typecheck": 1, "tests": 2, "build": 3, "other": 4}
 
 PLACEHOLDER_MARK = "configure me"
 
+# Stack-independent gate: guard_models --check needs only python3, which the
+# hooks already require, so it is proposed for every project (including a
+# no-stack repo) and ordered before the test gates (it is cheap).
+MODELS_GATE_JSON = {
+    "name": "models",
+    "command": "python3 .claude/hooks/guard_models.py --check",
+    "blocking": True,
+}
+MODELS_GATE_DISPLAY = {
+    "name": "models",
+    "command": MODELS_GATE_JSON["command"],
+    "binary": "python3",
+}
+
+# Verification gates (wave 2). Both need only python3, which the hooks already
+# require. witnesses rides FIRST (ahead of models) whenever a seeded registry
+# exists; trace rides after the stack gates (which include tests) and before
+# the audit gate, whenever a spec with FR IDs exists.
+WITNESSES_GATE_JSON = {
+    "name": "witnesses",
+    "command": "python3 .claude/hooks/witness_check.py",
+    "blocking": True,
+}
+WITNESSES_GATE_DISPLAY = {
+    "name": "witnesses",
+    "command": WITNESSES_GATE_JSON["command"],
+    "binary": "python3",
+}
+TRACE_GATE_JSON = {
+    "name": "trace",
+    "command": "python3 .claude/hooks/trace_check.py",
+    "blocking": True,
+}
+TRACE_GATE_DISPLAY = {
+    "name": "trace",
+    "command": TRACE_GATE_JSON["command"],
+    "binary": "python3",
+}
+
+# A requirement id looks like FR-AUTH-01 / BR-PAY-3, or the short FR-03 form.
+FR_ID_RE = re.compile(r"\b(?:FR|BR)-[A-Z0-9]+-\d+\b|\bFR-\d+\b")
+
 
 def project_dir():
     root = os.environ.get("CLAUDE_PROJECT_DIR")
@@ -305,6 +347,66 @@ def emit_json(obj):
     print("GATES_JSON: " + json.dumps(obj, sort_keys=True))
 
 
+def has_witnesses(root):
+    """True when company/witnesses.json exists with >= 1 registered witness."""
+    data = c.read_json_file(os.path.join(root, "company", "witnesses.json"))
+    if not isinstance(data, dict):
+        return False
+    w = data.get("witnesses")
+    return isinstance(w, list) and len(w) >= 1
+
+
+def has_fr_spec(root):
+    """True when a company/specs/*.md file carries at least one FR/BR id."""
+    specs_dir = os.path.join(root, "company", "specs")
+    if not os.path.isdir(specs_dir):
+        return False
+    try:
+        names = os.listdir(specs_dir)
+    except Exception:
+        return False
+    for name in names:
+        if not name.endswith(".md"):
+            continue
+        if FR_ID_RE.search(read_text(os.path.join(specs_dir, name))):
+            return True
+    return False
+
+
+def audit_candidates(pm, stacks):
+    """CVE-audit gate candidates, one per detected stack. Always ordered last.
+
+    Node command varies by package manager; python audit uses pip-audit and is
+    only proposed when the tool is on PATH (the split_invocable idiom).
+    """
+    out = []
+    if pm:
+        if pm == "pnpm":
+            cmd = "pnpm audit --prod --audit-level=high"
+        elif pm == "yarn":
+            cmd = "yarn npm audit --severity high"
+        else:
+            cmd = "npm audit --omit=dev --audit-level=high"
+        out.append({"name": "audit", "command": cmd, "binary": pm})
+    if "python" in stacks:
+        out.append(
+            {"name": "audit", "command": "pip-audit", "binary": "pip-audit"}
+        )
+    # Unique-ify names if a repo carries more than one stack (audit, audit-2).
+    seen = {}
+    result = []
+    for g in out:
+        n = g["name"]
+        if n in seen:
+            seen[n] += 1
+            g = dict(g)
+            g["name"] = "{}-{}".format(n, seen[n])
+        else:
+            seen[n] = 1
+        result.append(g)
+    return result
+
+
 def main(argv):
     write = "--write" in argv[1:]
     root = project_dir()
@@ -318,9 +420,41 @@ def main(argv):
     detect_make(root, gates, stacks)
 
     gates = dedupe_and_order(gates)
-    proposed, skipped = split_invocable(gates)
+    stack_proposed, stack_skipped = split_invocable(gates)
+
+    # Front verification gates (stack-independent, python3 only): witnesses
+    # first (when a seeded registry exists), then models. Both ride ahead of
+    # the stack gates.
+    front_display = []
+    front_json = []
+    if has_witnesses(root):
+        front_display.append(dict(WITNESSES_GATE_DISPLAY))
+        front_json.append(dict(WITNESSES_GATE_JSON))
+    front_display.append(dict(MODELS_GATE_DISPLAY))
+    front_json.append(dict(MODELS_GATE_JSON))
+
+    # Trace rides after the stack gates (which include tests) and before audit,
+    # only when a spec with FR ids is present.
+    tail_display = []
+    tail_json = []
+    if has_fr_spec(root):
+        tail_display.append(dict(TRACE_GATE_DISPLAY))
+        tail_json.append(dict(TRACE_GATE_JSON))
+
+    # The CVE audit gate is ALWAYS last; the pip-audit variant is skipped when
+    # the tool is not on PATH (split_invocable idiom).
+    audit_proposed, audit_skipped = split_invocable(
+        audit_candidates(pm, stacks)
+    )
 
-    proposed_json = to_config_gates(proposed)
+    proposed = front_display + stack_proposed + tail_display + audit_proposed
+    proposed_json = (
+        front_json
+        + to_config_gates(stack_proposed)
+        + tail_json
+        + to_config_gates(audit_proposed)
+    )
+    skipped = stack_skipped + audit_skipped
     skipped_json = [
         {
             "name": g["name"],
@@ -331,14 +465,16 @@ def main(argv):
         for g in skipped
     ]
 
-    # No stack at all: leave config untouched, report, exit 0.
+    # No stack at all: leave config untouched, report, exit 0. The
+    # stack-independent gates (witnesses when seeded, models, and trace when a
+    # spec exists) are still surfaced in the proposal so the CEO can see them.
     if not stacks:
         print("no stack detected - leaving company/gates.config untouched")
         emit_json(
             {
                 "stacks": [],
                 "package_manager": pm,
-                "proposed": [],
+                "proposed": front_json + tail_json,
                 "skipped": [],
                 "wrote": False,
                 "status": "no_stack",

package/.claude/hooks/guard_commit.py

@@ -3,9 +3,19 @@
 
   - push to protected branch (main/master), explicit or bare push while on it:
     BLOCK (owner-only).
+  - commit on a protected branch (main/master) while a task is active:
+    BLOCK with a task-branch recipe (all work happens on task branches).
+    Hotfix tasks are exempt (ALLOW + log BYPASS); a commit with no active
+    task is a founding commit and is exempt; merge on main is the owner's
+    local integration and is exempt.
   - commit / merge: require a green, fresh, valid gates.status stamp. If
-    gates.config is missing or has zero gates, ALLOW + log BYPASS. If the
-    active task is a hotfix, ALLOW + log BYPASS.
+    gates.config is missing, has zero gates, or contains ONLY CONFIGURE-ME
+    placeholders (a fresh project with nothing to gate yet), ALLOW + log
+    BYPASS - unconfigured gates must not deadlock founding commits, and the
+    bypass stays visible in the adherence log. Placeholders still fail loudly
+    in run-gates.sh and still block task completion via stop_gate; only the
+    commit path treats them as not-yet-configured. If the active task is a
+    hotfix, ALLOW + log BYPASS.
   - everything else: allow.
 
 Fails open on any internal error.
@@ -44,7 +54,26 @@ def git_subcmd(segment):
     return toks[i], toks[i + 1:]
 
 
-def push_targets_protected(root, args):
+def git_cwd(payload, root):
+    """Resolve the directory the git command actually runs in (#26).
+
+    The branch checks must reflect the working tree git operates on, not the
+    project root. A commit issued from a worktree checkout of a task branch
+    must be judged by that worktree's branch, even when CLAUDE_PROJECT_DIR (and
+    thus root) points at the main checkout on a protected branch. Prefer the
+    payload's cwd when it is present and inside a git work tree; otherwise fall
+    back to root.
+    """
+    if isinstance(payload, dict):
+        cwd = payload.get("cwd")
+        if cwd:
+            out = c._git(cwd, ["rev-parse", "--is-inside-work-tree"])
+            if out is not None and out.strip() == "true":
+                return cwd
+    return root
+
+
+def push_targets_protected(branch_dir, args):
     non_opt = [a for a in args if not a.startswith("-")]
     # first non-option is the remote; the rest are refspecs
     refspecs = non_opt[1:]
@@ -53,7 +82,7 @@ def push_targets_protected(root, args):
         if dst in PROTECTED:
             return True
     if not refspecs:
-        cur = c.current_branch(root)
+        cur = c.current_branch(branch_dir)
         if cur in PROTECTED:
             return True
     return False
@@ -71,6 +100,9 @@ def main():
     if not command:
         sys.exit(0)
 
+    # #26: branch checks must reflect the tree the git command runs in.
+    branch_dir = git_cwd(payload, root)
+
     try:
         for seg in segments(command):
             sub, args = git_subcmd(seg)
@@ -78,7 +110,7 @@ def main():
                 continue
 
             if sub == "push":
-                if push_targets_protected(root, args):
+                if push_targets_protected(branch_dir, args):
                     c.block(
                         root, HOOK, "git push", "protected branch push",
                         "BLOCKED: push to a protected branch (main/master) is "
@@ -88,15 +120,60 @@ def main():
 
             if sub in ("commit", "merge"):
                 task = c.active_task(root)
+
+                # All work happens on task branches. A plain commit on a
+                # protected branch while a task is active is misplaced work.
+                # (merge is the owner's local integration and is exempt; a
+                # commit with NO active task is a founding commit and is
+                # exempt.) Branch message wins over the gate-stamp checks
+                # below. Fail open when the branch is unknown.
+                if sub == "commit" and isinstance(task, dict):
+                    branch = c.current_branch(branch_dir)
+                    if branch in PROTECTED:
+                        if task.get("type") == "hotfix":
+                            c.log_bypass(
+                                root, HOOK, "git commit",
+                                "hotfix commit on protected branch",
+                            )
+                            continue
+                        slug = task.get("task") or "<task-slug>"
+                        c.block(
+                            root, HOOK, "git commit",
+                            "commit on protected branch",
+                            "BLOCKED: work belongs on a task branch, never "
+                            "directly on main.\n"
+                            "Create the isolated task branch and commit "
+                            "there:\n"
+                            "  git worktree add .claude/worktrees/{slug} "
+                            "-b task/{slug}\n"
+                            "or, if you are already in the right working "
+                            "tree:\n"
+                            "  git switch -c task/{slug}\n"
+                            "then retry your commit on that branch.\n"
+                            "If this task is finished and you are "
+                            "integrating, use git merge (allowed on main) "
+                            "- see company/GIT.md.".format(slug=slug),
+                        )
+
                 if isinstance(task, dict) and task.get("type") == "hotfix":
                     c.log_bypass(root, HOOK, "git " + sub, "hotfix mode")
                     continue
                 cfg = c.gates_config(root)
-                if not isinstance(cfg, dict) or not cfg.get("gates"):
+                gates = cfg.get("gates") if isinstance(cfg, dict) else None
+                if not gates:
                     c.log_bypass(
                         root, HOOK, "git " + sub, "no gates configured"
                     )
                     continue
+                if all(
+                    "CONFIGURE ME" in (g.get("command") or "")
+                    for g in gates if isinstance(g, dict)
+                ):
+                    c.log_bypass(
+                        root, HOOK, "git " + sub,
+                        "gates.config has only CONFIGURE-ME placeholders",
+                    )
+                    continue
                 ok, reason = c.check_stamp(root)
                 if not ok:
                     c.block(