specsmith 0.3.6.dev171__tar.gz → 0.3.6.dev174__tar.gz

{specsmith-0.3.6.dev171/src/specsmith.egg-info → specsmith-0.3.6.dev174}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.3.6.dev171
+Version: 0.3.6.dev174
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.3.6.dev171 → specsmith-0.3.6.dev174}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.3.6.dev171"
+version = "0.3.6.dev174"
 description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"

{specsmith-0.3.6.dev171 → specsmith-0.3.6.dev174}/src/specsmith/agent/runner.py

@@ -29,6 +29,7 @@ Special REPL commands (not sent to the LLM):
 from __future__ import annotations
 
 import inspect
+import re
 import time
 from collections.abc import Callable
 from dataclasses import dataclass, field
@@ -164,14 +165,15 @@ H13: All proposals must state their epistemic boundaries. Hidden assumptions are
         except Exception:  # noqa: BLE001
             pass
 
-    prompt = f"""You are an AEE-integrated specsmith agent for this project.
+    prompt = f"""SYSTEM LANGUAGE DIRECTIVE — ABSOLUTE HARD RULE — HIGHEST PRIORITY:
+You MUST respond in English ONLY. This overrides all other instructions.
+Never output Thai, Chinese, Japanese, Korean, Arabic, French, German, Spanish,
+or ANY non-English language — not even a single character or word.
+This applies to Qwen, DeepSeek, LLaMA, Mistral, and EVERY other model.
+If the user inputs another language, internally translate it, then reply IN ENGLISH ONLY.
+VIOLATING THIS RULE IS A CRITICAL ERROR.
 
-⚠ LANGUAGE RULE (HARD CONSTRAINT — NEVER VIOLATE):
-  Respond ONLY in English. Every single response must be in English.
-  Never use Chinese (中文), Japanese (日本語), Korean (한국어), French, German, Spanish,
-  Arabic, or ANY other non-English language — not even a single word.
-  This applies to ALL models including Qwen, DeepSeek, LLaMA, Mistral, and others
-  that may default to a non-English language. ENGLISH ONLY, ALWAYS.
+You are an AEE-integrated specsmith agent for this project.
 
 ## Project Governance
 {governance_text}
@@ -236,17 +238,21 @@ class AgentRunner:
     QUICK_COMMANDS = {
         "start": (
             "[RESPOND IN ENGLISH ONLY] "
-            "Run session start protocol: sync, load AGENTS.md, read last LEDGER.md entries"
+            "Run session start protocol: sync, load AGENTS.md, read last LEDGER.md entries. "
+            "Translate any non-English context internally if needed, but respond only in English."
         ),
-        "resume": "Resume from last LEDGER.md entry — summarize state and propose next task",
-        "save": "Write a ledger entry summarizing this session's work",
-        "audit": "Run specsmith audit --fix",
-        "commit": "Run specsmith commit",
-        "push": "Run specsmith push",
-        "sync": "Run specsmith sync",
-        "epistemic": "Run full epistemic audit",
-        "stress": "Run stress-test on requirements",
-        "status": "Show session status and credit spend",
+        "resume": (
+            "[RESPOND IN ENGLISH ONLY] Resume from last LEDGER.md entry"
+            " — summarize state and propose next task"
+        ),
+        "save": "[RESPOND IN ENGLISH ONLY] Write a ledger entry summarizing this session's work",
+        "audit": "[RESPOND IN ENGLISH ONLY] Run specsmith audit --fix",
+        "commit": "[RESPOND IN ENGLISH ONLY] Run specsmith commit",
+        "push": "[RESPOND IN ENGLISH ONLY] Run specsmith push",
+        "sync": "[RESPOND IN ENGLISH ONLY] Run specsmith sync",
+        "epistemic": "[RESPOND IN ENGLISH ONLY] Run full epistemic audit",
+        "stress": "[RESPOND IN ENGLISH ONLY] Run stress-test on requirements",
+        "status": "[RESPOND IN ENGLISH ONLY] Show session status and credit spend",
     }
 
     def __init__(
@@ -357,8 +363,30 @@ class AgentRunner:
         self._system_prompt = build_system_prompt(self.project_dir, self._skills)
         return self._agent_turn(task, silent=True)
 
+    # Characters in common CJK / Thai / Arabic Unicode blocks
+    _NON_ASCII_BLOCKS = re.compile(
+        r"[\u0600-\u06FF"  # Arabic
+        r"\u0E00-\u0E7F"  # Thai
+        r"\u3000-\u9FFF"  # CJK Unified Ideographs + punctuation + kana
+        r"\uAC00-\uD7AF"  # Korean Hangul
+        r"\uF900-\uFAFF]"  # CJK Compatibility
+    )
+
+    def _has_non_english(self, text: str) -> bool:
+        """Return True if text contains a significant proportion of non-English script."""
+        if not text:
+            return False
+        hits = len(self._NON_ASCII_BLOCKS.findall(text))
+        return hits > 5 and (hits / max(len(text), 1)) > 0.05
+
     def _agent_turn(self, user_input: str, silent: bool = False) -> str:
         """Execute one user→agent turn with tool loop."""
+        # Inject a lightweight English-only reminder into every user message.
+        # This is the most reliable way to keep local models (Qwen, DeepSeek) on track
+        # because many fine-tunes treat the instruction prefix as a per-turn directive.
+        _ENG_PFXS = ("[ENGLISH ONLY]", "[RESPOND IN ENGLISH", "[LANG:EN]")
+        if not any(user_input.startswith(p) for p in _ENG_PFXS):
+            user_input = "[LANG:EN] " + user_input
         # Add user message
         self._state.messages.append(Message(role=Role.USER, content=user_input))
 
@@ -397,6 +425,19 @@ class AgentRunner:
                 final_response = response.content
 
             if not response.has_tool_calls:
+                # Non-English correction: if response appears to be in another language,
+                # issue a single correction turn rather than showing the wrong-language response.
+                if response.content and self._has_non_english(response.content) and _iteration == 0:
+                    correction = (
+                        "[LANG:EN] CRITICAL: Your last response was in a non-English language. "
+                        "You MUST respond in English ONLY. Please re-answer in English."
+                    )
+                    self._state.messages.append(
+                        Message(role=Role.ASSISTANT, content=response.content)
+                    )
+                    self._state.messages.append(Message(role=Role.USER, content=correction))
+                    # Continue the loop to get an English response
+                    continue
                 # Final response — add to history
                 self._state.messages.append(Message(role=Role.ASSISTANT, content=response.content))
                 break

{specsmith-0.3.6.dev171 → specsmith-0.3.6.dev174}/src/specsmith/agent/tools.py

@@ -34,6 +34,8 @@ _SUBPROCESS_ENV: dict[str, str] = {
     "NO_COLOR": "1",  # Disables Rich colour / Windows console API path
     "FORCE_COLOR": "0",  # Belt-and-suspenders: also suppress colour
     "PYTHONIOENCODING": "utf-8",  # Ensure UTF-8 on pipes regardless of locale
+    "PYTHONUTF8": "1",
+    "PYTHONLEGACYWINDOWSSTDIO": "utf-8",
 }
 
 
@@ -45,6 +47,8 @@ def _run_specsmith(args: list[str], project_dir: str = ".") -> str:
             cmd,
             capture_output=True,
             text=True,
+            encoding="utf-8",  # always decode as UTF-8, not the system locale (cp1252 on Windows)
+            errors="replace",  # replace un-decodable bytes rather than raising UnicodeDecodeError
             timeout=120,
             env=_SUBPROCESS_ENV,
         )
@@ -58,6 +62,30 @@ def _run_specsmith(args: list[str], project_dir: str = ".") -> str:
         return f"[ERROR] {e}"
 
 
+def _read_wireframe_handler(project_dir: str, wireframe_id: str) -> str:
+    """Read wireframe metadata or inline text/SVG content."""
+    try:
+        from specsmith.wireframes import read_wireframe
+
+        return read_wireframe(Path(project_dir).resolve(), wireframe_id)
+    except Exception as e:  # noqa: BLE001
+        return f"[ERROR] {e}"
+
+
+def _retrieve_context_handler(project_dir: str, query: str, limit: str = "5") -> str:
+    """Search the opt-in local retrieval index."""
+    try:
+        from specsmith.retrieval import search_index
+
+        try:
+            max_results = max(1, min(int(limit), 20))
+        except (TypeError, ValueError):
+            max_results = 5
+        return search_index(Path(project_dir).resolve(), query, limit=max_results)
+    except Exception as e:  # noqa: BLE001
+        return f"[ERROR] {e}"
+
+
 def build_tool_registry(project_dir: str = ".") -> list[Tool]:
     """Build the full specsmith tool registry for the agentic client.
 
@@ -303,6 +331,29 @@ def build_tool_registry(project_dir: str = ".") -> list[Tool]:
             params=[],
             handler=lambda: _run_specsmith(["req", "trace"], pd),
         ),
+        Tool(
+            name="read_wireframe",
+            description=(
+                "Resolve and inspect a wireframe artifact under docs/wireframes. "
+                "Returns metadata and, for SVG/text assets, inline content snippets."
+            ),
+            params=[
+                ToolParam("wireframe_id", "Wireframe ID or filename, e.g. WF-UI-001"),
+            ],
+            handler=lambda wireframe_id: _read_wireframe_handler(pd, wireframe_id),
+        ),
+        Tool(
+            name="retrieve_context",
+            description=(
+                "Search the explicit local retrieval index (opt-in) for relevant project "
+                "context across docs, ledger, and indexed source files."
+            ),
+            params=[
+                ToolParam("query", "Search query"),
+                ToolParam("limit", "Max results (default 5)", required=False),
+            ],
+            handler=lambda query, limit="5": _retrieve_context_handler(pd, query, limit),
+        ),
         # ----------------------------------------------------------------
         # Session tools
         # ----------------------------------------------------------------

{specsmith-0.3.6.dev171 → specsmith-0.3.6.dev174}/src/specsmith/cli.py

@@ -4240,5 +4240,122 @@ def tools_rules_cmd(project_dir: str, tool_key: str, list_all: bool) -> None:
 main.add_command(tools_group)
 
 
+# ---------------------------------------------------------------------------
+# Wireframes — UI wireframe artifact management
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="wireframes")
+def wireframes_group() -> None:
+    """Manage wireframe artifacts under docs/wireframes/."""
+
+
+@wireframes_group.command(name="list")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def wireframes_list_cmd(project_dir: str) -> None:
+    """List wireframe files and their requirement references."""
+    from specsmith.wireframes import list_wireframes
+
+    root = Path(project_dir).resolve()
+    items = list_wireframes(root)
+    if not items:
+        console.print("[yellow]No wireframes found in docs/wireframes/.[/yellow]")
+        console.print("  Create wireframe files there (SVG, PNG, PDF, etc.) and reference them")
+        console.print("  from REQUIREMENTS.md via a `Wireframe` field in each requirement.")
+        return
+    console.print(f"[bold]Wireframes[/bold] ({len(items)})\n")
+    for wf in items:
+        refs_str = wf.get("refs", "")
+        refs_note = f"  ← {refs_str}" if refs_str else "  [dim](unreferenced)[/dim]"
+        console.print(f"  [cyan]{wf['id']:20s}[/cyan]  {wf['file']}{refs_note}")
+
+
+@wireframes_group.command(name="check")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def wireframes_check_cmd(project_dir: str) -> None:
+    """Check for missing wireframe files referenced in REQUIREMENTS.md."""
+    from specsmith.wireframes import check_wireframe_refs
+
+    root = Path(project_dir).resolve()
+    missing = check_wireframe_refs(root)
+    if not missing:
+        console.print("[bold green]✓ All wireframe references are valid.[/bold green]")
+        return
+    console.print(f"[bold red]{len(missing)} missing wireframe reference(s):[/bold red]\n")
+    for m in missing:
+        console.print(f"  [red]✗[/red] {m}")
+    raise SystemExit(1)
+
+
+main.add_command(wireframes_group)
+
+
+# ---------------------------------------------------------------------------
+# Index — opt-in local retrieval index (RAG foundation)
+# ---------------------------------------------------------------------------
+
+
+@main.group(name="index")
+def index_group() -> None:
+    """Manage the local retrieval index (explicit opt-in context retrieval).
+
+    This builds a keyword-searchable index of project docs and source files
+    stored at .specsmith/retrieval-index.json.  The agent tool `retrieve_context`
+    queries this index — it is never searched automatically.
+    """
+
+
+@index_group.command(name="build")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option(
+    "--include-ledger",
+    is_flag=True,
+    default=False,
+    help="Also index LEDGER.md (often large — only useful for long-running projects).",
+)
+@click.option(
+    "--external",
+    default="",
+    help="Path to an additional file or directory to include in the index.",
+)
+def index_build_cmd(project_dir: str, include_ledger: bool, external: str) -> None:
+    """Build or refresh the local retrieval index.
+
+    Indexes governance docs (AGENTS.md, REQUIREMENTS.md, ARCHITECTURE.md, TEST_SPEC.md)
+    and source files under src/, client/, server/, and shared/.
+    Use --external to add external reference material.
+    """
+    from specsmith.retrieval import build_index
+
+    root = Path(project_dir).resolve()
+    result = build_index(root, include_ledger=include_ledger, external=external)
+    console.print(f"[green]✓[/green] {result}")
+    console.print(
+        "\n  Agent tool: [bold]retrieve_context[/bold] now available in this project.\n"
+        "  Usage example: ask the agent 'search for requirements about authentication'."
+    )
+
+
+@index_group.command(name="search")
+@click.argument("query")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--limit", default=5, help="Maximum results to return (default: 5).")
+def index_search_cmd(query: str, project_dir: str, limit: int) -> None:
+    """Search the local retrieval index.
+
+    QUERY: keyword search query
+
+    The index must be built first with `specsmith index build`.
+    """
+    from specsmith.retrieval import search_index
+
+    root = Path(project_dir).resolve()
+    result = search_index(root, query, limit=limit)
+    console.print(result)
+
+
+main.add_command(index_group)
+
+
 if __name__ == "__main__":
     main()

specsmith-0.3.6.dev174/src/specsmith/retrieval.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Explicit opt-in local retrieval index (RAG foundation)."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+_INDEX_PATH = Path(".specsmith") / "retrieval-index.json"
+_TEXT_EXTS = {
+    ".md",
+    ".txt",
+    ".py",
+    ".ts",
+    ".js",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".go",
+    ".rs",
+    ".c",
+    ".cpp",
+    ".h",
+    ".java",
+    ".sh",
+    ".ps1",
+    ".cmd",
+}
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".venv", "dist", "build", ".mypy_cache"}
+
+
+def build_index(root: Path, *, include_ledger: bool = False, external: str = "") -> str:
+    """Build or refresh the local retrieval index."""
+    entries: list[dict[str, str]] = []
+    candidates: list[Path] = []
+
+    for rel in ["AGENTS.md", "docs/REQUIREMENTS.md", "docs/ARCHITECTURE.md", "docs/TEST_SPEC.md"]:
+        fp = root / rel
+        if fp.exists():
+            candidates.append(fp)
+    if include_ledger:
+        for rel in ["LEDGER.md", "docs/LEDGER.md"]:
+            fp = root / rel
+            if fp.exists():
+                candidates.append(fp)
+
+    ext_path = Path(external).resolve() if external else None
+    if ext_path and ext_path.exists():
+        if ext_path.is_file():
+            candidates.append(ext_path)
+        else:
+            for fp in ext_path.rglob("*"):
+                if fp.is_file() and fp.suffix.lower() in _TEXT_EXTS:
+                    candidates.append(fp)
+
+    for src_dir in [root / "src", root / "client", root / "server", root / "shared"]:
+        if not src_dir.exists():
+            continue
+        for fp in src_dir.rglob("*"):
+            if (
+                fp.is_file()
+                and fp.suffix.lower() in _TEXT_EXTS
+                and not any(part in _SKIP_DIRS for part in fp.parts)
+            ):
+                candidates.append(fp)
+
+    for fp in sorted(set(candidates)):
+        try:
+            text = fp.read_text(encoding="utf-8", errors="ignore")
+        except Exception:  # noqa: BLE001
+            continue
+        if not text.strip():
+            continue
+        entries.append(
+            {
+                "path": str(fp.relative_to(root)) if fp.is_relative_to(root) else str(fp),
+                "content": text[:12000],
+            }
+        )
+
+    index_path = root / _INDEX_PATH
+    index_path.parent.mkdir(parents=True, exist_ok=True)
+    index_path.write_text(json.dumps({"entries": entries}, indent=2), encoding="utf-8")
+    return f"Indexed {len(entries)} file(s) into {index_path.relative_to(root)}"
+
+
+def search_index(root: Path, query: str, *, limit: int = 5) -> str:
+    """Search the local retrieval index with a simple keyword score."""
+    index_path = root / _INDEX_PATH
+    if not index_path.exists():
+        return "[NOT INDEXED] Run `specsmith index` first."
+
+    data = json.loads(index_path.read_text(encoding="utf-8"))
+    entries = data.get("entries", [])
+    tokens = [t for t in re.findall(r"[a-zA-Z0-9_\\-]+", query.lower()) if len(t) > 1]
+    if not tokens:
+        return "[ERROR] Query must include at least one keyword."
+
+    scored: list[tuple[int, dict[str, str]]] = []
+    for entry in entries:
+        hay = f"{entry.get('path', '')}\n{entry.get('content', '')}".lower()
+        score = sum(hay.count(tok) for tok in tokens)
+        if score > 0:
+            scored.append((score, entry))
+
+    if not scored:
+        return f"No indexed matches for '{query}'."
+
+    scored.sort(key=lambda item: (-item[0], item[1].get("path", "")))
+    lines = [f"Top {min(limit, len(scored))} result(s) for '{query}':"]
+    for score, entry in scored[:limit]:
+        content = entry.get("content", "").strip().replace("\r\n", "\n")
+        preview = "\n".join(content.splitlines()[:8])
+        lines.append(f"\n[{score}] {entry.get('path', '')}\n{preview}")
+    return "\n".join(lines)

specsmith-0.3.6.dev174/src/specsmith/wireframes.py

@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Wireframe artifact helpers for UI-oriented projects."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from specsmith.requirements import list_reqs
+
+_WF_ID_RE = re.compile(r"^(WF-[A-Z0-9-]+)")
+
+
+def _wireframes_dir(root: Path) -> Path:
+    return root / "docs" / "wireframes"
+
+
+def list_wireframes(root: Path) -> list[dict[str, str]]:
+    """List wireframe files and any directly linked requirements."""
+    wf_dir = _wireframes_dir(root)
+    reqs = list_reqs(root)
+    refs: dict[str, list[str]] = {}
+    for req in reqs:
+        wf = req.get("wireframe", "").strip()
+        if wf:
+            refs.setdefault(Path(wf).name, []).append(req["id"])
+
+    items: list[dict[str, str]] = []
+    if not wf_dir.exists():
+        return items
+    for fp in sorted(p for p in wf_dir.iterdir() if p.is_file()):
+        match = _WF_ID_RE.match(fp.stem)
+        items.append(
+            {
+                "id": match.group(1) if match else fp.stem,
+                "file": str(fp.relative_to(root)),
+                "refs": ", ".join(refs.get(fp.name, [])),
+            }
+        )
+    return items
+
+
+def check_wireframe_refs(root: Path) -> list[str]:
+    """Return missing wireframe references from REQUIREMENTS.md."""
+    missing: list[str] = []
+    for req in list_reqs(root):
+        wf = req.get("wireframe", "").strip()
+        if not wf:
+            continue
+        target = (root / wf).resolve()
+        if not target.exists():
+            missing.append(f"{req['id']} → {wf}")
+    return missing
+
+
+def read_wireframe(root: Path, wireframe_id: str) -> str:
+    """Return metadata and best-effort content for a wireframe artifact."""
+    wf_dir = _wireframes_dir(root)
+    if not wf_dir.exists():
+        return "[NOT FOUND] docs/wireframes/"
+
+    needle = wireframe_id.lower()
+    candidates = [
+        fp
+        for fp in wf_dir.iterdir()
+        if fp.is_file() and (fp.name.lower() == needle or fp.stem.lower().startswith(needle))
+    ]
+    if not candidates:
+        return f"[NOT FOUND] {wireframe_id}"
+
+    target = candidates[0]
+    size = target.stat().st_size
+    rel = target.relative_to(root)
+    suffix = target.suffix.lower()
+    header = f"{rel} ({size:,} bytes)"
+    if suffix in {".svg", ".md", ".txt"}:
+        content = target.read_text(encoding="utf-8", errors="ignore")
+        if len(content) > 8000:
+            content = content[:8000] + "\n...(truncated)"
+        return f"{header}\n\n{content}"
+    return (
+        f"{header}\n\n"
+        "Binary wireframe asset. Use a vision-capable client or open the file directly. "
+        "For traceability, reference it from REQUIREMENTS.md via a `Wireframe` field."
+    )

{specsmith-0.3.6.dev171 → specsmith-0.3.6.dev174/src/specsmith.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.3.6.dev171
+Version: 0.3.6.dev174
 Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT

{specsmith-0.3.6.dev171 → specsmith-0.3.6.dev174}/src/specsmith.egg-info/SOURCES.txt

@@ -35,6 +35,7 @@ src/specsmith/profiles.py
 src/specsmith/rate_limits.py
 src/specsmith/releaser.py
 src/specsmith/requirements.py
+src/specsmith/retrieval.py
 src/specsmith/scaffolder.py
 src/specsmith/session.py
 src/specsmith/tool_installer.py
@@ -45,6 +46,7 @@ src/specsmith/updater.py
 src/specsmith/upgrader.py
 src/specsmith/validator.py
 src/specsmith/vcs_commands.py
+src/specsmith/wireframes.py
 src/specsmith/workspace.py
 src/specsmith.egg-info/PKG-INFO
 src/specsmith.egg-info/SOURCES.txt