Make governance promises executable and visible

This binds docs, runtime receipts and progress summaries, integration contracts, approval coordination, plugin governance, audit surfaces, and user workflow evidence to executable checks.

Constraint: Existing staged work covered broad docs, scripts, runtime, and tests; kept fixes scoped to validation blockers.

Rejected: Reverting stricter plugin and symlink behavior | WS3/WS5 contracts establish those as security boundaries.

Confidence: high

Scope-risk: broad

Directive: Keep optional signing dependencies failure-tolerant so unrelated CLI commands can boot.

Tested: python3 -m ruff check .; python3 -m ruff format --check .; python3 -m mypy teaagent/; python3 -m pytest -q; python3 scripts/validate_docs_consistency.py; python3 scripts/detect_stale_plans.py; python3 scripts/refresh_competitive_docs.py --check; python3 scripts/audit_test_quality.py --fail-on severe; teaagent tool lint --root .; teaagent selftest --root .; python3 scripts/run_acceptance_tier.py --tier all; git diff --cached --check

Not-tested: Live provider/API smoke tests and real Sigstore signing; local Python 3.11 sigstore import fails against cryptography and is now treated as an optional unavailable dependency.

Author: johnteee

README.md

@@ -1,7 +1,26 @@
 # TeaAgent
 
+> **Last reviewed:** 2026-06-06
+> **Review trigger:** README feature claims, golden path, or provider count changes.
+
 Governance-first agent harness for autonomous coding tasks. Thin orchestration layer with tool governance, state boundaries, audit logging, and destructive-tool approval.
 
+**TeaAgent is not** a generic IDE agent clone or hosted cloud delegate. It is a local-first harness you operate — with explicit permission modes, hash-chained audit logs, and verification commands a security reviewer can run. See [When Not to Use TeaAgent](docs/guides/when-not-to-use-teaagent.md) for honest non-fit cases.
+
+## Governance-first harness
+
+| Pillar | What you get |
+| --- | --- |
+| **Permission matrix** | `read-only` → `workspace-write` → `prompt` → `allow` — not binary on/off |
+| **Audit trail** | Append-only JSONL per run, hash-chained, exportable for compliance review |
+| **Bounded runs** | Hard caps on iterations, tool calls, and estimated cost |
+| **Human gates** | Destructive tools require approval; subagent queues are durable and inspectable |
+| **Verify, don't trust** | `teaagent audit verify`, `doctor config-lint`, run receipts with audit health |
+
+Trust model: [Trust and Audit Whitepaper](docs/governance/trust-and-audit-whitepaper.md). Enterprise NIST mapping: [Security Whitepaper](docs/security-whitepaper.md).
+
+**Start by persona:** [Solo CLI](docs/guides/getting-started-solo-cli.md) · [Team operator](docs/guides/getting-started-team-operator.md) · [Tool/plugin author](docs/guides/getting-started-tool-plugin-author.md) · [Security reviewer](docs/guides/getting-started-security-reviewer.md)
+
 ## What makes it different
 
 | Feature | TeaAgent | Most agents |
@@ -12,7 +31,7 @@ Governance-first agent harness for autonomous coding tasks. Thin orchestration l
 | Cost cap | ✅ hard budget via `--max-estimated-cost-cents` | ❌ surprise bills |
 | Model/provider choice | ✅ multiple adapters | ❌ vendor locked |
 
-Enterprise evaluation artifact: `docs/security-whitepaper.md`.
+Enterprise evaluation artifact: [Trust and Audit Whitepaper](docs/governance/trust-and-audit-whitepaper.md) (NIST detail: [Security Whitepaper](docs/security-whitepaper.md)).
 
 ## Golden path (first hour)
 

docs/INDEX.md

@@ -1,6 +1,9 @@
 # TeaAgent Documentation Index
 # 2026-06-06
 
+> **Last reviewed:** 2026-06-06
+> **Review trigger:** New front-door docs, supersession links, or validation command changes.
+
 This is the curated front door for TeaAgent documentation. It is intentionally
 not an exhaustive file list. Use it to find the current source of truth, then
 follow dated evidence documents only when you need the reasoning trail.
@@ -14,6 +17,27 @@ follow dated evidence documents only when you need the reasoning trail.
 | What is the documentation operating model? | [Documentation Operating Model](governance/documentation-operating-model-2026-06-04.md) | Governance rulebook for claim types, TTL, owners, supersession, and CI guard targets. |
 | What should be done next? | [Documentation Optimization Master Plan](plans/documentation-optimization-master-plan-2026-06-04.md) | Execution plan for reducing drift and improving discoverability. |
 | What are the concrete work items? | [Documentation Optimization Work Items](work-log/documentation-optimization-work-items-2026-06-04.md) | Task ledger with priority, status, dependencies, and acceptance criteria. |
+| Exhaustive docs inventory (generated) | [Docs Inventory](generated/docs-inventory.md) | Deterministic catalog; not current truth — use this index table first. |
+| Documentation aging dashboard (generated) | [Docs Aging Dashboard](generated/docs-aging-dashboard.md) | Current-truth review freshness grouped by owner surface. |
+| Command snippet inventory (generated) | [Command Snippet Inventory](generated/command-snippet-inventory.md) | Guide command coverage vs smoke/manual registry. |
+
+## Status vocabulary
+
+Active indexes and work-item ledgers use the canonical states in
+[Document State Model](governance/document-state-model.md). When updating a
+ledger row, map legacy labels instead of introducing new synonyms:
+
+| Legacy label | Canonical state |
+| --- | --- |
+| OPEN | Active |
+| DONE / Complete / Closed | Fixed |
+| Pending | Proposed |
+| In Progress | Active |
+| PARTIAL | Partially fixed |
+| Stale | Superseded |
+
+Roadmap tables may keep horizon-specific wording (`In Progress`, `Pending`) but
+governance ledgers should prefer the canonical set above.
 
 ## Current Truth
 
@@ -36,8 +60,9 @@ follow dated evidence documents only when you need the reasoning trail.
 | June 4 total review | [Total Review Index](analysis/total-review-2026-06-04-INDEX.md) |
 | June 4 documentation critique | [Documentation Critical Questioning](reviews/documentation-critical-questioning-2026-06-04.md) |
 | June 1 daily-driver review package | [Daily-Driver Review Package Index](analysis/daily-driver-review-INDEX-2026-06-01.md) |
+| Active daily-driver finding closure | [Active Findings Status Ledger](analysis/active-findings-status-ledger-2026-06-06.md) |
 | Markdown governance review | [Markdown Status Review](analysis/markdown-status-review-2026-06-02.md) |
-| Competitor signal survey | [Competitor Signal Survey](analysis/competitor-signal-survey-2026-06-04.md) |
+| Competitor signal survey | [Competitor Signal Survey](analysis/competitor-signal-survey-2026-06-06.md) (June 4 snapshot: [2026-06-04](analysis/competitor-signal-survey-2026-06-04.md)) |
 | Product principles | [TeaAgent Product Principles](strategy/teaagent-product-principles-2026-06-04.md) |
 | Dynamic skill and long-result audit | [Dynamic Skill Generation And Long Result Audit](analysis/dynamic-skill-generation-and-long-result-audit-2026-06-05.md) |
 | RSS dynamic skill failure case study | [RSS Dynamic Skill Failure Case Study](analysis/rss-failure-case-study-2026-06-05.md) |
@@ -71,7 +96,9 @@ follow dated evidence documents only when you need the reasoning trail.
 | Post-fix re-audit | [Postfix Reaudit Process](processes/postfix-reaudit-process.md) |
 | Daily-driver verification | [Daily-Driver Verification](processes/daily-driver-verification.md) |
 | Daily-driver manual QA smoke | [Daily-Driver Manual QA Smoke](processes/daily-driver-manual-qa-smoke.md) |
-| Quarterly competitor refresh | [Release Checklist](release-checklist.md) |
+| Quarterly competitor refresh | [Quarterly Competitor Refresh Process](processes/quarterly-competitor-refresh.md) · [Release Checklist](release-checklist.md) |
+| Trust and audit whitepaper | [Trust and Audit Whitepaper](governance/trust-and-audit-whitepaper.md) |
+| When not to use TeaAgent | [When Not to Use TeaAgent](guides/when-not-to-use-teaagent.md) |
 
 ## Governance
 
@@ -83,6 +110,8 @@ follow dated evidence documents only when you need the reasoning trail.
 | [Documentation Taxonomy And Ownership](governance/doc-taxonomy-and-ownership.md) | Where each document type belongs and who owns it. |
 | [Documentation Maintenance Policy](governance/doc-maintenance-policy-2026-06-02.md) | Short policy for adding, updating, and validating docs. |
 | [Documentation Operating Model](governance/documentation-operating-model-2026-06-04.md) | Practical rules for claim classes, freshness windows, source-of-truth conflicts, and CI guard scope. |
+| [Documentation Audit Cadence](governance/documentation-audit-cadence-2026-06-06.md) | When to run docs gates and which evidence artifacts to keep. |
+| [Command Snippet Registry](governance/command-snippet-registry.md) | Smoke vs manual coverage for high-value guide commands. |
 | [Coverage Omit Ledger](governance/coverage-omit-ledger.md) | Governance ledger for files and directories omitted from test coverage reporting. |
 | [Architecture Decision Records](adr/README.md) | Index of ADRs and their current accepted/closed states. |
 
@@ -140,6 +169,7 @@ for current status.
 | Surface | Documentation |
 | --- | --- |
 | CLI | [CLI](cli.md) and [USAGE](USAGE.md) |
+| Conversation UX | [Chat Surface Semantics](guides/chat-surface-semantics.md) and [Background/Resume Vocabulary](guides/background-resume-vocabulary.md) |
 | TUI | [TUI Daily-Driver Guide](tui-daily-driver-guide.md) and [TUI Chat Reference](tui-chat-reference.md) |
 | Agent mode | [Agent Mode Operator Guide](agent-mode-operator-guide.md) |
 | APIs | [API Index](api/README.md) |

docs/USAGE.md

@@ -7,6 +7,9 @@ last_audit: 2026-06-01
 ---
 # TeaAgent Quick Start Guide
 
+> **Last reviewed:** 2026-06-06
+> **Review trigger:** CLI/TUI command behavior, permission modes, or surface recipes change.
+
 A beginner-friendly walkthrough from installation to your first agent run and chat session.
 
 **Docs map:** This file is the guided walkthrough. [README.md](../README.md) is the short golden path. [cli.md](cli.md) is the command reference.

docs/acceptance.md

@@ -1,6 +1,13 @@
 # Acceptance Coverage
 
-**Last reviewed:** 2026-06-05
+> **Claim class:** Current truth for acceptance/integration test inventory and count.
+>
+> **Owns:** How to run acceptance tests and the current passed-count guard target.
+>
+> **Does not own:** Full-suite CI results (see dated evidence) or roadmap priorities.
+>
+> **Review trigger:** Acceptance test inventory or count changes.
+> **Last reviewed:** 2026-06-06
 
 TeaAgent acceptance tests live under `tests/acceptance/` and verify
 user-facing workflows rather than isolated primitives. Integration tests live
@@ -23,7 +30,7 @@ acceptance flow writes the user TUI state file. In sandboxed environments, run
 them with permission to bind localhost ports and write the TeaAgent state
 directory.
 
-**Current acceptance test count: `442 passed`** (P0+P1+P2 streams finalized)
+**Current acceptance test count: `446 passed`** (P0+P1+P2 streams finalized)
 
 ## Acceptance Flows
 
@@ -143,7 +150,7 @@ directory.
 
 ## Current Status
 
-Acceptance collection currently reports `442` acceptance tests, matching the
+Acceptance collection currently reports `446` acceptance tests, matching the
 headline above. The last recorded supported-interpreter full-suite verification
 in the June 5 daily-driver finalization package reported `4265 passed, 0 failed, 6 skipped`
 on Python 3.14.4 (4265 = 4090 baseline + 175 new tests across P0–P2 workstreams). Treat that full-suite

docs/analysis/active-findings-status-ledger-2026-06-06.md

@@ -0,0 +1,80 @@
+# Active Findings Status Ledger
+# 2026-06-06
+
+> **Claim class:** Current truth for daily-driver finding closure status.
+>
+> **Owns:** Whether CG/AG/DS review findings from the June 1–4 passes are still
+> open, partially fixed, or verified closed.
+>
+> **Does not own:** Roadmap horizon ownership (`docs/roadmap-status.md`), ticket
+> execution steps (`docs/plans/ticket-plans/index.md`), or historical review
+> prose in dated analysis files.
+>
+> **Review trigger:** Finding closure status or new CG/AG/DS ids.
+> **Last reviewed:** 2026-06-06
+
+**Successor to:** [Daily-Driver Findings Status Ledger (2026-06-01)](daily-driver-findings-status-ledger-2026-06-01.md)
+
+When this ledger and a dated detail doc disagree on **status**, this ledger is
+authoritative. Dated detail docs remain evidence for reasoning and test names.
+
+## Roll-up (2026-06-06)
+
+| Bucket | Count | Notes |
+| --- | ---: | --- |
+| Fixed | 18 | Verified in code + named regression or acceptance tests |
+| Partially fixed | 1 | TASK-DD2-005 git sandbox — core lifecycle fixed; broader ACs deferred |
+| Active | 0 | No daily-driver defects remain open from the June 1 review package |
+
+## Finding rows
+
+| ID | Priority | State | Statement | Ticket / evidence | Verification |
+| --- | --- | --- | --- | --- | --- |
+| CG-01 | P0 | Fixed | REPL prints answer and branches on status | TICKET-12 / controller | `test_chat_repl_displays_answer` |
+| CG-02 | P0 | Fixed | `/undo` surgical via UndoJournal | TICKET-12 | `test_task002_undo_honesty.py` |
+| CG-03 (REPL) | P1 | Fixed | REPL cost accumulates | TICKET-12 | `test_task003_cost_truth.py` |
+| CG-04 | P1 | Fixed | Compaction on real observations | chat REPL | `chat_repl.py` compaction path |
+| CG-05 | P1 | Fixed | Shared controller on CLI and TUI | TICKET-12 | `test_task001_surface_parity.py` |
+| CG-06 | P1 | Fixed | TUI no clear-screen regression | TUI | `test_tui.py` |
+| CG-07 | P2 | Fixed | TUI compact is real | TUI | `test_tui.py` |
+| CG-08 | P2 | Fixed | Undo vocabulary aligned (journal-first) | TICKET-12 / TASK-DD2-006 | `test_task002_undo_honesty.py` |
+| CG-09 | P1 | Fixed | Suspend: honest copy, no branch switch | TICKET-16 Phase 1 | suspend tests in `test_cli_chat.py` |
+| CG-10 | P1 | Fixed | Suspend emits real audit event | TICKET-16 Phase 1 | suspend audit assertions |
+| CG-11 | P1 | Fixed | TUI `/cost` accumulates via controller | TICKET-12 | `test_tui_cost_shows_session_cost` |
+| CG-12 | P1 | Fixed | TUI adopted ChatSessionController | TICKET-12 | `test_cli_tui_surface_parity_flow` |
+| CG-13 | P2 | Fixed | Controller no longer swallows errors as mock | TICKET-13 | controller isinstance checks |
+| CG-14 | P3 | Fixed | Redundant suspension `audit_trail` removed | TICKET-15 | review JSON tests |
+| CG-15 | P2 | Fixed | TUI/REPL undo semantics aligned | TICKET-12 / TICKET-15 | surface parity + help text |
+| CG-16 | P1 | Fixed | Misleading cost state-injection test removed | TICKET-14 | active-path cost tests |
+| CG-17 | P1 | Fixed | Surface parity test exercises controller path | TICKET-12 | `test_task001_surface_parity.py` |
+| AG-01 | P1 | Fixed | `teaagent resume <repl-id>` round-trip | TICKET-16 Phase 2 | `test_repl_suspend_resume_roundtrip` |
+| AG-02 | P1 | Fixed | Background run no longer treats id as task | TICKET-16 | background UUID rejection test |
+| AG-03 | P2 | Fixed | Observations rehydrated on resume | TICKET-16 Phase 2 | suspend/resume roundtrip |
+| AG-04 | P2 | Fixed | Resume command vocabulary honest | TICKET-16 Phase 1 | chat help / suspend copy |
+| DS-01 | P1 | Fixed | TUI cost accumulation | TICKET-12 | `test_task003_cost_truth.py` |
+| DS-08 | P1 | Fixed | Resume after REPL suspend | TICKET-16 Phase 2 | `test_repl_suspend_resume_roundtrip` |
+| DS-11 | P1 | Fixed | Positional chat task forwarded to TUI | TASK-DD2-001 | `test_cli_chat.py` task forwarding |
+| DS-12 | P0 | Fixed | Empty-path approval rejected | TASK-DD2-004 | `test_empty_path_globs_rejected_ds12` |
+| TASK-DD2-005 | P1 | Partially fixed | Git sandbox lifecycle | TASK-DD2-005 plan | Core object preserved; broader ACs need human review |
+
+## Superseded June 1 rows
+
+The June 1 ledger marked CG-13, CG-14, CG-15, AG-01..04, and several guard-test
+gaps as OPEN. Those rows are **superseded** by the June 4 ticket closure pass
+documented in [Ticket Execution Plans](../plans/ticket-plans/index.md) and
+verified by the regression guards listed above.
+
+## Maintenance
+
+Update this ledger when:
+
+- A daily-driver finding reopens or a new review pass adds a CG/AG/DS id.
+- Ticket index status changes for TICKET-12..16 or TASK-DD2-* items.
+- User-facing docs change recommended chat, cost, undo, or resume behavior.
+
+Verification:
+
+```bash
+python3 scripts/validate_docs_consistency.py
+python3 -m pytest tests/test_docs_consistency.py -q
+```

docs/analysis/competitor-signal-survey-2026-06-04.md

@@ -1,5 +1,9 @@
 # Competitor Signal Survey - 2026-06-04
 
+> Supersession note, 2026-06-06: For the latest quarterly refresh, use
+> [Competitor Signal Survey (2026-06-06)](competitor-signal-survey-2026-06-06.md)
+> and [Competitor Self-Comparison Matrix (2026-06-06)](competitor-self-comparison-matrix-2026-06-06.md).
+
 ## Purpose
 
 This survey collects current competitor signals from official documentation, release notes, and community feedback. The goal is not to rank "best agent" in the abstract. The goal is to extract what TeaAgent should learn, what it should avoid, and which product shapes are now common enough to count as baseline expectations.

docs/analysis/competitor-signal-survey-2026-06-06.md

@@ -0,0 +1,72 @@
+# Competitor Signal Survey - 2026-06-06
+
+> **Claim class:** Dated evidence snapshot (quarterly refresh).
+>
+> **Supersedes:** [Competitor Signal Survey (2026-06-04)](competitor-signal-survey-2026-06-04.md)
+> for positioning claims after 2026-06-06.
+>
+> **Companion:** [Competitor Self-Comparison Matrix (2026-06-06)](competitor-self-comparison-matrix-2026-06-06.md)
+> for source-backed row-by-row comparison.
+
+## Purpose
+
+Refresh competitor signals from official documentation checked on 2026-06-06.
+This pass emphasizes remote async agents, IDE-native UX, plan/spec separation,
+and audit/compliance lanes — the patterns TeaAgent must either match in UX or
+win on with provable governance.
+
+## Method
+
+- Official docs and upstream pages are primary evidence.
+- Community posts remain secondary signals.
+- Volatile metrics (stars, pricing tiers) are omitted unless sourced on the
+  review date.
+
+## Market shifts since June 4
+
+1. **Remote async agents** are now table stakes for Codex, Copilot cloud agent,
+   Cursor background agents, Kiro autonomous mode, Devin, and Jules — not
+   optional premium features.
+2. **IDE-native entry** (Cursor, Windsurf/Cascade, Cline, Copilot) sets the
+   daily-driver bar higher than terminal-only onboarding.
+3. **Plan/spec before write** (Cline Plan/Act, Kiro specs, Claude subagents,
+   OpenCode permissioned agents) is the expected mental model.
+4. **Audit/compliance** (Codex Compliance API, Devin enterprise audit logs,
+   GitHub PR/session logs) is becoming a purchase criterion — TeaAgent's
+   hash-chained audit is a strategic lane if made visible.
+
+## Core competitor lessons (unchanged thesis)
+
+| Project | TeaAgent lesson |
+| --- | --- |
+| Pi.dev | Adopt malleability; reject YOLO-default security. |
+| OpenCode | Closest terminal threat — governance must be visible, not buried. |
+| Claude Code | Full engineering loop expected; fake success is punished quickly. |
+| Codex | Benchmark async handoff, review UX, and compliance surfaces. |
+| Aider | Borrow git-native clarity for file targets and undo. |
+| OpenHands | Safety language must match sandbox reality. |
+| GitHub Copilot cloud agent | Do not compete on GitHub distribution; build adapters with TeaAgent audit exports. |
+| Cursor / Cline / Kiro | IDE and plan/act receipts are UX targets, not reasons to abandon local-first governance. |
+
+## TeaAgent implications (2026-06-06)
+
+1. Keep local-first and provider-agnostic positioning — but stop implying remote
+   readiness until WS2 safety gates pass.
+2. Make run receipts, approval selectors, and cost taxonomy user-visible (WS1).
+3. Treat audit/compliance as the primary public story once durability gates pass.
+4. Refresh competitor docs quarterly or before release planning claims.
+
+## Risks
+
+- Official docs overstate maturity (especially cloud/enterprise surfaces).
+- Competitor shutdowns (for example Roo Code product wind-down) can invalidate
+  prior comparisons quickly.
+- Remote-agent UX moves faster than governance hardening.
+
+## Sources (checked 2026-06-06)
+
+See the full source map in
+[competitor-self-comparison-matrix-2026-06-06.md](competitor-self-comparison-matrix-2026-06-06.md).
+
+Landscape survey artifact for matrix generation:
+[scripts/refresh_agent_readme_survey.md](../../scripts/refresh_agent_readme_survey.md)

docs/analysis/daily-driver-findings-status-ledger-2026-06-01.md

@@ -1,6 +1,12 @@
 # Daily-Driver Findings Status Ledger (All Passes)
 # 2026-06-01
 
+> Supersession note, 2026-06-06: This file is historical evidence from the
+> June 1 review pass. For current finding closure status, use
+> [Active Findings Status Ledger (2026-06-06)](active-findings-status-ledger-2026-06-06.md).
+> Ticket execution state lives in
+> [Ticket Execution Plans](../plans/ticket-plans/index.md).
+
 **Why.** Four review passes produced findings CG-01…CG-17 and AG-01…AG-04 across many
 docs. This is the single page that answers "where does everything stand right now" —
 status, owning ticket, guard test, and one-line evidence — re-anchored against current