spec-agent-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/.agents/skills/spec-drift-sync/SKILL.md

@@ -19,17 +19,23 @@ non-normative derived traceability index from backlinks that already exist in co
 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.
+2. Run `spec-agent validate --repo REPOSITORY`; if the CLI is unavailable, 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.
+After an approved implementation or explicit reconciliation, run `spec-agent
+traceability-sync --repo REPOSITORY`; if the CLI is unavailable, run `scripts/check.py
+sync --repo REPOSITORY --output spec/traceability.json`. It records behavior IDs,
+backlink locations, and linked-file fingerprints in the derived traceability baseline.
+
+Do not refresh traceability to silence unexplained drift. Validate first, understand
+existing findings, and refresh only when product intent or implementation authority is
+explicit. Never copy traceability into `spec.md` or `acceptance.md` or treat it as
+product authority.
 
 ## Evidence report
 
@@ -41,9 +47,10 @@ For every finding report:
 - 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.
+Structural findings include `phantom`, `unlinked`, `unbaselined`, `stale-trace`,
+`code-changed`, legacy `dead-ref`, `silent-implementation`, and `stale-verification`.
+Semantic conflicts include code contradicting accepted behavior, obsolete or ambiguous
+product rules, and behavior without product authority.
 
 ## Authority handoff
 

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/.agents/skills/spec-drift-sync/scripts/check.py

@@ -1,11 +1,12 @@
 #!/usr/bin/env python3
 """Dependency-free structural specification/code drift checker."""
 
-# spec: SA-013, SA-014, SA-015
+# spec: SA-013, SA-014, SA-015, SA-021, SA-022, SA-023, TRACE-004, TRACE-005, TRACE-006, TRACE-007, TRACE-008, TRACE-009, TRACE-011, TRACE-012
 
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
 import re
 import subprocess
@@ -42,6 +43,7 @@ class SpecEntry:
     statement: str
     spec_file: str
     line: int
+    status: str | None
     planned: bool
     code_status: str | None
     code_refs: tuple[str, ...]
@@ -87,7 +89,12 @@ def analyze_repo(
     entries = tuple(
         entry for source in specs for entry in parse_spec_entries(source, repo)
     )
-    backlinks = tuple(scan_code_backlinks(repo))
+    backlinks = tuple(
+        backlink
+        for backlink in scan_code_backlinks(repo)
+        if _is_spec_agent_source(repo)
+        or not backlink.code_file.startswith(".agents/skills/")
+    )
     known = {entry.behavior_id: entry for entry in entries}
     by_id: dict[str, list[CodeBacklink]] = {}
     for backlink in backlinks:
@@ -119,7 +126,8 @@ def analyze_repo(
                         ref=ref,
                     )
                 )
-        if entry.planned and entry.behavior_id in by_id:
+        requires_link = entry.status in {None, "approved"}
+        if requires_link and entry.planned and entry.behavior_id in by_id:
             link = by_id[entry.behavior_id][0]
             issues.append(
                 DriftIssue(
@@ -132,7 +140,8 @@ def analyze_repo(
                 )
             )
         if (
-            not entry.planned
+            requires_link
+            and not entry.planned
             and entry.code_status != "not_applicable"
             and not entry.code_refs
             and entry.behavior_id not in by_id
@@ -164,6 +173,10 @@ def analyze_repo(
                         )
                     )
 
+    traceability = _read_traceability(repo / "spec/traceability.json")
+    if traceability is not None:
+        issues.extend(_baseline_issues(repo, known, backlinks, traceability))
+
     return DriftReport(
         str(repo),
         " | ".join(str(source) for source in specs),
@@ -181,6 +194,7 @@ def parse_spec_entries(spec_root: Path, repo_root: Path) -> Iterable[SpecEntry]:
         text = _read(path)
         verified = _frontmatter(text, "verified_commit")
         code_status = _frontmatter(text, "code_status")
+        status = _frontmatter(text, "status")
         lines = text.splitlines()
         index = 0
         while index < len(lines):
@@ -203,6 +217,7 @@ def parse_spec_entries(spec_root: Path, repo_root: Path) -> Iterable[SpecEntry]:
                 statement,
                 _relative(path, repo_root),
                 index + 1,
+                status,
                 "[planned]" in statement.lower(),
                 code_status,
                 tuple(refs),
@@ -227,17 +242,24 @@ def scan_code_backlinks(repo_root: Path) -> Iterable[CodeBacklink]:
 def write_traceability(report: DriftReport, output: Path | str) -> dict[str, object]:
     """Write a deterministic, non-normative index derived from code backlinks."""
     target = Path(output)
+    repo = Path(report.repo_root)
     behaviors: dict[str, list[dict[str, object]]] = {}
     for backlink in sorted(
         report.backlinks,
         key=lambda item: (item.behavior_id, item.code_file, item.line),
     ):
+        code_path = repo / backlink.code_file
         behaviors.setdefault(backlink.behavior_id, []).append(
-            {"path": backlink.code_file, "line": backlink.line}
+            {
+                "path": backlink.code_file,
+                "line": backlink.line,
+                "file_sha256": _file_sha256(code_path),
+            }
         )
     document: dict[str, object] = {
-        "schema_version": 1,
+        "schema_version": 2,
         "source": "derived-from-code-backlinks",
+        "baseline_commit": _git(repo, ["rev-parse", "HEAD"]) or None,
         "behaviors": behaviors,
     }
     target.parent.mkdir(parents=True, exist_ok=True)
@@ -248,6 +270,102 @@ def write_traceability(report: DriftReport, output: Path | str) -> dict[str, obj
     return document
 
 
+def _read_traceability(path: Path) -> dict[str, object] | None:
+    if not path.is_file():
+        return None
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {"behaviors": {}, "invalid": True}
+    if not isinstance(value, dict) or not isinstance(value.get("behaviors"), dict):
+        return {"behaviors": {}, "invalid": True}
+    return value
+
+
+def _baseline_issues(
+    repo: Path,
+    known: dict[str, SpecEntry],
+    backlinks: tuple[CodeBacklink, ...],
+    traceability: dict[str, object],
+) -> list[DriftIssue]:
+    if traceability.get("invalid"):
+        return [
+            DriftIssue(
+                "invalid-traceability",
+                "TRACEABILITY",
+                "derived traceability file is invalid",
+                code_file="spec/traceability.json",
+            )
+        ]
+
+    raw_behaviors = traceability.get("behaviors", {})
+    baseline: dict[tuple[str, str], dict[str, object]] = {}
+    if isinstance(raw_behaviors, dict):
+        for behavior_id, raw_links in raw_behaviors.items():
+            if not isinstance(behavior_id, str) or not isinstance(raw_links, list):
+                continue
+            for raw_link in raw_links:
+                if not isinstance(raw_link, dict):
+                    continue
+                path = raw_link.get("path")
+                if isinstance(path, str) and path:
+                    baseline[(behavior_id, path)] = raw_link
+
+    current = {(link.behavior_id, link.code_file): link for link in backlinks}
+    findings: list[DriftIssue] = []
+    for key, backlink in sorted(current.items()):
+        behavior_id, code_file = key
+        if not _entry_exists(behavior_id, known):
+            continue
+        previous = baseline.get(key)
+        if previous is None:
+            findings.append(
+                DriftIssue(
+                    "unbaselined",
+                    behavior_id,
+                    "current backlink is not in the traceability baseline",
+                    code_file=code_file,
+                    line=backlink.line,
+                )
+            )
+            continue
+        expected_hash = previous.get("file_sha256")
+        if isinstance(expected_hash, str) and expected_hash:
+            current_hash = _file_sha256(repo / code_file)
+            if current_hash != expected_hash:
+                findings.append(
+                    DriftIssue(
+                        "code-changed",
+                        behavior_id,
+                        "linked code file changed since the traceability baseline",
+                        code_file=code_file,
+                        line=backlink.line,
+                    )
+                )
+
+    for key, previous in sorted(baseline.items()):
+        if key in current:
+            continue
+        behavior_id, code_file = key
+        findings.append(
+            DriftIssue(
+                "stale-trace",
+                behavior_id,
+                "baseline backlink moved or disappeared",
+                code_file=code_file,
+                line=previous.get("line") if isinstance(previous.get("line"), int) else None,
+            )
+        )
+    return findings
+
+
+def _file_sha256(path: Path) -> str:
+    try:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+    except OSError:
+        return hashlib.sha256(b"").hexdigest()
+
+
 def render_text(report: DriftReport) -> str:
     if report.clean:
         return "=== SPEC-AGENT DRIFT CHECK ===\n\nCLEAN\n  - no structural drift detected"
@@ -377,6 +495,11 @@ def _is_git_repo(repo: Path) -> bool:
     return _git(repo, ["rev-parse", "--is-inside-work-tree"]) == "true"
 
 
+def _is_spec_agent_source(repo: Path) -> bool:
+    """True only in this package's source tree, not an initialized consumer repo."""
+    return (repo / "src/spec_agent/installer.py").is_file()
+
+
 def _git(repo: Path, args: list[str]) -> str:
     try:
         return subprocess.check_output(

spec_agent_cli-0.2.0/.agents/skills/spec-request-flow/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: spec-request-flow
+description: Use when a user asks to add, change, fix, refactor, design, or implement repository behavior under spec-driven development, including vague requests and follow-ups that modify an existing feature even when specifications are not mentioned.
+---
+
+# Spec Request Flow
+
+Produce an approved product specification, then stop with a Code Agent handoff.
+
+<HARD-GATE>
+Do not scaffold or write specifications before product-decision approval.
+Do not create an implementation plan or choose files or technologies. Do not write
+code or tests, dispatch implementation, or perform engineering verification.
+</HARD-GATE>
+
+## Explore context
+
+Read `AGENTS.md`, root `SPEC.md`, the existing packet, relevant behavior, and related
+evolution events. Separate evidence, outcomes, conflicts, assumptions, and unknowns.
+Decompose independent subsystems and process one valuable feature at a time.
+
+## Clarify product behavior
+
+Ask one blocking question at a time. Present 2-3 approaches for each material product
+decision, with trade-offs and a recommendation about observable behavior. Cover actors,
+rules, conceptual data, flows, failures, recovery, states, edges, permissions, privacy,
+defaults, constraints, non-goals, and measurable outcomes. Label every unresolved item
+`blocking` or `non-blocking`; never convert an assumption into a requirement.
+
+## Requirements-completeness gate
+
+Verify every category above. Continue while a blocking item remains; defer only with
+user approval of a stated default.
+
+## Product-decision approval gate
+
+Present the product behavior for approval or revision. Do not write either file while
+approval is absent or ambiguous.
+
+## Write and self-review the specification
+
+1. Reuse `spec/features/<feature-slug>/` when present; otherwise run
+   `scripts/create_feature.py <feature-slug> --title "Feature Title"`.
+2. Read [references/spec-format.md](references/spec-format.md). Write both `spec.md`
+   and `acceptance.md`; add both paths to root `SPEC.md`.
+3. Keep both files strictly product-facing. Do not include code paths, symbols,
+   frameworks, storage choices, ordered engineering steps, test files, commands,
+   deployment instructions, or code backlinks.
+4. Run the complete self-review on both files and fix every finding.
+
+## Written-spec approval gate
+
+Show both paths and summarize their delta. Ask for explicit written-spec approval. If
+revised, update both files, rerun self-review, and ask again.
+
+## Completion and Code Agent handoff
+
+After approval, mark both files `approved`, use `spec-evolution` to record the decision,
+emit the contract below, and stop. `spec-drift-sync` is used after implementation.
+
+Output exactly the following, replacing `[SPEC_PATH]` with the actual `spec.md` path:
+
+Spec complete. To implement this, give your Code Agent the following prompt: 'Read the specification at [SPEC_PATH] and its companion acceptance.md, then generate an implementation plan. During implementation, add spec: BEHAVIOR-ID backlinks to relevant production code and tests for every implemented rule. After the approved implementation, run spec-agent traceability-sync --repo ., followed by spec-agent validate --repo . Do not claim completion unless validation reports CLEAN.'
+
+This is a handoff contract, not implementation by the Spec Agent. Do not append other
+planning advice, implementation steps, or an offer to write code.
+
+## Later changes
+
+A later prompt updates the same two-file packet and preserves stable behavior IDs.
+Return to clarification and both approval gates for every normative product change.

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/.agents/skills/spec-request-flow/scripts/create_feature.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Create a non-overwriting two-file feature specification packet."""
 
-# spec: FSP-001, FSP-002, FSP-003
+# spec: FSP-001, FSP-002, FSP-003, TRACE-001
 
 from __future__ import annotations
 

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/AGENTS.md

@@ -16,3 +16,17 @@ never writes implementation plans, code, tests, or engineering commands.
 Code backlinks use `spec: BEHAVIOR-ID`. `spec-drift-sync` observes them and may
 regenerate only non-normative `spec/traceability.json`; it never repairs code or
 specifications. Product decision history lives in `spec/evolution/events.jsonl`.
+
+## Code Agent contract
+
+When implementing an approved handoff, the Code Agent MUST:
+
+1. Read the feature `spec.md` and `acceptance.md`.
+2. Add `spec: BEHAVIOR-ID` backlinks to relevant production code and tests for every
+   implemented rule.
+3. Run `spec-agent traceability-sync --repo .` after the approved implementation.
+4. Run `spec-agent validate --repo .` and resolve or report every finding.
+
+The Code Agent MUST NOT claim completion unless validation reports `CLEAN`. It MUST NOT
+edit product specifications merely to match code; changed product intent returns to
+`spec-request-flow` for clarification and approval.

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spec-agent-cli
-Version: 0.1.0
+Version: 0.2.0
 Summary: A strict Spec Agent workflow for spec-driven development
 Author: Spec Agent contributors
 License: MIT
@@ -79,7 +79,23 @@ Use spec-request-flow to define feature X. Do not implement it.
 The Spec Agent repeatedly clarifies blocking product questions, compares meaningful
 product approaches, writes `spec.md` and `acceptance.md`, asks for approval, records
 the approved product evolution, and then gives you the prompt for a separate Code
-Agent.
+Agent. That handoff requires `spec: BEHAVIOR-ID` backlinks in relevant production code
+and tests.
+
+## Validate implementation traceability
+
+After an approved implementation, the Code Agent establishes the derived baseline and
+then validates it:
+
+```sh
+spec-agent traceability-sync --repo .
+spec-agent validate --repo .
+```
+
+`validate` is read-only and returns failure for missing, unknown, unbaselined, moved,
+or changed backlink evidence. `traceability-sync` is used only after approved
+implementation or explicit reconciliation; it must not be used to hide unexplained
+drift.
 
 ## License
 

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/README.md

@@ -56,7 +56,23 @@ Use spec-request-flow to define feature X. Do not implement it.
 The Spec Agent repeatedly clarifies blocking product questions, compares meaningful
 product approaches, writes `spec.md` and `acceptance.md`, asks for approval, records
 the approved product evolution, and then gives you the prompt for a separate Code
-Agent.
+Agent. That handoff requires `spec: BEHAVIOR-ID` backlinks in relevant production code
+and tests.
+
+## Validate implementation traceability
+
+After an approved implementation, the Code Agent establishes the derived baseline and
+then validates it:
+
+```sh
+spec-agent traceability-sync --repo .
+spec-agent validate --repo .
+```
+
+`validate` is read-only and returns failure for missing, unknown, unbaselined, moved,
+or changed backlink evidence. `traceability-sync` is used only after approved
+implementation or explicit reconciliation; it must not be used to hide unexplained
+drift.
 
 ## License
 

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/SPEC.md

@@ -2,7 +2,7 @@
 id: SPEC-AGENT
 title: Strict Spec Agent
 status: approved
-version: 4.0.0
+version: 4.1.0
 ---
 
 # Strict Spec Agent
@@ -28,6 +28,7 @@ hands the approved specification to a separate Code Agent.
 - [Evolution event log rules](spec/features/evolution-event-log/spec.md) and [acceptance](spec/features/evolution-event-log/acceptance.md)
 - [Strict skill behavior](spec/features/production-skill-hardening/spec.md) and [acceptance](spec/features/production-skill-hardening/acceptance.md)
 - [CLI distribution](spec/features/cli-distribution/spec.md) and [acceptance](spec/features/cli-distribution/acceptance.md)
+- [Code/spec traceability](spec/features/code-spec-traceability/spec.md) and [acceptance](spec/features/code-spec-traceability/acceptance.md)
 
 ## Product structure
 
@@ -125,6 +126,23 @@ merge a managed rules block safely, and scaffold only missing project-owned arti
 SA-019: Repeated initialization MUST be safe and idempotent, and forced updates MUST
 remain limited to CLI-managed skill assets.
 
+## Code Agent traceability contract
+
+SA-020: The Code Agent handoff MUST require both feature specifications, stable
+behavior-ID backlinks in relevant production code and tests, traceability refresh, and
+a clean drift validation before implementation completion.
+
+SA-021: Derived traceability MUST preserve a baseline of backlink locations and linked
+file fingerprints so later code changes can be reported without placing code paths in
+normative specifications.
+
+SA-022: Drift validation MUST be read-only and MUST distinguish missing, unknown,
+unbaselined, moved, and changed-code evidence while leaving semantic authority to a
+human product decision.
+
+SA-023: Traceability refresh MUST establish a new baseline only after an approved
+implementation or reconciliation; it MUST NOT silently make changed code authoritative.
+
 ## Workflow
 
 ```text
@@ -163,3 +181,7 @@ refresh derived traceability, and route a product decision back through request
 - AC-SA-006: Approved product evolution remains append-only and UI-readable.
 - AC-SA-007: A built wheel installs in a clean environment and initializes a repository
   that passes `spec-agent init --check`.
+- AC-SA-008: A Code Agent handoff cannot complete without behavior backlinks, refreshed
+  traceability, and clean read-only validation.
+- AC-SA-009: Modifying a baselined linked code file produces a drift finding until an
+  authorized reconciliation establishes a new baseline.

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "spec-agent-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "A strict Spec Agent workflow for spec-driven development"
 readme = "README.md"
 license = { text = "MIT" }

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/src/spec_agent/cli.py

@@ -11,6 +11,7 @@ from pathlib import Path
 import typer
 
 from spec_agent.commands.init import cmd_init
+from spec_agent.commands.traceability import cmd_traceability_sync, cmd_validate
 
 
 app = typer.Typer(
@@ -58,6 +59,24 @@ def init_command(
     raise typer.Exit(cmd_init(repo, check=check, force=force))
 
 
+@app.command("validate")
+def validate_command(
+    repo: Path = typer.Option(Path("."), "--repo", help="Repository to validate."),
+) -> None:
+    """Read-only validation of specifications, backlinks, and traceability."""
+    raise typer.Exit(cmd_validate(repo))
+
+
+@app.command("traceability-sync")
+def traceability_sync_command(
+    repo: Path = typer.Option(
+        Path("."), "--repo", help="Repository whose approved baseline is refreshed."
+    ),
+) -> None:
+    """Refresh derived traceability after approved implementation or reconciliation."""
+    raise typer.Exit(cmd_traceability_sync(repo))
+
+
 def main(argv: list[str] | None = None) -> int:
     try:
         app(args=argv, prog_name="spec-agent")

spec_agent_cli-0.2.0/src/spec_agent/commands/traceability.py

@@ -0,0 +1,35 @@
+"""Run the installed read-only drift checker and traceability refresh."""
+
+# spec: SA-020, SA-022, TRACE-003, TRACE-008, TRACE-009, TRACE-012
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _checker(repo_root: Path) -> Path:
+    return repo_root / ".agents/skills/spec-drift-sync/scripts/check.py"
+
+
+def _run(repo_root: Path, command: str) -> int:
+    root = repo_root.resolve()
+    checker = _checker(root)
+    if not checker.is_file():
+        print("Spec Agent drift checker is missing. Run 'spec-agent init' first.")
+        return 2
+    arguments = [sys.executable, str(checker), command, "--repo", str(root)]
+    if command == "sync":
+        arguments.extend(["--output", "spec/traceability.json"])
+    return subprocess.run(arguments, check=False).returncode
+
+
+def cmd_validate(repo_root: Path) -> int:
+    """Validate current specs, backlinks, and traceability without writes."""
+    return _run(repo_root, "check")
+
+
+def cmd_traceability_sync(repo_root: Path) -> int:
+    """Accept current approved backlink evidence as the derived baseline."""
+    return _run(repo_root, "sync")

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/src/spec_agent/installer.py

@@ -1,6 +1,6 @@
 """Safely install packaged Spec Agent assets into a repository."""
 
-# spec: CLI-002, CLI-003, CLI-004, CLI-005, CLI-006, CLI-007, CLI-008, CLI-009, CLI-010, CLI-011, SA-017, SA-018, SA-019
+# spec: CLI-002, CLI-003, CLI-004, CLI-005, CLI-006, CLI-007, CLI-008, CLI-009, CLI-010, CLI-011, SA-017, SA-018, SA-019, TRACE-005
 
 from __future__ import annotations
 
@@ -28,7 +28,8 @@ timeline
 EMPTY_TRACEABILITY = json.dumps(
     {
         "behaviors": {},
-        "schema_version": 1,
+        "baseline_commit": None,
+        "schema_version": 2,
         "source": "derived-from-code-backlinks",
     },
     indent=2,

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/tests/test_agent_assets.py

@@ -96,6 +96,18 @@ class AgentArchitectureTests(unittest.TestCase):
             self.assertIn(name, text)
         self.assertLessEqual(len(text.split()), 220)
 
+    def test_agents_file_contains_mandatory_code_agent_traceability_contract(self) -> None:
+        text = (ROOT / "AGENTS.md").read_text(encoding="utf-8")
+        for term in (
+            "Code Agent contract",
+            "spec: BEHAVIOR-ID",
+            "production code and tests",
+            "spec-agent traceability-sync",
+            "spec-agent validate",
+            "MUST NOT claim completion",
+        ):
+            self.assertIn(term, text)
+
     def test_spec_md_indexes_feature_spec_packets(self) -> None:
         self.assertTrue((ROOT / "SPEC.md").is_file())
         root_spec = (ROOT / "SPEC.md").read_text(encoding="utf-8")

spec_agent_cli-0.2.0/tests/test_cli.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# spec: CLI-001, CLI-007, TRACE-003, TRACE-008, TRACE-012
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from spec_agent.cli import main
+
+
+def test_cli_version(capsys) -> None:
+    assert main(["--version"]) == 0
+    assert capsys.readouterr().out.startswith("spec-agent ")
+
+
+def test_cli_init_and_check(tmp_path: Path) -> None:
+    assert main(["init", "--repo", str(tmp_path)]) == 0
+    assert main(["init", "--repo", str(tmp_path), "--check"]) == 0
+    assert (tmp_path / ".agents/skills/spec-request-flow/SKILL.md").is_file()
+
+
+def test_cli_traceability_sync_and_validate_detect_later_code_change(tmp_path: Path) -> None:
+    assert main(["init", "--repo", str(tmp_path)]) == 0
+    (tmp_path / "SPEC.md").write_text(
+        "---\nstatus: approved\n---\n\nFEATURE-001: Feature works.\n",
+        encoding="utf-8",
+    )
+    code = tmp_path / "service.py"
+    code.write_text("# spec: FEATURE-001\nvalue = 1\n", encoding="utf-8")
+
+    assert main(["traceability-sync", "--repo", str(tmp_path)]) == 0
+    before_validation = {
+        str(path.relative_to(tmp_path)): path.read_bytes()
+        for path in tmp_path.rglob("*")
+        if path.is_file()
+    }
+    assert main(["validate", "--repo", str(tmp_path)]) == 0
+    after_validation = {
+        str(path.relative_to(tmp_path)): path.read_bytes()
+        for path in tmp_path.rglob("*")
+        if path.is_file()
+    }
+    assert after_validation == before_validation
+
+    code.write_text("# spec: FEATURE-001\nvalue = 2\n", encoding="utf-8")
+    assert main(["validate", "--repo", str(tmp_path)]) == 1

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/tests/test_cli_installer.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import json
+
 import sys
 from pathlib import Path
 
@@ -35,6 +37,11 @@ def test_fresh_init_installs_complete_open_agent_package(tmp_path: Path) -> None
     assert (tmp_path / "spec/evolution/events.jsonl").read_text() == ""
     assert (tmp_path / "spec/evolution/timeline.md").is_file()
     assert (tmp_path / "spec/traceability.json").is_file()
+    traceability = json.loads(
+        (tmp_path / "spec/traceability.json").read_text(encoding="utf-8")
+    )
+    assert traceability["schema_version"] == 2
+    assert traceability["baseline_commit"] is None
 
 
 def test_init_is_idempotent_and_preserves_project_content(tmp_path: Path) -> None:

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/tests/test_skill_workflows.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import unittest
 from pathlib import Path
 
-# spec: SA-005, SA-006, SA-007, SA-008, SA-009, SA-010, SA-011, SA-012, SA-016, ELOG-006, PSH-002, PSH-003, PSH-004, PSH-005, PSH-006, PSH-007, PSH-008, PSH-009, PSH-010, PSH-011
+# spec: SA-005, SA-006, SA-007, SA-008, SA-009, SA-010, SA-011, SA-012, SA-016, SA-020, ELOG-006, PSH-002, PSH-003, PSH-004, PSH-005, PSH-006, PSH-007, PSH-008, PSH-009, PSH-010, PSH-011, TRACE-002, TRACE-003, TRACE-009, TRACE-010, TRACE-011
 
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -70,10 +70,18 @@ class SkillWorkflowTests(unittest.TestCase):
         self.assertNotIn("TDD", text)
         self.assertNotIn("debugging", text)
         self.assertIn(
-            "Spec complete. To implement this, give your Code Agent the following prompt: "
-            "'Read the specification at [SPEC_PATH] and generate an implementation plan.'",
+            "Spec complete. To implement this, give your Code Agent the following prompt:",
             text,
         )
+        for term in (
+            "acceptance.md",
+            "spec: BEHAVIOR-ID",
+            "production code and tests",
+            "spec-agent traceability-sync",
+            "spec-agent validate",
+            "reports CLEAN",
+        ):
+            self.assertIn(term, text)
         self.assertIn("spec-drift-sync", text)
         self.assertIn("spec-evolution", text)
 
@@ -144,6 +152,9 @@ class SkillWorkflowTests(unittest.TestCase):
         self.assertIn("Do not edit specifications, code, tests", text)
         self.assertNotIn("## Repair and validation", text)
         self.assertNotIn("Apply only the approved delta", text)
+        self.assertIn("linked-file fingerprints", text)
+        self.assertIn("Do not refresh", text)
+        self.assertIn("spec-agent validate", text)
 
     def test_evolution_flow_defines_product_boundaries_and_privacy(self) -> None:
         text = skill("spec-evolution")

{spec_agent_cli-0.1.0 → spec_agent_cli-0.2.0}/tests/test_spec_drift.py

@@ -7,6 +7,8 @@ import tempfile
 import unittest
 from pathlib import Path
 
+# spec: SA-021, SA-022, SA-023, TRACE-004, TRACE-005, TRACE-006, TRACE-007, TRACE-008, TRACE-009, TRACE-011
+
 
 PACKAGE_ROOT = Path(__file__).resolve().parents[1]
 SCRIPTS_DIR = (
@@ -37,12 +39,13 @@ class SpecDriftTests(unittest.TestCase):
             spec_drift.write_traceability(spec_drift.analyze_repo(root), output)
 
             data = json.loads(output.read_text(encoding="utf-8"))
-            self.assertEqual(data["schema_version"], 1)
+            self.assertEqual(data["schema_version"], 2)
             self.assertEqual(data["source"], "derived-from-code-backlinks")
-            self.assertEqual(
-                data["behaviors"]["FEATURE-X-001"],
-                [{"path": "service.py", "line": 1}],
-            )
+            link = data["behaviors"]["FEATURE-X-001"][0]
+            self.assertEqual(link["path"], "service.py")
+            self.assertEqual(link["line"], 1)
+            self.assertRegex(link["file_sha256"], r"^[0-9a-f]{64}$")
+            self.assertIn("baseline_commit", data)
             self.assertEqual(
                 spec_file.read_text(encoding="utf-8"),
                 "FEATURE-X-001: Users can complete Feature X.\n",
@@ -227,6 +230,101 @@ PROCESS-001: Specs describe current intended behavior.
             f"Expected no unlinked drift for not_applicable spec, got {report.issues!r}",
         )
 
+    def test_draft_spec_does_not_require_backlinks(self) -> None:
+        import check as spec_drift
+
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            spec = root / "SPEC.md"
+            spec.write_text(
+                """---
+status: draft
+---
+
+DRAFT-001: Product behavior is still being decided.
+""",
+                encoding="utf-8",
+            )
+
+            report = spec_drift.analyze_repo(root)
+
+        self.assertFalse(
+            any(issue.kind == "unlinked" for issue in report.issues),
+            report.issues,
+        )
+
+    def test_reports_unbaselined_backlink_until_traceability_is_synced(self) -> None:
+        import check as spec_drift
+
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "spec").mkdir()
+            (root / "SPEC.md").write_text(
+                "---\nstatus: approved\n---\n\nFEATURE-001: Feature works.\n",
+                encoding="utf-8",
+            )
+            (root / "service.py").write_text(
+                "# spec: FEATURE-001\nvalue = 1\n", encoding="utf-8"
+            )
+            traceability = root / "spec/traceability.json"
+            traceability.write_text(
+                '{"schema_version": 2, "source": "derived-from-code-backlinks", "baseline_commit": null, "behaviors": {}}\n',
+                encoding="utf-8",
+            )
+
+            report = spec_drift.analyze_repo(root)
+            self.assertIssue(report, "unbaselined", "FEATURE-001")
+
+            spec_drift.write_traceability(report, traceability)
+            clean = spec_drift.analyze_repo(root)
+
+        self.assertTrue(clean.clean, clean.issues)
+
+    def test_reports_linked_code_changed_since_traceability_baseline(self) -> None:
+        import check as spec_drift
+
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "spec").mkdir()
+            (root / "SPEC.md").write_text(
+                "---\nstatus: approved\n---\n\nFEATURE-001: Feature works.\n",
+                encoding="utf-8",
+            )
+            code = root / "service.py"
+            code.write_text("# spec: FEATURE-001\nvalue = 1\n", encoding="utf-8")
+            traceability = root / "spec/traceability.json"
+            initial = spec_drift.analyze_repo(root)
+            spec_drift.write_traceability(initial, traceability)
+
+            code.write_text("# spec: FEATURE-001\nvalue = 2\n", encoding="utf-8")
+            changed = spec_drift.analyze_repo(root)
+
+        self.assertIssue(changed, "code-changed", "FEATURE-001")
+
+    def test_reports_baseline_link_that_moved_or_disappeared(self) -> None:
+        import check as spec_drift
+
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / "spec").mkdir()
+            (root / "SPEC.md").write_text(
+                "---\nstatus: approved\n---\n\nFEATURE-001: Feature works.\n",
+                encoding="utf-8",
+            )
+            old = root / "old_service.py"
+            old.write_text("# spec: FEATURE-001\nvalue = 1\n", encoding="utf-8")
+            traceability = root / "spec/traceability.json"
+            spec_drift.write_traceability(spec_drift.analyze_repo(root), traceability)
+
+            old.unlink()
+            (root / "new_service.py").write_text(
+                "# spec: FEATURE-001\nvalue = 1\n", encoding="utf-8"
+            )
+            moved = spec_drift.analyze_repo(root)
+
+        self.assertIssue(moved, "stale-trace", "FEATURE-001")
+        self.assertIssue(moved, "unbaselined", "FEATURE-001")
+
     def test_default_spec_root_is_standalone_spec_directory(self) -> None:
         import check as spec_drift
 

spec_agent_cli-0.1.0/.agents/skills/spec-request-flow/SKILL.md

@@ -1,78 +0,0 @@
----
-name: spec-request-flow
-description: Use when a user asks to add, change, fix, refactor, design, or implement repository behavior under spec-driven development, including vague requests and follow-ups that modify an existing feature even when specifications are not mentioned.
----
-
-# Spec Request Flow
-
-Produce an approved, implementation-independent product specification, then stop with
-a discoverable Code Agent handoff.
-
-<HARD-GATE>
-Do not scaffold or write specification files before the user approves the presented
-product decisions. Do not create an implementation plan, choose repository files,
-write code or tests, dispatch implementation, or perform engineering verification at
-any point in this skill.
-</HARD-GATE>
-
-## Explore context
-
-1. Read applicable `AGENTS.md`, root `SPEC.md`, the existing feature packet, relevant
-   product behavior, and related `spec/evolution/events.jsonl` entries.
-2. Separate evidence, outcomes, conflicts, assumptions, and unknowns.
-3. If the request contains independent subsystems, propose decomposition and process
-   one independently valuable feature at a time.
-
-## Clarify product behavior
-
-1. Ask one blocking question at a time. Do not ask what repository evidence answers.
-2. For each material product decision, present 2-3 approaches, trade-offs, and a
-   recommendation. Keep choices about observable behavior, not technical solutions.
-3. Cover actors, rules, conceptual data, primary and alternate flows, failures,
-   recovery, states, edges, permissions, privacy, defaults, constraints, non-goals,
-   and measurable outcomes.
-4. Label every unresolved item `blocking` or `non-blocking`. Never turn an assumption
-   into an accepted requirement.
-
-## Requirements-completeness gate
-
-Verify every category above before presenting the product decision. Continue while any
-blocking item remains. Defer one only when the user approves a stated default.
-
-## Product-decision approval gate
-
-Present the proposed product behavior and ask the user to approve or revise it. Do not
-scaffold or write either specification file while approval is absent or ambiguous.
-
-## Write and self-review the specification
-
-1. Reuse `spec/features/<feature-slug>/` when present; otherwise run
-   `scripts/create_feature.py <feature-slug> --title "Feature Title"`.
-2. Read [references/spec-format.md](references/spec-format.md). Write both `spec.md`
-   and `acceptance.md`; add both paths to root `SPEC.md`.
-3. Keep both files strictly product-facing. Do not include code paths, symbols,
-   frameworks, storage choices, ordered engineering steps, test files, commands,
-   deployment instructions, or code backlinks.
-4. Run the complete self-review on both files and fix every finding.
-
-## Written-spec approval gate
-
-Show both paths and summarize their delta. Ask for explicit written-spec approval. If
-revised, update both files, rerun self-review, and ask again.
-
-## Completion and Code Agent handoff
-
-After approval, mark both files `approved`, use `spec-evolution` to record the approved
-product decision, and stop. `spec-drift-sync` is used later as a read-only observer;
-it is not implementation work for this skill.
-
-Output exactly the following, replacing `[SPEC_PATH]` with the actual `spec.md` path:
-
-Spec complete. To implement this, give your Code Agent the following prompt: 'Read the specification at [SPEC_PATH] and generate an implementation plan.'
-
-Do not append planning advice, implementation steps, or an offer to write code.
-
-## Later changes
-
-A later prompt updates the same two-file packet and preserves stable behavior IDs.
-Return to clarification and both approval gates for every normative product change.

spec_agent_cli-0.1.0/tests/test_cli.py

@@ -1,23 +0,0 @@
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-# spec: CLI-001, CLI-007
-
-
-ROOT = Path(__file__).resolve().parents[1]
-sys.path.insert(0, str(ROOT / "src"))
-
-from spec_agent.cli import main
-
-
-def test_cli_version(capsys) -> None:
-    assert main(["--version"]) == 0
-    assert capsys.readouterr().out.startswith("spec-agent ")
-
-
-def test_cli_init_and_check(tmp_path: Path) -> None:
-    assert main(["init", "--repo", str(tmp_path)]) == 0
-    assert main(["init", "--repo", str(tmp_path), "--check"]) == 0
-    assert (tmp_path / ".agents/skills/spec-request-flow/SKILL.md").is_file()