Skip to content

Commit f7aa895

Browse files
johnteeejohnteee
committed
Documentation optimization pass: project state analysis, doc governance, and Phase 0→1 outlook
Consolidate project-state analysis findings into actionable documentation: - **Governance**: Add documentation-operating-model to formalize doc lifecycle - **Analysis**: Document project-state cross-review, total-review (claim verification, critique, future outlook, real situation), and documentation-state-review - **Strategy**: Add Phase 0→1 outlook document with transition criteria - **Security**: Add Phase 0 trust-repair risk brief - **Plans**: Add documentation-optimization master plan + work items, Phase 0 priority work items - **Reviews**: Add critical-questioning reviews for docs and project state - **Updates**: Refresh INDEX.md (root), modules/INDEX.md, daily-driver-current-status, roadmap-status, governance/README.md, ticket-plans/index.md, daily-driver/README.md, acceptance.md, doc-maintenance-policy Constraint: All new documents follow the existing date-stamped naming convention and state-model requirements. Tested: git diff --check; no code changes — documentation only. Confidence: high Scope-risk: narrow
1 parent f43d8ca commit f7aa895

25 files changed

Lines changed: 2252 additions & 11 deletions

‎docs/INDEX.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# TeaAgent Documentation Index
2+
# 2026-06-04
3+
4+
This is the curated front door for TeaAgent documentation. It is intentionally
5+
not an exhaustive file list. Use it to find the current source of truth, then
6+
follow dated evidence documents only when you need the reasoning trail.
7+
8+
## Start Here
9+
10+
| Need | Start here | Status rule |
11+
| --- | --- | --- |
12+
| What can a daily user trust today? | [Daily-Driver Current Status](daily-driver-current-status.md) | Current truth; update whenever TUI, chat, agent mode, approval, cost, undo, or resume behavior changes. |
13+
| What is the current documentation-state assessment? | [Documentation State Review](analysis/documentation-state-review-2026-06-04.md) | Current dated evidence for corpus shape, drift risks, and consolidation priorities. |
14+
| 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. |
15+
| 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. |
16+
| 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. |
17+
18+
## Current Truth
19+
20+
| Question | Canonical source |
21+
| --- | --- |
22+
| Current daily-driver behavior | [Daily-Driver Current Status](daily-driver-current-status.md) |
23+
| Acceptance flow inventory | [Acceptance Coverage](acceptance.md) |
24+
| Roadmap state | [Roadmap Status](roadmap-status.md) |
25+
| Ticket execution order | [Ticket Execution Plans](plans/ticket-plans/index.md) |
26+
| Module ownership and inspection paths | [Module Documentation Index](modules/INDEX.md) |
27+
| Release gates | [Release Checklist](release-checklist.md) and [Daily-Driver Release Gates](governance/daily-driver-release-gates-2026-06-02.md) |
28+
| Permission and approval behavior | [Permission And Approval Playbook](permission-and-approval-playbook.md) |
29+
| Operator trust model | [Operator Trust Model](operator-trust-model.md) |
30+
31+
## Evidence And Review
32+
33+
| Topic | Evidence package |
34+
| --- | --- |
35+
| June 4 project-state fact check | [Project State Cross-Review Fact Check](analysis/project-state-cross-review-fact-check-2026-06-04.md) |
36+
| June 4 total review | [Total Review Index](analysis/total-review-2026-06-04-INDEX.md) |
37+
| June 4 documentation critique | [Documentation Critical Questioning](reviews/documentation-critical-questioning-2026-06-04.md) |
38+
| June 1 daily-driver review package | [Daily-Driver Review Package Index](analysis/daily-driver-review-INDEX-2026-06-01.md) |
39+
| Markdown governance review | [Markdown Status Review](analysis/markdown-status-review-2026-06-02.md) |
40+
| Competitor signal survey | [Competitor Signal Survey](analysis/competitor-signal-survey-2026-06-04.md) |
41+
| Product principles | [TeaAgent Product Principles](strategy/teaagent-product-principles-2026-06-04.md) |
42+
43+
## Governance
44+
45+
| Rule surface | Purpose |
46+
| --- | --- |
47+
| [Governance Index](governance/README.md) | Standards and process entry point. |
48+
| [Document State Model](governance/document-state-model.md) | Canonical state vocabulary for findings, risks, issues, tickets, and roadmap rows. |
49+
| [Risk Issue Roadmap Workflow](governance/risk-issue-roadmap-workflow.md) | Pipeline from finding to issue, ticket, roadmap, verification, and supersession. |
50+
| [Documentation Taxonomy And Ownership](governance/doc-taxonomy-and-ownership.md) | Where each document type belongs and who owns it. |
51+
| [Documentation Maintenance Policy](governance/doc-maintenance-policy-2026-06-02.md) | Short policy for adding, updating, and validating docs. |
52+
| [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. |
53+
54+
## Plans And Work
55+
56+
| Plan | Use it for |
57+
| --- | --- |
58+
| [Documentation Optimization Master Plan](plans/documentation-optimization-master-plan-2026-06-04.md) | Prioritizing documentation work by stability, UX, risk, and ROI. |
59+
| [Documentation Optimization Work Items](work-log/documentation-optimization-work-items-2026-06-04.md) | Concrete task execution ledger. |
60+
| [Daily-Driver Complete Work Plan](plans/daily-driver-complete-work-plan-risk-roi-2026-06-04.md) | Daily-driver risk, feasibility, ROI, and sequence. |
61+
| [Roadmap Work Items](work-log/roadmap-work-items-2026-06-04.md) | Product roadmap work items and acceptance criteria. |
62+
| [Phase 0 Priority Work Items](work-log/phase-0-priority-work-items-2026-06-04.md) | Trust-repair tasks derived from project-state review. |
63+
64+
## Security And Reliability
65+
66+
| Topic | Start here |
67+
| --- | --- |
68+
| Threat model | [Threat Model](threat-model.md) |
69+
| Security risk register | [Risk Register And Threat Model](security/risk-register-and-threat-model-2026-06-02.md) |
70+
| Phase 0 trust repair | [Phase 0 Trust Repair Risk Brief](security/phase-0-trust-repair-risk-brief-2026-06-04.md) |
71+
| FMEA | [FMEA](reliability/fmea-2026-06-02.md) |
72+
| Trust-sensitive invariants | [Trust Sensitive Invariants](reliability/trust-sensitive-invariants-2026-06-02.md) |
73+
| UX stability contract | [UX Stability Contract](ux-stability-contract.md) |
74+
75+
## Guides And References
76+
77+
| Surface | Documentation |
78+
| --- | --- |
79+
| CLI | [CLI](cli.md) and [USAGE](USAGE.md) |
80+
| TUI | [TUI Daily-Driver Guide](tui-daily-driver-guide.md) and [TUI Chat Reference](tui-chat-reference.md) |
81+
| Agent mode | [Agent Mode Operator Guide](agent-mode-operator-guide.md) |
82+
| APIs | [API Index](api/README.md) |
83+
| Module references | [Module Documentation Index](modules/INDEX.md) |
84+
| Tools | [Tool Authoring Guide](tool-authoring.md) |
85+
| Providers | [Provider Authoring Guide](provider-authoring.md) |
86+
87+
## Rules For Reading Dated Documents
88+
89+
- Dated analysis, reviews, surveys, audits, and work logs are evidence snapshots.
90+
- Stable entry points and ledgers own current truth.
91+
- If a dated document contradicts a stable current source, prefer the stable
92+
source and add a supersession note if the contradiction could mislead.
93+
- Test counts, full-suite claims, dependency audit results, and competitor
94+
observations must include a date, command, and commit or they should be
95+
treated as stale.
96+
- When adding a new document, link it from one active front door or explicitly
97+
mark it as archived evidence.
98+
99+
## Validation
100+
101+
After governance-sensitive documentation edits, run:
102+
103+
```bash
104+
python3 scripts/validate_docs_consistency.py
105+
python3 -m pytest tests/test_docs_consistency.py tests/acceptance/test_docs_acceptance_count_accuracy.py -q
106+
```

‎docs/acceptance.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -141,8 +141,12 @@ directory.
141141

142142
## Current Status
143143

144-
As of the latest local verification (2026-06-03), `python3 -m pytest -q` reports
145-
`3255 passed, 26 failed, 76 skipped`. The failures are primarily in automation webhook delivery, skill installation, provider matrix consistency, and other integration tests. 26 tests were skipped due to deep architectural issues (undo diff preview budget config, llm_conformance test config, deprecated ultrawork module, A2A circuit breaker timing, TUI feature implementation, file policy audit events, A2A federation flow). These are pre-existing issues unrelated to the recent safety fixes.
144+
Acceptance collection currently reports `441` acceptance tests, matching the
145+
headline above. The last recorded supported-interpreter full-suite verification
146+
in the June 4 total-review package reported `3355 passed, 0 failed, 22 skipped`
147+
on Python 3.12.8. Treat that full-suite number as a dated evidence snapshot, not
148+
as a substitute for re-running `python3 -m pytest -q` before a release or safety
149+
claim.
146150

147151
<!-- ACCEPTANCE_TIERS:START -->
148152

‎docs/analysis/daily-driver-review-INDEX-2026-06-01.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,32 @@ disagree, use the active status ledgers and the governance rules below:
1717
Document type ownership and source-of-truth rules.
1818
4. **`markdown-status-review-2026-06-02.md`** *(analysis)*
1919
`cx`/repo review of the Markdown corpus and recommended consolidation policy.
20+
5. **`../INDEX.md`** *(front door)*
21+
Curated documentation index for current truth, evidence, governance, plans,
22+
security, reliability, guides, and validation.
23+
6. **`../governance/documentation-operating-model-2026-06-04.md`** *(governance)*
24+
Claim classes, evidence hierarchy, freshness windows, guarded claims, and
25+
documentation definition of done.
26+
27+
## 2026-06-04 documentation-state optimization
28+
29+
This layer reviews the whole Markdown corpus as a trust surface and adds a
30+
plan for reducing status drift without deleting historical evidence.
31+
32+
1. **`documentation-state-review-2026-06-04.md`** *(analysis)*
33+
Current inventory, `cx` discovery facts, drift findings, front-door model,
34+
and consolidation recommendations.
35+
2. **`../reviews/documentation-critical-questioning-2026-06-04.md`** *(review)*
36+
Critical questions about volume, guarded docs, historical/current ambiguity,
37+
roadmap-risk drift, and user clarity.
38+
3. **`../governance/documentation-operating-model-2026-06-04.md`** *(governance)*
39+
Operating model for documentation claim classes, evidence hierarchy,
40+
freshness windows, guarded claims, merge policy, and DoD.
41+
4. **`../plans/documentation-optimization-master-plan-2026-06-04.md`** *(plans)*
42+
Prioritized P0/P1/P2 plan with ROI, risk, acceptance criteria, and exit
43+
conditions.
44+
5. **`../work-log/documentation-optimization-work-items-2026-06-04.md`** *(work log)*
45+
Concrete task ledger for documentation-current-truth work.
2046

2147
## 2026-06-02 expansion after further code improvements
2248

@@ -70,6 +96,23 @@ why behind the current priorities.
7096
8. **`../plans/daily-driver-complete-work-plan-risk-roi-2026-06-04.md`** *(plans)*
7197
Complete execution plan ranked by risk, feasibility, ROI, and strategic leverage.
7298

99+
## 2026-06-04 project-state cross-review
100+
101+
This layer fact-checks a broad external-style project review against the current
102+
repo and records the critique, trust-repair implications, outlook, and concrete
103+
Phase 0 work items.
104+
105+
1. **`project-state-cross-review-fact-check-2026-06-04.md`** *(analysis)*
106+
Commit-stamped metrics, confirmed claims, corrected claims, and evidence gaps.
107+
2. **`../reviews/project-state-critical-questioning-2026-06-04.md`** *(review)*
108+
Critical questions about approval authority, docs truth, test integrity, and optional dependency risk.
109+
3. **`../security/phase-0-trust-repair-risk-brief-2026-06-04.md`** *(security)*
110+
Phase 0 trust-boundary risk brief with P0/P1 risk refresh.
111+
4. **`../strategy/phase-0-to-phase-1-outlook-2026-06-04.md`** *(strategy)*
112+
Future outlook, investment view, and Phase 1 entry criteria.
113+
5. **`../work-log/phase-0-priority-work-items-2026-06-04.md`** *(work log)*
114+
Concrete work items, ordering, human-review gates, and done criteria.
115+
73116
## 2026-06-02 additional guide/module supplement
74117

75118
This supplement makes the June 2 findings easier to use day to day.

‎docs/analysis/documentation-state-review-2026-06-04.md‎

Lines changed: 210 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,210 @@
1+
# Documentation State Review
2+
# 2026-06-04
3+
4+
## Purpose
5+
6+
This review records the current state of TeaAgent's Markdown corpus and turns
7+
that state into concrete consolidation, governance, and UX recommendations. It
8+
is written as a current evidence snapshot, not as a replacement for historical
9+
audits.
10+
11+
The central question is:
12+
13+
> Can a daily user, maintainer, or future agent find the current truth quickly
14+
> without being misled by an older but plausible document?
15+
16+
## Scope And Method
17+
18+
Reviewed:
19+
20+
- Repository Markdown inventory and directory shape.
21+
- `cx overview docs --limit 120`.
22+
- `cx symbols --kind heading --name '*Status*' --limit 120`.
23+
- `cx symbols --kind heading --name '*Risk*' --limit 120`.
24+
- `cx symbols --kind heading --name '*Roadmap*' --limit 120`.
25+
- Current front doors: `docs/daily-driver-current-status.md`,
26+
`docs/analysis/daily-driver-review-INDEX-2026-06-01.md`,
27+
`docs/plans/ticket-plans/index.md`, `docs/roadmap-status.md`,
28+
`docs/modules/INDEX.md`, and `docs/governance/README.md`.
29+
- Current staged review package created on 2026-06-04.
30+
31+
Not reviewed:
32+
33+
- Every line of every Markdown file.
34+
- Full external competitor refresh.
35+
- Full link validation across all Markdown files.
36+
- Runtime truth of every risk row in module docs.
37+
38+
## Inventory Snapshot
39+
40+
| Signal | Current value | Evidence |
41+
| --- | ---: | --- |
42+
| Tracked Markdown files | 456 | `git ls-files '*.md'` |
43+
| Markdown files under `docs/` | 421 | `find docs -type f -name '*.md'` |
44+
| `docs/analysis` files | 62 | `cx overview docs --limit 120` |
45+
| `docs/plans` files | 43 | `cx overview docs --limit 120` |
46+
| `docs/modules` files | 103 | `cx overview docs --limit 120` |
47+
| `docs/governance` files | 15 | `cx overview docs --limit 120` |
48+
| Status-heading hits | 60 | `cx symbols --kind heading --name '*Status*' --limit 120` |
49+
| Risk-heading hits | 120 shown out of 133 | `cx symbols --kind heading --name '*Risk*' --limit 120` |
50+
| Roadmap-heading hits | 23 | `cx symbols --kind heading --name '*Roadmap*' --limit 120` |
51+
| Current collected tests | 3,379 | `/tmp/tea312/bin/python -m pytest --collect-only -q` |
52+
| Current acceptance collection | 441 | `/tmp/tea312/bin/python -m pytest tests/acceptance --collect-only -q` and acceptance collection guard |
53+
54+
The counts differ from older docs because the corpus is growing quickly and
55+
because different commands include different scopes. Future reports must name
56+
the counting method.
57+
58+
## Findings
59+
60+
### DSR-001: The corpus is large but highly structured
61+
62+
State: Active.
63+
64+
The documentation tree is not random. It has recognizable families: user
65+
guides, analysis, governance, plans, module docs, security, reliability, specs,
66+
decisions, and operations. The problem is not lack of structure. The problem is
67+
that structure has outgrown the reader's ability to infer current truth from
68+
date alone.
69+
70+
Recommendation: preserve dated evidence, add stronger front doors, and avoid
71+
mass merging historical reviews.
72+
73+
### DSR-002: Current-truth docs and evidence docs are not visually distinct enough
74+
75+
State: Active.
76+
77+
Files such as `daily-driver-current-status.md` are current truth. Files such as
78+
dated audits and review packages are evidence snapshots. Both appear side by
79+
side in search and indexes, which means a reader can easily treat old evidence
80+
as a current instruction.
81+
82+
Recommendation: use `docs/INDEX.md` and supersession notes to mark current
83+
truth surfaces clearly.
84+
85+
### DSR-003: `docs/acceptance.md` had a high-trust contradiction
86+
87+
State: Fixed in this documentation pass.
88+
89+
The headline correctly said `441 passed`, but the body still stated an older
90+
full-suite failure result from 2026-06-03. This was dangerous because
91+
`docs/acceptance.md` is guarded by tests, and a reader could reasonably assume
92+
all status claims in that file were guarded.
93+
94+
Change made: the stale failure paragraph now separates acceptance collection
95+
from the last recorded supported-interpreter full-suite evidence.
96+
97+
Follow-up: add a prose-claim guard for full-suite status phrases.
98+
99+
### DSR-004: The total-review package needed cleanup before becoming durable evidence
100+
101+
State: Fixed in this documentation pass.
102+
103+
The staged total-review package contained non-English labels and stray closing
104+
tags from generation. It also mixed measured-baseline facts with current-HEAD
105+
phrasing.
106+
107+
Change made: the package now uses English headings, removes stray tags, and
108+
labels its `4695d46` full-suite evidence as a measured baseline while recording
109+
the current documentation-pass inventory separately.
110+
111+
### DSR-005: `docs/modules/INDEX.md` was a useful generated map with stale status edges
112+
113+
State: Partially fixed.
114+
115+
The module index is valuable as a map, but its generated risk summary and old
116+
"known P0/P1 bugs" section can mislead readers if treated as live closure
117+
truth.
118+
119+
Change made: added a supersession note and replaced the stale bug list with
120+
current front-door pointers.
121+
122+
Follow-up: regenerate the module index or split it into "module map" and
123+
"module risk inventory" so generated historical risk rows do not masquerade as
124+
current status.
125+
126+
### DSR-006: Status, risk, and roadmap claims are spread across many valid files
127+
128+
State: Active.
129+
130+
`cx` found 60 status-heading hits, 133 risk-heading hits, and 23 roadmap-heading
131+
hits. This is not automatically bad: ADRs, module risks, FMEA, roadmap, and
132+
ticket plans all need their own local views. It becomes bad when those local
133+
views compete to answer the same current-truth question.
134+
135+
Recommendation: keep local views, but require upward links for P0/P1 risks and
136+
one canonical source of truth for each status question.
137+
138+
### DSR-007: The current validators are necessary but insufficient
139+
140+
State: Active.
141+
142+
`validate_docs_consistency.py` and the acceptance-count guard catch important
143+
drift, but they do not parse most prose status claims. The `acceptance.md`
144+
contradiction proves the gap: a test can pass while a nearby paragraph is stale.
145+
146+
Recommendation: add a small guarded-claim registry for volatile facts such as
147+
test counts, provider counts, dependency audit results, full-suite results, and
148+
release claims.
149+
150+
### DSR-008: Roadmap status needs fresher connection to documentation work
151+
152+
State: Active.
153+
154+
`docs/roadmap-status.md` is canonical, but it was last updated before the June 4
155+
documentation-state review. H0 claim and risk hygiene should explicitly include
156+
documentation-current-truth work.
157+
158+
Recommendation: update H0 rows to link this documentation optimization package
159+
and add a doc-vs-HEAD guard as a named roadmap item.
160+
161+
### DSR-009: More documentation is still useful, but only when it reduces future search
162+
163+
State: Active.
164+
165+
The user requested more plans, risks, surveys, and work items. That is useful
166+
only if each new document either becomes a front door, records dated evidence,
167+
or turns ambiguity into executable work.
168+
169+
Recommendation: every new doc must declare whether it is current truth,
170+
evidence, plan, governance, or work log.
171+
172+
## Current Front-Door Model
173+
174+
| Reader question | Current front door | Needed improvement |
175+
| --- | --- | --- |
176+
| What should I use today? | `docs/daily-driver-current-status.md` | Keep short and current; avoid historical caveats. |
177+
| What happened in the daily-driver review? | `docs/analysis/daily-driver-review-INDEX-2026-06-01.md` | Link newer total-review and documentation-state packages. |
178+
| What is the current roadmap? | `docs/roadmap-status.md` | Add June 4 documentation work and H0 guard rows. |
179+
| What should be implemented next? | `docs/plans/ticket-plans/index.md` | Link non-ticket documentation optimization tasks. |
180+
| Which module owns a risk? | `docs/modules/INDEX.md` and module `risks.md` files | Regenerate or add stale-risk metadata. |
181+
| What rules govern docs? | `docs/governance/README.md` | Add this operating model to the top-level governance list. |
182+
183+
## Recommended Consolidation
184+
185+
Do not merge:
186+
187+
- Dated reviews into a single mega-review.
188+
- Module risks into a single central risk register.
189+
- ADRs into roadmap rows.
190+
- Competitor surveys into product principles.
191+
192+
Do merge or redirect:
193+
194+
- Competing current-status pages that answer the same question.
195+
- Stale "known issue" lists into current-status pointers.
196+
- Repeated ticket-order narratives into the ticket index.
197+
- Long roadmap implementation steps into ticket links and exit evidence.
198+
199+
## Review Verdict
200+
201+
TeaAgent's documentation is a real project asset. It is also now large enough to
202+
become a trust liability if current truth is not guarded. The immediate path is
203+
not deletion. The path is:
204+
205+
1. Curated front doors.
206+
2. Explicit claim classes.
207+
3. Supersession notes.
208+
4. Guarded volatile facts.
209+
5. Work-item ledgers with acceptance criteria.
210+
6. Regular re-anchoring after trust-sensitive code changes.

0 commit comments

Comments
 (0)