Edison Jwa
bba6273af7
- Move ASPICE docs to chanoraapp/docs submodule at docs/ - Move development docs to dev-docs/ (superpowers, offline-knowledge, impl-mapping) - Add AGENTS.md with project conventions for AI agents - Add impl-mapping.md (SAD component → source file mapping) - Archive completed plans to dev-docs/superpowers/plans/_archived/ - Remove AGENTS.md from .gitignore (now tracked)
99 lines
5.2 KiB
Markdown
99 lines
5.2 KiB
Markdown
# Review: Documentation Link Not-Covered Analysis
|
|
|
|
**Reviewer:** opencode (automated)
|
|
**Reviewed file:** `docs/offline-knowledge/docs-link-not-covered.md`
|
|
**Date:** 2026-06-13
|
|
|
|
## Verdict: Largely Accurate — Minor Corrections Needed
|
|
|
|
The analysis is well-structured and its core findings are correct. A few claims need nuance or correction.
|
|
|
|
---
|
|
|
|
## 1. Broken Markdown Links (2 claimed)
|
|
|
|
**Verdict: CORRECT**
|
|
|
|
| Claim | Verified |
|
|
|-------|----------|
|
|
| `README.md:428` links to `LICENSE-APACHE` | Yes — file does not exist at repo root. Confirmed `ls LICENSE*` returns nothing. |
|
|
| `README.md:431` links to `LICENSE-MIT` | Yes — file does not exist at repo root. |
|
|
|
|
Both are real broken links. The `NOTICE` file does exist (line 444), so that one is fine.
|
|
|
|
---
|
|
|
|
## 2. Missing File Targets (9 claimed — checked 3)
|
|
|
|
**Verdict: CORRECT**
|
|
|
|
| Claim | Verified |
|
|
|-------|----------|
|
|
| `LICENSE-APACHE` / `LICENSE-MIT` missing at repo root | Yes — confirmed missing. All 6 references across 3 files (README.md, license-inventory.md, flutter-license-inventory.md) are broken. |
|
|
| `docs/chanora_SysDes.md` hypothetical | Yes — file does not exist. Same for `chanora_SRS.md` and `chanora_SAD.md` (checked). |
|
|
| `snapshot_state_mapper.dart` directory mismatch | **Correct.** File exists at `apps/chanora_flutter/lib/services/snapshot_state_mapper.dart`, not under `widgets/` as documented in sdd.md. |
|
|
| `voice_settings*.dart` glob ambiguity | **Correct.** Two files match: `voice_settings.dart` and `voice_settings_controls.dart`, both in `widgets/`. The glob reference is ambiguous. |
|
|
|
|
**Correction:** The analysis says `voice_settings*.dart` is listed under "Voice UI widgets" — this is actually correct placement since both files ARE in `widgets/`. The issue is glob ambiguity, not directory mismatch. The analysis description is accurate but the "Issue" column could be clearer.
|
|
|
|
---
|
|
|
|
## 3. Orphaned Docs (18 claimed — checked 3)
|
|
|
|
**Verdict: MOSTLY CORRECT, with nuance**
|
|
|
|
| Claim | Verified |
|
|
|-------|----------|
|
|
| `docs/offline-knowledge/function-inventory.md` orphaned | **Yes** — no references from outside `docs/offline-knowledge/`. Only self-referenced in its own README. |
|
|
| `docs/offline-knowledge/coverage-analysis.md` orphaned | **Yes** — same situation. |
|
|
| `docs/offline-knowledge/doc-quality-analysis.md` orphaned | **Yes** — same situation. |
|
|
|
|
These are correctly identified as orphaned from the main doc tree. However, the analysis correctly notes they are self-referencing within `docs/offline-knowledge/README.md`. The "Should Be Referenced From" column lists reasonable targets.
|
|
|
|
**Note:** The `docs/governance/document-review-report.md` and `docs/references/external-references.md` files (listed as potential parents) do exist, so the suggested link targets are valid.
|
|
|
|
---
|
|
|
|
## 4. Suspicious URLs (3 claimed)
|
|
|
|
**Verdict: CORRECT, but understated**
|
|
|
|
| Claim | Verified |
|
|
|-------|----------|
|
|
| `https://git.did.science/TeaSpeak/Server/Server` | **Correct** — self-hosted GitLab. The analysis notes it references branch `new-groups` commit `b54c6d4e`. This is a real fragility risk. |
|
|
| `http://github.com/ejmahler/strength_reduce` | **Correct** — uses HTTP instead of HTTPS. Found at `docs/security/license-inventory.md:96`. |
|
|
| `http://www.apache.org/licenses/` and `http://mozilla.org/MPL/2.0/` | **Correct** — these are HTTP URLs, but the analysis correctly notes they are in license text bodies, not navigational links. They are quotes from upstream license files, not Chanora's own links. |
|
|
|
|
**Correction needed:** The analysis says "various" for the flutter-license-inventory.md HTTP URLs but there are actually **93 HTTP URL occurrences** across the two license inventory files (mostly `apache.org/licenses`). The analysis should note these are all in quoted license text, not actionable links. Only the `strength_reduce` URL (line 96 of license-inventory.md) is a Chanora-authored navigational link using HTTP.
|
|
|
|
---
|
|
|
|
## 5. Missed Broken Links
|
|
|
|
**Verdict: NO MAJOR OMISSIONS FOUND**
|
|
|
|
After checking:
|
|
- All markdown `[text](path)` links in `docs/` — the analysis covers them
|
|
- README.md inline references — all verified
|
|
- Cross-reference chains — confirmed correct
|
|
- No additional broken internal links found
|
|
|
|
**One minor observation:** The analysis does not flag that `docs/governance/document-index.md` does not list `docs/offline-knowledge/` or `docs/superpowers/` documents. While noted as "orphaned," the document index itself is incomplete — it only lists DV-baseline documents, which may be intentional.
|
|
|
|
---
|
|
|
|
## Summary of Corrections
|
|
|
|
| # | Issue | Severity |
|
|
|---|-------|----------|
|
|
| 1 | HTTP URL count in flutter-license-inventory.md understated (93 occurrences, not "various") | Low — all are quoted license text |
|
|
| 2 | `voice_settings*.dart` described as directory mismatch but is actually glob ambiguity | Low — wording issue |
|
|
| 3 | Analysis could note that `docs/governance/document-index.md` intentionally excludes offline-knowledge/ | Informational |
|
|
|
|
## Recommended Actions (unchanged from original)
|
|
|
|
1. **P0:** Create `LICENSE-APACHE` and `LICENSE-MIT` at repo root
|
|
2. **P1:** Fix `snapshot_state_mapper.dart` categorization in sdd.md
|
|
3. **P2:** Fix HTTP URL for `strength_reduce` in license-inventory.md:96
|
|
4. **P2:** Consider adding offline-knowledge docs to document index or references
|