@nidvue/teamwork 0.0.0-stage → 1.1.1

package/skills/teamwork/src/teamwork/bundle.py

@@ -0,0 +1,157 @@
+"""The skill bundle as a movable set of files, and the mirror that keeps a copy fresh.
+
+The repository root *is* the skill, but an agent host loads a **copy** from its
+skills directory, and a `pi`/pip install unpacks another copy. Those copies are
+what an agent actually reads, so they must be replaceable byte for byte: a stale
+copy is a live defect (a renamed engine module that lingers shadows the new one,
+an old ``SKILL.md`` describes a command that no longer exists).
+
+One manifest lives here - :data:`BUNDLE_FILES` and :data:`BUNDLE_TREES` - and
+everything that copies the bundle uses it: the wheel build, the pi package build,
+``scripts/sync_skill.py`` and ``teamwork.py refresh``. Two copies of the list
+would drift, and the drift would be invisible until a shipped file went missing.
+"""
+
+from __future__ import annotations
+
+import filecmp
+import os
+import shutil
+from pathlib import Path
+
+#: Files the skill needs at runtime, at the bundle root.
+BUNDLE_FILES = ("SKILL.md", "AGENTS.md")
+
+#: Trees the skill needs at runtime. Tests, docs and build output stay out.
+BUNDLE_TREES = ("references", "roles", "templates", "scripts", "src")
+
+#: Where a host scans skills from. Only a default - any directory works.
+HOST_DEFAULTS = {
+    "pi": Path("~/.pi/agent/skills/teamwork"),
+    "agents": Path("~/.agents/skills/teamwork"),
+}
+
+#: Marker that identifies a directory as a skill bundle rather than a random tree.
+MARKERS = ("SKILL.md", "roles", "references", "templates")
+
+_SKIP_SUFFIXES = (".pyc", ".pyo")
+
+
+def looks_like_bundle(path: Path) -> bool:
+    return path.is_dir() and any((path / marker).exists() for marker in MARKERS)
+
+
+def _skip(path: Path) -> bool:
+    if "__pycache__" in path.parts or any(p.endswith(".egg-info") for p in path.parts):
+        return True
+    return path.suffix in _SKIP_SUFFIXES
+
+
+def bundle_files(source: Path) -> list[Path]:
+    """Every file the bundle needs, relative to ``source``."""
+    found: list[Path] = [Path(name) for name in BUNDLE_FILES if (source / name).is_file()]
+    for tree in BUNDLE_TREES:
+        base = source / tree
+        if not base.is_dir():
+            continue
+        for path in sorted(base.rglob("*")):
+            if path.is_dir() or _skip(path.relative_to(source)):
+                continue
+            found.append(path.relative_to(source))
+    return found
+
+
+def installed_files(dest: Path) -> list[Path]:
+    """Every file currently in ``dest``, relative to it."""
+    if not dest.is_dir():
+        return []
+    return [
+        path.relative_to(dest)
+        for path in sorted(dest.rglob("*"))
+        if path.is_file() and not _skip(path.relative_to(dest))
+    ]
+
+
+def managed(rel: Path) -> bool:
+    """Is ``rel`` a path the mirror owns? Unmanaged files are never deleted.
+
+    Only the bundle trees are pruned. A file the host or the operator put in the
+    skills directory (a note, a README, a local override) is left alone: a sync
+    that deletes what it did not write is a data-loss bug, not a convenience.
+    """
+    return bool(rel.parts) and rel.parts[0] in BUNDLE_TREES
+
+
+def plan(source: Path, dest: Path) -> tuple[list[Path], list[Path], list[Path]]:
+    """``(added, updated, removed)`` - what mirroring ``source`` into ``dest`` does."""
+    wanted = bundle_files(source)
+    have = set(installed_files(dest))
+    added, updated = [], []
+    for rel in wanted:
+        if rel not in have:
+            added.append(rel)
+        elif not filecmp.cmp(source / rel, dest / rel, shallow=False):
+            updated.append(rel)
+    removed = sorted(rel for rel in have - set(wanted) if managed(rel))
+    return added, updated, removed
+
+
+def sync(source: Path, dest: Path, *, dry_run: bool, quiet: bool = False) -> int:
+    """Mirror ``source`` into ``dest``. Returns the number of files touched."""
+    added, updated, removed = plan(source, dest)
+    touched = len(added) + len(updated) + len(removed)
+    if not quiet:
+        for rel in added:
+            print(f"  + {rel}")
+        for rel in updated:
+            print(f"  ~ {rel}")
+        for rel in removed:
+            print(f"  - {rel}")
+    if dry_run:
+        return touched
+    dest.mkdir(parents=True, exist_ok=True)
+    for rel in added + updated:
+        target = dest / rel
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(source / rel, target)
+    for rel in removed:
+        (dest / rel).unlink()
+    # A stale __pycache__ would keep importing a module the source dropped.
+    for path in sorted(dest.rglob("__pycache__"), reverse=True):
+        shutil.rmtree(path, ignore_errors=True)
+    for directory in sorted((p for p in dest.rglob("*") if p.is_dir()), reverse=True):
+        if not any(directory.iterdir()):
+            directory.rmdir()
+    if not quiet:
+        print(f"# {len(added)} added, {len(updated)} updated, {len(removed)} removed -> {dest}")
+    return touched
+
+
+def resolve_dest(host: str = "pi", dest: str = "") -> Path:
+    """The skills directory to write: ``--dest`` first, else the host default."""
+    target = Path(dest).expanduser() if dest else HOST_DEFAULTS.get(host, HOST_DEFAULTS["pi"])
+    target = target.expanduser()
+    if not target.is_absolute():
+        target = (Path.cwd() / target).resolve()
+    return target
+
+
+def is_checkout(path: Path) -> bool:
+    """Is ``path`` a git checkout of the skill (so it can be fetched and pulled)?"""
+    return (path / ".git").exists() and (path / "src" / "teamwork").is_dir()
+
+
+def default_mirror_path(dest: Path) -> Path:
+    """Where a tool-managed mirror checkout of the skill lives for ``dest``.
+
+    Next to the skills directory, hidden, so it is obvious that no operator owns
+    it: ``refresh`` fetches into it and mirrors into ``dest``.
+    """
+    parent = dest.parent
+    if parent.name == "skills":
+        parent = parent.parent
+    return parent / ".teamwork-source"
+
+
+def env_source() -> str:
+    return os.environ.get("TEAMWORK_SOURCE", "")

package/skills/teamwork/src/teamwork/cli.py

@@ -0,0 +1,16 @@
+"""Console entry point: ``teamwork`` and ``python -m teamwork``."""
+
+from __future__ import annotations
+
+import sys
+
+from .engine import main as _engine_main
+
+
+def main(argv=None) -> int:
+    """Run the Teamwork CLI and return its exit code."""
+    return _engine_main(argv)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

package/skills/teamwork/src/teamwork/config.py

@@ -0,0 +1,396 @@
+"""Workspace paths, record names, caps and shared constants.
+
+Everything here is data: changing a constant is the supported way to tune the
+workspace, and no module imports the command layer to read it.
+"""
+
+from __future__ import annotations
+
+import os
+
+from . import resources as _resources
+
+SKILL_DIR = _resources.skill_root()
+
+ROLES_DIR = _resources.asset("roles")
+
+TEMPLATES_DIR = _resources.asset("templates")
+
+DIR_TEAM_MAP_TPL = "TeamMap.md"
+
+TEAM_ROOT_DIR = ".pi/Teamwork"
+
+TEAMS_SUBDIR = "Teams"
+
+DIR_GLOBAL = "Global"
+
+DIR_ROLES = "Roles"
+
+DIR_AGENTS = "Agents"
+
+DIR_RUNTIME = "Runtime"
+
+DIR_LOCKS = "Locks"
+
+DIR_SLOTS = "Slots"
+
+DIR_ARTIFACTS = "Artifacts"
+
+DIR_REPORTS = "Reports"
+
+DIR_SCRATCH = "Scratch"
+
+DIR_DOCS = ("docs", "Team")
+
+F_SHORT = "ShortTermMemory.md"
+
+F_LONG = "LongTermMemory.md"
+
+F_MEM_ARCHIVE = "ArchivedMemory.md"
+
+F_TASKS = "TaskQueue.md"
+
+F_ROLE = "Role.md"
+
+F_START = "StartHere.md"
+
+F_WORKLOG = "WorkLog.md"
+
+F_INBOX = "Inbox.md"
+
+F_GLOBAL = "GlobalMemory.md"
+
+F_GLOBAL_ARCHIVE = "GlobalMemoryArchive.md"
+
+F_DISPUTES = "Disputes.md"
+
+F_REDLINES = "RedLines.md"
+
+F_MAP = "TeamMap.md"
+
+F_REVIEWS = "Reviews.md"
+
+F_CRITERIA = "Criteria.md"
+F_TESTS = "Tests.md"
+F_TESTPLAN = "TestPlan.md"
+
+DIR_WORKTREES = "Worktrees"
+
+F_SETTINGS = "Settings.json"
+
+IDENTITY_DOMAIN = os.environ.get("TEAMWORK_IDENTITY_DOMAIN", "agents.nidvue.com")
+
+TEST_LAYERS = (
+    "goal",
+    "requirements",
+    "plan",
+    "tech",
+    "release",
+    "data",
+    "process",
+    "cost",
+    "system",
+    "ui",
+    "docs",
+    "unit",
+    "integration",
+    "acceptance",
+    "security",
+)
+
+LAYER_OWNER = {
+    "goal": "ceo",
+    "requirements": "product-manager",
+    "plan": "project-manager",
+    "tech": "cto",
+    "release": "release-engineer",
+    "data": "data-engineer",
+    "process": "coo",
+    "cost": "cfo",
+    "system": "architect",
+    "ui": "designer",
+    "docs": "technical-writer",
+    "unit": "developer",
+    "integration": "tester",
+    "acceptance": "reviewer",
+    "security": "security-auditor",
+}
+
+LAYER_WHAT = {
+    "goal": "black-box verification that the delivered result meets the user's objective",
+    "requirements": "requirement coverage and traceability: every requirement maps to a passing check",
+    "plan": "plan integrity: dependency graph, duplicate work, milestone exit criteria",
+    "tech": "technology validation: toolchain and dependency upgrades, feasibility spikes, version drills",
+    "release": "release tests: reproducible build, CI gates, packaging, upgrade and rollback",
+    "data": "data tests: schema and migration correctness, backfill, backup and restore drills",
+    "process": "process and automation tests: the documented workflow and tooling actually run",
+    "cost": "cost and budget tests: metering, cap enforcement, unit-economics assertions",
+    "system": "architecture-conformance tests (boundaries, dependency direction, contract, ADR)",
+    "ui": "UI use-case tests (flows, component states, accessibility)",
+    "docs": "documentation tests: every documented command and claim is executed as written",
+    "unit": "unit tests for the code the Developer wrote",
+    "integration": "integration / system / end-to-end tests",
+    "acceptance": "acceptance tests over every role's output",
+    "security": "security tests (auth, input handling, secrets, red lines)",
+}
+
+DEFAULT_REQUIRED_LAYERS = ("unit", "integration", "acceptance")
+
+ALL_LAYERS_SENTINEL = "__all__"
+
+LAYER_CELL = {
+    "goal": "goal",
+    "requirements": "req",
+    "plan": "plan",
+    "tech": "tech",
+    "release": "rel",
+    "data": "data",
+    "process": "proc",
+    "cost": "cost",
+    "system": "sys",
+    "ui": "ui",
+    "docs": "docs",
+    "unit": "unit",
+    "integration": "int",
+    "acceptance": "acc",
+    "security": "sec",
+}
+
+TEST_STATUSES = ("pending", "passing", "failing", "na")
+
+F_LEDGER = "Ledger.jsonl"
+
+F_HEAD = "LedgerHead.json"
+
+F_MANIFEST = "AuditManifest.json"
+
+F_AUDITREPORT = "AuditManifest.md"
+
+F_SKILLS = "Skills.md"
+
+SKILLS_DIR = (".agents", "skills")
+
+DEFAULT_PROVIDER_LIMITS = {
+    "ollama-cloud": 64,
+    "deepseek": 2500,
+    "openai": 64,
+    "anthropic": 64,
+    "default": 32,
+}
+
+SLOT_TTL_MINUTES = int(os.environ.get("TEAMWORK_SLOT_TTL_MINUTES", "90"))
+
+REVIEW_FAIL_LIMIT = int(os.environ.get("TEAMWORK_REVIEW_FAIL_LIMIT", "3"))
+
+SHORT_CAP = int(os.environ.get("TEAMWORK_SHORT_CAP", "24"))
+
+LONG_CAP = int(os.environ.get("TEAMWORK_LONG_CAP", "64"))
+
+ARCHIVE_CAP = int(os.environ.get("TEAMWORK_ARCHIVE_CAP", "256"))
+
+STALE_DAYS = int(os.environ.get("TEAMWORK_STALE_DAYS", "3"))
+
+MIN_USES = int(os.environ.get("TEAMWORK_MIN_USES", "2"))
+
+PROMOTE_MIN_IMPORTANCE = int(os.environ.get("TEAMWORK_PROMOTE_MIN_IMPORTANCE", "2"))
+
+DOCS = {
+    "Project.md": "CEO",
+    "Plan.md": "ProjectManager",
+    "Board.md": "ProjectManager",
+    "Decisions.md": "Architect",
+    "Architecture.md": "Architect",
+    "Research.md": "ProductManager",
+    "Design.md": "Designer",
+    "Risks.md": "COO",
+    "Costs.md": "CFO",
+    "Release.md": "Release Engineer",
+    "Archive.md": "CEO",
+}
+
+CODE_DIRS = ("src", "lib", "cmd", "internal", "app", "packages", "crates", "rust")
+
+TEST_HINTS = ("test", "tests", "spec", "specs", "e2e", "integration")
+
+GITIGNORE_LINES = (
+    "# --- teamwork: local working state (never commit) ---",
+    ".pi/",
+    "# --- teamwork: scratch and editor noise ---",
+    "*.tmp",
+    "*.temp",
+    "*.bak",
+    "*.orig",
+    "*.rej",
+    "*.swp",
+    "*~",
+    ".DS_Store",
+    "Thumbs.db",
+    "# --- teamwork: secrets ---",
+    ".env",
+    ".env.local",
+    ".env.*.local",
+    "*.pem",
+    "*.key",
+    "# --- teamwork: caches / build output (keep them on disk, just uncommitted) ---",
+    "__pycache__/",
+    "*.py[cod]",
+    ".pytest_cache/",
+    ".mypy_cache/",
+    ".ruff_cache/",
+    "node_modules/",
+    "dist/",
+    "build/",
+    "target/",
+    ".venv/",
+    "venv/",
+    "coverage/",
+    ".coverage",
+)
+
+SCRATCH_DIRS = (DIR_SCRATCH,)
+
+SCRATCH_PATTERNS = ("*.tmp", "*.temp", "*.bak", "*.orig", "*.rej", "*.log")
+
+MAX_ROUNDS = int(os.environ.get("TEAMWORK_MAX_DISPUTE_ROUNDS", "3"))
+
+TRIBUNAL = ("ceo", "cto", "cfo")
+
+# Who each role reports to. One parent per role - a role with two managers answers
+# to neither - and the CEO is the only lane that reaches the user. The parent is
+# the role that owns the standard the child is judged by: technology work under the
+# CTO, execution and planning under the COO, product and documentation under the
+# Product Manager. Three roles stay with the CEO on purpose, because their job is
+# to disagree with everyone else: the Reviewer passes and merges (it must not be
+# managed by a lane whose work it reviews), the Security Auditor audits the whole
+# team, CTO included, and the CFO holds the budget cap that binds every lane.
+# `ROLE_PARENT` is the single source of truth; the docs, the charters, the
+# AGENTS.md block and the generated StartHere brief are checked against it.
+ROLE_PARENT = {
+    "ceo": None,
+    "cto": "ceo",
+    "coo": "ceo",
+    "cfo": "ceo",
+    "product-manager": "ceo",
+    "reviewer": "ceo",
+    "security-auditor": "ceo",
+    "architect": "cto",
+    "developer": "cto",
+    "tester": "cto",
+    "release-engineer": "cto",
+    "data-engineer": "cto",
+    "project-manager": "coo",
+    "designer": "product-manager",
+    "technical-writer": "product-manager",
+}
+
+# Reporting order, parents before children: the order the tree is rendered in and
+# the order an escalation walks. Kept explicit so `map`, the docs and the tests
+# agree without recomputing a graph from a plain dict.
+ROLE_REPORT_ORDER = (
+    "ceo",
+    "cto",
+    "architect",
+    "developer",
+    "tester",
+    "release-engineer",
+    "data-engineer",
+    "coo",
+    "project-manager",
+    "product-manager",
+    "designer",
+    "technical-writer",
+    "reviewer",
+    "security-auditor",
+    "cfo",
+)
+
+TRIBUNAL_MIN_SIGNERS = 2
+
+# Code-scanning findings are a release gate, not a nice-to-have: a red alert on
+# the default branch means the shipped revision has a known defect. The Release
+# Engineer owns the read and the routing because it already owns repository and CI
+# integrity (`references/Remotes.md`); the fix lands with whoever owns the file.
+# `SCAN_ROUTE` is the file-ownership map, most specific pattern first.
+SCAN_OWNER_ROLE = "release-engineer"
+
+SCAN_ROUTE = (
+    (".github/**", "release-engineer"),
+    ("scripts/privacy_scan.py", "security-auditor"),
+    ("scripts/**", "developer"),
+    ("src/**", "developer"),
+    ("tests/**", "developer"),
+    ("docs/guide/**", "technical-writer"),
+    ("docs/Team/Architecture.md", "architect"),
+    ("docs/Team/Release.md", "release-engineer"),
+    ("docs/Team/AuditReport.md", "security-auditor"),
+    ("docs/**", "technical-writer"),
+    ("templates/**", "ceo"),
+    ("roles/**", "ceo"),
+    ("references/**", "ceo"),
+    ("README.md", "designer"),
+    ("assets/**", "designer"),
+)
+
+# A scan alert at or above this severity blocks the release gate.
+SCAN_BLOCKING = ("error", "critical", "high")
+
+# Roster tiers, cheapest first. A role earns a seat only if it owns a deliverable,
+# a test layer and a decision right that no other role holds; everything else rides
+# as a lane. `slim` is the default because every extra role is another charter, queue
+# and memory set loaded at startup, and the gates do not need it: `staffed_layers`
+# already restricts the matrix to staffed roles, and `required_tribunal` stays at or
+# above TRIBUNAL_MIN_SIGNERS with the Reviewer as the neutral seat.
+ROSTER_TIERS = {
+    "slim": (
+        "ceo",
+        "architect",
+        "developer",
+        "tester",
+        "reviewer",
+    ),
+    "standard": (
+        "ceo",
+        "architect",
+        "product-manager",
+        "project-manager",
+        "developer",
+        "tester",
+        "reviewer",
+        "release-engineer",
+    ),
+    "full": (
+        "ceo",
+        "cto",
+        "coo",
+        "cfo",
+        "architect",
+        "product-manager",
+        "project-manager",
+        "designer",
+        "developer",
+        "tester",
+        "reviewer",
+        "security-auditor",
+        "release-engineer",
+        "technical-writer",
+        "data-engineer",
+    ),
+}
+
+DEFAULT_ROSTER_TIER = "slim"
+
+# Roles the gates cannot do without, whichever tier is chosen.
+ROSTER_REQUIRED = ("ceo", "developer", "tester", "reviewer")
+
+# Instances per role for a tier: reviewers get two so one verifies and another merges.
+ROSTER_INSTANCE_COUNT = {"reviewer": 2, "developer": 1, "tester": 1}
+
+SETTINGS_NON_PROVIDER = ("PulseMinutes", "Criteria")
+
+DEFAULT_BASE = "main"
+
+REVIEW_STATUSES = ("open", "approved", "changes-requested", "merged", "closed")
+
+PRIORITY_ORDER = {"P0": 0, "P1": 1, "P2": 2, "P3": 3}
+
+STATUSES = ("todo", "doing", "selfcheck", "review", "blocked", "done", "dropped")