spec-agent-cli 0.1.0__tar.gz

spec_agent_cli-0.1.0/.agents/skills/spec-drift-sync/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: spec-drift-sync
+description: Use when accepted specifications may disagree with implementations after refactors, merges, hotfixes, or code-only changes, or when backlinks, traceability, tests, or verification evidence may be missing or stale.
+---
+
+# Spec Drift Sync
+
+Act as a read-only observer of specification/code disagreement. Product specs
+remain normative; code, tests, Git history, and passing verification are evidence.
+
+<HARD-GATE>
+Do not edit specifications, code, tests, code backlinks, or verification state. Do not
+run an implementation or repair workflow. The only permitted write is regenerating the
+non-normative derived traceability index from backlinks that already exist in code.
+</HARD-GATE>
+
+## Detection
+
+1. Read root `SPEC.md`, both files in the affected feature packet, current code and
+   public behavior, existing `spec: BEHAVIOR-ID` backlinks, relevant Git changes, and
+   related product-decision history.
+2. Run `scripts/check.py check --repo REPOSITORY`. Use `--spec-root SPEC_SOURCE` only
+   for an intentionally scoped observation.
+3. Inspect meaning manually. A clean structural report proves identity consistency,
+   not semantic compliance.
+
+## Traceability refresh
+
+Run `scripts/check.py sync --repo REPOSITORY --output spec/traceability.json` to replace
+only the derived traceability index. It maps behavior IDs to existing code backlink
+locations. It must not be copied into `spec.md` or `acceptance.md`, treated as product
+authority, or edited to conceal missing links.
+
+## Evidence report
+
+For every finding report:
+
+- behavior ID and drift category;
+- normative product evidence with specification path and rule;
+- implementation evidence with code, interface, test, or Git location;
+- structural identity problem or semantic conflict;
+- observable impact and the authority decision required.
+
+Structural findings include `phantom`, `dead-ref`, `silent-implementation`, `unlinked`,
+and `stale-verification`. Semantic conflicts include code contradicting accepted
+behavior, obsolete or ambiguous product rules, and behavior without product authority.
+
+## Authority handoff
+
+Ask one product decision at a time and present viable outcomes with impact. Never
+silently promote observed code to intended behavior.
+
+- If intended product behavior changes, hand the decision to `spec-request-flow` for
+  clarification, both spec files, and approval.
+- If the approved product behavior remains correct, hand the evidence to a separate
+  Code Agent to plan engineering changes.
+- Use `spec-evolution` only to preserve an approved product authority decision.
+
+Stop after the evidence report and handoff. Do not apply the selected repair, add
+backlinks, execute tests, weaken the checker, or mark verification current.

spec_agent_cli-0.1.0/.agents/skills/spec-drift-sync/scripts/check.py

@@ -0,0 +1,404 @@
+#!/usr/bin/env python3
+"""Dependency-free structural specification/code drift checker."""
+
+# spec: SA-013, SA-014, SA-015
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import subprocess
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Iterable
+
+
+UPPER_ID = re.compile(r"^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d{3}):\s*(.*)$")
+SLUG_ID = re.compile(r"^((?:[CQ]:)?[a-z][a-z0-9]*(?:-[a-z0-9]+)+):\s*(.*)$")
+CODE_REF = re.compile(r"^\s*~\s+(.+?)\s*$")
+COMMENT = re.compile(r"(?:#|//|/\*|\*)\s*spec:\s*([^#/*\n]*)", re.I)
+TOKEN = re.compile(
+    r"^(?:(?:[CQ]:)?[a-z][a-z0-9]*(?:-[a-z0-9]+)+|"
+    r"[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d{3})$"
+)
+SKIP_DIRS = {
+    ".git",
+    ".spec",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    "dist",
+    "build",
+    "evolution",
+}
+SKIP_FILES = {"AGENTS.md", "CLAUDE.md", "GEMINI.md"}
+
+
+@dataclass(frozen=True)
+class SpecEntry:
+    behavior_id: str
+    statement: str
+    spec_file: str
+    line: int
+    planned: bool
+    code_status: str | None
+    code_refs: tuple[str, ...]
+    verified_commit: str | None
+
+
+@dataclass(frozen=True)
+class CodeBacklink:
+    behavior_id: str
+    code_file: str
+    line: int
+
+
+@dataclass(frozen=True)
+class DriftIssue:
+    kind: str
+    behavior_id: str
+    message: str
+    spec_file: str | None = None
+    code_file: str | None = None
+    line: int | None = None
+    ref: str | None = None
+
+
+@dataclass(frozen=True)
+class DriftReport:
+    repo_root: str
+    spec_root: str
+    entries: tuple[SpecEntry, ...]
+    backlinks: tuple[CodeBacklink, ...]
+    issues: tuple[DriftIssue, ...]
+
+    @property
+    def clean(self) -> bool:
+        return not self.issues
+
+
+def analyze_repo(
+    repo_root: Path | str, spec_root: Path | str | None = None
+) -> DriftReport:
+    repo = Path(repo_root).resolve()
+    specs = _resolve_spec_sources(repo, spec_root)
+    entries = tuple(
+        entry for source in specs for entry in parse_spec_entries(source, repo)
+    )
+    backlinks = tuple(scan_code_backlinks(repo))
+    known = {entry.behavior_id: entry for entry in entries}
+    by_id: dict[str, list[CodeBacklink]] = {}
+    for backlink in backlinks:
+        by_id.setdefault(backlink.behavior_id, []).append(backlink)
+
+    issues: list[DriftIssue] = []
+    for backlink in backlinks:
+        if not _entry_exists(backlink.behavior_id, known):
+            issues.append(
+                DriftIssue(
+                    "phantom",
+                    backlink.behavior_id,
+                    "code backlink has no spec entry",
+                    code_file=backlink.code_file,
+                    line=backlink.line,
+                )
+            )
+    for entry in entries:
+        for ref in entry.code_refs:
+            path = ref.split(":", 1)[0]
+            if not (repo / path).exists():
+                issues.append(
+                    DriftIssue(
+                        "dead-ref",
+                        entry.behavior_id,
+                        "spec code reference does not exist",
+                        spec_file=entry.spec_file,
+                        line=entry.line,
+                        ref=ref,
+                    )
+                )
+        if entry.planned and entry.behavior_id in by_id:
+            link = by_id[entry.behavior_id][0]
+            issues.append(
+                DriftIssue(
+                    "silent-implementation",
+                    entry.behavior_id,
+                    "planned behavior already has a code backlink",
+                    spec_file=entry.spec_file,
+                    code_file=link.code_file,
+                    line=link.line,
+                )
+            )
+        if (
+            not entry.planned
+            and entry.code_status != "not_applicable"
+            and not entry.code_refs
+            and entry.behavior_id not in by_id
+        ):
+            issues.append(
+                DriftIssue(
+                    "unlinked",
+                    entry.behavior_id,
+                    "accepted behavior has no trace link",
+                    spec_file=entry.spec_file,
+                    line=entry.line,
+                )
+            )
+        if entry.verified_commit and _is_git_repo(repo):
+            for ref in entry.code_refs:
+                path = ref.split(":", 1)[0]
+                if _git(
+                    repo,
+                    ["log", "--format=%H", f"{entry.verified_commit}..HEAD", "--", path],
+                ):
+                    issues.append(
+                        DriftIssue(
+                            "stale-verification",
+                            entry.behavior_id,
+                            "linked code changed after verification",
+                            spec_file=entry.spec_file,
+                            line=entry.line,
+                            ref=ref,
+                        )
+                    )
+
+    return DriftReport(
+        str(repo),
+        " | ".join(str(source) for source in specs),
+        entries,
+        backlinks,
+        tuple(issues),
+    )
+
+
+def parse_spec_entries(spec_root: Path, repo_root: Path) -> Iterable[SpecEntry]:
+    paths = [spec_root] if spec_root.is_file() else sorted(spec_root.rglob("*.md"))
+    for path in paths:
+        if "evolution" in path.parts:
+            continue
+        text = _read(path)
+        verified = _frontmatter(text, "verified_commit")
+        code_status = _frontmatter(text, "code_status")
+        lines = text.splitlines()
+        index = 0
+        while index < len(lines):
+            match = UPPER_ID.match(lines[index]) or SLUG_ID.match(lines[index])
+            if not match:
+                index += 1
+                continue
+            refs: list[str] = []
+            cursor = index + 1
+            while cursor < len(lines) and not (
+                UPPER_ID.match(lines[cursor]) or SLUG_ID.match(lines[cursor])
+            ):
+                ref = CODE_REF.match(lines[cursor])
+                if ref:
+                    refs.append(ref.group(1).strip())
+                cursor += 1
+            statement = match.group(2).strip()
+            yield SpecEntry(
+                match.group(1),
+                statement,
+                _relative(path, repo_root),
+                index + 1,
+                "[planned]" in statement.lower(),
+                code_status,
+                tuple(refs),
+                verified,
+            )
+            index = cursor
+
+
+def scan_code_backlinks(repo_root: Path) -> Iterable[CodeBacklink]:
+    for path in sorted(repo_root.rglob("*")):
+        if _skip(path):
+            continue
+        for number, line in enumerate(_read(path).splitlines(), 1):
+            visible = _mask_strings(line)
+            for match in COMMENT.finditer(visible):
+                for raw in match.group(1).replace(",", " ").split():
+                    token = raw.strip().strip("`'\"").rstrip(".,;")
+                    if TOKEN.match(token):
+                        yield CodeBacklink(token, _relative(path, repo_root), number)
+
+
+def write_traceability(report: DriftReport, output: Path | str) -> dict[str, object]:
+    """Write a deterministic, non-normative index derived from code backlinks."""
+    target = Path(output)
+    behaviors: dict[str, list[dict[str, object]]] = {}
+    for backlink in sorted(
+        report.backlinks,
+        key=lambda item: (item.behavior_id, item.code_file, item.line),
+    ):
+        behaviors.setdefault(backlink.behavior_id, []).append(
+            {"path": backlink.code_file, "line": backlink.line}
+        )
+    document: dict[str, object] = {
+        "schema_version": 1,
+        "source": "derived-from-code-backlinks",
+        "behaviors": behaviors,
+    }
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(
+        json.dumps(document, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return document
+
+
+def render_text(report: DriftReport) -> str:
+    if report.clean:
+        return "=== SPEC-AGENT DRIFT CHECK ===\n\nCLEAN\n  - no structural drift detected"
+    lines = [
+        "=== SPEC-AGENT DRIFT CHECK ===",
+        "",
+        f"DRIFT SUMMARY: {len(report.issues)} item(s)",
+    ]
+    for issue in report.issues:
+        location = issue.code_file or issue.spec_file or ""
+        lines.append(
+            f"  - {issue.kind}: {issue.behavior_id}: {issue.message} {location}".rstrip()
+        )
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Check structural spec/code drift.")
+    sub = parser.add_subparsers(dest="command")
+    check = sub.add_parser("check")
+    check.add_argument("--repo", default=".")
+    check.add_argument("--spec-root")
+    check.add_argument("--json", action="store_true")
+    sync = sub.add_parser("sync")
+    sync.add_argument("--repo", default=".")
+    sync.add_argument("--spec-root")
+    sync.add_argument("--output", default="spec/traceability.json")
+    args = parser.parse_args(argv)
+    if args.command not in {"check", "sync"}:
+        parser.print_help()
+        return 2
+    try:
+        report = analyze_repo(args.repo, args.spec_root)
+    except (FileNotFoundError, NotADirectoryError) as error:
+        print(f"error: {error}")
+        return 2
+    if args.command == "sync":
+        output = Path(args.output)
+        if not output.is_absolute():
+            output = Path(args.repo).resolve() / output
+        try:
+            write_traceability(report, output)
+        except OSError as error:
+            print(f"error: {error}")
+            return 2
+        print(output)
+        return 0
+    print(json.dumps(asdict(report), indent=2) if args.json else render_text(report))
+    return 0 if report.clean else 1
+
+
+def _resolve_spec_sources(
+    repo: Path, spec_root: Path | str | None
+) -> tuple[Path, ...]:
+    if spec_root is not None:
+        candidate = Path(spec_root)
+        candidate = candidate if candidate.is_absolute() else repo / candidate
+        if not candidate.exists() or not (candidate.is_file() or candidate.is_dir()):
+            raise FileNotFoundError(f"spec source does not exist: {candidate}")
+        return (candidate.resolve(),)
+    root_spec = repo / "SPEC.md"
+    if root_spec.is_file():
+        sources = [root_spec.resolve()]
+        spec_dir = repo / "spec"
+        if spec_dir.is_dir():
+            sources.append(spec_dir.resolve())
+        return tuple(sources)
+    for name in ("spec", "specs"):
+        candidate = repo / name
+        if candidate.is_dir():
+            return (candidate.resolve(),)
+    raise FileNotFoundError("No spec source found. Expected SPEC.md, spec/, or specs/.")
+
+
+def _frontmatter(text: str, key: str) -> str | None:
+    if not text.startswith("---\n"):
+        return None
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return None
+    match = re.search(rf"^\s*{re.escape(key)}:\s*([^\s#]+)\s*$", parts[1], re.M)
+    if not match:
+        return None
+    value = match.group(1).strip("'\"")
+    return None if value in {"", "null", "None"} else value
+
+
+def _mask_strings(line: str) -> str:
+    output: list[str] = []
+    quote: str | None = None
+    escaped = False
+    for char in line:
+        if quote:
+            output.append(" ")
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                quote = None
+        elif char in {"'", '"'}:
+            quote = char
+            output.append(" ")
+        else:
+            output.append(char)
+    return "".join(output)
+
+
+def _skip(path: Path) -> bool:
+    if any(part in SKIP_DIRS for part in path.parts) or path.name in SKIP_FILES:
+        return True
+    try:
+        return not path.is_file() or path.suffix.lower() == ".md"
+    except OSError:
+        return True
+
+
+def _entry_exists(behavior_id: str, entries: dict[str, SpecEntry]) -> bool:
+    return (
+        behavior_id in entries
+        or f"C:{behavior_id}" in entries
+        or f"Q:{behavior_id}" in entries
+    )
+
+
+def _is_git_repo(repo: Path) -> bool:
+    return _git(repo, ["rev-parse", "--is-inside-work-tree"]) == "true"
+
+
+def _git(repo: Path, args: list[str]) -> str:
+    try:
+        return subprocess.check_output(
+            ["git", *args], cwd=repo, text=True, stderr=subprocess.DEVNULL
+        ).strip()
+    except (subprocess.CalledProcessError, FileNotFoundError):
+        return ""
+
+
+def _read(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return ""
+
+
+def _relative(path: Path, root: Path) -> str:
+    try:
+        return str(path.relative_to(root)).replace("\\", "/")
+    except ValueError:
+        return str(path).replace("\\", "/")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

spec_agent_cli-0.1.0/.agents/skills/spec-evolution/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: spec-evolution
+description: Use when an approved specification change, product authority decision, correction, terminal spec outcome, timeline, or UI history must be preserved as durable product evolution.
+---
+
+# Spec Evolution
+
+Preserve meaningful product decisions and contract transitions in one append-only, UI-ready log.
+Current specifications own present truth; evolution owns why that truth changed.
+
+## Event boundaries
+
+Append one event only at these boundaries:
+
+| Boundary | Record when |
+|---|---|
+| approved specification change | Product authority explicitly approves new or revised `spec.md` and `acceptance.md`. |
+| product authority decision | A drift conflict or open product question receives an authoritative decision. |
+| correction | A historical product record is wrong and a replacement names it in `supersedes`. |
+| terminal spec outcome | Specification work completes or is explicitly stopped, blocked, or abandoned with a meaningful product state. |
+
+Routine reads, tool calls, unanswered clarification, unchanged drift observations, and
+engineering execution do not create product evolution events.
+
+## Record the event
+
+1. Run `scripts/record.py --help`, then append to `spec/evolution/events.jsonl` with a
+   unique ID and ISO-8601 timestamp.
+2. Include summarized user intent, task type, behavior IDs, both spec files, assumptions,
+   approved product decision, rationale, normative spec delta, follow-ups, and
+   `supersedes` when correcting history.
+3. Exclude implementation plans, code locations or deltas, engineering evidence, test
+   outcomes, verification status, commands, full prompts, secrets, credentials, copied
+   file contents, and unnecessary private data.
+4. Never rewrite, reorder, or delete completed lines. Correct by appending a replacement.
+
+## Regenerate and verify
+
+1. Run `scripts/timeline.py --log spec/evolution/events.jsonl --output spec/evolution/timeline.md`.
+2. Verify the event ID appears in both the JSONL source and generated timeline.
+3. Report exact validation or line errors; never reconstruct missing product evidence.
+
+UI consumers read `events.jsonl` for structured history. `timeline.md` is generated
+Markdown/Mermaid presentation and is never normative.
+
+## Ownership boundaries
+
+- Root and feature product specs own current approved behavior.
+- `events.jsonl` owns product intent, decisions, rationale, deltas, and supersession.
+- Git and external engineering systems own code diffs, plans, tests, and verification.
+- `timeline.md` owns no source data.
+
+## Gotchas
+
+- Do not append one event per prompt; record defined product boundaries only.
+- Later prompts reuse the same feature and stable behavior IDs.
+- Missing information remains missing rather than being inferred.

spec_agent_cli-0.1.0/.agents/skills/spec-evolution/scripts/record.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Append one validated, product-only specification evolution event."""
+
+# spec: ELOG-001, ELOG-002, ELOG-003, ELOG-004
+
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+LIST_FIELDS = ("behavior_ids", "spec_files")
+TEXT_DEFAULTS = {
+    "actor": "agent",
+    "status": "completed",
+    "assumptions": "",
+    "decision": "",
+    "rationale": "",
+    "spec_delta": "",
+    "follow_ups": "",
+    "supersedes": "",
+}
+REQUIRED_TEXT = ("id", "timestamp", "title", "task_type", "user_intent")
+ENGINEERING_FIELDS = {
+    "code_files",
+    "evidence_refs",
+    "implementation_delta",
+    "drift_status",
+    "drift_summary",
+    "verification_result",
+    "verification_summary",
+}
+
+
+def append_event(log: Path, event: dict[str, Any]) -> dict[str, Any]:
+    normalized = normalize_event(event)
+    existing_ids: set[str] = set()
+    if log.exists():
+        for line_number, line in enumerate(log.read_text(encoding="utf-8").splitlines(), 1):
+            if not line.strip():
+                continue
+            try:
+                value = json.loads(line)
+            except json.JSONDecodeError as error:
+                raise ValueError(f"existing log has invalid JSON at line {line_number}") from error
+            if not isinstance(value, dict):
+                raise ValueError(f"existing log line {line_number} is not an object")
+            event_id = value.get("id")
+            if isinstance(event_id, str):
+                existing_ids.add(event_id)
+    if normalized["id"] in existing_ids:
+        raise ValueError(f"duplicate event id: {normalized['id']}")
+
+    log.parent.mkdir(parents=True, exist_ok=True)
+    with log.open("a", encoding="utf-8") as handle:
+        handle.write(json.dumps(normalized, ensure_ascii=False, sort_keys=True))
+        handle.write("\n")
+    return normalized
+
+
+def normalize_event(event: dict[str, Any]) -> dict[str, Any]:
+    forbidden = sorted(ENGINEERING_FIELDS.intersection(event))
+    if forbidden:
+        raise ValueError(f"engineering field is not allowed: {', '.join(forbidden)}")
+
+    normalized: dict[str, Any] = {"schema_version": 2}
+    for field in REQUIRED_TEXT:
+        value = event.get(field)
+        if not isinstance(value, str) or not value.strip():
+            raise ValueError(f"missing required field: {field}")
+        normalized[field] = value.strip()
+    try:
+        datetime.fromisoformat(normalized["timestamp"].replace("Z", "+00:00"))
+    except ValueError as error:
+        raise ValueError("timestamp must be ISO-8601") from error
+    for field, default in TEXT_DEFAULTS.items():
+        value = event.get(field, default)
+        if not isinstance(value, str):
+            raise ValueError(f"field must be text: {field}")
+        normalized[field] = value.strip()
+    for field in LIST_FIELDS:
+        value = event.get(field, [])
+        if not isinstance(value, list) or any(not isinstance(item, str) for item in value):
+            raise ValueError(f"field must be a string list: {field}")
+        normalized[field] = [item.strip() for item in value if item.strip()]
+    return normalized
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--log", type=Path, default=Path("spec/evolution/events.jsonl"))
+    parser.add_argument("--id", required=True)
+    parser.add_argument("--timestamp", required=True)
+    parser.add_argument("--title", required=True)
+    parser.add_argument("--task-type", required=True)
+    parser.add_argument("--user-intent", required=True)
+    parser.add_argument("--actor", default="agent")
+    parser.add_argument("--status", default="completed")
+    parser.add_argument("--behavior-id", action="append", default=[])
+    parser.add_argument("--spec-file", action="append", default=[])
+    parser.add_argument("--assumptions", default="")
+    parser.add_argument("--decision", default="")
+    parser.add_argument("--rationale", default="")
+    parser.add_argument("--spec-delta", default="")
+    parser.add_argument("--follow-ups", default="")
+    parser.add_argument("--supersedes", default="")
+    args = parser.parse_args(argv)
+    event = vars(args)
+    log = event.pop("log")
+    event["task_type"] = event.pop("task_type")
+    event["user_intent"] = event.pop("user_intent")
+    event["behavior_ids"] = event.pop("behavior_id")
+    event["spec_files"] = event.pop("spec_file")
+    try:
+        append_event(log, event)
+    except (OSError, ValueError) as error:
+        parser.error(str(error))
+    print(log)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())