pi-dev-team 0.2.0

package/skills/ubiquitous-language/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: ubiquitous-language
+description: Build or refresh the project's ubiquitous language glossary — one markdown file per business concept at `.plans/domain/<Concept>.md` plus a `_index.md`. Mines grep-based signals (class names, enum values, interface names, domain-event names, BDD scenario names, validator rules) and applies a four-gate filter to keep only genuine business concepts. Optional interactive interview phase to refine definitions and capture behavior (state transitions, invariants, synonyms to avoid). Language-agnostic — works for JS/TS, C#, Java, Python, Go, or any mix. Use whenever the user says "build the glossary", "extract domain terms", "document the ubiquitous language", "what are the domain concepts", or when domain-review surfaces pervasive terminology inconsistency (3+ names for the same concept).
+role: worker
+user-invocable: true
+argument-hint: "[path-to-source-root]"
+---
+
+# Ubiquitous Language
+
+Produces a queryable per-concept glossary at `.plans/domain/`. Each concept gets its own file (one-sentence definition, classification, related terms). The glossary feeds `domain-review` as classification ground truth — run this skill before `domain-review` for sharper findings.
+
+**This skill never modifies source files.** It writes only to `.plans/domain/` and `.plans/domain-language-plan.md`.
+
+---
+
+## Announce on start
+
+"Running ubiquitous-language. Gathering domain signals from `$ARGUMENTS` (or cwd if empty). I'll apply a four-gate filter and write one file per approved business concept to `.plans/domain/`. Existing files are append-mostly — previous definitions are preserved."
+
+---
+
+## Phase 1: Gather signals (grep-based, no build required)
+
+Run the colocated gather script. It collects raw candidates; it does not decide what is domain language (that is Phase 3's job).
+
+```bash
+python3 .claude/skills/ubiquitous-language/scripts/collect_domain_signals.py "$ARGUMENTS"
+```
+
+The script writes to `.plans/raw/domain-language/`:
+
+- `class-names.txt` — PascalCase class/struct/record/interface names from domain and application layers
+- `enum-values.txt` — enum declarations with their values
+- `domain-events.txt` — type names ending in `Created`, `Updated`, `Submitted`, `Approved`, `Cancelled`, `Rejected`, `Completed`, `Failed`, `Requested`
+- `bdd-names.txt` — BDD scenario and step names from `.feature` files (`Given_`, `When_`, `Then_`, `Should_`)
+- `validator-rules.txt` — validation rule method names and error messages
+- `interface-names.txt` — interface/protocol names from domain and application layers
+
+If the script is unavailable, gather manually using `Grep` with the patterns documented in the script's comments.
+
+**Graph-assisted disambiguation.** Prefer CodeGraph/Repowise over more `Grep` passes to check a candidate term's actual call sites and surrounding context when the raw signal is ambiguous (e.g. a name that could be a technical or a business concept, or two near-duplicate names that might be the same concept under different spellings). This is a supplement to Phase 1's grep-based collection, not a replacement — the collector script output is still the primary candidate source. See [`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md) for tool selection and the fallback contract.
+
+---
+
+## Phase 2: Load existing glossary (if present)
+
+Check for `.plans/domain/_index.md`. If it exists, read the current term list so new terms can be diffed against what already exists. Do not regenerate files for terms already in the glossary unless the definition is missing or clearly wrong.
+
+---
+
+## Phase 3: Apply the four-gate filter
+
+For each candidate term from Phase 1, apply all four gates. Promote only terms that pass all four.
+
+| Gate | Question | Fail condition |
+| --- | --- | --- |
+| 1. Business concept | Would a domain expert (not a developer) recognize this term as part of the business vocabulary? | Pure technical terms: `Repository`, `Controller`, `Factory`, `Builder`, `Manager`, `Handler`, `Util`, `Helper`, `Config`, `Base`, `Abstract` |
+| 2. Non-generic | Does the name carry specific business meaning beyond "thing that does stuff"? | Single-word generics: `Item`, `Data`, `Info`, `Record`, `Object`, `Entity`, `Model` (unless qualified: `OrderLineItem` passes) |
+| 3. Appears in ≥2 signal sources | Is the term used in at least two different signal types (e.g., class name AND BDD scenario name)? | Terms that appear only once in a single file with no corroborating evidence |
+| 4. Domain expert would recognize it | Would a domain expert, reading only the name, understand roughly what it refers to? | Portmanteaus, internal jargon, or abbreviations not explainable without context |
+
+When in doubt on gate 3, lean toward including the term — false positives are cheap (the user can remove a file); false negatives mean silent glossary gaps.
+
+---
+
+## Phase 4: Write concept files
+
+For each approved term, write (or update) `.plans/domain/<Concept>.md` using this format:
+
+```markdown
+---
+classification: Aggregate | Entity | Value Object | Domain Event | Domain Service | Policy | Concept
+context: <bounded context name, if multi-context repo>
+---
+
+# <ConceptName>
+
+<One to two sentence definition in plain business language. Avoid technical terms.>
+
+## Lifecycle / State Transitions
+<!-- Optional: fill in during interview phase or when state-transition signals are present -->
+
+## Invariants
+<!-- Optional: business rules that must always hold for this concept -->
+
+## Related
+<!-- Optional: link to related concepts -->
+- [[RelatedConcept]]
+
+## Avoid
+<!-- Optional: synonyms the codebase uses that should be consolidated to this term -->
+- `PurchaseOrder` (use `Order` instead)
+
+## Sources
+<!-- Optional: where this definition came from -->
+```
+
+**Append-mostly**: if the file already exists, preserve existing content. Add new sections; do not overwrite human-curated definitions. Update only if the existing definition is blank or contradicted by new evidence.
+
+---
+
+## Phase 5: Regenerate index
+
+After writing all concept files, regenerate `.plans/domain/_index.md`:
+
+```markdown
+# Domain Glossary Index
+
+_Last updated: <date>_
+
+## Aggregates
+- [Order](Order.md)
+- [Payment](Payment.md)
+
+## Entities
+- [OrderLine](OrderLine.md)
+
+## Value Objects
+- [Money](Money.md)
+- [Address](Address.md)
+
+## Domain Events
+- [OrderSubmitted](OrderSubmitted.md)
+
+## Domain Services
+- [PricingPolicy](PricingPolicy.md)
+
+## Concepts
+- [FulfillmentWindow](FulfillmentWindow.md)
+```
+
+Preserve human-curated categorical structure if it exists. Only the term links are auto-maintained; section headings and ordering are owned by the human.
+
+---
+
+## Phase 6: Optional interview (interactive sessions only)
+
+If running interactively (not in a non-interactive CI context), ask: "Would you like to interview to refine definitions and capture behavior (state transitions, invariants, synonyms to avoid)? This usually takes 5-10 minutes."
+
+If yes, for each aggregate and entity in the glossary:
+
+1. Ask: "How would you describe `<Term>` to a new team member in one sentence?"
+2. Ask: "What states can a `<Term>` be in? What triggers transitions between them?"
+3. Ask: "What must always be true about a `<Term>` (invariants)?"
+4. Ask: "Are there other names in the codebase for `<Term>` that we should consolidate?"
+
+Update the concept files with answers. Record the interview transcript in `.plans/domain-language-plan.md`.
+
+---
+
+## Output
+
+Write a run summary to `.plans/domain-language-plan.md`:
+
+```markdown
+# Domain Language — Run Summary
+
+**Date**: <date>
+**Scope**: <path>
+**Mode**: grep-fallback | roslyn (if available)
+
+## New concepts written
+- `Payment` (Aggregate) — new
+- `Money` (Value Object) — new
+
+## Updated concepts
+- `Order` (Aggregate) — added Invariants section
+
+## Skipped (already current)
+- `Customer` — definition present, no changes
+
+## Filtered out
+- `Repository` — gate 1 fail (technical term)
+- `Data` — gate 2 fail (generic)
+
+## Open questions
+- Is `Transaction` the same concept as `Payment`? Found both in codebase.
+
+## Interview transcript
+<!-- appended if Phase 6 ran -->
+```
+
+Tell the user: "Glossary written to `.plans/domain/`. Run `/code-review` or `domain-review` for domain boundary analysis using these terms as ground truth."
+
+---
+
+## Integration
+
+- **[Domain Analysis](../domain-analysis/SKILL.md)** — run domain-analysis after this skill to get architectural coupling findings annotated with canonical terms
+- **[Domain-Driven Design](../domain-driven-design/SKILL.md)** — use the glossary as input when designing bounded contexts or aggregate boundaries
+- **[Specs](../specs/SKILL.md)** — when writing BDD scenarios, pull term names from `.plans/domain/` to ensure scenario language matches the glossary

package/skills/ubiquitous-language/scripts/collect_domain_signals.py

@@ -0,0 +1,300 @@
+#!/usr/bin/env python3
+"""Python port of collect-domain-signals.sh (#617 / #572 Phase 3).
+
+Gathers grep-based domain signals for the ubiquitous-language skill.
+
+Deliberate divergence from the .sh: the shipped
+`collect-domain-signals.sh` runs under `set -euo pipefail`, and every
+section is a `{ safe_grep ... } | grep -v ... | sed ... | sort -u` pipe.
+When any intermediate grep matches nothing (the common case for a real
+project — e.g. no Java code), the pipe returns non-zero → pipefail →
+`set -e` aborts. The script therefore stops after the first section, so
+only `class-names.txt` is ever written in practice.
+
+The .sh has zero bats coverage, so nothing tests (or depends on) the
+broken early-exit. This port implements the six-section contract the
+script's docstring + the ubiquitous-language SKILL.md both describe:
+class names, enum values, domain events, BDD names, validator rules,
+interface names — every section always runs and writes its file.
+
+Usage: python3 collect_domain_signals.py [source-root]
+
+Output: .plans/raw/domain-language/{class-names,enum-values,domain-events,
+        bdd-names,validator-rules,interface-names}.txt
+
+Uses `grep -rn --include=<glob> <pattern> -- <root>` under the hood (subprocess)
+because reproducing bash grep -r's file walk + include semantics natively in
+Python would drift on Windows line-endings and locale collation. The .sh is
+authoritative; this port dispatches the same greps so both sides find the same
+matches. Additional filtering + regex substitution is done in-process.
+
+Stdlib-only. See docs/python-hook-contract.md.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def _safe_grep(glob: str, pattern: str, root: str) -> list[str]:
+    """`grep -rnE --include=<glob> <pattern> -- <root>`, silencing errors.
+
+    The .sh runs plain `grep -rn`, which uses BRE and treats the ERE
+    metachars in the shipped patterns (`(...|...)`, `[A-Z]+`) as
+    literals — so the shipped .sh finds nothing and writes empty files
+    on every real project. The port fixes this by using ERE (`grep -E`);
+    the SKILL.md intent is a working signal collector, not a broken
+    stub.
+    """
+    try:
+        r = subprocess.run(
+            ["grep", "-rnE", f"--include={glob}", pattern, "--", root],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except (FileNotFoundError, OSError):
+        return []
+    if r.returncode not in (0, 1):
+        # 0 = matches; 1 = no match; anything else is unexpected — treat as
+        # no matches (the .sh does `|| true`).
+        return []
+    return [line for line in r.stdout.splitlines() if line]
+
+
+def _sort_unique(lines: Iterable[str]) -> list[str]:
+    return sorted(set(lines))
+
+
+def _write_lines(path: Path, lines: list[str]) -> None:
+    path.write_text("".join(f"{line}\n" for line in lines))
+
+
+# Repeated exclusion list from the .sh's `grep -v` chain.
+_CLASS_EXCLUDES = re.compile(
+    r"Test|Spec|Mock|Fake|Stub|Builder|Factory|Repository|Controller|Handler"
+    r"|Middleware|Config|Settings|Helper|Util|Base|Abstract|Migration"
+)
+
+_INTERFACE_EXCLUDES = re.compile(
+    r"Repository|Controller|Handler|Middleware|Factory|Builder|Config"
+    r"|Logger|Cache|Queue|Bus|Mapper|Serializer|Parser"
+)
+
+# The .sh chains four `sed` substitutions to pull just the identifier out
+# of a matched line. Each one strips everything up to a keyword then keeps
+# only the [A-Z][a-zA-Z]* run and the trailing junk.
+_NAME_EXTRACT_PATTERNS = [
+    re.compile(r".*class ([A-Z][a-zA-Z]*).*"),
+    re.compile(r".*interface ([A-Z][a-zA-Z]*).*"),
+    re.compile(r".*struct ([A-Z][a-zA-Z]*).*"),
+    re.compile(r".*record ([A-Z][a-zA-Z]*).*"),
+]
+
+
+def _extract_name(line: str) -> str:
+    for pattern in _NAME_EXTRACT_PATTERNS:
+        m = pattern.match(line)
+        if m:
+            return m.group(1)
+    return line
+
+
+def collect_class_names(root: str, out_dir: Path) -> int:
+    print("  → class names...")
+    raw: list[str] = []
+    raw.extend(_safe_grep("*.ts", "^export (abstract )?class [A-Z][a-zA-Z]+", root))
+    raw.extend(_safe_grep("*.ts", "^export (abstract )?interface [A-Z][a-zA-Z]+", root))
+    raw.extend(
+        _safe_grep(
+            "*.cs",
+            r"^[[:space:]]*(public|internal|sealed|abstract) (partial )?"
+            r"(class|record|struct) [A-Z][a-zA-Z]+",
+            root,
+        )
+    )
+    raw.extend(
+        _safe_grep(
+            "*.java",
+            "^public (abstract |final )?(class|interface|enum|record) [A-Z][a-zA-Z]+",
+            root,
+        )
+    )
+    raw.extend(_safe_grep("*.py", "^class [A-Z][a-zA-Z]+", root))
+    raw.extend(_safe_grep("*.go", "^type [A-Z][a-zA-Z]+ struct", root))
+    raw.extend(_safe_grep("*.go", "^type [A-Z][a-zA-Z]+ interface", root))
+    raw.extend(_safe_grep("*.rb", "^class [A-Z][a-zA-Z]+", root))
+
+    filtered = [line for line in raw if not _CLASS_EXCLUDES.search(line)]
+    names = [_extract_name(line) for line in filtered]
+    unique = _sort_unique(names)
+    _write_lines(out_dir / "class-names.txt", unique)
+    print(f"    {len(unique)} candidates")
+    return len(unique)
+
+
+def collect_enum_values(root: str, out_dir: Path) -> int:
+    print("  → enum values...")
+    raw: list[str] = []
+    raw.extend(_safe_grep("*.ts", "^export (const )?enum [A-Z]", root))
+    raw.extend(_safe_grep("*.cs", r"^[[:space:]]*(public|internal) enum [A-Z]", root))
+    raw.extend(_safe_grep("*.java", "^public enum [A-Z]", root))
+    raw.extend(
+        _safe_grep("*.py", r"class [A-Z][a-zA-Z]*(Enum|Status|Type|State)\b", root)
+    )
+    raw.extend(_safe_grep("*.go", "// [A-Z][a-zA-Z]+ (is|represents|indicates)", root))
+    unique = _sort_unique(raw)
+    _write_lines(out_dir / "enum-values.txt", unique)
+    print(f"    {len(unique)} candidates")
+    return len(unique)
+
+
+_EVENT_SUFFIXES = (
+    "Created|Updated|Submitted|Approved|Cancelled|Rejected|Completed|Failed"
+    "|Requested|Issued|Revoked|Expired|Activated|Deactivated|Shipped"
+    "|Delivered|Refunded|Disputed"
+)
+
+
+def collect_domain_events(root: str, out_dir: Path) -> int:
+    print("  → domain events...")
+    raw: list[str] = []
+    raw.extend(_safe_grep("*.ts", f"class [A-Z][a-zA-Z]*({_EVENT_SUFFIXES})", root))
+    raw.extend(_safe_grep("*.cs", f"class [A-Z][a-zA-Z]*({_EVENT_SUFFIXES})", root))
+    raw.extend(_safe_grep("*.java", f"class [A-Z][a-zA-Z]*({_EVENT_SUFFIXES})", root))
+    raw.extend(
+        _safe_grep("*.go", f"type [A-Z][a-zA-Z]*({_EVENT_SUFFIXES}) struct", root)
+    )
+
+    event_class = re.compile(r".*class ([A-Z][a-zA-Z]*).*")
+    event_type = re.compile(r".*type ([A-Z][a-zA-Z]*) struct.*")
+    names = []
+    for line in raw:
+        m = event_class.match(line) or event_type.match(line)
+        names.append(m.group(1) if m else line)
+
+    unique = _sort_unique(names)
+    _write_lines(out_dir / "domain-events.txt", unique)
+    print(f"    {len(unique)} candidates")
+    return len(unique)
+
+
+def collect_bdd_names(root: str, out_dir: Path) -> int:
+    print("  → BDD names...")
+    raw: list[str] = []
+    # Gherkin keywords: `Scenario:`, `Given x`, `When y`, etc. — the
+    # trailing char after the keyword is either whitespace or `:` (for
+    # `Scenario` outlines / `Feature`). The .sh required trailing `\s`,
+    # which never matches `Scenario:` — another bug we fix here.
+    raw.extend(
+        _safe_grep(
+            "*.feature",
+            r"^[[:space:]]*(Scenario|Given|When|Then|And)([[:space:]]|:)",
+            root,
+        )
+    )
+    raw.extend(_safe_grep("*.ts", "it\\(['\"].*['\"]", root))
+    raw.extend(_safe_grep("*.ts", "describe\\(['\"].*['\"]", root))
+    raw.extend(
+        _safe_grep("*.cs", r"\[Fact\]|public void (Given|When|Then|Should)[A-Z]", root)
+    )
+    raw.extend(
+        _safe_grep("*.java", r"@Test.*\n.*void (given|when|then|should)[A-Z]", root)
+    )
+    unique = _sort_unique(raw)
+    _write_lines(out_dir / "bdd-names.txt", unique)
+    print(f"    {len(unique)} candidates")
+    return len(unique)
+
+
+def collect_validator_rules(root: str, out_dir: Path) -> int:
+    print("  → validator rules...")
+    raw: list[str] = []
+    # ERE alternation (matches grep -E): raw `|` is the alternation
+    # operator, not the escaped BRE `\|` the .sh has (which grep -E treats
+    # as a literal `|` character).
+    raw.extend(
+        _safe_grep(
+            "*.ts",
+            r"\.withMessage|\.mustBe|\.isRequired|z\.string\(\)\.refine|yup\.",
+            root,
+        )
+    )
+    raw.extend(
+        _safe_grep("*.cs", r"RuleFor|\.Must|\.WithMessage|\.NotNull|\.NotEmpty", root)
+    )
+    raw.extend(
+        _safe_grep(
+            "*.java",
+            r"@NotNull|@NotBlank|@Size|@Min|@Max|@Pattern|@Valid|@Constraint",
+            root,
+        )
+    )
+    raw.extend(
+        _safe_grep("*.py", r"raise ValueError|raise TypeError|assert .*, ['\"]", root)
+    )
+    unique = _sort_unique(raw)
+    _write_lines(out_dir / "validator-rules.txt", unique)
+    print(f"    {len(unique)} candidates")
+    return len(unique)
+
+
+def collect_interface_names(root: str, out_dir: Path) -> int:
+    print("  → interface names...")
+    raw: list[str] = []
+    raw.extend(_safe_grep("*.ts", "^export interface [A-Z][a-zA-Z]+", root))
+    raw.extend(
+        _safe_grep(
+            "*.cs",
+            r"^[[:space:]]*(public|internal) interface I[A-Z][a-zA-Z]+",
+            root,
+        )
+    )
+    raw.extend(_safe_grep("*.java", "^public interface [A-Z][a-zA-Z]+", root))
+    raw.extend(_safe_grep("*.go", "type [A-Z][a-zA-Z]+ interface", root))
+
+    filtered = [line for line in raw if not _INTERFACE_EXCLUDES.search(line)]
+    iface_extract = re.compile(r".*interface (I?)([A-Z][a-zA-Z]*).*")
+    names = []
+    for line in filtered:
+        m = iface_extract.match(line)
+        names.append(m.group(2) if m else line)
+
+    unique = _sort_unique(names)
+    _write_lines(out_dir / "interface-names.txt", unique)
+    print(f"    {len(unique)} candidates")
+    return len(unique)
+
+
+def main(argv: list) -> int:
+    root = argv[1] if len(argv) > 1 else "."
+    out_dir = Path(".plans/raw/domain-language")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    print(f"Collecting domain signals from: {root}")
+
+    collect_class_names(root, out_dir)
+    collect_enum_values(root, out_dir)
+    collect_domain_events(root, out_dir)
+    collect_bdd_names(root, out_dir)
+    collect_validator_rules(root, out_dir)
+    collect_interface_names(root, out_dir)
+
+    print()
+    print(f"Signal collection complete. Results in {out_dir}/")
+
+    # Total unique candidates across all txt files.
+    combined = set()
+    for txt in out_dir.glob("*.txt"):
+        combined.update(txt.read_text().splitlines())
+    combined.discard("")
+    print(f"Total raw candidates: {len(combined)}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/skills/unfreeze/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: unfreeze
+description: >-
+  Lift the scope lock set by /freeze. All files become editable again.
+user-invocable: true
+allowed-tools: Bash(rm *)
+---
+
+# Unfreeze
+
+Role: worker. This command removes the file editing scope lock.
+
+You have been invoked with the `/unfreeze` command.
+
+Arguments: none — operates on the current freeze state.
+
+## Worker constraints
+
+1. Clear only the freeze-state file.
+2. Do not edit source.
+3. **Be concise.** Confirm the lock is lifted in one line.
+
+## Steps
+
+### 1. Remove freeze state
+
+Delete `.claude/hooks/freeze-state.json` if it exists (the same per-repo
+path `/freeze` writes and `hooks/pre_tool_guard.py` reads — see issue #1890):
+
+```bash
+rm -f .claude/hooks/freeze-state.json
+```
+
+### 2. Confirm
+
+Display:
+> Scope lock lifted. All files are editable.

package/skills/upgrade/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: upgrade
+description: >-
+  Check for and apply pi-dev-team package updates using pi's package manager.
+user-invocable: true
+allowed-tools: Read, Bash
+---
+
+# Upgrade
+
+Role: worker. Updates the pi-dev-team package through pi's own package
+mechanism. Never hand-edit installed package files.
+
+You have been invoked with the `/upgrade` command. Arguments: none.
+
+## Steps
+
+1. Report the current version: run the `/version` command's script
+   (`${CLAUDE_PLUGIN_ROOT}/package.json` and `UPSTREAM.json`).
+2. Find how the package is installed: `pi list` (look for `pi-dev-team`).
+   - **git or npm source** → run `pi update <source>` to update that package,
+     regardless of whether it is installed globally or in project settings.
+     Report the version delta afterwards.
+   - **local path** (e.g. `./pi-dev-team`) → pi does not update local packages.
+     Tell the user to pull the package directory (`git -C <path> pull`) or, when
+     it is a sync of upstream, to run
+     `python3 <path>/sync/sync_upstream.py --upstream <agentic-dev-team checkout>`.
+3. Tell the user to run `/reload` (or restart pi) so the new extension code,
+   skills and agents load.
+
+**Be concise.** Report version deltas only.

package/skills/upgrade/scripts/check_version_drift.py

@@ -0,0 +1,113 @@
+#!/usr/bin/env python3
+"""Report dev-team plugin version drift: installed version vs latest catalog.
+
+Read-only diagnostic. Prints a one-line advisory when the installed plugin
+version differs from the version the (refreshed) marketplace catalog offers.
+That mismatch is the signal auto-update alone cannot surface:
+
+* a refreshed catalog is ahead but the update lands only on the next launch, or
+* the refresh was blocked (e.g. by a restrictive network policy) so the session
+  is silently stale.
+
+Prints nothing when the versions match (or when either can't be resolved), so a
+caller can gate on empty output.
+
+Modes:
+  (default)         Print a plain advisory line, or nothing when current.
+  --session-start   Print a SessionStart hookSpecificOutput JSON wrapping the
+                    advisory, or nothing when current — for the cloud hook.
+
+Honors ``CLAUDE_CONFIG_DIR``. Stdlib only, (ADR 0014 / 0015).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+PLUGIN = "dev-team"
+
+
+def config_dir() -> str:
+    """The Claude Code config dir — ``CLAUDE_CONFIG_DIR`` if set, else ~/.claude."""
+    return os.environ.get("CLAUDE_CONFIG_DIR") or os.path.join(
+        os.path.expanduser("~"), ".claude"
+    )
+
+
+def load(path: str):
+    """Parse a JSON file, or return None if missing or malformed."""
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+
+
+def installed(cfg: str) -> tuple[str | None, str | None]:
+    """(version, marketplace) for the installed dev-team plugin, or (None, None)."""
+    plugins = (
+        load(os.path.join(cfg, "plugins", "installed_plugins.json")) or {}
+    ).get("plugins", {})
+    for pid, entries in plugins.items():
+        if pid.split("@", 1)[0] == PLUGIN and "@" in pid and entries:
+            return entries[0].get("version"), pid.split("@", 1)[1]
+    return None, None
+
+
+def latest(cfg: str, market: str) -> str | None:
+    """The dev-team version the cached marketplace catalog offers, or None."""
+    reg = load(os.path.join(cfg, "plugins", "known_marketplaces.json")) or {}
+    loc = (reg.get(market) or {}).get("installLocation")
+    if not loc:
+        return None
+    catalog = load(os.path.join(loc, ".claude-plugin", "marketplace.json")) or {}
+    for p in catalog.get("plugins", []):
+        if p.get("name") == PLUGIN:
+            return p.get("version")
+    return None
+
+
+def advisory(cfg: str) -> str:
+    """The drift advisory line, or '' when current / indeterminate."""
+    inst, market = installed(cfg)
+    if not inst or not market:
+        return ""
+    newest = latest(cfg, market)
+    if not newest or newest == inst:
+        return ""
+    return (
+        f"dev-team plugin is v{inst}; v{newest} is available from '{market}'. "
+        "Restart Claude Code (or run /upgrade) to apply."
+    )
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(description="Report dev-team version drift.")
+    parser.add_argument(
+        "--session-start",
+        action="store_true",
+        help="Emit a SessionStart hookSpecificOutput JSON instead of a plain line.",
+    )
+    args = parser.parse_args(argv)
+    msg = advisory(config_dir())
+    if not msg:
+        return 0
+    if args.session_start:
+        print(
+            json.dumps(
+                {
+                    "hookSpecificOutput": {
+                        "hookEventName": "SessionStart",
+                        "additionalContext": msg,
+                    }
+                }
+            )
+        )
+    else:
+        print(msg)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())