scriptoriumadmin/veritas-kanban
1
0
Fork 0
mirror of https://github.com/BradGroux/veritas-kanban.git synced 2026-08-28 02:44:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: audit and update documentation for v3.3.3 accuracy

Browse source 
- README: fix tech stack versions (Express 5.2, Tailwind 4.2, Vite 7.3)
- SECURITY-AUDIT: update audit date, fix override versions, add minimatch/qs
- DOC-FRESHNESS: update freshness header from v2.0.0 to v3.3.3
- ANALYTICS: remove 3 broken links to deleted internal docs
- index.html: fix Vite version reference
- Add docs audit summary (DOCS-AUDIT-2026-03-02.md)
This commit is contained in:
BradGroux 2026-03-02 01:00:07 -06:00
parent 16160e69bb
commit 91bf24a45e
6 changed files with 90 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
README.md
View file

@ -229,16 +229,16 @@ All gates are toggleable via `PATCH /api/settings/features` under the `enforceme
## 🛠️ Tech Stack
| Layer | Technology | Version |
| ------------------- | ------------------------------------ | ------------------------------ |
| **Frontend** | React, Vite, Tailwind CSS, Shadcn UI | React 19, Vite 6, Tailwind 3.4 |
| **Backend** | Express, WebSocket | Express 4.21 |
| **Language** | TypeScript (strict mode) | 5.7 |
| **Storage** | Markdown files with YAML frontmatter | gray-matter |
| **Git** | simple-git, worktree management | — |
| **Testing** | Playwright (E2E), Vitest (unit) | Playwright 1.58, Vitest 4 |
| **Runtime** | Node.js | 22+ |
| **Package Manager** | pnpm | 9+ |
| Layer | Technology | Version |
| ------------------- | ------------------------------------ | -------------------------------- |
| **Frontend** | React, Vite, Tailwind CSS, Shadcn UI | React 19, Vite 7.3, Tailwind 4.2 |
| **Backend** | Express, WebSocket | Express 5.2 |
| **Language** | TypeScript (strict mode) | 5.7 |
| **Storage** | Markdown files with YAML frontmatter | gray-matter |
| **Git** | simple-git, worktree management | — |
| **Testing** | Playwright (E2E), Vitest (unit) | Playwright 1.58, Vitest 4 |
| **Runtime** | Node.js | 22+ |
| **Package Manager** | pnpm | 9+ |
---

10
SECURITY-AUDIT.md
View file

@ -1,6 +1,6 @@
# Security Audit Report
**Last audited:** 2026-01-29
**Last audited:** 2026-03-02
**Tool:** pnpm audit (pnpm 9.15.4)
**Node version:** 22.x
@ -27,9 +27,11 @@
The following version overrides are configured in the root `package.json` to pin patched versions:
| Package | Override | Reason |
| ------- | ---------- | ---------------------------------------- |
| `hono` | `>=4.11.7` | Ensures patched version (prior advisory) |
| Package | Override | Reason |
| ----------- | ---------- | ------------------------------------------------ |
| `hono` | `>=4.12.2` | Timing attack vulnerability fix (GHSA-xh87-mx6m) |
| `minimatch` | `>=10.2.3` | ReDoS vulnerabilities (GHSA-7r86, GHSA-23c5) |
| `qs` | `^6.14.2` | Prototype pollution fix |
## Accepted Risks / Suppressions

4
docs/ANALYTICS.md
View file

@ -420,7 +420,3 @@ curl -s "http://localhost:3001/api/analytics/metrics?from=2026-01-01T00:00:00Z&t
---
**See Also:**
- [Time Tracking](./TIME_TRACKING.md)
- [Status History](./STATUS_HISTORY.md)
- [Architecture](./ARCHITECTURE.md)

41
docs/DOC-FRESHNESS.md
View file

@ -8,16 +8,16 @@ VK is agent-first. When docs are wrong, agents make wrong decisions. This guide
### When to Update Docs
| Trigger | What to Update |
|---------|---------------|
| New API endpoint added | README API section, relevant route docs |
| Schema change (shared/types) | Type documentation, API examples |
| New CLI command | CLI README, help text |
| Config option added/changed | Settings docs, example configs |
| New feature shipped | README features section, changelog |
| Architecture change | Architecture docs, diagrams |
| Bug fix with user impact | Known issues, changelog |
| Dependency upgrade | Requirements section if version matters |
| Trigger | What to Update |
| ---------------------------- | --------------------------------------- |
| New API endpoint added | README API section, relevant route docs |
| Schema change (shared/types) | Type documentation, API examples |
| New CLI command | CLI README, help text |
| Config option added/changed | Settings docs, example configs |
| New feature shipped | README features section, changelog |
| Architecture change | Architecture docs, diagrams |
| Bug fix with user impact | Known issues, changelog |
| Dependency upgrade | Requirements section if version matters |
### Doc Update Checklist
@ -33,21 +33,21 @@ When completing a task that changes user-facing behavior:
### Where Docs Live
| Doc | Purpose | Owner |
|-----|---------|-------|
| `README.md` | Public-facing overview | Any contributor |
| `docs/` | Detailed guides & specs | Feature author |
| `CHANGELOG.md` | Release history | Release manager |
| `docs/AGENTS-TEMPLATE.md` | Agent integration guide | Agent team |
| `docs/multi-agent-git-workflow.md` | Multi-agent coordination | Agent team |
| JSDoc in source files | API contracts | Feature author |
| Doc | Purpose | Owner |
| ---------------------------------- | ------------------------ | --------------- |
| `README.md` | Public-facing overview | Any contributor |
| `docs/` | Detailed guides & specs | Feature author |
| `CHANGELOG.md` | Release history | Release manager |
| `docs/AGENTS-TEMPLATE.md` | Agent integration guide | Agent team |
| `docs/multi-agent-git-workflow.md` | Multi-agent coordination | Agent team |
| JSDoc in source files | API contracts | Feature author |
### Freshness Indicators
Each doc should include a freshness header:
```markdown
<!-- doc-freshness: 2026-02-05 | v2.0.0 | @veritas -->
<!-- doc-freshness: 2026-03-02 | v3.3.3 | @tars -->
```
Format: `date | version | last-updater`
@ -57,16 +57,19 @@ When a doc is older than the current version, it may need review.
## Automation Plan
### Phase 1: Manual (Current)
- Doc update checklist in PR template
- Freshness headers in docs
- Agent instructions include "update docs" step
### Phase 2: Hook-Based
- Lifecycle hook on `task.done` checks for doc-related files
- If code changes but no doc changes, create a follow-up task
- Use `docs/` path detection in git diff
### Phase 3: AI-Powered Doc Steward
- Dedicated "doc steward" agent type
- Subscribes to all `task.done` events
- Reads recent commits, identifies doc gaps

51
docs/DOCS-AUDIT-2026-03-02.md Normal file
View file

@ -0,0 +1,51 @@
# Documentation Audit — 2026-03-02
**Auditor:** TARS (sub-agent)
**Version:** v3.3.3
**Scope:** Full doc freshness audit across README, CHANGELOG, docs/\*, SECURITY-AUDIT
## Changes Made
### README.md — Tech Stack Drift (Fixed)
- Express `4.21` → `5.2` (upgraded via #153 wildcard routes for Express 5)
- Tailwind `3.4` → `4.2` (upgraded via #149)
- Vite `6` → `7.3` (upgraded via #148)
### SECURITY-AUDIT.md — Stale Audit Data (Fixed)
- Last audited date: `2026-01-29` → `2026-03-02`
- Updated overrides table: hono `>=4.11.7` → `>=4.12.2`, added minimatch `>=10.2.3` and qs `^6.14.2`
- Re-ran `pnpm audit --prod` — confirmed 0 vulnerabilities
### docs/DOC-FRESHNESS.md — Stale Freshness Header (Fixed)
- Header claimed `v2.0.0` — updated to `v3.3.3`
### docs/index.html — Version Drift (Fixed)
- "Vite 6" → "Vite 7" in architecture section
### docs/ANALYTICS.md — Broken Links (Fixed)
- Removed 3 dead links to `TIME_TRACKING.md`, `STATUS_HISTORY.md`, `ARCHITECTURE.md` (deleted in internal docs purge, commits 8599249–7a39770)
## Link/Reference Check Results
| Status | Count | Notes |
| -------------------- | ----- | -------------------------------------------------------------------------- |
| Broken links fixed | 3 | ANALYTICS.md dead internal refs |
| False-positive parse | 2 | GETTING-STARTED, enforcement — markdown syntax fine, grep pattern mismatch |
| Clean links | ~50+ | All other cross-doc refs resolve correctly |
## Follow-Up Gaps (Not Addressed)
1. **19 stale remote branches** — Feature branches from v1.5–v3.0 era still exist on origin. Recommend periodic cleanup.
2. **MCP tools table in README** — Lists only 5 tools but sprint management added 6 more in v3.3.2. Low priority — full list in CLI guide.
3. **CHANGELOG.md** — Healthy, current through v3.3.3. No drift.
4. **DEPLOYMENT.md** — References Express but no version-specific claims. Clean.
5. **GETTING-STARTED.md** — Current and accurate. No drift detected.
## Verdict
Documentation is now accurate and reflects v3.3.3 state. Primary drift was in tech stack versions (Express 5 migration and Tailwind 4/Vite 7 upgrades not reflected in README).

2
docs/index.html
View file

@ -1604,7 +1604,7 @@ curl -X POST .../tasks/&lt;id&gt;/comments \
<div class="stack-item fade-in">
<span class="stack-icon">⚛️</span>
<h3>Frontend</h3>
<p>React 19 + TypeScript<br>Vite 6 + Tailwind CSS<br>shadcn/ui components</p>
<p>React 19 + TypeScript<br>Vite 7 + Tailwind CSS<br>shadcn/ui components</p>
</div>
<div class="stack-item fade-in fade-in-delay-1">
<span class="stack-icon">🟢</span>