workbay-system 0.1.0__py3-none-any.whl

workbay_system/__init__.py

@@ -0,0 +1,25 @@
+"""workbay-system overlay payload package.
+
+Ships the canonical overlay surfaces — skills, the workflow generator,
+agent-workflows config, and the shared hook/contract surfaces — as package
+data so ``workbay-bootstrap`` can materialize them from an installed
+distribution (the package delivery source) instead of a git clone.
+
+The payload is co-located under ``workbay_system/payload/`` and ships by
+"ship the package" (``only-include = ["workbay_system"]`` in
+``pyproject.toml`` — no force-include map), so :func:`data_root` resolves to the
+``payload/`` directory that contains ``skills/``, ``scripts/``, ``config/``,
+``docs/``, ``Makefile.d/``, and ``.github/`` once installed.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+
+__all__ = ["data_root"]
+
+
+def data_root() -> Path:
+    """Return the filesystem root of the installed overlay payload."""
+    return Path(str(resources.files(__name__) / "payload"))

workbay_system/payload/.claude/hooks/ensure-agent-surfaces.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# SessionStart hook — ensure this clone's GENERATED agent surfaces exist.
+#
+# Three agent surfaces are generated into GITIGNORED paths, so a fresh clone
+# carries the pins/sources but not the generated output — and the surfaces
+# silently fail to load until they are built:
+#   - Claude plugin tree  .workbay/generated/plugins/workbay-system/base/claude  (make plugins-build)
+#   - Codex  plugin tree  .workbay/generated/plugins/workbay-system/base/codex   (make plugins-build)
+#   - VS Code Copilot      .github/prompts/                                       (make generate-agent-workflows)
+#
+# This hook regenerates all of them when missing. It can only run on CLAUDE CODE
+# session start — Codex and VS Code Copilot have no equivalent trigger (see the
+# README "Developing in this repo" section) — but because `plugins-build` emits
+# BOTH plugin trees and `generate-agent-workflows` emits the Copilot prompts,
+# opening Claude once bootstraps every surface. Plugins load only at session
+# start, so a one-time restart is needed after the first build. The hook is a
+# no-op (fast, silent) once the surfaces exist and never blocks session start.
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+claude_manifest="$repo_root/.workbay/generated/plugins/workbay-system/base/claude/.claude-plugin/plugin.json"
+codex_manifest="$repo_root/.workbay/generated/plugins/workbay-system/base/codex/.codex-plugin/plugin.json"
+copilot_prompts="$repo_root/.github/prompts"
+
+# All three surfaces must be present to skip; checking only Claude + Copilot
+# would leave a partial-drift clone (e.g. only the codex tree deleted) unhealed.
+if [ -f "$claude_manifest" ] && [ -f "$codex_manifest" ] && [ -d "$copilot_prompts" ]; then
+  exit 0
+fi
+
+echo "workbay-system agent surfaces missing (fresh clone?) — generating them…"
+ok=1
+make -C "$repo_root" plugins-build >/dev/null 2>&1 || ok=0
+# Pass WORKFLOW_TARGET_ROOT so the Copilot prompts land in this repo's root
+# .github/prompts/ (the surface VS Code reads); without --target the generator
+# only rewrites the tracked package-level source copy.
+make -C "$repo_root" generate-agent-workflows WORKFLOW_TARGET_ROOT="$repo_root" >/dev/null 2>&1 || ok=0
+if [ "$ok" -eq 1 ]; then
+  echo "Generated the Claude + Codex plugin trees and the VS Code Copilot prompts."
+  echo "RESTART Claude Code (/exit, then reopen) to load the /branch-review, /plan-analyze, … slash commands."
+else
+  echo "Could not auto-generate every surface. Run 'cd \"$repo_root\" && make plugins-build && make generate-agent-workflows WORKFLOW_TARGET_ROOT=\"\$PWD\"' (or 'workbay-bootstrap install --target \"$repo_root\"') manually, then restart Claude Code."
+fi
+exit 0

workbay_system/payload/.claude/settings.hooks.json

@@ -0,0 +1,162 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|apply_patch|create_file|replace_string_in_file|multi_replace_string_in_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-worktree-drift.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|apply_patch|create_file|replace_string_in_file|multi_replace_string_in_file",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-main-branch.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-bash-main-branch.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-task-plan-findings.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__record_event|mcp__workbay-handoff-mcp__close_slice",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/guard-rationale-size.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__record_event|mcp__workbay-handoff-mcp__review_findings|mcp__workbay-handoff-mcp__review_runs",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/validate-mcp-dict-params.py\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/record-file-touch.py\"",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__review_findings",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/ace-detect.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__get_handoff_state|mcp__workbay-handoff-mcp__load_session|mcp__workbay-handoff-mcp__render_handoff",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/slim-handoff-response.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/filter-test-output.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/capture-agent-errors.py\"",
+            "timeout": 15
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/ensure-agent-surfaces.sh\"",
+            "timeout": 60
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/advise-worktree-cd.py\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/coherence-self-check.py\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/scripts/hooks/advise-worktree-cd.py\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

workbay_system/payload/.codex/hooks.json

@@ -0,0 +1,127 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|apply_patch|create_file|replace_string_in_file|multi_replace_string_in_file",
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py .github/hooks/guard-worktree-drift.py",
+        "timeout": 5,
+        "statusMessage": "Guarding worktree drift"
+      },
+      {
+        "matcher": "Edit|Write|apply_patch|create_file|replace_string_in_file|multi_replace_string_in_file",
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py .github/hooks/guard-main-branch.py",
+        "timeout": 5,
+        "statusMessage": "Guarding main branch edits"
+      },
+      {
+        "matcher": "Bash",
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/guard-bash-main-branch.py",
+        "timeout": 5,
+        "statusMessage": "Guarding main branch"
+      },
+      {
+        "matcher": "Edit|Write",
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/guard-task-plan-findings.py",
+        "timeout": 5,
+        "statusMessage": "Guarding task plan findings"
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__record_event|mcp__workbay-handoff-mcp__close_slice",
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/guard-rationale-size.py",
+        "timeout": 5,
+        "statusMessage": "Checking rationale size"
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__record_event|mcp__workbay-handoff-mcp__review_findings|mcp__workbay-handoff-mcp__review_runs",
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/validate-mcp-dict-params.py",
+        "timeout": 5,
+        "statusMessage": "Validating MCP dict params"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/record-file-touch.py",
+            "timeout": 10,
+            "statusMessage": "Recording file touch"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__review_findings",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/ace-detect.py",
+            "timeout": 5,
+            "statusMessage": "Detecting ACE references"
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__workbay-handoff-mcp__get_handoff_state|mcp__workbay-handoff-mcp__load_session|mcp__workbay-handoff-mcp__render_handoff",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/slim-handoff-response.py",
+            "timeout": 5,
+            "statusMessage": "Slimming handoff response"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/filter-test-output.py",
+            "timeout": 5,
+            "statusMessage": "Filtering test output"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/capture-agent-errors.py",
+            "timeout": 15,
+            "statusMessage": "Capturing agent errors"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/advise-worktree-cd.py",
+        "timeout": 5,
+        "statusMessage": "Advising worktree cd"
+      },
+      {
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/coherence-self-check.py",
+        "timeout": 10,
+        "statusMessage": "Checking hook-surface coherence"
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "type": "command",
+        "command": "python3 scripts/hooks/_run_guard.py scripts/hooks/advise-worktree-cd.py",
+        "timeout": 5,
+        "statusMessage": "Advising worktree cd"
+      }
+    ]
+  }
+}

workbay_system/payload/.github/hooks/guard-main-branch.py

@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: block protected edits on main/master in the VS Code harness."""
+from __future__ import annotations
+
+import datetime
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+HELPER_DIR = Path(__file__).resolve().parents[2] / "scripts" / "hooks"
+if str(HELPER_DIR) not in sys.path:
+    sys.path.insert(0, str(HELPER_DIR))
+
+from _harness_protocol import (  # noqa: E402
+    HarnessContractMissingError,
+    find_permitted_main_surface,
+    load_branch_isolation_policy,
+)
+from _branch_isolation_guard import (  # noqa: E402
+    build_branch_naming_block_reason as _build_branch_naming_block_reason,
+    check_branch_naming as _check_branch_naming,
+    check_file_edit as _check_file_edit,
+    extract_candidate_paths as _extract_candidate_paths,
+    find_dirty_protected_paths as _check_dirty_protected_paths,
+    resolve_path_branch as _resolve_path_branch,
+    to_repo_relative as _to_repo_relative,
+)
+from _interp import resolve_env_alias  # noqa: E402
+
+
+_PROTECTED_BRANCHES = {"main", "master"}
+
+
+def _run_git(*args: str) -> str:
+    proc = subprocess.run(
+        ["git", *args],
+        capture_output=True,
+        text=True,
+        timeout=5,
+        check=False,
+    )
+    if proc.returncode != 0:
+        return ""
+    return proc.stdout.strip()
+
+
+def _repo_root() -> str:
+    return _run_git("rev-parse", "--show-toplevel")
+
+
+def _current_branch() -> str:
+    return _run_git("branch", "--show-current")
+
+
+def _build_reason(branch: str, blocked_paths: list[str]) -> str:
+    rendered_paths = "\n".join(f"  - {path}" for path in blocked_paths)
+    return (
+        "BLOCKED: Protected edits are not allowed on the main branch.\n\n"
+        f"Branch: {branch}\n"
+        "Files:\n"
+        f"{rendered_paths}\n\n"
+        "Create a feature branch first:\n"
+        "  git checkout -b feature/<task-id>-<slug>\n\n"
+        "If you already have dirty code changes on main, move them to a feature branch or stash them before continuing.\n\n"
+        "Isolation options:\n"
+        "  1. Feature branch for single-agent work\n"
+        "  2. Worktree isolation for delegated subtasks\n"
+        "  3. Lane orchestration for multi-agent parallel work\n\n"
+        "Only explicitly permitted operator docs/config surfaces remain allowed on main.\n"
+        "Planning docs and implementation files now require a feature branch from the first edit.\n"
+        "See: docs/workbay/rules/development-workflow.md#branch-isolation-protocol-mandatory"
+    )
+
+
+def _build_dirty_reason(branch: str, dirty_paths: list[str]) -> str:
+    rendered_paths = "\n".join(f"  - {path}" for path in dirty_paths)
+    return (
+        "BLOCKED: Protected code files are already dirty on the main branch.\n\n"
+        f"Branch: {branch}\n"
+        "Dirty files:\n"
+        f"{rendered_paths}\n\n"
+        "Move the work onto a feature branch or stash it before making more edits.\n\n"
+        "Recommended recovery:\n"
+        "  1. git checkout -b feature/<task-id>-<slug>\n"
+        "  2. keep the dirty changes on that branch, or stash them intentionally\n"
+        "  3. return to main only after the protected paths are clean again\n\n"
+        "See: docs/workbay/rules/development-workflow.md#branch-isolation-protocol-mandatory"
+    )
+
+
+def _permitted_candidate_paths(tool_name: str, tool_input: dict, repo_root: str, policy) -> list[str]:
+    candidate_paths = [
+        _to_repo_relative(raw_path, repo_root)
+        for raw_path in _extract_candidate_paths(tool_name, tool_input)
+    ]
+    normalized = [path for path in candidate_paths if path]
+    if not normalized:
+        return []
+    if not all(find_permitted_main_surface(path, policy) is not None for path in normalized):
+        return []
+    return normalized
+
+
+def _log_telemetry(tool_name: str, blocked_paths: list[str], branch: str, *, outcome: str) -> None:
+    try:
+        state_dir = Path(".task-state")
+        state_dir.mkdir(exist_ok=True)
+        record = {
+            "timestamp": datetime.datetime.now(tz=datetime.timezone.utc).isoformat(),
+            "tool": tool_name,
+            "branch": branch,
+            "outcome": outcome,
+            "paths": blocked_paths,
+        }
+        with (state_dir / "branch_isolation_guard.jsonl").open("a", encoding="utf-8") as handle:
+            handle.write(json.dumps(record) + "\n")
+    except OSError:
+        pass
+
+
+def main() -> None:
+    try:
+        data = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        sys.exit(0)
+
+    tool_name = data.get("toolName") or data.get("tool_name") or ""
+    tool_input = data.get("toolInput") or data.get("tool_input") or {}
+    if not isinstance(tool_input, dict):
+        sys.exit(0)
+
+    branch = _current_branch()
+    repo_root = _repo_root()
+    workspace_root = Path(repo_root or Path.cwd())
+    try:
+        policy = load_branch_isolation_policy(workspace_root)
+    except HarnessContractMissingError as exc:
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": "block",
+                        "permissionDecisionReason": str(exc),
+                    }
+                }
+            )
+        )
+        sys.exit(0)
+
+    # Branch-naming gate (internal). Fires before the
+    # protected-path check so non-conforming branches reject
+    # uniformly. ``WORKBAY_ALLOW_NONCONFORMING_BRANCH=1`` is the
+    # documented escape valve; pre-commit / pre-push gates honour
+    # their own env vars per implementation note §4 / §4b.
+    non_conforming = _check_branch_naming(branch)
+    if non_conforming is not None and resolve_env_alias("WORKBAY_ALLOW_NONCONFORMING_BRANCH") != "1":
+        _log_telemetry(tool_name, [], non_conforming, outcome="non_conforming_branch")
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": "block",
+                        "permissionDecisionReason": _build_branch_naming_block_reason(non_conforming),
+                    }
+                }
+            )
+        )
+        sys.exit(0)
+
+    result = _check_file_edit(
+        tool_name,
+        tool_input,
+        branch=branch,
+        repo_root=repo_root,
+        policy=policy,
+        protected_branches=_PROTECTED_BRANCHES,
+    )
+    if result is not None:
+        resolved_branch, blocked_paths = result
+        _log_telemetry(tool_name, blocked_paths, resolved_branch, outcome="attempted_protected_edit")
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "PreToolUse",
+                        "permissionDecision": "block",
+                        "permissionDecisionReason": _build_reason(resolved_branch, blocked_paths),
+                    }
+                }
+            )
+        )
+        sys.exit(0)
+
+    dirty_result = _check_dirty_protected_paths(
+        branch=branch,
+        repo_root=repo_root,
+        policy=policy,
+        protected_branches=_PROTECTED_BRANCHES,
+    )
+    if dirty_result is None:
+        sys.exit(0)
+
+    resolved_branch, dirty_paths = dirty_result
+
+    # Per-path worktree resolution: if every candidate edit path resolves
+    # (via its own worktree) to a non-protected branch, the edit isn't a
+    # main-branch write at all and the dirty-paths-on-main check shouldn't
+    # apply. This unblocks edits to sibling worktrees while the harness cwd
+    # remains on main.
+    raw_paths = [p for p in _extract_candidate_paths(tool_name, tool_input) if p]
+    if raw_paths:
+        resolved = [(_resolve_path_branch(p) or branch) for p in raw_paths]
+        if all(b not in _PROTECTED_BRANCHES for b in resolved):
+            sys.exit(0)
+
+    candidate_paths = _permitted_candidate_paths(tool_name, tool_input, repo_root, policy)
+    if candidate_paths and not any(path in set(dirty_paths) for path in candidate_paths):
+        sys.exit(0)
+
+    _log_telemetry(tool_name, dirty_paths, resolved_branch, outcome="dirty_protected_main_paths")
+    print(
+        json.dumps(
+            {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "block",
+                    "permissionDecisionReason": _build_dirty_reason(resolved_branch, dirty_paths),
+                }
+            }
+        )
+    )
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

workbay_system/payload/.github/hooks/guard-worktree-drift.py

@@ -0,0 +1,18 @@
+#!/usr/bin/env python3
+"""VS Code PreToolUse wrapper for the shared worktree-drift hook."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+HELPER_DIR = Path(__file__).resolve().parents[2] / "scripts" / "hooks"
+if str(HELPER_DIR) not in sys.path:
+    sys.path.insert(0, str(HELPER_DIR))
+
+from _worktree_drift import main  # noqa: E402
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())