specsmith 0.3.6.dev179__py3-none-any.whl → 0.3.6.dev182__py3-none-any.whl

specsmith/auditor.py

@@ -57,7 +57,8 @@ REQUIRED_FILES = [
 
 GOVERNANCE_FILES = [
     "docs/governance/RULES.md",
-    "docs/governance/WORKFLOW.md",
+    "docs/governance/SESSION-PROTOCOL.md",
+    "docs/governance/LIFECYCLE.md",
     "docs/governance/ROLES.md",
     "docs/governance/CONTEXT-BUDGET.md",
     "docs/governance/VERIFICATION.md",
@@ -331,7 +332,8 @@ def check_ledger_health(root: Path) -> list[AuditResult]:
 _DEFAULT_THRESHOLDS: dict[str, int] = {
     "AGENTS.md": 200,
     "docs/governance/RULES.md": 800,
-    "docs/governance/WORKFLOW.md": 400,
+    "docs/governance/SESSION-PROTOCOL.md": 400,
+    "docs/governance/LIFECYCLE.md": 200,
     "docs/governance/ROLES.md": 300,
     "docs/governance/CONTEXT-BUDGET.md": 300,
     "docs/governance/VERIFICATION.md": 400,
@@ -342,12 +344,12 @@ _DEFAULT_THRESHOLDS: dict[str, int] = {
 _TYPE_THRESHOLD_OVERRIDES: dict[str, dict[str, int]] = {
     "fpga-rtl": {
         "docs/governance/RULES.md": 1000,
-        "docs/governance/WORKFLOW.md": 500,
+        "docs/governance/SESSION-PROTOCOL.md": 500,
         "docs/governance/VERIFICATION.md": 600,
     },
     "yocto-bsp": {
         "docs/governance/RULES.md": 1000,
-        "docs/governance/WORKFLOW.md": 500,
+        "docs/governance/SESSION-PROTOCOL.md": 500,
         "docs/governance/VERIFICATION.md": 500,
     },
     "embedded-hardware": {
@@ -579,6 +581,43 @@ def check_trace_chain_integrity(root: Path) -> list[AuditResult]:
         return []
 
 
+def check_phase_readiness(root: Path) -> list[AuditResult]:
+    """Check AEE phase readiness (advisory — failed checks are warnings)."""
+    results: list[AuditResult] = []
+    scaffold_path = root / "scaffold.yml"
+    if not scaffold_path.exists():
+        return results
+
+    from specsmith.phase import PHASE_MAP, evaluate_phase, read_phase
+
+    phase_key = read_phase(root)
+    phase = PHASE_MAP.get(phase_key)
+    if not phase:
+        return results
+
+    passed, failed = evaluate_phase(phase, root)
+    pct = int(len(passed) / len(phase.checks) * 100) if phase.checks else 100
+
+    if failed:
+        results.append(
+            AuditResult(
+                name="phase-readiness",
+                passed=True,  # advisory — don't fail the audit
+                message=(
+                    f"Phase {phase.emoji} {phase.label}: {pct}% ready "
+                    f"({len(failed)} check(s) remaining: {', '.join(failed[:3])})"
+                ),
+            )
+        )
+    else:
+        msg = f"Phase {phase.emoji} {phase.label}: 100% ready"
+        if phase.next_phase:
+            msg += f" — run `specsmith phase next` to advance to {phase.next_phase}"
+        results.append(AuditResult(name="phase-readiness", passed=True, message=msg))
+
+    return results
+
+
 def run_audit(root: Path) -> AuditReport:
     """Run all audit checks and return a report."""
     report = AuditReport()
@@ -589,6 +628,7 @@ def run_audit(root: Path) -> AuditReport:
     report.results.extend(check_tool_configuration(root))
     report.results.extend(check_type_mismatch(root))
     report.results.extend(check_trace_chain_integrity(root))
+    report.results.extend(check_phase_readiness(root))
     return report
 
 

specsmith/cli.py

@@ -184,6 +184,11 @@ def init(config_path: str | None, output_dir: str, no_git: bool, guided: bool) -
     with open(config_out, "w") as fh:
         yaml.dump(cfg.model_dump(mode="json"), fh, default_flow_style=False, sort_keys=False)
 
+    # Ensure AEE phase is set (write_phase appends to scaffold.yml)
+    from specsmith.phase import write_phase
+
+    write_phase(target, "inception")
+
 
 def _load_config_with_inheritance(config_path: str) -> dict[str, object]:
     """Load scaffold.yml, merging parent config if `extends` is set."""
@@ -641,7 +646,8 @@ def import_project(
             "docs/ARCHITECTURE.md",
             "scaffold.yml",
             "docs/governance/RULES.md",
-            "docs/governance/WORKFLOW.md",
+            "docs/governance/SESSION-PROTOCOL.md",
+            "docs/governance/LIFECYCLE.md",
             "docs/governance/ROLES.md",
             "docs/governance/CONTEXT-BUDGET.md",
             "docs/governance/VERIFICATION.md",
@@ -682,6 +688,11 @@ def import_project(
             yaml.dump(config.model_dump(mode="json"), fh, default_flow_style=False, sort_keys=False)
         console.print("  [green]\u2713[/green] scaffold.yml")
 
+    # Ensure AEE phase is set
+    from specsmith.phase import write_phase
+
+    write_phase(root, "inception")
+
     # Guided architecture definition after import
     if guided:
         guided_files = _run_guided_architecture(config, root)
@@ -3442,14 +3453,25 @@ def phase_status(project_dir: str) -> None:
 
 
 @phase_group.command(name="list")
-def phase_list() -> None:
-    """List all AEE workflow phases in order."""
-    from specsmith.phase import PHASES
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+def phase_list(project_dir: str) -> None:
+    """List all AEE lifecycle phases with current position highlighted."""
+    from specsmith.phase import PHASES, read_phase
 
-    console.print("[bold]AEE Workflow Phases[/bold]\n")
+    root = Path(project_dir).resolve()
+    current = read_phase(root)
+
+    console.print("[bold]AEE Project Lifecycle[/bold]\n")
+    console.print(
+        "  inception \u2192 architecture \u2192 requirements \u2192 test_spec "
+        "\u2192 implementation \u2192 verification \u2192 release\n"
+    )
     for i, p in enumerate(PHASES, 1):
-        arrow = " → " if i < len(PHASES) else ""
-        console.print(f"  {i}. {p.emoji} [bold]{p.label}[/bold]  {p.description}{arrow}")
+        is_cur = p.key == current
+        marker = "[bold cyan]\u25b6[/bold cyan]" if is_cur else " "
+        label = f"[bold cyan]{p.label:<20s}[/bold cyan]" if is_cur else f"{p.label:<20s}"
+        console.print(f"  {marker} {i}. {p.emoji} {label} {p.description}")
+    console.print(f"\n  Current: [bold]{current}[/bold]")
 
 
 main.add_command(phase_group)

specsmith/differ.py

@@ -14,7 +14,8 @@ from specsmith.config import ProjectConfig
 
 _GOVERNANCE_FILES: list[tuple[str, str]] = [
     ("governance/rules.md.j2", "docs/governance/RULES.md"),
-    ("governance/workflow.md.j2", "docs/governance/WORKFLOW.md"),
+    ("governance/session-protocol.md.j2", "docs/governance/SESSION-PROTOCOL.md"),
+    ("governance/lifecycle.md.j2", "docs/governance/LIFECYCLE.md"),
     ("governance/roles.md.j2", "docs/governance/ROLES.md"),
     ("governance/context-budget.md.j2", "docs/governance/CONTEXT-BUDGET.md"),
     ("governance/verification.md.j2", "docs/governance/VERIFICATION.md"),
@@ -47,13 +48,19 @@ def run_diff(root: Path) -> list[tuple[str, str]]:
         lstrip_blocks=True,
     )
 
+    from specsmith.phase import PHASE_MAP, read_phase
     from specsmith.tools import get_tools
 
+    phase_key = read_phase(root)
+    phase_obj = PHASE_MAP.get(phase_key, PHASE_MAP["inception"])
     ctx = {
         "project": config,
         "today": date.today().isoformat(),
         "package_name": config.package_name,
         "tools": get_tools(config),
+        "aee_phase": phase_key,
+        "aee_phase_label": phase_obj.label,
+        "aee_phase_emoji": phase_obj.emoji,
     }
 
     results: list[tuple[str, str]] = []
@@ -101,11 +108,18 @@ def run_diff_html(root: Path) -> str:
         trim_blocks=True,
         lstrip_blocks=True,
     )
+    from specsmith.phase import PHASE_MAP, read_phase
+
+    phase_key = read_phase(root)
+    phase_obj = PHASE_MAP.get(phase_key, PHASE_MAP["inception"])
     ctx = {
         "project": config,
         "today": date.today().isoformat(),
         "package_name": config.package_name,
         "tools": get_tools(config),
+        "aee_phase": phase_key,
+        "aee_phase_label": phase_obj.label,
+        "aee_phase_emoji": phase_obj.emoji,
     }
 
     differ = difflib.HtmlDiff(wrapcolumn=80)

specsmith/exporter.py

@@ -138,7 +138,8 @@ def run_export(root: Path) -> str:
         "docs/TEST_SPEC.md",
         "docs/ARCHITECTURE.md",
         "docs/governance/RULES.md",
-        "docs/governance/WORKFLOW.md",
+        "docs/governance/SESSION-PROTOCOL.md",
+        "docs/governance/LIFECYCLE.md",
         "docs/governance/ROLES.md",
         "docs/governance/VERIFICATION.md",
     ]

specsmith/importer.py

@@ -877,8 +877,8 @@ def _extract_governance_sections(root: Path) -> dict[str, str]:
             "H2: All proposals require human approval.\n"
             "H3: The ledger is append-only.\n"
         ),
-        "workflow": (
-            "# Workflow\n\n"
+        "session-protocol": (
+            "# Session Protocol\n\n"
             "1. Propose changes\n2. Get approval\n"
             "3. Execute\n4. Verify\n5. Record in ledger\n"
         ),
@@ -935,7 +935,7 @@ def _extract_governance_sections(root: Path) -> dict[str, str]:
     # Classify each section into a governance category
     category_map: list[tuple[str, list[str]]] = [
         ("rules", _RULES_KW),
-        ("workflow", _WORKFLOW_KW),
+        ("session-protocol", _WORKFLOW_KW),
         ("roles", _ROLES_KW),
         ("context-budget", _CTX_KW),
         ("verification", _VERIFY_KW),
@@ -944,7 +944,7 @@ def _extract_governance_sections(root: Path) -> dict[str, str]:
 
     buckets: dict[str, list[tuple[str, str]]] = {
         "rules": [],
-        "workflow": [],
+        "session-protocol": [],
         "roles": [],
         "context-budget": [],
         "verification": [],
@@ -1007,7 +1007,7 @@ def _extract_governance_sections(root: Path) -> dict[str, str]:
     # Build output
     titles = {
         "rules": "# Rules",
-        "workflow": "# Workflow",
+        "session-protocol": "# Session Protocol",
         "roles": "# Roles",
         "context-budget": "# Context Budget",
         "verification": "# Verification",
@@ -1279,12 +1279,33 @@ def generate_overlay(
     # Otherwise use generic stubs.
     gov = _extract_governance_sections(target)
     _write("docs/governance/RULES.md", gov["rules"])
-    _write("docs/governance/WORKFLOW.md", gov["workflow"])
+    _write("docs/governance/SESSION-PROTOCOL.md", gov["session-protocol"])
+    _write(
+        "docs/governance/LIFECYCLE.md",
+        "# Project Lifecycle\n\n"
+        "See `specsmith phase show` for current phase readiness.\n"
+        "See `specsmith phase list` for the full AEE lifecycle.\n",
+    )
     _write("docs/governance/ROLES.md", gov["roles"])
     _write("docs/governance/CONTEXT-BUDGET.md", gov["context-budget"])
     _write("docs/governance/VERIFICATION.md", gov["verification"])
     _write("docs/governance/DRIFT-METRICS.md", gov["drift-metrics"])
 
+    # Migrate old WORKFLOW.md files if found
+    import shutil as _shutil
+
+    old_gov_wf = target / "docs" / "governance" / "WORKFLOW.md"
+    new_sp = target / "docs" / "governance" / "SESSION-PROTOCOL.md"
+    if old_gov_wf.exists() and not new_sp.exists():
+        _shutil.move(str(old_gov_wf), str(new_sp))
+        created.append(new_sp)
+    elif old_gov_wf.exists():
+        old_gov_wf.unlink()  # new file already exists, remove old one
+
+    old_doc_wf = target / "docs" / "WORKFLOW.md"
+    if old_doc_wf.exists():
+        old_doc_wf.unlink()  # replaced by LIFECYCLE.md + phase system
+
     # If existing AGENTS.md is oversized, back it up and replace with a hub.
     agents_path = target / "AGENTS.md"
     if agents_path.exists():
@@ -1306,8 +1327,10 @@ def generate_overlay(
                 "| ---- | ------- | ----------- |\n"
                 "| `docs/governance/RULES.md` | Hard rules, stop conditions, "
                 "project-specific rules | Every session start |\n"
-                "| `docs/governance/WORKFLOW.md` | Session lifecycle, "
+                "| `docs/governance/SESSION-PROTOCOL.md` | Session lifecycle, "
                 "save/push protocol | Every session start |\n"
+                "| `docs/governance/LIFECYCLE.md` | AEE phase lifecycle, "
+                "readiness gates | Every session start |\n"
                 "| `docs/governance/ROLES.md` | Agent role boundaries | "
                 "Every session start |\n"
                 "| `docs/governance/CONTEXT-BUDGET.md` | Context management | "

specsmith/phase.py

@@ -184,7 +184,7 @@ PHASES: list[Phase] = [
                 "ARCHITECTURE.md has content",
                 _file_min_lines("docs/ARCHITECTURE.md", 20),
             ),
-            PhaseCheck("AGENTS.md references architecture", _file_exists("AGENTS.md")),
+            PhaseCheck("AGENTS.md has substantial content", _file_min_lines("AGENTS.md", 30)),
             PhaseCheck("Trace vault has at least 1 seal", _trace_vault_exists()),
         ],
         commands=[
@@ -207,7 +207,7 @@ PHASES: list[Phase] = [
             PhaseCheck("At least 5 requirements defined", _req_count(5)),
             PhaseCheck("TEST_SPEC.md exists", _file_exists("docs/TEST_SPEC.md")),
             PhaseCheck("ARCHITECTURE.md exists", _file_exists("docs/ARCHITECTURE.md")),
-            PhaseCheck("Audit passes", _file_exists("AGENTS.md")),
+            PhaseCheck("REQUIREMENTS.md has content", _file_min_lines("REQUIREMENTS.md", 10)),
         ],
         commands=[
             "specsmith stress-test",
@@ -230,7 +230,7 @@ PHASES: list[Phase] = [
             ),
             PhaseCheck("TEST coverage ≥ 80 %", _test_spec_covers_reqs(80)),
             PhaseCheck("REQUIREMENTS.md has ≥ 5 REQs", _req_count(5)),
-            PhaseCheck("Audit passes", _file_exists("AGENTS.md")),
+            PhaseCheck("LEDGER.md exists", _file_exists("LEDGER.md")),
         ],
         commands=[
             "specsmith validate",
@@ -267,7 +267,7 @@ PHASES: list[Phase] = [
             PhaseCheck("ARCHITECTURE.md exists", _file_exists("docs/ARCHITECTURE.md")),
             PhaseCheck("TEST coverage ≥ 80 %", _test_spec_covers_reqs(80)),
             PhaseCheck("Trace vault has seals", _trace_vault_exists()),
-            PhaseCheck("Audit passes", _file_exists("AGENTS.md")),
+            PhaseCheck("Trace vault has ≥ 2 seals", _trace_vault_exists()),
             PhaseCheck("LEDGER.md has content", _file_min_lines("LEDGER.md", 10)),
         ],
         commands=[
@@ -286,8 +286,8 @@ PHASES: list[Phase] = [
         checks=[
             PhaseCheck("CHANGELOG.md has version entry", _changelog_has_version()),
             PhaseCheck("Trace vault has seals", _trace_vault_exists()),
-            PhaseCheck("Export report clean", _file_exists("docs/ARCHITECTURE.md")),
-            PhaseCheck("Audit passes", _file_exists("AGENTS.md")),
+            PhaseCheck("CHANGELOG.md exists", _file_exists("CHANGELOG.md")),
+            PhaseCheck("ARCHITECTURE.md exists", _file_exists("docs/ARCHITECTURE.md")),
         ],
         commands=[
             "specsmith export --output docs/COMPLIANCE.md",

specsmith/scaffolder.py

@@ -11,6 +11,7 @@ from pathlib import Path
 from jinja2 import Environment, PackageLoader, select_autoescape
 
 from specsmith.config import ProjectConfig, ProjectType
+from specsmith.phase import PHASE_MAP
 
 
 def scaffold_project(config: ProjectConfig, target: Path) -> list[Path]:
@@ -29,11 +30,16 @@ def scaffold_project(config: ProjectConfig, target: Path) -> list[Path]:
     from specsmith.tools import get_tools
 
     tools = get_tools(config)
+    phase_key = "inception"  # new projects always start at inception
+    phase_obj = PHASE_MAP[phase_key]
     ctx = {
         "project": config,
         "today": date.today().isoformat(),
         "package_name": config.package_name,
         "tools": tools,
+        "aee_phase": phase_key,
+        "aee_phase_label": phase_obj.label,
+        "aee_phase_emoji": phase_obj.emoji,
     }
 
     created: list[Path] = []
@@ -86,6 +92,11 @@ def scaffold_project(config: ProjectConfig, target: Path) -> list[Path]:
     save_budget(target, CreditBudget())  # unlimited by default
     created.append(target / ".specsmith" / "credit-budget.json")
 
+    # Set initial AEE phase in scaffold.yml
+    from specsmith.phase import write_phase
+
+    write_phase(target, "inception")
+
     # Git init
     if config.git_init:
         subprocess.run(  # noqa: S603
@@ -109,14 +120,14 @@ def _build_file_map(config: ProjectConfig) -> list[tuple[str, str]]:
         ("editorconfig.j2", ".editorconfig"),
         # Modular governance
         ("governance/rules.md.j2", "docs/governance/RULES.md"),
-        ("governance/workflow.md.j2", "docs/governance/WORKFLOW.md"),
+        ("governance/session-protocol.md.j2", "docs/governance/SESSION-PROTOCOL.md"),
+        ("governance/lifecycle.md.j2", "docs/governance/LIFECYCLE.md"),
         ("governance/roles.md.j2", "docs/governance/ROLES.md"),
         ("governance/context-budget.md.j2", "docs/governance/CONTEXT-BUDGET.md"),
         ("governance/verification.md.j2", "docs/governance/VERIFICATION.md"),
         ("governance/drift-metrics.md.j2", "docs/governance/DRIFT-METRICS.md"),
         # Project docs
         ("docs/architecture.md.j2", "docs/ARCHITECTURE.md"),
-        ("docs/workflow.md.j2", "docs/WORKFLOW.md"),
         ("docs/requirements.md.j2", "docs/REQUIREMENTS.md"),
         ("docs/test-spec.md.j2", "docs/TEST_SPEC.md"),
         # Scripts