edison/chanora
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97118bb6a321eb7dec643e8a675711fe78dfbdd
chanora/dev-docs/superpowers/plans/2026-06-13-documentation-site.md
T

1489 lines
45 KiB
Markdown
Raw Blame History

# Documentation Site & ASPICE Traceability Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Create a private Docusaurus doc site with tag-based ASPICE traceability, hosted on Cloudflare Pages with access control, served from a git submodule.
**Architecture:** The docs repo (`chanoraapp/docs`) is a standalone Docusaurus project added as a git submodule at `docs/` in the code repo. A custom Docusaurus plugin validates requirement ID traceability chains on every build. The code repo retains development-only docs in `dev-docs/`.
**Tech Stack:** Docusaurus 3.10 (Meta-maintained), Node.js 20, custom traceability plugin (~100 lines JavaScript), standalone CI validator (Node.js), GitHub Actions, Cloudflare Pages + Access, git submodules
**Spec:** `dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md`
> **Note:** This plan was originally written for MkDocs Material. During implementation, MkDocs was replaced with Docusaurus due to MkDocs ecosystem instability (1.x unmaintained, 2.0 breaking). The task descriptions below reference MkDocs but the actual implementation uses Docusaurus 3.10. See the spec for the Docusaurus configuration details.
---
### Task 1: Create Docs Repo and MkDocs Configuration
**Files:**
- Create: `mkdocs.yml`
- Create: `requirements.txt`
- Create: `pyproject.toml`
- Create: `docs/index.md`
- Create: `docs/.meta.yml`
- Create: `README.md`
Note: This task creates the `chanora-docs` GitHub repo. The `chanora-docs` repo must be created on GitHub first (private repo), then cloned locally for these steps.
- [ ] **Step 1: Create the private `chanora-docs` GitHub repo**
```bash
gh repo create chanora-docs --private --description "Chanora engineering documentation with ASPICE traceability"
```
- [ ] **Step 2: Clone and initialize**
```bash
git clone git@github.com:EdisonJwa/chanora-docs.git
cd chanora-docs
```
- [ ] **Step 3: Create `requirements.txt`**
```
mkdocs-material>=9.6.0
mkdocs-git-revision-date-localized-plugin>=1.5.0
```
- [ ] **Step 4: Create `pyproject.toml`**
```toml
[project]
name = "chanora-docs"
version = "0.1.0"
description = "Chanora engineering documentation with ASPICE traceability"
requires-python = ">=3.12"
```
- [ ] **Step 5: Create `mkdocs.yml` with full configuration**
```yaml
site_name: Chanora Engineering Docs
site_description: ASPICE-compliant engineering documentation with automated traceability
site_url: https://docs.chanora.dev
repo_name: EdisonJwa/chanora-docs
repo_url: https://github.com/EdisonJwa/chanora-docs
edit_uri: edit/main/docs/
theme:
name: material
language: en
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.sections
- navigation.expand
- navigation.footer
- search.highlight
- search.suggest
- content.code.copy
- content.tabs.link
palette:
- media: "(prefers-color-scheme)"
toggle:
icon: material/brightness-auto
name: Switch to light mode
- media: "(prefers-color-scheme: light)"
scheme: default
primary: deep purple
accent: purple
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: "(prefers-color-scheme: dark)"
scheme: slate
primary: deep purple
accent: purple
toggle:
icon: material/brightness-4
name: Switch to system preference
icon:
repo: fontawesome/brands/github
plugins:
- search
- tags:
tags_allowed:
- sysrs
- sysdes
- srs
- sad
- sdd
- swe.1
- swe.2
- swe.3
- swe.4
- swe.5
- swe.6
- sys.4
- requirements
- architecture
- verification
- governance
- security
- privacy
- legal
- release
- references
- ui-ux
- localization
- baseline
- draft
- candidate
- deferred
tags_file: tags.md
- git-revision-date-localized:
type: iso_date
enable_creation_date: true
- traceability:
strict: true
coverage_file: true
dashboard: true
nav:
- Home: index.md
- Requirements:
- System Requirements (SysRS): requirements/sysrs.md
- System Design (SysDes): requirements/sysdes.md
- Software Requirements (SRS): requirements/srs.md
- Architecture & Design:
- Software Architecture (SWE.2 / SAD): architecture/sad.md
- Detailed Design (SWE.3 / SDD): architecture/sdd.md
- File Transfer Design: architecture/file-transfer-design.md
- File Transfer Research: architecture/file-transfer-research.md
- File Transfer Implementation Plan: architecture/file-transfer-implementation-plan.md
- Desktop PTT Architecture: architecture/desktop-ptt-architecture.md
- Verification:
- System Level:
- SYS.4 System Integration: verification/sys4-system-integration-verification-plan.md
- Software Integration:
- SWE.5 Software Integration: verification/swe5-software-integration-verification-plan.md
- Unit Level:
- SWE.4 Unit Verification: verification/swe4-unit-verification-plan.md
- Software Qualification:
- SWE.6 Software Verification: verification/swe6-software-verification-plan.md
- Master Plan: verification/verification-master-plan.md
- Governance:
- Document Index: governance/document-index.md
- Traceability Matrix: governance/traceability-matrix.md
- Decision Register: governance/product-decision-register.md
- Baseline Approval Record: governance/baseline-approval-record.md
- Baseline Candidate Validation: governance/baseline-candidate-validation-report.md
- Document Review Report: governance/document-review-report.md
- Document Naming Convention: governance/document-naming-convention.md
- Decision Impact Assessment: governance/decision-impact-assessment.md
- Git Commit Message Convention: governance/git-commit-message-convention.md
- Repo Format Validation: governance/repo-format-validation-report.md
- Path Migration Map: governance/path-migration-map.md
- Maintainability Review: governance/maintainability-review-2026-06-08.md
- Security & Privacy:
- Security Guidelines: security/security-privacy-legal-guideline.md
- Threat Model: security/threat-model.md
- Secure Storage Audit: security/secure-storage-audit-report.md
- Diagnostic Redaction Audit: security/diagnostic-redaction-audit-report.md
- Dependency & Supply Chain: security/dependency-and-supply-chain-report.md
- License Inventory: security/license-inventory.md
- Flutter License Inventory: security/flutter-license-inventory.md
- Privacy Policy: privacy/privacy-policy.md
- Legal Review: legal/trademark-and-attribution-review.md
- Release:
- Platform Release Policy: release/platform-release-policy.md
- Release Readiness (Go/No-Go): release/release-readiness-go-nogo-record.md
- DV Waiver Register: release/dv-waiver-register.md
- References:
- External References: references/external-references.md
- ASPICE SWE.2/SWE.3 Note: references/aspice-swe2-swe3-integration-note.md
- TeamSpeak Protocol Reference (EN): references/yatqa-en.md
- TeamSpeak Protocol Reference (DE): references/yatqa-de.md
- TeaSpeak Overview: references/teaspeak-overview.md
- ReSpeak Overview: references/respeak-overview.md
- UI/UX:
- Material 3 Guideline: ui-ux/material3-guideline.md
- Design Tokens: ui-ux/material3-design-tokens.md
- Component Catalog: ui-ux/material3-component-catalog.md
- Adaptive Layout Guide: ui-ux/adaptive-layout-platform-guide.md
- Localization:
- Localization Architecture: i18n/localization-architecture.md
markdown_extensions:
- admonition
- pymdownx.details
- pymdownx.superfences
- pymdownx.tabbed:
alternate_style: true
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.inlinehilite
- pymdownx.snippets
- attr_list
- md_in_html
- tables
- toc:
permalink: true
```
- [ ] **Step 6: Create `docs/.meta.yml` (global defaults)**
```yaml
status: draft
```
- [ ] **Step 7: Create `docs/index.md` (landing page)**
```markdown
# Chanora Engineering Documentation
**ASPICE-compliant engineering documentation with automated traceability**
---
## Lifecycle Chain
```text
SysRS → SysDes → SRS → SAD (SWE.2) → SDD (SWE.3) → Verification
↓ ↓
SWE.4 (unit) SWE.4/5/6/SYS.4
```
## Quick Navigation
- [System Requirements (SysRS)](requirements/sysrs.md)
- [System Design (SysDes)](requirements/sysdes.md)
- [Software Requirements (SRS)](requirements/srs.md)
- [Software Architecture (SAD)](architecture/sad.md)
- [Detailed Design (SDD)](architecture/sdd.md)
- [Verification Master Plan](verification/verification-master-plan.md)
- [Traceability Matrix](governance/traceability-matrix.md)
- [Document Index](governance/document-index.md)
## Baseline Status
| Document | Status |
|---|---|
| SysRS | Baseline |
| SysDes | Baseline |
| SRS | Baseline |
| SAD | Baseline candidate |
| SDD | Baseline candidate |
| Verification plans | Baseline candidate |
| Release readiness | No-Go |
---
[View all tags →](tags.md)
```
- [ ] **Step 8: Create `README.md`**
```markdown
# Chanora Engineering Docs
ASPICE-compliant engineering documentation site for Chanora.
## Local Development
```bash
pip install -r requirements.txt
mkdocs serve
```
## Build
```bash
mkdocs build --strict
```
## Traceability Validation
```bash
python scripts/validate_traceability.py docs/
```
## Deployment
Deploys automatically to Cloudflare Pages on push to `main`.
```
- [ ] **Step 9: Create directory structure for docs**
```bash
mkdir -p docs/{requirements,architecture,verification,governance,security,privacy,legal,release,references,ui-ux,i18n}
mkdir -p plugins/traceability
mkdir -p scripts
mkdir -p .github/workflows
```
- [ ] **Step 10: Commit**
```bash
git add -A
git commit -m "chore: initialize MkDocs Material project with configuration and landing page"
```
---
### Task 2: Build Custom Traceability Plugin
**Files:**
- Create: `plugins/traceability/__init__.py`
- Create: `plugins/traceability/traceability.py`
- Create: `tests/test_traceability.py`
- [ ] **Step 1: Create plugin package init**
```python
# plugins/traceability/__init__.py
from .traceability import TraceabilityPlugin
def make_plugin(config, **kwargs):
return TraceabilityPlugin(config)
```
- [ ] **Step 2: Write the traceability plugin**
```python
# plugins/traceability/traceability.py
"""MkDocs plugin for ASPICE requirement traceability validation."""
import json
import re
from collections import defaultdict
from pathlib import Path
from mkdocs.plugins import BasePlugin
from mkdocs.structure.pages import Page
REQUIREMENT_ID_PATTERNS = {
"sysrs": re.compile(r"SysRS-\d+"),
"sysdes": re.compile(r"SysDes-\d+"),
"srs": re.compile(r"SRS-\d+"),
"sdd_mod": re.compile(r"SDD-MOD-\d+"),
"dec": re.compile(r"DEC-\d+"),
}
CHAINS = [
("sysrs", "sysdes"),
("sysdes", "srs"),
("srs", "sad"),
("srs", "sdd"),
("sad", "swe5"),
("sdd", "swe4"),
("srs", "swe6"),
("sysdes", "sys4"),
]
class TraceabilityPlugin(BasePlugin):
config_scheme = (
("strict", {"type": bool, "default": True}),
("coverage_file", {"type": bool, "default": True}),
("dashboard", {"type": bool, "default": True}),
)
def __init__(self, config):
super().__init__(config)
self.defined_ids: dict[str, set[str]] = defaultdict(set)
self.referenced_ids: dict[str, set[str]] = defaultdict(set)
self.page_ids: dict[str, set[str]] = defaultdict(set)
self.page_src: dict[str, str] = {}
def on_page_markdown(self, markdown: str, page: Page, config, files):
src_path = page.file.src_path
self.page_src[src_path] = src_path
for pattern_name, pattern in REQUIREMENT_ID_PATTERNS.items():
found = set(pattern.findall(markdown))
if found:
self.page_ids[src_path].update(found)
tags = page.meta.get("tags", [])
for tag in tags:
if isinstance(tag, str) and any(
tag.startswith(prefix)
for prefix in ["SysRS-", "SysDes-", "SRS-", "SDD-MOD-", "DEC-"]
):
self.defined_ids[tag].add(src_path)
for pattern_name, pattern in REQUIREMENT_ID_PATTERNS.items():
for match in pattern.findall(markdown):
self.referenced_ids[match].add(src_path)
return markdown
def on_post_build(self, config):
orphans = []
for req_id, pages in self.referenced_ids.items():
if req_id not in self.defined_ids:
orphans.append((req_id, sorted(pages)))
coverage = {}
for upstream, downstream in CHAINS:
upstream_ids = set()
for req_id, pages in self.defined_ids.items():
if req_id.upper().startswith(upstream.upper()):
upstream_ids.add(req_id)
downstream_refs = set()
for req_id, pages in self.referenced_ids.items():
for page in pages:
if downstream in page.lower():
downstream_refs.add(req_id)
if upstream_ids:
covered = upstream_ids & downstream_refs
coverage[f"{upstream} -> {downstream}"] = {
"total": len(upstream_ids),
"covered": len(covered),
"percentage": round(100 * len(covered) / len(upstream_ids), 1)
if upstream_ids
else 0,
"orphaned": sorted(upstream_ids - covered),
}
report = {
"chains": coverage,
"orphaned_references": [
{"id": rid, "referenced_in": sorted(pages)}
for rid, pages in orphans
],
}
if self.config["coverage_file"]:
output_dir = Path(config["site_dir"])
with open(output_dir / "traceability-coverage.json", "w") as f:
json.dump(report, f, indent=2)
self._print_summary(report)
if self.config["strict"] and (orphans or any(
c.get("orphaned") for c in coverage.values()
)):
import sys
print(
"\nERROR: Traceability validation failed. "
"Set strict: false to allow broken chains.",
file=sys.stderr,
)
sys.exit(1)
def _print_summary(self, report):
print("\n" + "=" * 60)
print("ASPICE Traceability Summary")
print("=" * 60)
for chain, data in report["chains"].items():
status = "PASS" if not data["orphaned"] else "WARN"
print(
f" [{status}] {chain}: "
f"{data['covered']}/{data['total']} "
f"({data['percentage']}%)"
)
if report["orphaned_references"]:
print(f"\n Orphaned references: {len(report['orphaned_references'])}")
for orphan in report["orphaned_references"][:10]:
print(f" - {orphan['id']} in {', '.join(orphan['referenced_in'])}")
if len(report["orphaned_references"]) > 10:
print(
f" ... and {len(report['orphaned_references']) - 10} more"
)
print("=" * 60 + "\n")
```
- [ ] **Step 3: Write plugin test**
```python
# tests/test_traceability.py
"""Tests for the traceability MkDocs plugin."""
import json
import tempfile
from pathlib import Path
from unittest.mock import MagicMock
import pytest
from traceability import TraceabilityPlugin, REQUIREMENT_ID_PATTERNS
def test_pattern_matches_sysrs():
pattern = REQUIREMENT_ID_PATTERNS["sysrs"]
assert pattern.findall("This traces to SysRS-233 and SysRS-234") == [
"SysRS-233",
"SysRS-234",
]
def test_pattern_matches_srs():
pattern = REQUIREMENT_ID_PATTERNS["srs"]
assert pattern.findall("Covers SRS-045 through SRS-053") == [
"SRS-045",
"SRS-053",
]
def test_pattern_matches_sdd_mod():
pattern = REQUIREMENT_ID_PATTERNS["sdd_mod"]
assert pattern.findall("Module SDD-MOD-009 handles this") == ["SDD-MOD-009"]
def test_no_false_positives():
pattern = REQUIREMENT_ID_PATTERNS["sysrs"]
assert pattern.findall("No requirements here") == []
assert pattern.findall("sysrs-123 lowercase should not match") == []
def test_plugin_stores_defined_ids():
config = {"strict": False, "coverage_file": False, "dashboard": False}
plugin = TraceabilityPlugin(config)
page = MagicMock()
page.meta = {"tags": ["SysRS-233", "swe.1", "baseline"]}
page.file.src_path = "requirements/sysrs.md"
plugin.on_page_markdown("content", page, {}, None)
assert "SysRS-233" in plugin.defined_ids
def test_plugin_stores_referenced_ids():
config = {"strict": False, "coverage_file": False, "dashboard": False}
plugin = TraceabilityPlugin(config)
page = MagicMock()
page.meta = {"tags": ["swe.4"]}
page.file.src_path = "verification/swe4-unit-verification-plan.md"
plugin.on_page_markdown(
"Verifies SDD-MOD-001, SDD-MOD-002, and SDD-MOD-003",
page,
{},
None,
)
assert "SDD-MOD-001" in plugin.referenced_ids
assert "SDD-MOD-002" in plugin.referenced_ids
assert "SDD-MOD-003" in plugin.referenced_ids
```
- [ ] **Step 4: Create directory structure and run tests**
```bash
mkdir -p tests
pip install -r requirements.txt
cd plugins/traceability && python -m pytest ../../tests/test_traceability.py -v
```
Expected: 5 tests pass (some may fail if mkdocs is not installed in test environment — adjust imports as needed).
- [ ] **Step 5: Commit**
```bash
git add plugins/ tests/
git commit -m "feat: add traceability plugin with requirement ID scanning and validation"
```
---
### Task 3: Build Standalone CI Validator
**Files:**
- Create: `scripts/validate_traceability.py`
- [ ] **Step 1: Write the standalone validator**
```python
#!/usr/bin/env python3
"""Standalone ASPICE traceability validator for CI.
Usage:
python scripts/validate_traceability.py docs/
Exit codes:
0 - All chains valid
1 - Broken chains found
"""
import re
import sys
from collections import defaultdict
from pathlib import Path
REQUIREMENT_ID_PATTERNS = {
"sysrs": re.compile(r"SysRS-\d+"),
"sysdes": re.compile(r"SysDes-\d+"),
"srs": re.compile(r"SRS-\d+"),
"sdd_mod": re.compile(r"SDD-MOD-\d+"),
"dec": re.compile(r"DEC-\d+"),
}
CHAINS = [
("sysrs", "sysdes"),
("sysdes", "srs"),
("srs", "sad"),
("srs", "sdd"),
("sad", "swe5"),
("sdd", "swe4"),
("srs", "swe6"),
("sysdes", "sys4"),
]
def extract_front_matter(content: str) -> dict:
"""Extract YAML front matter from markdown content."""
if content.startswith("---"):
end = content.find("---", 3)
if end != -1:
return {"raw": content[3:end]}
return {}
def scan_docs(docs_dir: Path) -> dict:
"""Scan all markdown files for requirement IDs."""
defined_ids: dict[str, set[str]] = defaultdict(set)
referenced_ids: dict[str, set[str]] = defaultdict(set)
for md_file in docs_dir.rglob("*.md"):
content = md_file.read_text(encoding="utf-8")
rel_path = str(md_file.relative_to(docs_dir))
# Extract tags from front matter
fm = extract_front_matter(content)
if "raw" in fm:
for line in fm["raw"].split("\n"):
if "tags:" in line:
for tag in re.findall(r"\b(?:SysRS|SysDes|SRS|SDD-MOD|DEC)-\d+", line):
defined_ids[tag].add(rel_path)
# Find all requirement ID references in content
for pattern_name, pattern in REQUIREMENT_ID_PATTERNS.items():
for match in pattern.findall(content):
referenced_ids[match].add(rel_path)
return {"defined": defined_ids, "referenced": referenced_ids}
def validate(data: dict) -> list[dict]:
"""Validate traceability chains."""
issues = []
# Check for orphaned references
for req_id, pages in data["referenced"].items():
if req_id not in data["defined"]:
issues.append({
"type": "orphaned_reference",
"id": req_id,
"referenced_in": sorted(pages),
})
return issues
def print_report(issues: list[dict], data: dict) -> None:
"""Print validation report."""
print("=" * 60)
print("ASPICE Traceability Validation")
print("=" * 60)
if not issues:
print(" [PASS] All requirement references have definitions")
else:
orphaned = [i for i in issues if i["type"] == "orphaned_reference"]
if orphaned:
print(f"\n [FAIL] {len(orphaned)} orphaned reference(s):")
for issue in orphaned[:20]:
print(f" - {issue['id']} referenced in {', '.join(issue['referenced_in'])}")
if len(orphaned) > 20:
print(f" ... and {len(orphaned) - 20} more")
print("=" * 60)
def main():
if len(sys.argv) < 2:
print(f"Usage: {sys.argv[0]} <docs-directory>", file=sys.stderr)
sys.exit(1)
docs_dir = Path(sys.argv[1])
if not docs_dir.is_dir():
print(f"Error: {docs_dir} is not a directory", file=sys.stderr)
sys.exit(1)
data = scan_docs(docs_dir)
issues = validate(data)
print_report(issues, data)
sys.exit(1 if issues else 0)
if __name__ == "__main__":
main()
```
- [ ] **Step 2: Make script executable**
```bash
chmod +x scripts/validate_traceability.py
```
- [ ] **Step 3: Create `docs/.meta.yml` and a test file to validate the script**
```bash
mkdir -p docs/test
echo -e '---\ntags: [swe.1, SysRS-999]\n---\n\nTest doc referencing SysRS-999.' > docs/test/validation-test.md
python scripts/validate_traceability.py docs/
```
Expected: Exit code 0 (SysRS-999 is defined and referenced in the same file, no orphans).
- [ ] **Step 4: Remove test file and commit**
```bash
rm -rf docs/test
git add scripts/
git commit -m "feat: add standalone traceability validator for CI"
```
---
### Task 4: Set Up CI/CD Pipeline
**Files:**
- Create: `.github/workflows/deploy.yml`
- Create: `wrangler.toml`
- [ ] **Step 1: Create GitHub Actions workflow**
```yaml
name: Build and Deploy Docs
on:
push:
branches: [main]
pull_request:
branches: [main]
permissions:
contents: read
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-python@v5
with:
python-version: "3.12"
cache: pip
- run: pip install -r requirements.txt
- name: Validate traceability chains
run: python scripts/validate_traceability.py docs/
- name: Build doc site
run: mkdocs build --strict
- if: github.event_name == 'push' && github.ref == 'refs/heads/main'
uses: cloudflare/wrangler-action@v3
with:
command: pages deploy site --project-name=chanora-docs
env:
CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
```
- [ ] **Step 2: Create Wrangler configuration**
```toml
name = "chanora-docs"
compatibility_date = "2026-06-13"
[site]
bucket = "./site"
```
- [ ] **Step 3: Commit**
```bash
git add .github/ wrangler.toml
git commit -m "ci: add GitHub Actions workflow for build, validate, and Cloudflare Pages deploy"
```
---
### Task 5: Migrate ASPICE Docs to Docs Repo
**Files:**
- Copy all ASPICE docs from `chanora/docs/` to `chanora-docs/docs/`
- Add YAML front matter to each migrated file
Note: This task runs in the `chanora-docs` repo. The source files are in the main `chanora` repo at `chanora/docs/`.
- [ ] **Step 1: Copy requirements docs**
```bash
# From chanora-docs repo root:
# Copy canonical files (these ARE the docs, not path records)
cp ../chanora/docs/sysrs.md docs/requirements/sysrs.md
cp ../chanora/docs/sysdes.md docs/requirements/sysdes.md
cp ../chanora/docs/srs.md docs/requirements/srs.md
# Note: The path records (docs/requirements/sysrs.md, docs/requirements/srs.md,
# docs/architecture/sysdes.md in the original repo) are stubs pointing to canonical
# files. We don't need them in the docs repo since the canonical files are now here.
```
- [ ] **Step 2: Copy architecture docs**
```bash
cp ../chanora/docs/architecture/sad.md docs/architecture/sad.md
cp ../chanora/docs/architecture/sdd.md docs/architecture/sdd.md
cp ../chanora/docs/architecture/file-transfer-design.md docs/architecture/
cp ../chanora/docs/architecture/file-transfer-research.md docs/architecture/
cp ../chanora/docs/architecture/file-transfer-implementation-plan.md docs/architecture/
cp ../chanora/docs/architecture/desktop-ptt-architecture.md docs/architecture/
# Note: docs/architecture/sysdes.md in the original repo is a path record
# pointing to docs/sysdes.md. Not needed — the canonical sysdes.md is in
# docs/requirements/sysdes.md in the docs repo.
```
- [ ] **Step 3: Copy verification docs**
```bash
cp ../chanora/docs/verification/*.md docs/verification/
```
- [ ] **Step 4: Copy governance docs**
```bash
cp ../chanora/docs/governance/*.md docs/governance/
```
- [ ] **Step 5: Copy security, privacy, legal docs**
```bash
cp ../chanora/docs/security/*.md docs/security/
cp ../chanora/docs/privacy/*.md docs/privacy/
cp ../chanora/docs/legal/*.md docs/legal/
```
- [ ] **Step 6: Copy release docs (policy, go-nogo, waiver only — NOT ios-build.md)**
```bash
cp ../chanora/docs/release/platform-release-policy.md docs/release/
cp ../chanora/docs/release/release-readiness-go-nogo-record.md docs/release/
cp ../chanora/docs/release/dv-waiver-register.md docs/release/
```
- [ ] **Step 7: Copy references + flatten external refs**
```bash
cp ../chanora/docs/references/*.md docs/references/
cp ../chanora/docs/offline-knowledge/external/yatqa-en.md docs/references/
cp ../chanora/docs/offline-knowledge/external/yatqa-de.md docs/references/
cp ../chanora/docs/offline-knowledge/external/teaspeak-overview.md docs/references/
cp ../chanora/docs/offline-knowledge/external/respeak-overview.md docs/references/
```
- [ ] **Step 8: Copy UI/UX, i18n, material3-guideline**
```bash
cp ../chanora/docs/ui-ux/*.md docs/ui-ux/
cp ../chanora/docs/i18n/*.md docs/i18n/
# Note: docs/material3-guideline.md in the original repo is a path record
# pointing to docs/ui-ux/material3-guideline.md. Not needed — the canonical
# file is already copied above.
```
- [ ] **Step 9: Create section `.meta.yml` files**
```bash
echo -e 'tags:\n - requirements\nstatus: baseline' > docs/requirements/.meta.yml
echo -e 'tags:\n - architecture\n - design\nstatus: candidate' > docs/architecture/.meta.yml
echo -e 'tags:\n - verification\nstatus: candidate' > docs/verification/.meta.yml
echo -e 'tags:\n - governance\nstatus: baseline' > docs/governance/.meta.yml
echo -e 'tags:\n - security\nstatus: candidate' > docs/security/.meta.yml
echo -e 'tags:\n - privacy\nstatus: candidate' > docs/privacy/.meta.yml
echo -e 'tags:\n - legal\nstatus: candidate' > docs/legal/.meta.yml
echo -e 'tags:\n - release\nstatus: candidate' > docs/release/.meta.yml
echo -e 'tags:\n - references\nstatus: baseline' > docs/references/.meta.yml
echo -e 'tags:\n - ui-ux\nstatus: candidate' > docs/ui-ux/.meta.yml
echo -e 'tags:\n - localization\nstatus: candidate' > docs/i18n/.meta.yml
```
- [ ] **Step 10: Commit all migrated files**
```bash
git add docs/
git commit -m "docs: migrate all ASPICE docs from chanora repo with section meta files"
```
---
### Task 6: Add Front Matter to Key ASPICE Documents
**Files:**
- Modify: `docs/requirements/sysrs.md`
- Modify: `docs/requirements/sysdes.md`
- Modify: `docs/requirements/srs.md`
- Modify: `docs/architecture/sad.md`
- Modify: `docs/architecture/sdd.md`
- Modify: `docs/verification/*.md`
- Modify: `docs/governance/traceability-matrix.md`
- [ ] **Step 1: Add front matter to `docs/requirements/sysrs.md`**
Insert at the very top of the file (before the existing `# Chanora SysRS` heading):
```yaml
---
tags: [sysrs, requirements, swe.1, baseline]
upstream: []
downstream: [sysdes, srs]
lifecycle: SysRS
status: baseline
---
```
- [ ] **Step 2: Add front matter to `docs/requirements/sysdes.md`**
```yaml
---
tags: [sysdes, requirements, swe.1, baseline]
upstream: [sysrs]
downstream: [srs, sys4]
lifecycle: SysDes
status: baseline
---
```
- [ ] **Step 3: Add front matter to `docs/requirements/srs.md`**
```yaml
---
tags: [srs, requirements, swe.1, baseline]
upstream: [sysdes, sysrs]
downstream: [sad, sdd, swe6]
lifecycle: SRS
status: baseline
---
```
- [ ] **Step 4: Add front matter to `docs/architecture/sad.md`**
```yaml
---
tags: [sad, architecture, swe.2, candidate]
upstream: [srs]
downstream: [sdd, swe5]
lifecycle: SWE.2
status: candidate
---
```
- [ ] **Step 5: Add front matter to `docs/architecture/sdd.md`**
```yaml
---
tags: [sdd, architecture, swe.3, candidate]
upstream: [sad, srs]
downstream: [swe4]
lifecycle: SWE.3
status: candidate
---
```
- [ ] **Step 6: Add front matter to each verification plan**
`docs/verification/verification-master-plan.md`:
```yaml
---
tags: [verification, baseline]
upstream: [sysrs, sysdes, srs, sad, sdd]
downstream: []
lifecycle: SWE.4-SWE.6
status: candidate
---
```
`docs/verification/swe4-unit-verification-plan.md`:
```yaml
---
tags: [swe.4, verification, candidate]
upstream: [sdd]
downstream: []
lifecycle: SWE.3 → SWE.4
status: candidate
---
```
`docs/verification/swe5-software-integration-verification-plan.md`:
```yaml
---
tags: [swe.5, verification, candidate]
upstream: [sad]
downstream: []
lifecycle: SWE.2 → SWE.5
status: candidate
---
```
`docs/verification/swe6-software-verification-plan.md`:
```yaml
---
tags: [swe.6, verification, candidate]
upstream: [srs]
downstream: []
lifecycle: SRS → SWE.6
status: candidate
---
```
`docs/verification/sys4-system-integration-verification-plan.md`:
```yaml
---
tags: [sys.4, verification, candidate]
upstream: [sysdes, sysrs]
downstream: []
lifecycle: SysDes → SYS.4
status: candidate
---
```
- [ ] **Step 7: Add front matter to `docs/governance/traceability-matrix.md`**
```yaml
---
tags: [governance, baseline]
upstream: [sysrs, sysdes, srs, sad, sdd]
downstream: []
lifecycle: traceability
status: candidate
---
```
- [ ] **Step 8: Commit**
```bash
git add docs/
git commit -m "docs: add ASPICE lifecycle front matter to key documents"
```
---
### Task 7: Create Tags Index Page and Validate Build
**Files:**
- Create: `docs/tags.md`
- [ ] **Step 1: Create `docs/tags.md`**
```markdown
# Tag Index
Browse all documentation by tag. Click any tag to see all pages that carry it.
<!-- material/tags -->
```
- [ ] **Step 2: Install dependencies and build locally**
```bash
pip install -r requirements.txt
mkdocs build --strict
```
Expected: Build succeeds, `site/` directory contains rendered HTML, `site/traceability-coverage.json` exists.
- [ ] **Step 3: Run standalone validator**
```bash
python scripts/validate_traceability.py docs/
```
Expected: Exit code 0 if all referenced IDs have definitions. Any broken chains will be reported.
- [ ] **Step 4: Check the generated coverage file**
```bash
cat site/traceability-coverage.json
```
Expected: JSON with chain coverage percentages and orphan list (if any).
- [ ] **Step 5: Commit**
```bash
git add docs/tags.md
git commit -m "docs: add tags index page for traceability browsing"
```
- [ ] **Step 6: Push to GitHub**
```bash
git push origin main
```
---
### Task 8: Restructure Code Repo — Create dev-docs/
**Files:**
- Create: `dev-docs/superpowers/specs/` (directory)
- Create: `dev-docs/superpowers/plans/_archived/` (directory)
- Create: `dev-docs/offline-knowledge/reviews/` (directory)
- Create: `dev-docs/release/` (directory)
Note: This task runs in the main `chanora` code repo.
- [ ] **Step 1: Create dev-docs directory structure**
```bash
mkdir -p dev-docs/superpowers/plans/_archived
mkdir -p dev-docs/superpowers/specs
mkdir -p dev-docs/offline-knowledge/reviews
mkdir -p dev-docs/release
```
- [ ] **Step 2: Move superpowers specs**
```bash
mv docs/superpowers/specs/* dev-docs/superpowers/specs/
```
- [ ] **Step 3: Move active plans**
```bash
mv docs/superpowers/plans/2026-05-28-server-resolution-prefetch.md dev-docs/superpowers/plans/
mv docs/superpowers/plans/2026-05-28-chanora-server-prefetch-crate.md dev-docs/superpowers/plans/
mv docs/superpowers/plans/2026-06-06-chat-panel-switching.md dev-docs/superpowers/plans/
mv docs/superpowers/plans/2026-06-08-core-internal-split.md dev-docs/superpowers/plans/
mv docs/superpowers/plans/2026-06-08-maintainability-continuation.md dev-docs/superpowers/plans/
```
- [ ] **Step 4: Move completed plans to archive**
```bash
mv docs/superpowers/plans/2026-05-29-finish-dv-document-tree.md dev-docs/superpowers/plans/_archived/
mv docs/superpowers/plans/2026-05-29-dv-evidence-pack.md dev-docs/superpowers/plans/_archived/
mv docs/superpowers/plans/2026-05-29-swe2-swe3-baselines.md dev-docs/superpowers/plans/_archived/
mv docs/superpowers/plans/2026-05-29-state-sync-ui-settings-validation.md dev-docs/superpowers/plans/_archived/
```
- [ ] **Step 5: Move offline-knowledge (minus external/)**
```bash
mv docs/offline-knowledge/coverage-analysis.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/doc-quality-analysis.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/link-coverage-report.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/docs-code-mismatch.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/docs-link-not-covered.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/docs-out-of-date.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/function-inventory.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/README.md dev-docs/offline-knowledge/
mv docs/offline-knowledge/reviews/* dev-docs/offline-knowledge/reviews/
```
- [ ] **Step 6: Move implementation status and ios-build**
```bash
mv docs/implementation-status-2026-05-28.md dev-docs/
mv docs/release/ios-build.md dev-docs/release/
```
- [ ] **Step 7: Remove now-empty directories**
```bash
rm -rf docs/superpowers
rm -rf docs/offline-knowledge
rm -f docs/implementation-status-2026-05-28.md
```
- [ ] **Step 8: Commit**
```bash
git add -A
git commit -m "refactor: move development docs to dev-docs/ directory"
```
---
### Task 9: Add Git Submodule and Remove Original Docs
**Files:**
- Modify: `.gitmodules` (created by git submodule add)
- Remove: `docs/` directory contents (replaced by submodule)
Note: This task runs in the main `chanora` code repo.
- [ ] **Step 1: Remove original docs/ contents (keeping the directory)**
```bash
# Back up any remaining files first
ls docs/
# Remove everything except what was already moved
rm -rf docs/architecture docs/governance docs/i18n docs/implementation-status-2026-05-28.md docs/legal docs/material3-guideline.md docs/offline-knowledge docs/privacy docs/references docs/release docs/requirements docs/security docs/srs.md docs/superpowers docs/sysdes.md docs/sysrs.md docs/ui-ux docs/verification
```
- [ ] **Step 2: Verify docs/ is empty**
```bash
ls -la docs/
```
Expected: Empty directory (or only hidden files like `.gitkeep`).
- [ ] **Step 3: Add chanora-docs as submodule**
```bash
git submodule add git@github.com:EdisonJwa/chanora-docs.git docs
```
Expected: Creates `.gitmodules` file and `docs/` directory with submodule content.
- [ ] **Step 4: Verify submodule is working**
```bash
ls docs/
```
Expected: Contents of the chanora-docs repo (mkdocs.yml, docs/, plugins/, etc.).
- [ ] **Step 5: Commit**
```bash
git add .gitmodules docs
git commit -m "chore: add chanora-docs as git submodule at docs/"
```
---
### Task 10: Write AGENTS.md and Update Cross-References
**Files:**
- Create: `AGENTS.md`
- Modify: `README.md` (update doc path references)
- Create: `dev-docs/impl-mapping.md`
Note: This task runs in the main `chanora` code repo.
- [ ] **Step 1: Write `AGENTS.md`**
```markdown
# AGENTS.md — Chanora Project Conventions
## Project Overview
Chanora is a cross-platform voice client (Flutter + Rust) targeting TeamSpeak-compatible servers. The project follows ASPICE engineering processes with full traceability from system requirements through verification.
## Repository Structure
```
chanora/ ← Code repo (this one)
├── docs/ → chanora-docs ← Git submodule: ASPICE docs, doc site source
├── dev-docs/ ← Local-only development docs
│ ├── superpowers/ ← AI agent specs and plans
│ │ ├── specs/ ← Feature/design specs (active)
│ │ └── plans/ ← Implementation plans (active)
│ │ └── _archived/ ← Completed plans
│ ├── offline-knowledge/ ← Doc maintenance tools, link coverage
│ ├── implementation-status-* ← Code state snapshots
│ └── release/ios-build.md ← Operational build instructions
├── apps/chanora_flutter/ ← Flutter application
├── core/chanora_core/ ← Rust core API + orchestration
├── crates/ ← Rust crates (protocol, audio, state, etc.)
└── dev-docs/impl-mapping.md ← SAD component → source file mapping
```
## Documentation Two-Repo Model
**`docs/` is a git submodule** pointing to the separate `chanora-docs` repository. It is NOT a local directory you can freely create files in.
### What lives where
| Content | Location | Reason |
|---|---|---|
| SysRS, SysDes, SRS, SAD, SDD | `docs/` (submodule) | ASPICE baselines, served on doc site |
| Verification plans (SWE.4/5/6, SYS.4) | `docs/` (submodule) | ASPICE verification evidence |
| Governance, traceability, decision register | `docs/` (submodule) | ASPICE governance |
| Security, privacy, legal | `docs/` (submodule) | Stakeholder-facing |
| UI/UX guidelines, i18n architecture | `docs/` (submodule) | Design references |
| Feature specs and implementation plans | `dev-docs/superpowers/` | Code-coupled, agent working files |
| Link coverage, doc quality analysis | `dev-docs/offline-knowledge/` | Maintenance tools |
| Implementation status snapshots | `dev-docs/` | Code state tracking |
| Source file path references | `dev-docs/impl-mapping.md` | Developer convenience, not ASPICE |
### Rules for agents
1. **Never create or edit files in `docs/`** without understanding it's a submodule. Changes there require committing in the `chanora-docs` repo first, then updating the submodule pointer in this repo.
2. **ASPICE documents do not contain code file paths.** ASPICE traces requirement IDs (e.g., `SysRS-233`, `SRS-045`, `SDD-MOD-009`), not source file paths. If you need to map a component to its source, use or update `dev-docs/impl-mapping.md`.
3. **Specs and plans go in `dev-docs/superpowers/`.** Follow the naming convention: `YYYY-MM-DD-<topic>-design.md` for specs, `YYYY-MM-DD-<topic>.md` for plans.
4. **Completed plans move to `_archived/`.** Once a plan is fully implemented and verified, move it to `dev-docs/superpowers/plans/_archived/`.
## ASPICE Traceability Chain
```text
SysRS → SysDes → SRS → SAD (SWE.2) → SDD (SWE.3) → Verification
↓ ↓
SWE.4 (unit) SWE.4/5/6/SYS.4
```
- Requirement IDs are the traceability mechanism, not file paths.
- Every downstream document must reference upstream IDs it traces from.
- Verification plans map to their upstream design/requirements level:
- SYS.4 ← SysDes, SysRS
- SWE.5 ← SAD (SWE.2)
- SWE.4 ← SDD (SWE.3)
- SWE.6 ← SRS
## Code Architecture
| Component | Location | Responsibility |
|---|---|---|
| Flutter app shell | `apps/chanora_flutter/` | UI, Material 3, navigation, localization |
| Rust core | `core/chanora_core/` | Session orchestration, bridge events |
| Protocol adapter | `crates/chanora_protocol/` | TeamSpeak protocol via tsclientlib |
| State sync | `crates/chanora_state/` | Snapshots, deltas, reducers |
| Audio subsystem | `crates/chanora_audio/` | Capture, DSP, Opus, PTT |
| Storage | `crates/chanora_storage/` | Bookmarks, identity, encryption |
| Diagnostics | `crates/chanora_diagnostics/` | Redaction, logs, export |
| Resolver | `crates/chanora_resolver/` | SRV/TSDNS/DNS resolution |
| Prefetch | `crates/chanora_prefetch/` | Resolution warming, TTL cache |
| Bridge | `crates/chanora_bridge/` | Flutter/Rust typed DTO boundary |
| Cache | `crates/chanora_cache/` | Avatar/icon blob cache |
## Coding Conventions
- **Rust:** Follow workspace `Cargo.toml` structure. Run `cargo check`, `cargo clippy`, `cargo test` before committing.
- **Flutter:** Run `flutter analyze`, `flutter test` before committing.
- **No code comments** unless explicitly requested.
- **Git commits:** Follow convention in `docs/governance/git-commit-message-convention.md` (accessible via submodule).
- **Bridge boundary:** Flutter must not directly depend on protocol-library internals. All cross-boundary communication goes through `chanora_bridge` typed DTOs.
## Verification Commands
```bash
cargo check && cargo clippy && cargo test
cd apps/chanora_flutter && flutter analyze && flutter test
```
## Important References
- Traceability matrix: `docs/governance/traceability-matrix.md`
- Decision register: `docs/governance/product-decision-register.md`
- Security guidelines: `docs/security/security-privacy-legal-guideline.md`
- Release readiness: `docs/release/release-readiness-go-nogo-record.md`
```
- [ ] **Step 2: Create `dev-docs/impl-mapping.md`**
```markdown
# SAD Component → Source File Mapping
**Purpose:** Developer convenience mapping from ASPICE architecture components to source file locations. This is NOT an ASPICE document — it's a lookup for developers.
## Component Mapping
| SAD Component | Source Location |
|---|---|
| Flutter app shell | `apps/chanora_flutter/lib/main.dart`, services, widgets |
| Flutter service layer | `apps/chanora_flutter/lib/services/` |
| Flutter widget layer | `apps/chanora_flutter/lib/widgets/` |
| Bridge layer | `crates/chanora_bridge/src/api.rs`, `apps/chanora_flutter/lib/src/rust/` |
| Rust core | `core/chanora_core/src/lib.rs`, `events.rs`, `network_diagnostics.rs`, `ptt.rs` |
| Protocol adapter | `crates/chanora_protocol/src/` |
| State sync | `crates/chanora_state/src/lib.rs`, `channel_join.rs` |
| Audio subsystem | `crates/chanora_audio/src/` |
| Storage | `crates/chanora_storage/src/lib.rs` |
| Diagnostics | `crates/chanora_diagnostics/src/lib.rs` |
| Resolution and prefetch | `crates/chanora_resolver/src/lib.rs`, `crates/chanora_prefetch/src/lib.rs`, `prefetch_debouncer.dart` |
| Build and release hooks | `.github/workflows/`, `tools/`, platform project files |
## SDD Module Mapping
| SDD Module | Source Location |
|---|---|
| SDD-MOD-001 Flutter app bootstrap | `apps/chanora_flutter/lib/services/app_bootstrap.dart`, `main.dart` |
| SDD-MOD-002 Connect UI | `apps/chanora_flutter/lib/widgets/connect_widgets.dart` |
| SDD-MOD-003 Snapshot and channel UI | `snapshot_view.dart`, `snapshot_state_mapper.dart`, `channel_spacer.dart` |
| SDD-MOD-004 Chat UI | `chat_views.dart`, `bbcode_text.dart` |
| SDD-MOD-005 Voice UI | `voice_bar.dart`, `voice_compact.dart`, `voice_settings*.dart`, `voice_level_meter.dart`, `ptt_capability_badge.dart` |
| SDD-MOD-006 Platform services | `android_permissions_service.dart`, `ios_permissions_service.dart`, `audio_lifecycle_service.dart`, `back_intent_*`, `link_trust_service.dart` |
| SDD-MOD-007 Bridge API | `crates/chanora_bridge/src/api.rs`, generated Dart/Rust bridge files |
| SDD-MOD-008 Rust core supervisor | `core/chanora_core/src/lib.rs`, `events.rs`, `network_diagnostics.rs`, `ptt.rs` |
| SDD-MOD-009 Protocol adapter | `crates/chanora_protocol/src/` |
| SDD-MOD-010 State sync | `crates/chanora_state/src/lib.rs`, `channel_join.rs` |
| SDD-MOD-011 Audio subsystem | `crates/chanora_audio/src/` |
| SDD-MOD-012 Storage | `crates/chanora_storage/src/lib.rs` |
| SDD-MOD-013 Diagnostics | `crates/chanora_diagnostics/src/lib.rs` |
| SDD-MOD-014 Resolution and prefetch | `crates/chanora_resolver/src/lib.rs`, `crates/chanora_prefetch/src/lib.rs`, `prefetch_debouncer.dart` |
| SDD-MOD-015 Build and release hooks | `.github/workflows/`, `tools/`, platform project files |
```
- [ ] **Step 3: Update README.md doc path references**
Replace any remaining references to old `docs/` paths (like `docs/superpowers/`) with `dev-docs/superpowers/`. Use grep to find all references:
```bash
grep -n "docs/superpowers\|docs/implementation-status\|docs/offline-knowledge" README.md
```
Update any found references to point to `dev-docs/`.
- [ ] **Step 4: Commit**
```bash
git add AGENTS.md dev-docs/impl-mapping.md README.md
git commit -m "docs: add AGENTS.md and impl-mapping.md, update README references"
```
---
### Task 11: Update .gitignore and Verify Final State
**Files:**
- Modify: `.gitignore`
- [ ] **Step 1: Verify submodule status**
```bash
git submodule status
```
Expected: Shows chanora-docs commit hash.
- [ ] **Step 2: Verify docs/ contains submodule content**
```bash
ls docs/mkdocs.yml
```
Expected: File exists.
- [ ] **Step 3: Verify dev-docs/ structure**
```bash
find dev-docs -type f -name '*.md' | sort
```
Expected: All local-only docs present.
- [ ] **Step 4: Verify no stale docs/ files remain outside submodule**
```bash
git status
```
Expected: No untracked files in `docs/` outside the submodule pointer.
- [ ] **Step 5: Final commit if needed**
```bash
git add -A
git commit -m "chore: finalize documentation repo restructure"
```
Reference in New Issue View Git Blame Copy Permalink