specsmith 0.11.3.dev433__tar.gz → 0.11.3.dev436__tar.gz

{specsmith-0.11.3.dev433/src/specsmith.egg-info → specsmith-0.11.3.dev436}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.11.3.dev433
+Version: 0.11.3.dev436
 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.11.3.dev433 → specsmith-0.11.3.dev436}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.11.3.dev433"
+version = "0.11.3.dev436"
 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.11.3.dev433 → specsmith-0.11.3.dev436}/src/specsmith/cli.py

@@ -2999,6 +2999,178 @@ def session_clear_cmd(project_dir: str, yes: bool) -> None:
     console.print("[green]\u2713[/green] Session context cleared.")
 
 
+@main.command(name="checkpoint")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option("--json", "as_json", is_flag=True, default=False, help="Emit as JSON.")
+def checkpoint_cmd(project_dir: str, as_json: bool) -> None:
+    """Emit a compact governance anchor to prevent session drift.
+
+    Run this every 8-10 turns and ALWAYS include the output in any context
+    summary. The anchor captures the exact governance state (phase, health,
+    work items, REQ/TEST counts, ESDB chain) so the next context window is
+    never blind to where the project stands.
+
+    Usage pattern (copy the output into the conversation)::
+
+        specsmith checkpoint              # human-readable anchor block
+        specsmith checkpoint --json       # machine-readable JSON
+
+    In AGENTS.md: agents MUST emit ``specsmith checkpoint`` output verbatim
+    whenever they produce a context summary.
+    """
+    import json as _json
+    import re
+    import time
+
+    root = Path(project_dir).resolve()
+    ts = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+
+    # ── Project name ──────────────────────────────────────────────────────────
+    project_name = root.name
+    try:
+        from specsmith.paths import find_scaffold
+
+        sp = find_scaffold(root)
+        if sp:
+            import yaml as _yaml
+
+            raw = _yaml.safe_load(sp.read_text(encoding="utf-8")) or {}
+            project_name = str(raw.get("name", root.name))
+    except Exception:  # noqa: BLE001
+        pass
+
+    # ── Phase ─────────────────────────────────────────────────────────────────
+    phase_key, phase_label, phase_emoji, phase_pct = "unknown", "Unknown", "", 0
+    try:
+        from specsmith.phase import PHASE_MAP, phase_progress_pct, read_phase
+
+        phase_key = read_phase(root)
+        phase = PHASE_MAP.get(phase_key)
+        if phase:
+            phase_label = phase.label
+            phase_emoji = phase.emoji
+            phase_pct = phase_progress_pct(phase, root)
+    except Exception:  # noqa: BLE001
+        pass
+
+    # ── Audit health ──────────────────────────────────────────────────────────
+    health_ok, audit_failed = True, 0
+    try:
+        from specsmith.auditor import run_audit
+
+        report = run_audit(root)
+        health_ok = report.healthy
+        audit_failed = report.failed
+    except Exception:  # noqa: BLE001
+        pass
+
+    # ── REQ / TEST counts ─────────────────────────────────────────────────────
+    req_count, test_count = 0, 0
+    try:
+        import json as _jl
+
+        rp = root / ".specsmith" / "requirements.json"
+        tp = root / ".specsmith" / "testcases.json"
+        if rp.exists():
+            req_count = len(_jl.loads(rp.read_text(encoding="utf-8")))
+        if tp.exists():
+            test_count = len(_jl.loads(tp.read_text(encoding="utf-8")))
+    except Exception:  # noqa: BLE001
+        pass
+
+    # ── ESDB ──────────────────────────────────────────────────────────────────
+    esdb_ok, esdb_records = True, 0
+    try:
+        from chronomemory import ChronoStore
+
+        wal = root / ".chronomemory" / "events.wal"
+        if wal.exists():
+            with ChronoStore(root) as store:
+                esdb_ok = store.chain_valid()
+                esdb_records = store.record_count()
+    except Exception:  # noqa: BLE001
+        pass
+
+    # ── Recent work items + last preflight from LEDGER.md ─────────────────────
+    recent_wis: list[str] = []
+    last_preflight = ""
+    try:
+        ledger_candidates = ["docs/LEDGER.md", "LEDGER.md"]
+        for cand in ledger_candidates:
+            lp = root / cand
+            if lp.exists():
+                text = lp.read_text(encoding="utf-8", errors="ignore")
+                wis = re.findall(r"\bWI-[A-F0-9]{8}\b", text)
+                seen: set[str] = set()
+                for wi in reversed(wis):
+                    if wi not in seen:
+                        seen.add(wi)
+                        recent_wis.insert(0, wi)
+                    if len(seen) >= 3:
+                        break
+                pf = re.findall(r"preflight accepted[^\n]{0,80}", text)
+                if pf:
+                    last_preflight = pf[-1]
+                break
+    except Exception:  # noqa: BLE001
+        pass
+
+    payload: dict[str, Any] = {
+        "ts": ts,
+        "project": project_name,
+        "phase": phase_key,
+        "phase_label": f"{phase_emoji} {phase_label}",
+        "phase_pct": phase_pct,
+        "health": "clean" if health_ok else f"{audit_failed} issues",
+        "audit_failed": audit_failed,
+        "req_count": req_count,
+        "test_count": test_count,
+        "esdb_records": esdb_records,
+        "esdb_chain_valid": esdb_ok,
+        "recent_wis": recent_wis,
+        "last_preflight": last_preflight,
+        "anchor": f"SPECSMITH-ANCHOR-{ts}",
+    }
+
+    if as_json:
+        click.echo(_json.dumps(payload, indent=2))
+        return
+
+    # ── Human-readable anchor block ───────────────────────────────────────────
+    # Designed to be compact and survive context summarization.
+    hbar = "\u2550" * 57  # ═══…
+    vbar = "\u2551"  # ║
+    health_icon = "\u2713" if health_ok else "\u2717"
+    esdb_icon = "\u2713" if esdb_ok else "\u2717"
+    wi_str = ", ".join(recent_wis) if recent_wis else "none seen"
+
+    console.print(f"[bold cyan]\u2554{hbar}\u2557[/bold cyan]")
+    console.print(f"[bold cyan]{vbar}[/bold cyan] GOVERNANCE ANCHOR  {ts}")
+    console.print(f"[bold cyan]{vbar}[/bold cyan] Project : [bold]{project_name}[/bold]")
+    console.print(
+        f"[bold cyan]{vbar}[/bold cyan] Phase   : {phase_emoji} {phase_label} ({phase_pct}%)"
+    )
+    health_str = (
+        f"[green]{health_icon} clean[/green]"
+        if health_ok
+        else f"[red]{health_icon} {audit_failed} issues[/red]"
+    )
+    console.print(f"[bold cyan]{vbar}[/bold cyan] Health  : {health_str}")
+    console.print(
+        f"[bold cyan]{vbar}[/bold cyan] REQs    : {req_count}   TESTs: {test_count}"
+        f"   ESDB: {esdb_records} records ({esdb_icon} chain)"
+    )
+    console.print(f"[bold cyan]{vbar}[/bold cyan] WIs     : {wi_str}")
+    if last_preflight:
+        pf_short = last_preflight[:55]
+        console.print(f"[bold cyan]{vbar}[/bold cyan] Preflight: {pf_short}")
+    console.print(f"[bold cyan]\u255a{hbar}\u255d[/bold cyan]")
+    console.print(
+        "[dim]Include this block verbatim in any context summary "
+        r"(\`specsmith checkpoint\` re-generates it).[/dim]"
+    )
+
+
 @main.command(name="session-end")
 @click.option("--project-dir", type=click.Path(exists=True), default=".")
 def session_end_cmd(project_dir: str) -> None:

{specsmith-0.11.3.dev433 → specsmith-0.11.3.dev436}/src/specsmith/config.py

@@ -66,6 +66,14 @@ class ProjectType(str, Enum):
     EMBEDDED_PYTHON_HMI = "embedded-python-hmi"  # #109: hardware-interfacing kiosk/HMI
     RESEARCH_PYTHON = "research-python"  # #153: experiment/research packages (no CLI)
     SAFETY_CRITICAL = "safety-critical"  # #129: IEC 60204-1/62061/61508 safety-critical
+    # IP / Patent
+    PATENT_PROSECUTION = "patent-prosecution"  # #177: IP prosecution with USPTO MCP lifecycle
+    # Modern web frameworks
+    NEXTJS_APP = "nextjs-app"  # Next.js / React full-stack app
+    NUXT_APP = "nuxt-app"  # Nuxt.js / Vue full-stack app
+    SVELTEKIT_APP = "sveltekit-app"  # SvelteKit app
+    REMIX_APP = "remix-app"  # Remix full-stack React app
+    ASTRO_SITE = "astro-site"  # Astro static/SSR site
 
 
 class Platform(str, Enum):
@@ -194,6 +202,67 @@ class ProjectConfig(BaseModel):
         ),
     )
 
+    # 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.
+    fallback_type: str = Field(
+        default="",
+        description=(
+            "Fallback project type for scaffold generation when `type` is not yet "
+            "supported by the installed specsmith version (e.g. 'spec-document' as "
+            "fallback for 'patent-prosecution')."
+        ),
+    )
+
+    # IP prosecution fields (used when type == 'patent-prosecution')
+    provisional_app_number: str = Field(
+        default="", description="USPTO provisional application number (e.g. '63/980,251')"
+    )
+    provisional_filed_date: str = Field(
+        default="", description="Date the provisional was filed (YYYY-MM-DD)"
+    )
+    non_provisional_deadline: str = Field(
+        default="",
+        description="12-month non-provisional conversion deadline (YYYY-MM-DD)",
+    )
+    entity_status: str = Field(default="", description="USPTO entity status: small, micro, large")
+    assignee: str = Field(default="", description="Patent assignee / rights holder")
+    counsel: str = Field(default="", description="Patent counsel firm name")
+    inventors: list[dict[str, str]] = Field(
+        default_factory=list,
+        description="List of inventors with name and role keys",
+    )
+    ip_families: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description=(
+            "IP patent families. Each entry: {id, name, phase, provisional, themes, "
+            "anchor_spec, ...}."
+        ),
+    )
+    claim_themes: list[dict[str, Any]] = Field(
+        default_factory=list,
+        description=(
+            "Claim themes for the primary IP family. Each entry: {id, name, description, "
+            "risk, primary_comparator, last_par_run}."
+        ),
+    )
+    specs_dir: str = Field(
+        default="docs/ip/specs",
+        description="Normative specification directory for IP repos",
+    )
+    prosecution_dir: str = Field(
+        default="docs/ip/prosecution",
+        description="Prior-art protocol and prosecution planning directory",
+    )
+    strategy_dir: str = Field(
+        default="docs/ip/strategy",
+        description="IP strategy documents directory",
+    )
+    filings_dir: str = Field(
+        default="docs/ip/filings",
+        description="Immutable filed artifacts directory",
+    )
+
     # FPGA-specific
     fpga_vendor: str = Field(
         default="",
@@ -471,6 +540,14 @@ _TYPE_LABELS: dict[str, str] = {
     ProjectType.EMBEDDED_PYTHON_HMI: "Embedded Python HMI / kiosk (hardware-interfacing)",
     ProjectType.RESEARCH_PYTHON: "Research Python (experiments, no CLI distribution)",
     ProjectType.SAFETY_CRITICAL: "Safety-critical embedded (IEC 60204-1/62061/61508)",
+    # IP / Patent
+    ProjectType.PATENT_PROSECUTION: "Patent prosecution repository (USPTO IP lifecycle)",
+    # Modern web frameworks
+    ProjectType.NEXTJS_APP: "Next.js application (React + SSR/SSG)",
+    ProjectType.NUXT_APP: "Nuxt.js application (Vue + SSR/SSG)",
+    ProjectType.SVELTEKIT_APP: "SvelteKit application",
+    ProjectType.REMIX_APP: "Remix application (React + full-stack)",
+    ProjectType.ASTRO_SITE: "Astro site (static / SSR)",
 }
 
 _SECTION_REFS: dict[str, str] = {

{specsmith-0.11.3.dev433 → specsmith-0.11.3.dev436}/src/specsmith/migrations/__init__.py

@@ -113,6 +113,7 @@ class _MigrationRegistry:
             m003_compliance_init,
             m004_ledger_esdb,
             m005_agent_run_tool,
+            m006_session_governance,
         )
 
         instances: list[Migration] = [
@@ -121,6 +122,7 @@ class _MigrationRegistry:
             m003_compliance_init.ComplianceInitMigration(),
             m004_ledger_esdb.LedgerEsdbMigration(),
             m005_agent_run_tool.AgentRunToolMigration(),
+            m006_session_governance.SessionGovernanceMigration(),
         ]
         instances.sort(key=lambda m: m.version)
         self._migrations = instances

specsmith-0.11.3.dev436/src/specsmith/migrations/m006_session_governance.py

@@ -0,0 +1,230 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""M006 — Inject Session Governance Protocol into AGENTS.md.
+
+What this migration does
+------------------------
+Adds the mandatory ``## Session Governance Protocol`` section to AGENTS.md
+when it is absent. This section teaches any agent (Warp, Cursor, Claude,
+GPT, or any other chat surface) to:
+
+1. Run ``specsmith checkpoint`` at session start and emit the GOVERNANCE ANCHOR
+   as the first response.
+2. Gate every code change behind ``specsmith preflight``.
+3. Emit ``specsmith checkpoint`` every 8–10 turns as a heartbeat so governance
+   state survives context summarisation.
+4. Include the GOVERNANCE ANCHOR at the top of any context summary.
+5. Run ``specsmith save && specsmith kill-session`` at session end.
+
+This is the most impactful upgrade for preventing silent governance drift in
+long agentic sessions.
+
+Non-destructive:
+- AGENTS.md is backed up to ``.specsmith/agents.md.m006.bak`` before modification.
+- The migration is idempotent: re-running it when the section is already present
+  is a no-op.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from specsmith.migrations import Migration, MigrationResult
+
+# ---------------------------------------------------------------------------
+# Sentinel strings that indicate the section is already present
+# ---------------------------------------------------------------------------
+
+_SENTINELS = [
+    "specsmith checkpoint",
+    "Session Governance Protocol",
+    "GOVERNANCE ANCHOR",
+    "governance heartbeat",
+]
+
+# ---------------------------------------------------------------------------
+# Section text to inject
+# ---------------------------------------------------------------------------
+
+_SESSION_GOVERNANCE_SECTION = """
+## Session Governance Protocol
+
+This section is non-negotiable. Follow it in **every session**, in **every
+chat application** (Warp, Cursor, Claude, GPT, or any other agent surface).
+
+### Session start (run once, output result verbatim)
+
+```bash
+specsmith kill-session 2>/dev/null || true   # kill orphaned processes
+specsmith audit --project-dir .              # verify governance health
+specsmith sync --project-dir .              # confirm machine state
+specsmith checkpoint --project-dir .        # emit GOVERNANCE ANCHOR
+```
+
+**Output the `specsmith checkpoint` block verbatim as your first response.**
+
+### Before every code change
+
+```bash
+specsmith preflight "<describe the change>" --json
+```
+
+- `decision == "accepted"` → proceed; note the `work_item_id`.
+- `decision == "needs_clarification"` → surface the `instruction` first.
+- **Never make a code change without an accepted preflight.**
+
+### Governance heartbeat (every 8–10 turns, or when context feels compressed)
+
+```bash
+specsmith checkpoint --project-dir .
+```
+
+Output the GOVERNANCE ANCHOR block verbatim in your response, tagged:
+
+```
+⎠ GOVERNANCE ANCHOR:
+<paste checkpoint output here>
+```
+
+### When producing any context summary
+
+1. Run `specsmith checkpoint` first.
+2. Place the GOVERNANCE ANCHOR at the **top** of the summary.
+3. Never omit phase, work items, or health status from a summary.
+
+### Drift detection — if you cannot answer these from memory, you have drifted
+
+- What is the current AEE phase?
+- What work item is active?
+- What was the last preflight decision?
+- Is the audit currently healthy?
+
+If any answer is unknown: **run `specsmith checkpoint` and re-anchor immediately.**
+
+### Session end
+
+```bash
+specsmith save --project-dir .   # ESDB backup + commit + push
+specsmith kill-session           # stop governance-serve and tracked processes
+```
+
+Never end a session with uncommitted governance changes.
+
+### Quick reference
+
+| When | Command |
+|---|---|
+| Session start | `specsmith audit && specsmith sync && specsmith checkpoint` |
+| Before any code change | `specsmith preflight "<intent>" --json` |
+| Every 8–10 turns | `specsmith checkpoint` (output verbatim) |
+| Context summary | Checkpoint output at top |
+| Session end | `specsmith save && specsmith kill-session` |
+| Drift detected | `specsmith checkpoint` immediately |
+"""
+
+
+class SessionGovernanceMigration(Migration):
+    version = 6
+    title = "Inject Session Governance Protocol into AGENTS.md"
+    description = (
+        "Adds the mandatory Session Governance Protocol section to AGENTS.md so "
+        "any agent (Warp, Cursor, Claude, GPT) knows to emit specsmith checkpoint "
+        "at session start, gate changes behind preflight, and maintain heartbeat "
+        "anchors every 8-10 turns to prevent silent governance drift. "
+        "Non-destructive — AGENTS.md is backed up before modification."
+    )
+
+    def run(self, root: Path, *, dry_run: bool = False) -> MigrationResult:
+        result = MigrationResult(version=self.version, title=self.title, dry_run=dry_run)
+        messages: list[str] = []
+
+        agents_md = root / "AGENTS.md"
+        specsmith_dir = root / ".specsmith"
+
+        if not agents_md.exists():
+            messages.append("AGENTS.md not found — skipping.")
+            result.message = "  ".join(messages)
+            return result
+
+        current = agents_md.read_text(encoding="utf-8", errors="replace")
+
+        # Idempotency check — any sentinel means the section is present
+        if any(sentinel in current for sentinel in _SENTINELS):
+            messages.append("AGENTS.md already contains Session Governance Protocol — skipping.")
+            result.message = "  ".join(messages)
+            return result
+
+        if dry_run:
+            messages.append(
+                "Would inject Session Governance Protocol section into AGENTS.md "
+                "and back up to .specsmith/agents.md.m006.bak."
+            )
+            result.files_created.append(".specsmith/agents.md.m006.bak")
+            result.files_modified.append("AGENTS.md")
+            result.message = "  ".join(messages)
+            return result
+
+        # Back up
+        specsmith_dir.mkdir(parents=True, exist_ok=True)
+        bak = specsmith_dir / "agents.md.m006.bak"
+        bak.write_text(current, encoding="utf-8")
+        result.files_created.append(".specsmith/agents.md.m006.bak")
+
+        # Inject the section — find the best insertion point.
+        # Strategy: insert BEFORE the first existing ## section after the header
+        # (which is typically ## Session Bootstrap), so the governance protocol
+        # is at the very top of agent instructions.
+        insertion_marker = "## Session Bootstrap"
+        if insertion_marker in current:
+            # Insert the governance section AFTER Session Bootstrap (it depends
+            # on Bootstrap completing first).
+            bootstrap_pos = current.find(insertion_marker)
+            # Find the next ## heading after Bootstrap to insert before it
+            next_section_pos = current.find("\n## ", bootstrap_pos + len(insertion_marker))
+            if next_section_pos != -1:
+                # Insert between Bootstrap section and whatever comes next
+                patched = (
+                    current[:next_section_pos]
+                    + "\n"
+                    + _SESSION_GOVERNANCE_SECTION.strip()
+                    + "\n"
+                    + current[next_section_pos:]
+                )
+            else:
+                # Bootstrap is the last section — append after it
+                patched = current.rstrip() + "\n\n" + _SESSION_GOVERNANCE_SECTION.strip() + "\n"
+        else:
+            # No Bootstrap section — just append
+            separator = "\n\n---\n" if not current.endswith("\n\n") else "\n---\n"
+            patched = current + separator + _SESSION_GOVERNANCE_SECTION.strip() + "\n"
+
+        agents_md.write_text(patched, encoding="utf-8")
+        result.files_modified.append("AGENTS.md")
+        messages.append(
+            "Injected Session Governance Protocol section into AGENTS.md "
+            "(original backed up to .specsmith/agents.md.m006.bak)."
+        )
+
+        result.message = "  ".join(messages)
+        return result
+
+    def rollback(self, root: Path) -> MigrationResult:
+        """Restore AGENTS.md from the M006 backup."""
+        result = MigrationResult(version=self.version, title=self.title)
+        messages: list[str] = []
+
+        specsmith_dir = root / ".specsmith"
+        bak = specsmith_dir / "agents.md.m006.bak"
+        agents_md = root / "AGENTS.md"
+
+        if bak.exists():
+            agents_md.write_text(
+                bak.read_text(encoding="utf-8", errors="replace"), encoding="utf-8"
+            )
+            messages.append("Restored AGENTS.md from .specsmith/agents.md.m006.bak.")
+            result.files_modified.append("AGENTS.md")
+        else:
+            messages.append("No AGENTS.md backup found — cannot restore.")
+
+        result.message = "  ".join(messages)
+        return result