specsmith 0.11.3.dev435__tar.gz → 0.11.3.dev436__tar.gz

{specsmith-0.11.3.dev435/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.dev435
+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.dev435 → specsmith-0.11.3.dev436}/pyproject.toml

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

@@ -68,6 +68,12 @@ class ProjectType(str, Enum):
     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):
@@ -536,6 +542,12 @@ _TYPE_LABELS: dict[str, str] = {
     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.dev435 → 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

{specsmith-0.11.3.dev435 → specsmith-0.11.3.dev436}/src/specsmith/skills/governance.py

@@ -293,6 +293,109 @@ print("Rust backend:", RUST_BACKEND)
 """
         ),
     ),
+    SkillEntry(
+        slug="specsmith-session-governance",
+        name="Specsmith Session Governance — drift prevention, heartbeat, preflight gate",
+        description=(
+            "Mandatory session protocol for any agent working in a specsmith-governed project: "
+            "initialization sequence, preflight gate before every change, governance heartbeat "
+            "every 8-10 turns, anchor-in-summary rule, and end-of-session save. "
+            "Works in any chat application without modifying the agent runtime."
+        ),
+        domain=SkillDomain.GOVERNANCE,
+        tags=[
+            "governance",
+            "session",
+            "drift",
+            "heartbeat",
+            "anchor",
+            "preflight",
+            "checkpoint",
+            "agents-md",
+            "context",
+        ],
+        prerequisites=["specsmith"],
+        body="""\
+# Specsmith Session Governance Skill
+
+This skill describes the **mandatory session protocol** for any agent working
+in a specsmith-governed project. It prevents silent drift and keeps governance
+state alive across context summarization without modifying the agent runtime.
+
+## Why agents drift
+When a conversation gets long, any chat application (Warp, Cursor, Claude,
+GPT) summarizes the history. That summary discards: the current work item ID,
+the last preflight decision, the project phase, and any uncommitted changes.
+The agent then operates on stale or invented governance state.
+
+## The fix: three rules
+
+### Rule 1 — Initialization (every session start)
+```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 and display the anchor
+```
+Output the checkpoint verbatim as your first response. This establishes the
+governance baseline that all subsequent work traces back to.
+
+### Rule 2 — Preflight gate (before EVERY proposed code change)
+```bash
+specsmith preflight "<describe the change you intend to make>" --json
+```
+- If `decision == "accepted"`: proceed with the work item ID in scope.
+- If `decision == "needs_clarification"`: surface the instruction to the user
+  before making any changes.
+- Never make a code change without an accepted preflight.
+
+### Rule 3 — Heartbeat (every 8-10 turns, or when context > 60%)
+```bash
+specsmith checkpoint --project-dir .
+```
+Output the GOVERNANCE ANCHOR block verbatim in your response. Tag it clearly:
+
+```
+⎠ GOVERNANCE ANCHOR (output of `specsmith checkpoint`):
+╔═════...
+║ GOVERNANCE ANCHOR  2026-05-19T22:43:04Z
+║ Project : specsmith
+...
+╚═════...
+```
+
+**When producing any context summary, ALWAYS include the most recent
+GOVERNANCE ANCHOR verbatim at the top of the summary.** The anchor is the
+minimum viable governance state that must survive summarization.
+
+## End of session
+```bash
+specsmith save --project-dir .    # ESDB backup + commit + push
+specsmith kill-session            # clean up processes
+```
+Never end a session with uncommitted governance changes.
+
+## Detecting drift (self-check)
+If you notice you cannot answer any of these from memory, you have drifted
+and MUST re-anchor immediately:
+- What is the current AEE phase?
+- What work item is active?
+- What was the last preflight decision?
+- Is the audit currently healthy?
+
+Run `specsmith checkpoint` and copy the output into your response.
+
+## 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 | Include checkpoint output at top |
+| Session end | `specsmith save && specsmith kill-session` |
+| Drift detected | `specsmith checkpoint` immediately |
+""",
+    ),
     SkillEntry(
         slug="gh-ci-polling",
         name="GitHub Actions CI polling — smart wait with gh CLI",

specsmith-0.11.3.dev436/src/specsmith/templates/agents.md.j2

@@ -0,0 +1,109 @@
+# AGENTS.md — {{ project.name }}
+
+This project is governed by **specsmith**. These rules apply in **any** chat
+application (Warp, Cursor, Claude, GPT, or any other agent surface).
+
+## Session Bootstrap
+
+Run these steps at the start of **every** session before touching any code:
+
+```bash
+# 0. Kill any orphaned processes from previous sessions
+specsmith kill-session 2>/dev/null || true
+
+# 1. Update specsmith (if this is specsmith itself, use editable source)
+pip install --pre --upgrade specsmith
+
+# 2. Migrate project scaffold if behind installed version
+specsmith migrate-project --project-dir .
+
+# 3. Verify governance health + sync machine state
+specsmith audit --project-dir .
+specsmith sync --project-dir .
+
+# 4. Emit the initial GOVERNANCE ANCHOR
+specsmith checkpoint --project-dir .
+```
+
+Output the `specsmith checkpoint` result verbatim as your **first response**.
+Only proceed once all steps complete without errors.
+
+## Session Governance Protocol
+
+This section is non-negotiable. Follow it in every session, in every
+chat application, regardless of context window size or summarization.
+
+### Before any code change
+
+```bash
+specsmith preflight "<describe the change>" --json
+```
+
+- `decision == "accepted"` → proceed; note the `work_item_id`.
+- `decision == "needs_clarification"` → surface the `instruction` to the user 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 as:
+
+```
+⎠ GOVERNANCE ANCHOR:
+<paste checkpoint output here>
+```
+
+### When producing any context summary
+
+1. Run `specsmith checkpoint` first.
+2. Place the full GOVERNANCE ANCHOR at the **top** of the summary.
+3. Never omit phase, work item IDs, or health status from a summary.
+
+This ensures governance state survives context window compression in any app.
+
+### Drift detection — if you can’t 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 Teardown
+
+```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 |
+
+## Governance data
+
+- Rules and state: `.specsmith/` and `.chronomemory/`
+- Before any action: `specsmith preflight "<describe what you want to do>"`
+- Emergency stop: `specsmith kill-session`
+
+Agents MUST defer to specsmith for ALL governance decisions.
+
+---
+
+**Project:** {{ project.name }}
+**Type:** {{ project.type_label }}
+**Platforms:** {{ project.platform_names | join(', ') }}
+**Phase:** {{ aee_phase_emoji }} {{ aee_phase_label }} (`specsmith phase` to check readiness)