chanora/dev-docs/superpowers/plans/2026-06-13-documentation-site.md

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 MkDocs Material doc site with tag-based ASPICE traceability, hosted on Cloudflare Pages with access control, served from a git submodule.

Architecture: The docs repo (chanora-docs) is a standalone MkDocs Material project added as a git submodule at docs/ in the code repo. A custom MkDocs plugin validates requirement ID traceability chains on every build. The code repo retains development-only docs in dev-docs/.

Tech Stack: MkDocs Material, Python 3.12, MkDocs tags/git-revision-date-localized plugins, custom traceability plugin (~200 lines Python), GitHub Actions, Cloudflare Pages + Access, git submodules

Spec: dev-docs/superpowers/specs/2026-06-13-documentation-site-design.md

---

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

gh repo create chanora-docs --private --description "Chanora engineering documentation with ASPICE traceability"

• Step 2: Clone and initialize

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

[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

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)

status: draft

• Step 7: Create docs/index.md (landing page)

# 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)
• System Design (SysDes)
• Software Requirements (SRS)
• Software Architecture (SAD)
• Detailed Design (SDD)
• Verification Master Plan
• Traceability Matrix
• Document Index

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 →

- [ ] **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

mkdocs build --strict

Traceability Validation

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

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

# plugins/traceability/__init__.py
from .traceability import TraceabilityPlugin

def make_plugin(config, **kwargs):
    return TraceabilityPlugin(config)

• Step 2: Write the traceability plugin

# 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

# 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

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

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

#!/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

chmod +x scripts/validate_traceability.py

• Step 3: Create docs/.meta.yml and a test file to validate the script

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

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

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

name = "chanora-docs"
compatibility_date = "2026-06-13"

[site]
bucket = "./site"

• Step 3: Commit

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

# 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

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

cp ../chanora/docs/verification/*.md docs/verification/

• Step 4: Copy governance docs

cp ../chanora/docs/governance/*.md docs/governance/

• Step 5: Copy security, privacy, legal docs

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)

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

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

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

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

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):

---
tags: [sysrs, requirements, swe.1, baseline]
upstream: []
downstream: [sysdes, srs]
lifecycle: SysRS
status: baseline
---

• Step 2: Add front matter to docs/requirements/sysdes.md

---
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

---
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

---
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

---
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:

---
tags: [verification, baseline]
upstream: [sysrs, sysdes, srs, sad, sdd]
downstream: []
lifecycle: SWE.4-SWE.6
status: candidate
---

docs/verification/swe4-unit-verification-plan.md:

---
tags: [swe.4, verification, candidate]
upstream: [sdd]
downstream: []
lifecycle: SWE.3 → SWE.4
status: candidate
---

docs/verification/swe5-software-integration-verification-plan.md:

---
tags: [swe.5, verification, candidate]
upstream: [sad]
downstream: []
lifecycle: SWE.2 → SWE.5
status: candidate
---

docs/verification/swe6-software-verification-plan.md:

---
tags: [swe.6, verification, candidate]
upstream: [srs]
downstream: []
lifecycle: SRS → SWE.6
status: candidate
---

docs/verification/sys4-system-integration-verification-plan.md:

---
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

---
tags: [governance, baseline]
upstream: [sysrs, sysdes, srs, sad, sdd]
downstream: []
lifecycle: traceability
status: candidate
---

• Step 8: Commit

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

# 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

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

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

cat site/traceability-coverage.json

Expected: JSON with chain coverage percentages and orphan list (if any).

• Step 5: Commit

git add docs/tags.md
git commit -m "docs: add tags index page for traceability browsing"

• Step 6: Push to GitHub

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

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

mv docs/superpowers/specs/* dev-docs/superpowers/specs/

• Step 3: Move active plans

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

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/)

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

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

rm -rf docs/superpowers
rm -rf docs/offline-knowledge
rm -f docs/implementation-status-2026-05-28.md

• Step 8: Commit

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)

# 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

ls -la docs/

Expected: Empty directory (or only hidden files like .gitkeep).

• Step 3: Add chanora-docs as submodule

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

ls docs/

Expected: Contents of the chanora-docs repo (mkdocs.yml, docs/, plugins/, etc.).

• Step 5: Commit

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

# 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

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:

grep -n "docs/superpowers\|docs/implementation-status\|docs/offline-knowledge" README.md

Update any found references to point to dev-docs/.

• Step 4: Commit

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

git submodule status

Expected: Shows chanora-docs commit hash.

• Step 2: Verify docs/ contains submodule content

ls docs/mkdocs.yml

Expected: File exists.

• Step 3: Verify dev-docs/ structure

find dev-docs -type f -name '*.md' | sort

Expected: All local-only docs present.

• Step 4: Verify no stale docs/ files remain outside submodule

git status

Expected: No untracked files in docs/ outside the submodule pointer.

• Step 5: Final commit if needed

git add -A
git commit -m "chore: finalize documentation repo restructure"