fix: resolve 5 open GitHub issues (#196 #197 #198 #199 #200)

#200 chronomemory import crash: wrap import in try/except in esdb/__init__.py;
stub all exports; save_cmd treats ImportError as non-fatal warning.

#196 type_override ignored: add type_override field to ProjectConfig; skip
type-mismatch check when type_override==type or type is unknown custom string.

#199 sync empty descriptions: _DIRECT_HEADING captures optional title group;
parse_requirements_md collects plain paragraph lines as description.

#198 req add wrong format: add_req now emits H2 heading with title and plain
paragraph description; CLI passes --title in legacy mode.

#197 preflight wrong path: read docs/REQUIREMENTS.md not root/REQUIREMENTS.md;
broker.parse_requirements rewritten to handle Style A (REQ-NNN: Title) format.

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

src/specsmith/agent/broker.py

@@ -144,6 +144,11 @@ def classify_intent(utterance: str) -> Intent:
 # Extended to match project-prefixed IDs e.g. REQ-NN-001, REQ-CLI-042
 _REQ_ID = re.compile(r"-\s*\*\*ID:\*\*\s*(REQ-(?:[A-Z][A-Z0-9_]*-)?\d+)")
 _REQ_DESC = re.compile(r"-\s*\*\*Description:\*\*\s*(.+)")
+# Style A heading: ## REQ-001  or  ## REQ-CLI-001: Title
+_STYLE_A_HEADING = re.compile(
+    r"^#{1,3}\s+(REQ-(?:[A-Z][A-Z0-9_]*-)?\d+)(?::\s*(.+))?\s*$",
+    re.MULTILINE,
+)
 
 # A small stopword list to keep keyword matches meaningful.
 _STOPWORDS = frozenset(
@@ -205,6 +210,19 @@ def text_blob(self) -> str:
 def parse_requirements(req_md_path: Path) -> list[RequirementSummary]:
     """Parse REQUIREMENTS.md into ``RequirementSummary`` records.
 
+    Handles two heading styles:
+
+    Style A (standard specsmith format)::
+
+        ## REQ-001: Title
+        Description text as a plain paragraph.
+
+    Style B (numbered-heading format)::
+
+        ## 1. Title
+        - **ID:** REQ-001
+        - **Description:** description text
+
     Best-effort: missing files yield an empty list.
     """
     req_md_path = req_md_path.resolve()  # CodeQL py/path-injection: normalise before fs access
@@ -215,14 +233,53 @@ def parse_requirements(req_md_path: Path) -> list[RequirementSummary]:
     except ValueError:
         return []
     out: list[RequirementSummary] = []
+
+    # ── Style A: ## REQ-NNN: Title  (standard specsmith format) ────────────────
+    # Split on any Style A heading first; if the file uses this format
+    # exclusively, the Style B pass below will be a no-op.
+    lines = text.splitlines()
+    current_id: str = ""
+    current_title: str = ""
+    current_desc: str = ""
+    seen_ids: set[str] = set()
+
+    def _flush_style_a() -> None:
+        if current_id and current_id not in seen_ids:
+            seen_ids.add(current_id)
+            out.append(
+                RequirementSummary(req_id=current_id, title=current_title, description=current_desc)
+            )
+
+    for line in lines:
+        m_a = _STYLE_A_HEADING.match(line)
+        if m_a:
+            _flush_style_a()
+            current_id = m_a.group(1)
+            current_title = (m_a.group(2) or "").strip()
+            current_desc = ""
+            continue
+        if current_id:
+            stripped = line.strip()
+            # Bullet description fields
+            m_desc = _REQ_DESC.match(line)
+            if m_desc:
+                current_desc = current_desc or m_desc.group(1).strip()
+                continue
+            # Plain paragraph text (not a heading, not a bullet, not empty)
+            if stripped and not stripped.startswith("#") and not stripped.startswith("-"):
+                current_desc = current_desc or stripped
+    _flush_style_a()
+
+    # ── Style B: ## N. Title  with - **ID:** REQ-NNN inline ────────────────────
     blocks = re.split(r"^##\s+\d+\.\s+", text, flags=re.MULTILINE)[1:]
     for block in blocks:
-        lines = block.splitlines()
-        title = lines[0].strip() if lines else ""
+        block_lines = block.splitlines()
+        title = block_lines[0].strip() if block_lines else ""
         m_id = _REQ_ID.search(block)
         m_desc = _REQ_DESC.search(block)
-        if not m_id:
-            continue
+        if not m_id or m_id.group(1) in seen_ids:
+            continue  # skip if no ID or already captured by Style A pass
+        seen_ids.add(m_id.group(1))
         out.append(
             RequirementSummary(
                 req_id=m_id.group(1),

src/specsmith/auditor.py

@@ -779,6 +779,34 @@ def check_type_mismatch(root: Path) -> list[AuditResult]:
             raw = yaml.safe_load(f)
         config = ProjectConfig(**raw)
 
+        # Skip when type_override == type (explicit user suppression, #196).
+        if config.type_override and config.type_override == config.type:
+            results.append(
+                AuditResult(
+                    name="type-mismatch",
+                    passed=True,
+                    message=(
+                        f"Project type {config.type} is explicitly overridden; "
+                        f"auto-detection skipped"
+                    ),
+                )
+            )
+            return results
+
+        # Skip for unrecognised (custom) type strings — there is no known
+        # ProjectType to compare against, so detection is meaningless.
+        if config.project_type_enum is None:
+            results.append(
+                AuditResult(
+                    name="type-mismatch",
+                    passed=True,
+                    message=(
+                        f"Project type {config.type!r} is a custom type; auto-detection skipped"
+                    ),
+                )
+            )
+            return results
+
         # Skip auto-detection for types that must be specified explicitly.
         if config.type in _EXPLICIT_ONLY_TYPES:
             results.append(

src/specsmith/cli.py

@@ -2159,6 +2159,7 @@ def req_add(
         add_req(
             root,
             effective_id,
+            title=title,
             component=component,
             priority=priority,
             description=description,
@@ -2592,6 +2593,13 @@ def save_cmd(project_dir: str, message: str, no_push: bool, force: bool, as_json
             steps.append(
                 {"step": "esdb_backup", "ok": True, "note": "JSON fallback (no WAL to backup)"}
             )
+    except ImportError:
+        # chronomemory not installed — non-fatal; commit and push still proceed.
+        # Install with: pipx inject specsmith
+        #   "chronomemory @ git+https://github.com/layer1labs/chronomemory.git@v0.1.1"
+        from specsmith.esdb import _INSTALL_HINT  # noqa: PLC0415
+
+        steps.append({"step": "esdb_backup", "ok": True, "note": f"skipped — {_INSTALL_HINT}"})
     except Exception as exc:  # noqa: BLE001
         steps.append({"step": "esdb_backup", "ok": False, "error": str(exc)})
 

src/specsmith/config.py

@@ -224,6 +224,18 @@ class ProjectConfig(BaseModel):
         ),
     )
 
+    # Explicit type override — suppresses the type-mismatch audit check.
+    # Set this when your project uses a custom or research-specific type string
+    # that cannot be auto-detected (e.g. 'research-mathematics').  When
+    # type_override matches type, check_type_mismatch is suppressed.
+    type_override: str = Field(
+        default="",
+        description=(
+            "Explicit type override.  When set to the same value as `type`, "
+            "the type-mismatch audit check is suppressed regardless of what "
+            "auto-detection infers from the project files."
+        ),
+    )
     # Fallback type — used when this project type is not yet supported
     # by the installed specsmith version. specsmith silently falls back to
     # this type for scaffolding purposes while still recording the intended type.

src/specsmith/esdb/__init__.py

@@ -3,37 +3,85 @@
 # Re-exports the full chronomemory v0.1.1 public surface under the
 # specsmith.esdb namespace so internal modules can use a single import
 # path and never import chronomemory directly in more than one place.
+#
+# chronomemory is a git-URL dependency stripped from the PyPI wheel.
+# If it is not installed, all symbols are stubbed with a class that
+# raises a clear ImportError with install instructions rather than
+# crashing silently at module import time.
+#
+# Install the missing dep:
+#   pipx inject specsmith "chronomemory @ git+https://github.com/layer1labs/chronomemory.git@v0.1.1"
 
-# Re-export query and metrics as module references so callers can do:
-#   from specsmith.esdb import query, metrics
-from chronomemory import (
-    RUST_BACKEND,
-    # Core store
-    ChronoRecord,
-    ChronoStore,
-    # Phase 2: context pack compiler
-    ContextPack,
-    ContextPackCompiler,
-    ContextPackEntry,
-    DependencyEdge,
-    # Phase 2: dependency graph
-    DepGraph,
-    # Bridge (backward-compat with .specsmith/*.json)
-    EsdbBridge,
-    EsdbRecord,
-    EsdbStatus,
-    # Phase 2: epistemic rollback
-    RollbackReport,
-    # Phase 3: optional Rust acceleration (None / False when not compiled)
-    RustChronoStore,
-    RustRecord,
-    WalEvent,
-    invalidate,
-    metrics,  # noqa: F401 — module re-export
-    open_store,
-    query,  # noqa: F401 — module re-export
+_INSTALL_HINT = (
+    "chronomemory is not installed.\n"
+    "Run: pipx inject specsmith "
+    '"chronomemory @ git+https://github.com/layer1labs/chronomemory.git@v0.1.1"'
 )
 
+try:
+    # Re-export query and metrics as module references so callers can do:
+    #   from specsmith.esdb import query, metrics
+    from chronomemory import (
+        RUST_BACKEND,
+        # Core store
+        ChronoRecord,
+        ChronoStore,
+        # Phase 2: context pack compiler
+        ContextPack,
+        ContextPackCompiler,
+        ContextPackEntry,
+        DependencyEdge,
+        # Phase 2: dependency graph
+        DepGraph,
+        # Bridge (backward-compat with .specsmith/*.json)
+        EsdbBridge,
+        EsdbRecord,
+        EsdbStatus,
+        # Phase 2: epistemic rollback
+        RollbackReport,
+        # Phase 3: optional Rust acceleration (None / False when not compiled)
+        RustChronoStore,
+        RustRecord,
+        WalEvent,
+        invalidate,
+        metrics,  # noqa: F401 — module re-export
+        open_store,
+        query,  # noqa: F401 — module re-export
+    )
+
+    CHRONO_AVAILABLE: bool = True
+
+except ImportError:
+    CHRONO_AVAILABLE = False
+
+    class _Stub:  # type: ignore[no-redef]
+        """Placeholder that raises a clear error on instantiation or call."""
+
+        def __init__(self, *_: object, **__: object) -> None:
+            raise ImportError(_INSTALL_HINT)
+
+        def __call__(self, *_: object, **__: object) -> "_Stub":
+            raise ImportError(_INSTALL_HINT)
+
+        def __class_getitem__(cls, _: object) -> "type[_Stub]":
+            return cls
+
+    # Stub every exported name so `from specsmith.esdb import X` doesn't fail.
+    ChronoRecord = ChronoStore = EsdbBridge = EsdbRecord = EsdbStatus = _Stub  # type: ignore[misc]
+    ContextPack = ContextPackCompiler = ContextPackEntry = _Stub  # type: ignore[misc]
+    DepGraph = DependencyEdge = RollbackReport = _Stub  # type: ignore[misc]
+    RustChronoStore = RustRecord = WalEvent = invalidate = open_store = _Stub  # type: ignore[misc]
+    RUST_BACKEND: bool = False  # type: ignore[misc]
+
+    class _StubModule:
+        """Stub module reference so 'from specsmith.esdb import query, metrics' works."""
+
+        def __getattr__(self, name: str) -> "_Stub":
+            raise ImportError(_INSTALL_HINT)
+
+    query = _StubModule()  # type: ignore[assignment]
+    metrics = _StubModule()  # type: ignore[assignment]
+
 __all__ = [
     # Core
     "ChronoStore",

src/specsmith/governance_logic.py

@@ -73,9 +73,16 @@ def run_preflight(
 
     root = _safe_resolve(project_dir)
     intent = classify_intent(utterance)
+    # Requirements live at docs/REQUIREMENTS.md, not at the project root.
+    # Falling back to root/REQUIREMENTS.md would always yield an empty list
+    # on standard projects, causing preflight to always return
+    # needs_clarification (GitHub issue #197).
+    _req_md = root / "docs" / "REQUIREMENTS.md"
+    if not _req_md.exists():
+        _req_md = root / "REQUIREMENTS.md"  # legacy fallback
     scope = infer_scope(
         utterance,
-        root / "REQUIREMENTS.md",
+        _req_md,
         repo_index_path=root / ".repo-index" / "files.json",
     )
 

src/specsmith/requirements.py

@@ -92,19 +92,33 @@ def add_req(
     root: Path,
     req_id: str,
     *,
+    title: str = "",
     component: str = "",
     priority: str = "medium",
     description: str = "",
 ) -> None:
-    """Append a new requirement to REQUIREMENTS.md."""
+    """Append a new requirement to REQUIREMENTS.md.
+
+    Emits the standard Style A format::
+
+        ## REQ-NNN: Title
+        Description text as a plain paragraph.
+
+    This matches the format already used by every other requirement in
+    REQUIREMENTS.md and is correctly parsed by ``sync`` and ``preflight``.
+    """
     req_path = root / "docs" / "REQUIREMENTS.md"
-    entry = f"\n### {req_id}\n"
+    # Build heading:  ## REQ-NNN  or  ## REQ-NNN: Title
+    heading_title = f": {title}" if title else ""
+    entry = f"\n## {req_id}{heading_title}\n"
+    if description:
+        # Plain paragraph — not a bullet list (matches parser expectations)
+        entry += f"{description}\n"
+    # Legacy fields kept for backward-compat but written as metadata bullets
     if component:
         entry += f"- **Component**: {component}\n"
-    entry += f"- **Priority**: {priority}\n"
-    entry += "- **Status**: Draft\n"
-    if description:
-        entry += f"- **Description**: {description}\n"
+    if priority and priority != "medium":
+        entry += f"- **Priority**: {priority}\n"
 
     content = req_path.read_text(encoding="utf-8") if req_path.exists() else "# Requirements\n"
 

src/specsmith/sync.py

@@ -33,11 +33,13 @@
 # ---------------------------------------------------------------------------
 
 # Matches either:
-#   Style A: ## REQ-001  or  ## REQ-CLI-001 — Title
+#   Style A: ## REQ-001  or  ## REQ-CLI-001: Title
+#     The optional ": Title" suffix is captured in group(2).
 #   Style B: ## N. Title  (ID comes from inline - **ID:** REQ-NNN field)
 _FLEX_REQ_ID = r"REQ-(?:[A-Z][A-Z0-9_]*-)?\d+"
 _NUMBERED_HEADING = re.compile(r"^#{1,3}\s+\d+\.\s+(.+?)\s*$")
-_DIRECT_HEADING = re.compile(r"^#{1,3}\s+(" + _FLEX_REQ_ID + r")\b")
+# Group 1: REQ-ID,  Group 2 (optional): title text after the colon.
+_DIRECT_HEADING = re.compile(r"^#{1,3}\s+(" + _FLEX_REQ_ID + r")(?::\s*(.+))?\s*$")
 _ID_FIELD = re.compile(r"^-\s+\*\*ID:\*\*\s+(" + _FLEX_REQ_ID + r")")
 _FIELD_LINE = re.compile(r"^-\s+\*\*(.+?):\*\*\s+(.+)")
 
@@ -61,7 +63,11 @@ def _flush() -> None:
         m_direct = _DIRECT_HEADING.match(line)
         if m_direct:
             _flush()
+            # Group 2 carries the title when the heading is '## REQ-NNN: Title'
+            inline_title = (m_direct.group(2) or "").strip()
             current = {"id": m_direct.group(1)}
+            if inline_title:
+                current["title"] = inline_title
             pending_title = ""
             continue
 
@@ -86,6 +92,10 @@ def _flush() -> None:
                 val = m_field.group(2).strip()
                 if key not in ("id",):
                     current.setdefault(key, val)
+            elif line.strip() and not line.startswith("#"):
+                # Plain paragraph text after the heading — capture as description
+                # (e.g. '## REQ-001: Title\nThe system SHALL...')
+                current.setdefault("description", line.strip())
 
     _flush()
     return [