feat: M006 session governance migration, checkpoint command, modern web types, docs

M006 migration — auto-inject Session Governance Protocol into AGENTS.md:
- Detects 4 sentinel strings; no-op when already present (idempotent)
- Injects heartbeat + preflight gate + drift detection + checkpoint-in-summary
  section AFTER Session Bootstrap, BEFORE next ## heading
- Backs up AGENTS.md to .specsmith/agents.md.m006.bak before patching
- Runs automatically via specsmith migrate-project and specsmith upgrade --full
- Registered as version=6 in MigrationRegistry

specsmith checkpoint command (REQ-351):
- Best-effort: phase, audit health, REQ/TEST counts, ESDB chain, recent WIs,
  last preflight — never fails even on projects with no ESDB or LEDGER
- --json: structured payload for machine consumers
- Human output: bordered GOVERNANCE ANCHOR block with footer instruction

Modern web framework project types (REQ-353):
- config.py: NEXTJS_APP, NUXT_APP, SVELTEKIT_APP, REMIX_APP, ASTRO_SITE
- tools.py: full ToolSet for each (eslint, tsc, vitest/jest, playwright, npm audit)
- _TYPE_LABELS: human-readable labels for all 5 types

AGENTS.md template:
- Session Governance Protocol section added to agents.md.j2 so all newly
  scaffolded/upgraded projects get the checkpoint + preflight + heartbeat rules

specsmith-session-governance skill (governance domain):
- Full session protocol as an installable skill
- Explains why agents drift, the three mandatory rules, drift self-check

Governance:
- REQ-351/352/353 + TEST-351/352/353 added and synced (308->311 reqs, 311->314 tests)
- REQUIREMENTS.md + TESTS.md regenerated
- api_surface.json fixture updated

GitHub issues filed for later:
- #179: Codity.ai — skill + CLI adapter + AGENTS rule (tri-layer)
- #180: Chumlab UI — skill-only initially (stealth, npm not yet public)

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

Author: tbitcs

.specsmith/requirements.json

@@ -3081,5 +3081,35 @@
     "test_ids": [
       "TEST-350"
     ]
+  },
+  {
+    "id": "REQ-351",
+    "title": "specsmith checkpoint Governance Anchor Command",
+    "description": "specsmith MUST provide a checkpoint CLI command that emits a compact GOVERNANCE ANCHOR summarising the current project state: project name (from scaffold.yml), AEE phase with readiness percentage, audit health and failed check count, REQ count, TEST count, ESDB record count with chain validity, up to 3 recent WI- identifiers from LEDGER.md, and the last preflight acceptance line. With --json it MUST emit a JSON payload containing ts, project, phase, phase_label, phase_pct, health, audit_failed, req_count, test_count, esdb_records, esdb_chain_valid, recent_wis, last_preflight, and anchor fields. Without --json it MUST emit a human-readable bordered GOVERNANCE ANCHOR block with a footer instructing agents to include it verbatim in any context summary. All data gathering MUST be best-effort (exceptions silently swallowed) so the command never fails even on projects with no ESDB or LEDGER.",
+    "source": "ARCHITECTURE.md §Session Governance Protocol",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-351"
+    ]
+  },
+  {
+    "id": "REQ-352",
+    "title": "M006 Session Governance Migration Auto-injects Protocol into AGENTS.md",
+    "description": "specsmith MUST include migration M006 (version=6) that detects whether AGENTS.md contains any of the sentinel strings 'specsmith checkpoint', 'Session Governance Protocol', 'GOVERNANCE ANCHOR', or 'governance heartbeat'. When none are present, M006 MUST back up AGENTS.md to .specsmith/agents.md.m006.bak and inject the full Session Governance Protocol section (heartbeat every 8-10 turns, preflight gate, drift detection checklist, checkpoint-in-summary rule, session end). M006 MUST be idempotent (re-running when section is present is a no-op), non-destructive (original always backed up), and registered in MigrationRegistry so it runs automatically via specsmith migrate-project and specsmith upgrade --full.",
+    "source": "ARCHITECTURE.md §Session Governance Protocol",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-352"
+    ]
+  },
+  {
+    "id": "REQ-353",
+    "title": "Modern Web Framework Project Types",
+    "description": "specsmith MUST support the following modern web framework project types in addition to the existing web-frontend and fullstack-js types: nextjs-app (Next.js / React with SSR/SSG, next lint, jest/playwright), nuxt-app (Nuxt.js / Vue, vitest, playwright), sveltekit-app (SvelteKit, vitest, playwright), remix-app (Remix React, vitest, playwright), astro-site (Astro static/SSR, vitest, playwright). Each MUST have a corresponding ToolSet entry in the tool registry with appropriate lint, typecheck, test, security, build, and format tools. Each MUST appear in _TYPE_LABELS with a human-readable label.",
+    "source": "ARCHITECTURE.md §Implemented Specsmith System",
+    "status": "implemented",
+    "test_ids": [
+      "TEST-353"
+    ]
   }
 ]

.specsmith/testcases.json

@@ -3419,5 +3419,38 @@
     "input": "YAML req with platform='linux', boundary='OS', confidence='0.9'; run_sync; inspect JSON",
     "expected_behavior": "JSON entry has platform, boundary, confidence keys; absent fields not present",
     "confidence": 0.9
+  },
+  {
+    "id": "TEST-351",
+    "title": "specsmith checkpoint Emits GOVERNANCE ANCHOR with Required Fields",
+    "description": "specsmith checkpoint --json on a project with scaffold.yml MUST exit 0 and return JSON containing ts (ISO-8601), project (string), phase (string), phase_label, phase_pct (int), health (string), audit_failed (int), req_count (int), test_count (int), esdb_records (int), esdb_chain_valid (bool), recent_wis (list), last_preflight (string), and anchor ('SPECSMITH-ANCHOR-' prefix). Without --json it MUST print a line containing 'GOVERNANCE ANCHOR'. Both forms MUST exit 0 on a project with no ESDB or LEDGER (best-effort, never throws).",
+    "requirement_id": "REQ-351",
+    "type": "cli",
+    "verification_method": "pytest",
+    "input": "specsmith checkpoint --json --project-dir tmp; specsmith checkpoint --project-dir tmp",
+    "expected_behavior": "JSON has all required fields; human output contains GOVERNANCE ANCHOR; exit 0 in both cases",
+    "confidence": 0.95
+  },
+  {
+    "id": "TEST-352",
+    "title": "M006 Injects Session Governance Protocol into AGENTS.md",
+    "description": "SessionGovernanceMigration().run(tmp_path) on a project with AGENTS.md that lacks 'specsmith checkpoint' MUST inject the Session Governance Protocol section, create .specsmith/agents.md.m006.bak, and return success=True with 'AGENTS.md' in files_modified. Re-running MUST be a no-op (idempotent). Running with dry_run=True MUST report what would change without writing. rollback() MUST restore AGENTS.md from the backup. M006 MUST appear in MigrationRegistry.all().",
+    "requirement_id": "REQ-352",
+    "type": "integration",
+    "verification_method": "pytest",
+    "input": "SessionGovernanceMigration().run(tmp_path); dry_run=True; rollback(); re-run after injection",
+    "expected_behavior": "Protocol injected; backup created; dry_run no writes; rollback restores; idempotent; registry includes v6",
+    "confidence": 0.95
+  },
+  {
+    "id": "TEST-353",
+    "title": "Modern Web Framework Types Have Tool Registry Entries",
+    "description": "list_tools_for_type(ProjectType.NEXTJS_APP) MUST return a ToolSet with 'next build' in build and 'eslint' in lint. list_tools_for_type(ProjectType.NUXT_APP) MUST have 'nuxt build' in build. list_tools_for_type(ProjectType.SVELTEKIT_APP) MUST have 'vite build'. list_tools_for_type(ProjectType.REMIX_APP) MUST have 'remix vite:build'. list_tools_for_type(ProjectType.ASTRO_SITE) MUST have 'astro build'. All five types MUST appear in _TYPE_LABELS with non-empty human-readable labels.",
+    "requirement_id": "REQ-353",
+    "type": "unit",
+    "verification_method": "pytest",
+    "input": "list_tools_for_type for each new type; check _TYPE_LABELS",
+    "expected_behavior": "Each type has correct build tool; all five types in _TYPE_LABELS",
+    "confidence": 0.95
   }
 ]

docs/REQUIREMENTS.md

@@ -2466,3 +2466,27 @@
 - **Source:** ARCHITECTURE.md §YAML-Native Governance Layer
 - **Test_Ids:** ['TEST-350']
 
+## REQ-351. specsmith checkpoint Governance Anchor Command
+- **ID:** REQ-351
+- **Title:** specsmith checkpoint Governance Anchor Command
+- **Description:** specsmith MUST provide a checkpoint CLI command that emits a compact GOVERNANCE ANCHOR summarising the current project state: project name (from scaffold.yml), AEE phase with readiness percentage, audit health and failed check count, REQ count, TEST count, ESDB record count with chain validity, up to 3 recent WI- identifiers from LEDGER.md, and the last preflight acceptance line. With --json it MUST emit a JSON payload containing ts, project, phase, phase_label, phase_pct, health, audit_failed, req_count, test_count, esdb_records, esdb_chain_valid, recent_wis, last_preflight, and anchor fields. Without --json it MUST emit a human-readable bordered GOVERNANCE ANCHOR block with a footer instructing agents to include it verbatim in any context summary. All data gathering MUST be best-effort (exceptions silently swallowed) so the command never fails even on projects with no ESDB or LEDGER.
+- **Status:** implemented
+- **Source:** ARCHITECTURE.md §Session Governance Protocol
+- **Test_Ids:** ['TEST-351']
+
+## REQ-352. M006 Session Governance Migration Auto-injects Protocol into AGENTS.md
+- **ID:** REQ-352
+- **Title:** M006 Session Governance Migration Auto-injects Protocol into AGENTS.md
+- **Description:** specsmith MUST include migration M006 (version=6) that detects whether AGENTS.md contains any of the sentinel strings 'specsmith checkpoint', 'Session Governance Protocol', 'GOVERNANCE ANCHOR', or 'governance heartbeat'. When none are present, M006 MUST back up AGENTS.md to .specsmith/agents.md.m006.bak and inject the full Session Governance Protocol section (heartbeat every 8-10 turns, preflight gate, drift detection checklist, checkpoint-in-summary rule, session end). M006 MUST be idempotent (re-running when section is present is a no-op), non-destructive (original always backed up), and registered in MigrationRegistry so it runs automatically via specsmith migrate-project and specsmith upgrade --full.
+- **Status:** implemented
+- **Source:** ARCHITECTURE.md §Session Governance Protocol
+- **Test_Ids:** ['TEST-352']
+
+## REQ-353. Modern Web Framework Project Types
+- **ID:** REQ-353
+- **Title:** Modern Web Framework Project Types
+- **Description:** specsmith MUST support the following modern web framework project types in addition to the existing web-frontend and fullstack-js types: nextjs-app (Next.js / React with SSR/SSG, next lint, jest/playwright), nuxt-app (Nuxt.js / Vue, vitest, playwright), sveltekit-app (SvelteKit, vitest, playwright), remix-app (Remix React, vitest, playwright), astro-site (Astro static/SSR, vitest, playwright). Each MUST have a corresponding ToolSet entry in the tool registry with appropriate lint, typecheck, test, security, build, and format tools. Each MUST appear in _TYPE_LABELS with a human-readable label.
+- **Status:** implemented
+- **Source:** ARCHITECTURE.md §Implemented Specsmith System
+- **Test_Ids:** ['TEST-353']
+

docs/TESTS.md

@@ -2902,3 +2902,36 @@
 - **Expected Behavior:** JSON entry has platform, boundary, confidence keys; absent fields not present
 - **Confidence:** 0.9
 
+## TEST-351. specsmith checkpoint Emits GOVERNANCE ANCHOR with Required Fields
+- **ID:** TEST-351
+- **Title:** specsmith checkpoint Emits GOVERNANCE ANCHOR with Required Fields
+- **Description:** specsmith checkpoint --json on a project with scaffold.yml MUST exit 0 and return JSON containing ts (ISO-8601), project (string), phase (string), phase_label, phase_pct (int), health (string), audit_failed (int), req_count (int), test_count (int), esdb_records (int), esdb_chain_valid (bool), recent_wis (list), last_preflight (string), and anchor ('SPECSMITH-ANCHOR-' prefix). Without --json it MUST print a line containing 'GOVERNANCE ANCHOR'. Both forms MUST exit 0 on a project with no ESDB or LEDGER (best-effort, never throws).
+- **Requirement ID:** REQ-351
+- **Type:** cli
+- **Verification Method:** pytest
+- **Input:** specsmith checkpoint --json --project-dir tmp; specsmith checkpoint --project-dir tmp
+- **Expected Behavior:** JSON has all required fields; human output contains GOVERNANCE ANCHOR; exit 0 in both cases
+- **Confidence:** 0.95
+
+## TEST-352. M006 Injects Session Governance Protocol into AGENTS.md
+- **ID:** TEST-352
+- **Title:** M006 Injects Session Governance Protocol into AGENTS.md
+- **Description:** SessionGovernanceMigration().run(tmp_path) on a project with AGENTS.md that lacks 'specsmith checkpoint' MUST inject the Session Governance Protocol section, create .specsmith/agents.md.m006.bak, and return success=True with 'AGENTS.md' in files_modified. Re-running MUST be a no-op (idempotent). Running with dry_run=True MUST report what would change without writing. rollback() MUST restore AGENTS.md from the backup. M006 MUST appear in MigrationRegistry.all().
+- **Requirement ID:** REQ-352
+- **Type:** integration
+- **Verification Method:** pytest
+- **Input:** SessionGovernanceMigration().run(tmp_path); dry_run=True; rollback(); re-run after injection
+- **Expected Behavior:** Protocol injected; backup created; dry_run no writes; rollback restores; idempotent; registry includes v6
+- **Confidence:** 0.95
+
+## TEST-353. Modern Web Framework Types Have Tool Registry Entries
+- **ID:** TEST-353
+- **Title:** Modern Web Framework Types Have Tool Registry Entries
+- **Description:** list_tools_for_type(ProjectType.NEXTJS_APP) MUST return a ToolSet with 'next build' in build and 'eslint' in lint. list_tools_for_type(ProjectType.NUXT_APP) MUST have 'nuxt build' in build. list_tools_for_type(ProjectType.SVELTEKIT_APP) MUST have 'vite build'. list_tools_for_type(ProjectType.REMIX_APP) MUST have 'remix vite:build'. list_tools_for_type(ProjectType.ASTRO_SITE) MUST have 'astro build'. All five types MUST appear in _TYPE_LABELS with non-empty human-readable labels.
+- **Requirement ID:** REQ-353
+- **Type:** unit
+- **Verification Method:** pytest
+- **Input:** list_tools_for_type for each new type; check _TYPE_LABELS
+- **Expected Behavior:** Each type has correct build tool; all five types in _TYPE_LABELS
+- **Confidence:** 0.95
+

docs/requirements/overflow.yml

@@ -294,3 +294,46 @@
     Absent fields MUST be omitted from the JSON entry (not written as null).
   source: ARCHITECTURE.md §YAML-Native Governance Layer
   status: implemented
+- id: REQ-351
+  title: specsmith checkpoint Governance Anchor Command
+  description: >-
+    specsmith MUST provide a checkpoint CLI command that emits a compact GOVERNANCE ANCHOR
+    summarising the current project state: project name (from scaffold.yml), AEE phase with
+    readiness percentage, audit health and failed check count, REQ count, TEST count,
+    ESDB record count with chain validity, up to 3 recent WI- identifiers from LEDGER.md,
+    and the last preflight acceptance line. With --json it MUST emit a JSON payload containing
+    ts, project, phase, phase_label, phase_pct, health, audit_failed, req_count, test_count,
+    esdb_records, esdb_chain_valid, recent_wis, last_preflight, and anchor fields.
+    Without --json it MUST emit a human-readable bordered GOVERNANCE ANCHOR block with a
+    footer instructing agents to include it verbatim in any context summary. All data
+    gathering MUST be best-effort (exceptions silently swallowed) so the command never
+    fails even on projects with no ESDB or LEDGER.
+  source: ARCHITECTURE.md §Session Governance Protocol
+  status: implemented
+- id: REQ-352
+  title: M006 Session Governance Migration Auto-injects Protocol into AGENTS.md
+  description: >-
+    specsmith MUST include migration M006 (version=6) that detects whether AGENTS.md
+    contains any of the sentinel strings 'specsmith checkpoint', 'Session Governance Protocol',
+    'GOVERNANCE ANCHOR', or 'governance heartbeat'. When none are present, M006 MUST
+    back up AGENTS.md to .specsmith/agents.md.m006.bak and inject the full Session Governance
+    Protocol section (heartbeat every 8-10 turns, preflight gate, drift detection checklist,
+    checkpoint-in-summary rule, session end). M006 MUST be idempotent (re-running when section
+    is present is a no-op), non-destructive (original always backed up), and registered in
+    MigrationRegistry so it runs automatically via specsmith migrate-project and
+    specsmith upgrade --full.
+  source: ARCHITECTURE.md §Session Governance Protocol
+  status: implemented
+- id: REQ-353
+  title: Modern Web Framework Project Types
+  description: >-
+    specsmith MUST support the following modern web framework project types in addition to
+    the existing web-frontend and fullstack-js types: nextjs-app (Next.js / React with
+    SSR/SSG, next lint, jest/playwright), nuxt-app (Nuxt.js / Vue, vitest, playwright),
+    sveltekit-app (SvelteKit, vitest, playwright), remix-app (Remix React, vitest,
+    playwright), astro-site (Astro static/SSR, vitest, playwright). Each MUST have a
+    corresponding ToolSet entry in the tool registry with appropriate lint, typecheck,
+    test, security, build, and format tools. Each MUST appear in _TYPE_LABELS with a
+    human-readable label.
+  source: ARCHITECTURE.md §Implemented Specsmith System
+  status: implemented

docs/tests/overflow.yml

@@ -380,3 +380,49 @@
   input: YAML req with platform='linux', boundary='OS', confidence='0.9'; run_sync; inspect JSON
   expected_behavior: JSON entry has platform, boundary, confidence keys; absent fields not present
   confidence: 0.9
+- id: TEST-351
+  title: specsmith checkpoint Emits GOVERNANCE ANCHOR with Required Fields
+  description: >-
+    specsmith checkpoint --json on a project with scaffold.yml MUST exit 0 and return
+    JSON containing ts (ISO-8601), project (string), phase (string), phase_label,
+    phase_pct (int), health (string), audit_failed (int), req_count (int), test_count (int),
+    esdb_records (int), esdb_chain_valid (bool), recent_wis (list), last_preflight (string),
+    and anchor ('SPECSMITH-ANCHOR-' prefix). Without --json it MUST print a line containing
+    'GOVERNANCE ANCHOR'. Both forms MUST exit 0 on a project with no ESDB or LEDGER
+    (best-effort, never throws).
+  requirement_id: REQ-351
+  type: cli
+  verification_method: pytest
+  input: specsmith checkpoint --json --project-dir tmp; specsmith checkpoint --project-dir tmp
+  expected_behavior: JSON has all required fields; human output contains GOVERNANCE ANCHOR; exit 0 in both cases
+  confidence: 0.95
+- id: TEST-352
+  title: M006 Injects Session Governance Protocol into AGENTS.md
+  description: >-
+    SessionGovernanceMigration().run(tmp_path) on a project with AGENTS.md that lacks
+    'specsmith checkpoint' MUST inject the Session Governance Protocol section, create
+    .specsmith/agents.md.m006.bak, and return success=True with 'AGENTS.md' in
+    files_modified. Re-running MUST be a no-op (idempotent). Running with dry_run=True
+    MUST report what would change without writing. rollback() MUST restore AGENTS.md
+    from the backup. M006 MUST appear in MigrationRegistry.all().
+  requirement_id: REQ-352
+  type: integration
+  verification_method: pytest
+  input: SessionGovernanceMigration().run(tmp_path); dry_run=True; rollback(); re-run after injection
+  expected_behavior: Protocol injected; backup created; dry_run no writes; rollback restores; idempotent; registry includes v6
+  confidence: 0.95
+- id: TEST-353
+  title: Modern Web Framework Types Have Tool Registry Entries
+  description: >-
+    list_tools_for_type(ProjectType.NEXTJS_APP) MUST return a ToolSet with 'next build'
+    in build and 'eslint' in lint. list_tools_for_type(ProjectType.NUXT_APP) MUST have
+    'nuxt build' in build. list_tools_for_type(ProjectType.SVELTEKIT_APP) MUST have
+    'vite build'. list_tools_for_type(ProjectType.REMIX_APP) MUST have 'remix vite:build'.
+    list_tools_for_type(ProjectType.ASTRO_SITE) MUST have 'astro build'. All five types
+    MUST appear in _TYPE_LABELS with non-empty human-readable labels.
+  requirement_id: REQ-353
+  type: unit
+  verification_method: pytest
+  input: list_tools_for_type for each new type; check _TYPE_LABELS
+  expected_behavior: Each type has correct build tool; all five types in _TYPE_LABELS
+  confidence: 0.95