feat(spec): steering scan/scaffold API and tasks CLI

Expose scan_steering_files and scaffold_steering_files for .cecli/STEERING.md
and .cecli/steering/*.md so BrightVision and bright-vision-tasks can list and
create project steering without duplicating logic in the HTTP layer.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: agentpike

cecli/spec/steering.py

@@ -3,8 +3,30 @@
 
 from __future__ import annotations
 
+from dataclasses import dataclass
 from pathlib import Path
 
+STEERING_MAIN_RELPATH = ".cecli/STEERING.md"
+STEERING_FRAGMENTS_DIR_RELPATH = ".cecli/steering"
+
+DEFAULT_STEERING_TEMPLATE = """\
+# Project steering
+
+Rules the spec agent and implementation turns should follow across **all** tasks in this repo.
+
+## Stack & conventions
+
+- Language / framework:
+- Test command:
+- Avoid:
+
+## Spec discipline
+
+- EARS: ### REQ-NNN with **WHEN** … **THE** system **SHALL** …
+- Keep design and tasks_md aligned with every REQ id.
+- Do not mark implementation done until requirements pass EARS lint.
+"""
+
 SPEC_FOCUS_INSTRUCTIONS = """\
 ## Spec-focus mode (BrightVision)
 
@@ -42,6 +64,76 @@ def workspace_lib_missing(workspace: str | Path) -> bool:
 """
 
 
+@dataclass(frozen=True)
+class SteeringFileRecord:
+    relpath: str
+    size_bytes: int
+    nonempty: bool
+
+
+@dataclass(frozen=True)
+class SteeringFilesSnapshot:
+    main: SteeringFileRecord | None
+    fragments: tuple[SteeringFileRecord, ...]
+
+    @property
+    def has_content(self) -> bool:
+        if self.main and self.main.nonempty:
+            return True
+        return any(fragment.nonempty for fragment in self.fragments)
+
+    @property
+    def file_count(self) -> int:
+        count = 0
+        if self.main and self.main.nonempty:
+            count += 1
+        count += sum(1 for fragment in self.fragments if fragment.nonempty)
+        return count
+
+
+def _steering_file_record(root: Path, relpath: str) -> SteeringFileRecord | None:
+    path = root / relpath
+    if not path.is_file():
+        return None
+    try:
+        size_bytes = path.stat().st_size
+        text = path.read_text(encoding="utf-8").strip()
+    except OSError:
+        return None
+    return SteeringFileRecord(
+        relpath=relpath.replace("\\", "/"),
+        size_bytes=size_bytes,
+        nonempty=bool(text),
+    )
+
+
+def scan_steering_files(workspace: str | Path) -> SteeringFilesSnapshot:
+    """List ``.cecli/STEERING.md`` and ``.cecli/steering/*.md`` with sizes."""
+    root = Path(workspace).resolve()
+    main = _steering_file_record(root, STEERING_MAIN_RELPATH)
+    fragments: list[SteeringFileRecord] = []
+    frag_dir = root / ".cecli" / "steering"
+    if frag_dir.is_dir():
+        for path in sorted(frag_dir.glob("*.md")):
+            rel = str(path.relative_to(root)).replace("\\", "/")
+            record = _steering_file_record(root, rel)
+            if record is not None:
+                fragments.append(record)
+    return SteeringFilesSnapshot(main=main, fragments=tuple(fragments))
+
+
+def scaffold_steering_files(workspace: str | Path) -> list[str]:
+    """Create ``.cecli/STEERING.md`` from template when missing. Returns new relpaths."""
+    root = Path(workspace).resolve()
+    created: list[str] = []
+    main_path = root / ".cecli" / "STEERING.md"
+    if not main_path.is_file():
+        main_path.parent.mkdir(parents=True, exist_ok=True)
+        main_path.write_text(DEFAULT_STEERING_TEMPLATE, encoding="utf-8")
+        created.append(STEERING_MAIN_RELPATH)
+    return created
+
+
 def load_steering_markdown(workspace: str | Path) -> str:
     """Load ``.cecli/STEERING.md`` and ``.cecli/steering/*.md`` if present."""
     root = Path(workspace).resolve()

cecli/spec/tasks_cli.py

@@ -15,6 +15,7 @@
     next_open_implementation_step,
 )
 from cecli.spec.pubspec_repair import repair_pubspec_dependencies
+from cecli.spec.steering import scaffold_steering_files, scan_steering_files
 from cecli.spec.todos import WorkspaceTodos
 
 
@@ -87,6 +88,33 @@ def cmd_sync_agent(workspace: Path) -> int:
     return 0
 
 
+def _steering_payload(snapshot) -> dict:
+    return {
+        "has_content": snapshot.has_content,
+        "file_count": snapshot.file_count,
+        "main": asdict(snapshot.main) if snapshot.main else None,
+        "fragments": [asdict(fragment) for fragment in snapshot.fragments],
+    }
+
+
+def cmd_steering_scan(workspace: Path) -> int:
+    snapshot = scan_steering_files(workspace)
+    print(json.dumps(_steering_payload(snapshot), indent=2))
+    return 0
+
+
+def cmd_steering_scaffold(workspace: Path) -> int:
+    created = scaffold_steering_files(workspace)
+    snapshot = scan_steering_files(workspace)
+    print(
+        json.dumps(
+            {"created": created, **_steering_payload(snapshot)},
+            indent=2,
+        )
+    )
+    return 0
+
+
 def cmd_repair_pubspec(workspace: Path, *, apply: bool) -> int:
     result = repair_pubspec_dependencies(workspace, apply=apply)
     print(
@@ -129,6 +157,11 @@ def build_parser() -> argparse.ArgumentParser:
         "--apply", action="store_true", help="Run flutter pub add or edit pubspec.yaml"
     )
 
+    p_steer = sub.add_parser("steering", help="Project steering files (.cecli/STEERING.md)")
+    steer_sub = p_steer.add_subparsers(dest="steering_cmd", required=True)
+    steer_sub.add_parser("scan", help="List steering markdown files as JSON")
+    steer_sub.add_parser("scaffold", help="Create STEERING.md template when missing")
+
     return parser
 
 
@@ -148,6 +181,12 @@ def main(argv: list[str] | None = None) -> int:
         return cmd_sync_agent(workspace)
     if args.command == "repair-pubspec":
         return cmd_repair_pubspec(workspace, apply=args.apply)
+    if args.command == "steering":
+        if args.steering_cmd == "scan":
+            return cmd_steering_scan(workspace)
+        if args.steering_cmd == "scaffold":
+            return cmd_steering_scaffold(workspace)
+        parser.error(f"unknown steering command: {args.steering_cmd}")
     parser.error(f"unknown command: {args.command}")
     return 2
 

tests/spec/test_spec_steering.py

@@ -6,7 +6,13 @@
 import unittest
 from pathlib import Path
 
-from cecli.spec.steering import build_spec_focus_preamble, load_steering_markdown
+from cecli.spec.steering import (
+    STEERING_MAIN_RELPATH,
+    build_spec_focus_preamble,
+    load_steering_markdown,
+    scaffold_steering_files,
+    scan_steering_files,
+)
 
 
 class TestSpecSteering(unittest.TestCase):
@@ -29,6 +35,32 @@ def test_preamble_includes_spec_focus(self):
             pre = build_spec_focus_preamble(tmp)
             self.assertIn("Spec-focus mode", pre)
 
+    def test_scan_steering_files(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            (root / ".cecli").mkdir()
+            (root / ".cecli" / "STEERING.md").write_text("Rules here.", encoding="utf-8")
+            steering = root / ".cecli" / "steering"
+            steering.mkdir()
+            (steering / "security.md").write_text("", encoding="utf-8")
+            (steering / "style.md").write_text("Tabs not spaces.", encoding="utf-8")
+            snapshot = scan_steering_files(root)
+            self.assertTrue(snapshot.has_content)
+            self.assertEqual(snapshot.file_count, 2)
+            self.assertIsNotNone(snapshot.main)
+            self.assertTrue(snapshot.main.nonempty)
+            self.assertEqual(len(snapshot.fragments), 2)
+            self.assertFalse(snapshot.fragments[0].nonempty)
+
+    def test_scaffold_steering_creates_main_once(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            root = Path(tmp)
+            created = scaffold_steering_files(root)
+            self.assertEqual(created, [STEERING_MAIN_RELPATH])
+            self.assertTrue((root / ".cecli" / "STEERING.md").is_file())
+            again = scaffold_steering_files(root)
+            self.assertEqual(again, [])
+
 
 if __name__ == "__main__":
     unittest.main()