speckit-specops 0.1.0__py3-none-any.whl

speckit_specops-0.1.0.dist-info/METADATA

@@ -0,0 +1,233 @@
+Metadata-Version: 2.4
+Name: speckit-specops
+Version: 0.1.0
+Summary: A Spec-Driven Development (SDD) process enforcement CLI extending Speckit
+Author-email: Paulo Segundo <paulosegundo@gmail.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: gitpython>=3.1.40
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.9.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SpecOps CLI
+
+[![CI](https://github.com/paulo2nd/specops/actions/workflows/ci.yml/badge.svg)](https://github.com/paulo2nd/specops/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/speckit-specops.svg)](https://pypi.org/project/speckit-specops/)
+[![Python](https://img.shields.io/pypi/pyversions/speckit-specops.svg)](https://pypi.org/project/speckit-specops/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**SpecOps turns [GitHub Speckit](https://github.com/vgrecov/speckit)'s
+spec-driven workflow into an enforced, auditable process.** It layers an
+agent-guided *atomic development* methodology on top of any Speckit repository —
+a physical state ledger, machine-collected evidence, and token-optimized review —
+**without replacing or forking a single Speckit file.**
+
+> Speckit gives your agents great artifacts (spec → plan → tasks → implement).
+> SpecOps makes sure they actually follow them: state is on disk and
+> Git-verifiable, evidence is collected by tooling instead of claimed by the
+> agent, and review rejects as cheaply as possible.
+
+## Why SpecOps?
+
+Spec-driven development with AI agents has three recurring failure modes.
+SpecOps addresses each one:
+
+| Problem | Without SpecOps | With SpecOps |
+|---|---|---|
+| **Agents hallucinate progress** | "Done ✅" with no proof | Every task is closed with machine-collected evidence (test output, commit hashes, diffs) recorded in the ledger |
+| **State lives in the chat** | Lost on context reset; not auditable | State is a physical `status.yaml` ledger, Git-verifiable and recovery-safe |
+| **Reviews are slow and expensive** | Agent reads the whole repo | `/specops-review` rejects cheapest-first (reconcile → lint/test → out-of-plan files) before reading any code |
+
+## What it adds to Speckit
+
+- **📒 Physical state ledger (Repo-as-State).** A structured `status.yaml`
+  tracks phase, tasks, evidence, and review cycles. Mutated only through
+  `specops` commands — never hand-edited, never held in agent memory.
+- **🔬 Automated evidence collection.** `complete-task --auto` runs your test
+  command, harvests commits and diffs, and records them as typed evidence. A
+  task cannot be `DONE` without proof.
+- **🔁 A phase state machine wired into the prompts.** `specops init` injects
+  directives into the specify, plan, tasks, and implement prompts so the ledger
+  is created and phases advance automatically — the human never runs the
+  bookkeeping by hand.
+- **✂️ Token-optimized surgical review.** The installed `/specops-review`
+  command reviews only in-scope files and stops at the first cheap rejection.
+- **📐 Empirical verification & gates.** `specops consistency` and
+  `specops reconcile` are exit-code gates you can drop into CI or agent prompts.
+- **➕ Additive and reversible.** Everything is delivered through
+  marker-delimited blocks. Uninstalling restores your Speckit files
+  byte-for-byte.
+
+## Install
+
+```bash
+pip install speckit-specops
+```
+
+Installs the `specops` command. Requires Python ≥ 3.10 and Git ≥ 2.30. No
+network I/O after install.
+
+## Quick Start
+
+```bash
+# In a Speckit-initialized repository:
+specops init          # inject directives, install /specops-review, create specops.json
+```
+
+That's it. From here you drive Speckit as usual (`/speckit.specify`,
+`/speckit.plan`, `/speckit.tasks`, `/speckit.implement`) and the injected
+directives take care of the ledger and phase transitions. Check state anytime:
+
+```bash
+specops status show
+```
+
+## How it works
+
+SpecOps rides the Speckit lifecycle. Once `specops init` has run, the injected
+directives drive the ledger at each stage seam:
+
+| Speckit stage | What SpecOps does |
+|---|---|
+| **specify** | Marks the repo as SpecOps-managed (informational; no ledger yet) |
+| **plan** | Enforces empirical path verification and the `consistency` gate |
+| **tasks** | Creates the ledger (`status init-spec`), advances the phase to `TASKS`, and requires `[SC-xxx]` coverage tags on every task |
+| **implement** | Opens `IMPLEMENT`, runs the evidence-backed ledger loop, then opens `REVIEW` |
+| **review** | `/specops-review` validates the diff and records `APPROVED` / `REJECTED` |
+
+The phase machine is `SPECIFY → PLAN → TASKS → IMPLEMENT → REVIEW → DONE`.
+If SpecOps is not installed, the Speckit prompts still work standalone — the
+directives degrade to no-ops.
+
+## Command reference
+
+### `specops init [--non-interactive]`
+
+Prepares a Speckit repository in one run: validates (or offers to create) a Git
+repo, detects Speckit, resolves prompt targets from Speckit's integration
+manifests (works with any recorded agent layout — Claude skills, GitHub
+Copilot, etc.), creates/merge-preserves `specops.json`, installs
+`/specops-review`, and injects the directive blocks into the specify, plan,
+tasks, and implement prompts (additive, idempotent, byte-identical restore on
+removal). `--non-interactive` declines all prompts (CI-safe).
+
+> **Speckit upgrade note**: a Speckit upgrade may rewrite prompt files and
+> remove the injected blocks. Just re-run `specops init` to re-inject.
+
+### `specops status show`
+
+Read-only. Prints ledger state: feature, branch, phase, active task, task counts
+(pending / in progress / done / orphaned), and the review-cycle history.
+
+### `specops status init-spec [<name>]`
+
+Creates `<feature_dir>/status.yaml` from the packaged scaffold, syncing task IDs
+from `tasks.md`. Usually run for you by the tasks directive.
+
+### `specops status start-task <task-id>`
+
+Marks the task `IN_PROGRESS` and records `started_commit = HEAD`. Enforces the
+single-active-task rule.
+
+### `specops status complete-task <task-id> [--auto | --evidence "CLASS:summary"]`
+
+Marks the task `DONE` with exactly one evidence source:
+
+- `--auto`: runs `test_command`; on success, harvests `started_commit..HEAD`
+  commits + diff as `TEST_REPORT`/`CODE_DIFF` evidence.
+- `--evidence "CLASS:summary"`: caller-supplied, with `CLASS` in
+  `CLI_LOG | TEST_REPORT | SCREENSHOT_PATH | CODE_DIFF`.
+
+### `specops status transition-phase <phase> [-r APPROVED|REJECTED]`
+
+Advances the phase one step forward. Two transitions require `-r`:
+
+```bash
+specops status transition-phase DONE -r APPROVED      # approved → close the feature
+specops status transition-phase IMPLEMENT -r REJECTED # rejected → send back for rework
+```
+
+Entering `DONE` requires the latest review cycle to be `APPROVED`.
+
+### `specops reconcile`
+
+Read-only gate. Verifies every ledger commit hash is reachable from `HEAD` and
+every `DONE` task has commits and evidence. Exit 1 on any divergence.
+
+```bash
+specops reconcile || exit 1   # preflight before review
+```
+
+### `specops consistency`
+
+Read-only gate. Verifies every `SC-\d+` in the spec has ≥ 1 task with a matching
+`[SC-xxx]` tag, and every `plan.md` path declaration carries a valid action
+suffix (`(create)`/`(modify)`/`(remove)`). Exit 1 on violation.
+
+### `specops --version`
+
+Prints the version and exits. Works anywhere.
+
+## Configuration — `specops.json`
+
+| Key | Purpose | Default |
+|---|---|---|
+| `test_command` | Command run by `complete-task --auto` | `pytest` |
+| `lint_command` | Command referenced by the review prompt | `""` |
+| `skills_dir` | Directory the review prompt loads skills from | `.specify/skills` |
+
+Unknown keys are preserved on re-init.
+
+## The `/specops-review` command
+
+Installed by `specops init` (the name follows the layout's separator, e.g.
+`/specops-review` for Claude skills). Not a CLI command — a packaged prompt that
+drives the review agent cheapest-rejection-first:
+
+1. Load skills from `skills_dir`.
+2. `specops reconcile` — abort immediately on failure.
+3. `lint_command` + `test_command` — reject on failure.
+4. `git status --porcelain` — reject any out-of-plan file without reading code.
+5. Surgical diff review of in-scope files only.
+6. Write `revisions/revision-X.md` and record the `APPROVED`/`REJECTED` outcome.
+
+## Language policy
+
+All SpecOps operational output (CLI messages, injected assets) is in English.
+Your prose (`spec.md`, `plan.md`, task descriptions) may be in **any language** —
+SpecOps parses only structural tokens (`SC-\d+`, `T\d+`, action suffixes), never
+content.
+
+## Supported Speckit layouts
+
+SpecOps resolves prompt targets at runtime from
+`.specify/integrations/<agent>.manifest.json`. Any Speckit integration with a
+recorded manifest is supported; unknown layouts fail closed. Tested with
+Speckit ≥ 0.12 (Claude skills mode, separator `-`).
+
+## Uninstall
+
+Remove the appended block from each prompt file, then delete `specops.json` and
+the installed review command. No other files are written; the restore is
+byte-identical.
+
+## Contributing
+
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup,
+the quality gates, and project principles. SpecOps is at `0.x`; the CLI surface
+and ledger format may still change before `1.0` (see [CHANGELOG.md](CHANGELOG.md)).
+
+## License
+
+[MIT](LICENSE) © Paulo Segundo

speckit_specops-0.1.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+specops/__init__.py,sha256=norFtsf5zFQJHWTkdIYOBGlM-Bgb0wTngCzE0iehTtQ,171
+specops/cli.py,sha256=aUnZa0LeApQuaBnFWsbSQQtwAayY2dgldQ1Q_Jwo9AQ,5888
+specops/config.py,sha256=CZ1hvmEi2dkkFSVk5tiNAeh671dN-RSRF-KB983_mbU,2274
+specops/consistency.py,sha256=91UDnkyUFAkkSjXC9BEblaaJz0DaKKXY2mdFelQFnAc,4411
+specops/errors.py,sha256=GaqWtIE-Yk7R3xTU4wRve2h6sRxbfAhM8eoGtO0Khn8,483
+specops/gitops.py,sha256=Q_jfT5UcdlztWBjP37gB90-0011E4a__Oaw9d4otXoM,2071
+specops/initializer.py,sha256=HqJ_ft3nYKNqoT-paY-lGM5eNzSKvwvqI5KdGuENO9s,10059
+specops/reconcile.py,sha256=aCXkfGfOpKPr36gxwtxeGC8s3UKh3PW_dQiEiLTSdwk,2613
+specops/speckit.py,sha256=jSd1P1IjJP9nKLiYUm3g295czdn8Tsx-hFdgspj6WY8,9886
+specops/status.py,sha256=0h7Cbws7gY7kz2F5W8bgyFZ2Kgn873JJKASXnhLRq9Q,16867
+specops/templates/review.md,sha256=F3pY1Wb-Ml25kywafsCGBXH_wgOvbpDfAU0amg3eK-k,2405
+specops/templates/specops.json,sha256=_BKhOLVrVTMai54YiOVMT7N7AEtBZQdb5hlNrgU2ltI,88
+specops/templates/status.yaml,sha256=map7cZsJdkkPlQnaQsd3P9Gvxt3_JYj8kcTgA0GgbMA,257
+specops/templates/directives/implement.md,sha256=5PfidS8HK9GfbZvbcnJk4lF5mfhS5P-YYh034jes6wE,2416
+specops/templates/directives/plan.md,sha256=Ph-RTKYYaZu-v3MOBbp2Es_uIzYsweNl8Bsh3Xkk8n0,1518
+specops/templates/directives/specify.md,sha256=TLaTmdUf_J02wnTMKPOrAlauHClaKe84kR0qJtP65lU,646
+specops/templates/directives/tasks.md,sha256=Hi4yeZS6tYC2S0yg0V3UpT6o-T9qTa5X-M5zVbs0yPo,1251
+speckit_specops-0.1.0.dist-info/METADATA,sha256=9AznotYcZXfDd-iBxTRcRH3_27z5RCAl24C3iuAgW8k,9775
+speckit_specops-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+speckit_specops-0.1.0.dist-info/entry_points.txt,sha256=1jtzdTyyNwLisxJ8zCBh6wIZMLAoRsOyYQ-hfjh-NfE,44
+speckit_specops-0.1.0.dist-info/licenses/LICENSE,sha256=BBBg5rGxqq0hAymn1JhjBzJyutAL83eM8bC8eetuOWQ,1070
+speckit_specops-0.1.0.dist-info/RECORD,,

speckit_specops-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

speckit_specops-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+specops = specops.cli:app

speckit_specops-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paulo Segundo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

specops/__init__.py

@@ -0,0 +1,6 @@
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("specops-cli")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

specops/cli.py

@@ -0,0 +1,200 @@
+"""SpecOps CLI entrypoint (Typer). All output is in English (FR-014)."""
+from __future__ import annotations
+
+import functools
+import importlib.metadata
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, TypeVar
+
+import typer
+
+from specops import gitops
+from specops.errors import SpecopsError
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        try:
+            version = importlib.metadata.version("specops-cli")
+        except importlib.metadata.PackageNotFoundError:
+            version = "0.0.0.dev0"
+        typer.echo(f"specops {version}")
+        raise typer.Exit(0)
+
+
+app = typer.Typer(
+    name="specops",
+    help="SpecOps CLI — Speckit companion for agent-guided atomic development.",
+    no_args_is_help=True,
+)
+
+
+@app.callback()
+def _root_callback(
+    version: bool | None = typer.Option(
+        None,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Show the version and exit.",
+    ),
+) -> None:
+    pass
+
+status_app = typer.Typer(
+    name="status",
+    help="Ledger management: init-spec, start-task, complete-task, transition-phase.",
+    no_args_is_help=True,
+)
+app.add_typer(status_app, name="status")
+
+# ---------------------------------------------------------------------------
+# Error boundary: single exit-code mapper (contracts/errors.md)
+# ---------------------------------------------------------------------------
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def _handle_errors(fn: _F) -> _F:
+    """Catch SpecopsError, echo message to stderr, exit with the mapped code."""
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except SpecopsError as exc:
+            typer.echo(exc.message, err=True)
+            raise typer.Exit(exc.exit_code) from None
+    return wrapper  # type: ignore[return-value]
+
+
+def _require_git(root: Path = Path(".")) -> None:
+    """Fail with exit 1 within <1 s when not inside a Git repo (FR-002, SC-008)."""
+    if not gitops.is_git_repo(root):
+        typer.echo("Not a Git repository. Run 'git init' or 'specops init' first.", err=True)
+        raise typer.Exit(1)
+
+
+# ---------------------------------------------------------------------------
+# Commands
+# ---------------------------------------------------------------------------
+
+@app.command("init")
+@_handle_errors
+def init(
+    non_interactive: bool = typer.Option(
+        False, "--non-interactive", help="Decline all interactive prompts.",
+    ),
+) -> None:
+    """Prepare a Speckit repository for SpecOps."""
+    from specops import initializer
+    root = Path(".")
+    initializer.run(root, non_interactive=non_interactive)
+
+
+@app.command("reconcile")
+@_handle_errors
+def reconcile() -> None:
+    """Validate ledger commit hashes against Git history."""
+    root = Path(".")
+    _require_git(root)
+    from specops import reconcile as rec_mod
+    warnings, violations = rec_mod.run(root)
+    for w in warnings:
+        typer.echo(w)
+    if violations:
+        for v in violations:
+            typer.echo(v, err=True)
+        raise typer.Exit(1)
+    typer.echo("reconcile: ok")
+
+
+@app.command("consistency")
+@_handle_errors
+def consistency() -> None:
+    """Validate SC-ID coverage and plan path-suffix declarations."""
+    root = Path(".")
+    _require_git(root)
+    from specops import consistency as con_mod
+    warnings, violations = con_mod.run(root)
+    for w in warnings:
+        typer.echo(w)
+    if violations:
+        for v in violations:
+            typer.echo(v, err=True)
+        raise typer.Exit(1)
+    typer.echo("consistency: ok")
+
+
+# ---------------------------------------------------------------------------
+# status subcommands
+# ---------------------------------------------------------------------------
+
+@status_app.command("init-spec")
+@_handle_errors
+def status_init_spec(
+    name: str = typer.Argument(None, help="Feature directory name (optional)."),
+) -> None:
+    """Create status.yaml for the active feature."""
+    root = Path(".")
+    _require_git(root)
+    from specops import status
+    typer.echo(status.cmd_init_spec(root, name))
+
+
+@status_app.command("start-task")
+@_handle_errors
+def status_start_task(
+    task_id: str = typer.Argument(..., help="Task identifier, e.g. T001."),
+) -> None:
+    """Mark a task IN_PROGRESS and record the start commit."""
+    root = Path(".")
+    _require_git(root)
+    from specops import status
+    typer.echo(status.cmd_start_task(root, task_id))
+
+
+@status_app.command("complete-task")
+@_handle_errors
+def status_complete_task(
+    task_id: str = typer.Argument(..., help="Task identifier, e.g. T001."),
+    auto: bool = typer.Option(
+        False, "--auto", help="Run test_command and harvest evidence automatically."
+    ),
+    evidence: str = typer.Option(
+        None, "--evidence", help='Caller-supplied evidence string, e.g. "CLI_LOG:checked ok".'
+    ),
+) -> None:
+    """Mark a task DONE with evidence."""
+    root = Path(".")
+    _require_git(root)
+    from specops import status
+    typer.echo(status.cmd_complete_task(root, task_id, auto=auto, evidence=evidence))
+
+
+@status_app.command("show")
+@_handle_errors
+def status_show() -> None:
+    """Show ledger state (read-only)."""
+    root = Path(".")
+    from specops import status
+    typer.echo(status.cmd_show(root))
+
+
+@status_app.command("transition-phase")
+@_handle_errors
+def status_transition_phase(
+    phase: str = typer.Argument(..., help="Target phase, e.g. PLAN."),
+    result: str = typer.Option(
+        None, "-r", "--result", help="Transition result (APPROVED|REJECTED)."
+    ),
+) -> None:
+    """Advance the feature phase state machine."""
+    root = Path(".")
+    _require_git(root)
+    from specops import status
+    typer.echo(status.cmd_transition_phase(root, phase, result=result))
+
+
+if __name__ == "__main__":
+    app()

specops/config.py

@@ -0,0 +1,77 @@
+"""specops.json load/validate/merge helpers (R10)."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from specops.errors import SpecopsError
+
+CONFIG_FILENAME = "specops.json"
+
+_DEFAULTS: dict[str, Any] = {
+    "test_command": "pytest",
+    "lint_command": "",
+    "skills_dir": ".specify/skills",
+}
+
+
+class ConfigError(SpecopsError):
+    """Raised on missing or unreadable specops.json."""
+
+
+def config_path(root: Path) -> Path:
+    return root / CONFIG_FILENAME
+
+
+def load(root: Path) -> dict[str, Any]:
+    """
+    Load specops.json from *root*.
+
+    Raises ConfigError when the file is absent or not valid JSON.
+    Unknown keys are preserved (R10).
+    """
+    path = config_path(root)
+    if not path.is_file():
+        raise ConfigError(
+            f"{CONFIG_FILENAME} not found in {root}. Run 'specops init' first."
+        )
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"Cannot parse {path}: {exc}") from exc
+
+
+def merge_preserve(existing: dict[str, Any], template: dict[str, Any]) -> dict[str, Any]:
+    """
+    Merge *template* into *existing*, keeping existing values and unknown keys.
+
+    New keys from *template* that are absent in *existing* are added with
+    their template values. Existing keys (including unknown ones) are untouched.
+    """
+    result = dict(existing)
+    for key, value in template.items():
+        if key not in result:
+            result[key] = value
+    return result
+
+
+def create_or_merge(root: Path) -> tuple[dict[str, Any], bool]:
+    """
+    Create specops.json from defaults, or merge-preserve an existing one.
+
+    Returns (config_dict, created) where *created* is True when the file
+    was newly created, False when an existing file was updated.
+    """
+    path = config_path(root)
+    if path.is_file():
+        try:
+            existing = json.loads(path.read_text())
+        except (json.JSONDecodeError, OSError):
+            existing = {}
+        merged = merge_preserve(existing, _DEFAULTS)
+        path.write_text(json.dumps(merged, indent=2) + "\n")
+        return merged, False
+    else:
+        path.write_text(json.dumps(_DEFAULTS, indent=2) + "\n")
+        return dict(_DEFAULTS), True

specops/consistency.py

@@ -0,0 +1,112 @@
+"""specops consistency: SC-ID coverage + plan path-suffix validation (US4, FR-012)."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from specops import gitops, speckit
+from specops.errors import SpecopsError
+
+
+def run(root: Path) -> tuple[list[str], list[str]]:
+    """
+    Validate SC-ID coverage traceability and plan path-suffix declarations.
+
+    Returns (warnings, violations). Violations map to exit 1.
+    Raises SpecopsError on blocking preconditions.
+    """
+    feature_dir = speckit.resolve_feature_dir(root)
+    if feature_dir is None:
+        raise SpecopsError("Cannot resolve active feature directory.")
+
+    spec_path = feature_dir / "spec.md"
+    tasks_path = feature_dir / "tasks.md"
+    plan_path = feature_dir / "plan.md"
+
+    violations: list[str] = []
+    warnings: list[str] = []
+
+    # ------------------------------------------------------------------
+    # SC-ID coverage check (R6, FR-012)
+    # ------------------------------------------------------------------
+    if spec_path.is_file() and tasks_path.is_file():
+        spec_text = spec_path.read_text(encoding="utf-8")
+        tasks_text = tasks_path.read_text(encoding="utf-8")
+
+        spec_scs = set(speckit.extract_sc_ids(spec_text))
+        spec_lines = spec_text.splitlines()
+
+        def _sc_line(sc_id: str) -> int:
+            for i, line in enumerate(spec_lines, start=1):
+                if f"**{sc_id}**:" in line:
+                    return i
+            return 0
+
+        covered: dict[str, list[str]] = {sc: [] for sc in spec_scs}
+        unknown_refs: list[tuple[str, int, str]] = []
+
+        for lineno, line in enumerate(tasks_text.splitlines(), start=1):
+            tags = speckit.extract_coverage_tags(line)
+            task_ids = speckit.extract_task_ids(line)
+            task_id = task_ids[0] if task_ids else "?"
+            for tag in tags:
+                if tag in spec_scs:
+                    covered[tag].append(task_id)
+                else:
+                    unknown_refs.append((str(tasks_path), lineno, tag))
+
+        for sc, covering_tasks in covered.items():
+            if not covering_tasks:
+                line_num = _sc_line(sc)
+                violations.append(
+                    f"consistency: {spec_path.name}:{line_num} - SC '{sc}' has no covering task"
+                )
+
+        for _file, lineno, tag in unknown_refs:
+            violations.append(
+                f"consistency: {tasks_path.name}:{lineno}"
+                f" - coverage tag '{tag}' references unknown SC"
+            )
+
+    # ------------------------------------------------------------------
+    # Path-suffix validation (FR-012)
+    # ------------------------------------------------------------------
+    if plan_path.is_file():
+        plan_text = plan_path.read_text(encoding="utf-8")
+        repo = gitops.find_repo(root)
+
+        for lineno, line in enumerate(plan_text.splitlines(), start=1):
+            parsed = speckit.parse_plan_path_action(line)
+            if not parsed:
+                continue
+
+            raw_path, action = parsed
+            candidate = root / raw_path if not raw_path.startswith("/") else Path(raw_path)
+
+            if action == "modify":
+                if not candidate.is_file():
+                    violations.append(
+                        f"consistency: {plan_path.name}:{lineno} - "
+                        f"(modify) path '{raw_path}' does not exist in worktree"
+                    )
+            elif action == "create":
+                if not candidate.parent.is_dir():
+                    violations.append(
+                        f"consistency: {plan_path.name}:{lineno} - "
+                        f"(create) parent of '{raw_path}' does not exist"
+                    )
+            elif action == "remove":
+                in_worktree = candidate.exists()
+                in_history = False
+                if repo is not None:
+                    try:
+                        repo.git.ls_files("--error-unmatch", raw_path)
+                        in_history = True
+                    except Exception:
+                        pass
+                if not in_worktree and not in_history:
+                    violations.append(
+                        f"consistency: {plan_path.name}:{lineno} - "
+                        f"(remove) path '{raw_path}' not in worktree or Git history"
+                    )
+
+    return warnings, violations