refactor: restructure docs as submodule, add dev-docs/ and AGENTS.md
- 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)
This commit is contained in:
Edison Jwa
@@ -0,0 +1,114 @@
|
||||
# DV Evidence Pack 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 document set that lets a DV meeting review Chanora's current verification posture, traceability, release blockers, waivers, and evidence without implying incomplete work is complete.
|
||||
|
||||
**Architecture:** The pack is documentation-only. Verification plans live under `docs/verification/`; release decision evidence lives under `docs/release/`; cross-document traceability lives under `docs/governance/`; security, privacy, and legal gate summaries live in their existing README-advertised folders.
|
||||
|
||||
**Tech Stack:** Markdown, existing SysRS/SysDes/SRS baselines, implementation status report, CI workflow definitions.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Create Verification Plan Set
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/verification/verification-master-plan.md`
|
||||
- Create: `docs/verification/swe4-unit-verification-plan.md`
|
||||
- Create: `docs/verification/swe5-software-integration-verification-plan.md`
|
||||
- Create: `docs/verification/swe6-software-verification-plan.md`
|
||||
- Create: `docs/verification/sys4-system-integration-verification-plan.md`
|
||||
|
||||
- [x] **Step 1: Write master plan**
|
||||
|
||||
Create `docs/verification/verification-master-plan.md` with lifecycle scope, evidence rules, entry/exit criteria, current evidence sources, open gates, and reviewer decision framing.
|
||||
|
||||
- [x] **Step 2: Write SWE.4 plan**
|
||||
|
||||
Create `docs/verification/swe4-unit-verification-plan.md` with unit verification scope for Rust crates, Flutter services/widgets, diagnostics, storage, state reducers, audio DSP, and known unit-test gaps.
|
||||
|
||||
- [x] **Step 3: Write SWE.5 plan**
|
||||
|
||||
Create `docs/verification/swe5-software-integration-verification-plan.md` with cross-component integration scope for Flutter-bridge-core, protocol-state, audio-platform, secure storage, diagnostics export, resolver prefetch, and packaging hooks.
|
||||
|
||||
- [x] **Step 4: Write SWE.6 plan**
|
||||
|
||||
Create `docs/verification/swe6-software-verification-plan.md` with SRS-level acceptance scope and the SysRS-241 through SysRS-257 MVP acceptance matrix.
|
||||
|
||||
- [x] **Step 5: Write SYS.4 plan**
|
||||
|
||||
Create `docs/verification/sys4-system-integration-verification-plan.md` with system-level integration scope for external compatible servers, OS services, hardware, network, app stores, diagnostics, and release evidence.
|
||||
|
||||
### Task 2: Create Release and DV Decision Records
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/release/release-readiness-go-nogo-record.md`
|
||||
- Create: `docs/release/dv-waiver-register.md`
|
||||
|
||||
- [x] **Step 1: Write release readiness record**
|
||||
|
||||
Create `docs/release/release-readiness-go-nogo-record.md` with current candidate metadata, decision state, platform readiness, verification status, legal/security/privacy gates, blockers, and meeting recommendation.
|
||||
|
||||
- [x] **Step 2: Write waiver register**
|
||||
|
||||
Create `docs/release/dv-waiver-register.md` with explicit waivers for DEC-012, Android Keystore DEK, iOS voice-processing mode, source-build-only desktop/iOS artifacts, state reducer coverage, and VAD deferral.
|
||||
|
||||
### Task 3: Create Traceability and Gate Summaries
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/governance/traceability-matrix.md`
|
||||
- Create: `docs/security/security-privacy-legal-guideline.md`
|
||||
- Create: `docs/security/dependency-and-supply-chain-report.md`
|
||||
- Create: `docs/privacy/privacy-policy.md`
|
||||
- Create: `docs/legal/trademark-and-attribution-review.md`
|
||||
|
||||
- [x] **Step 1: Write traceability matrix**
|
||||
|
||||
Create `docs/governance/traceability-matrix.md` summarizing SysRS to SysDes to SRS to verification coverage, including the MVP acceptance and verification handoff items.
|
||||
|
||||
- [x] **Step 2: Write security/privacy/legal guideline**
|
||||
|
||||
Create `docs/security/security-privacy-legal-guideline.md` summarizing release gates and evidence expectations for secure storage, diagnostics redaction, dependency review, privacy policy, and affiliation wording.
|
||||
|
||||
- [x] **Step 3: Write dependency report**
|
||||
|
||||
Create `docs/security/dependency-and-supply-chain-report.md` summarizing current CI checks and open evidence gaps without claiming DEC-012 completion.
|
||||
|
||||
- [x] **Step 4: Write privacy policy baseline**
|
||||
|
||||
Create `docs/privacy/privacy-policy.md` as an engineering release-candidate privacy baseline covering local storage, permissions, diagnostics, and the no automatic telemetry posture.
|
||||
|
||||
- [x] **Step 5: Write trademark review**
|
||||
|
||||
Create `docs/legal/trademark-and-attribution-review.md` with current non-affiliation wording requirement and open legal sign-off state.
|
||||
|
||||
### Task 4: Verify Documentation Pack
|
||||
|
||||
**Files:**
|
||||
- Inspect all created files.
|
||||
|
||||
- [x] **Step 1: Search for forbidden sentinel text**
|
||||
|
||||
Run the sentinel-language scan over `docs/verification`, `docs/release`, `docs/governance`, `docs/security`, `docs/privacy`, and `docs/legal`.
|
||||
|
||||
Expected: no matches introduced by the DV evidence pack except intentional historical references in source documents outside these folders.
|
||||
|
||||
- [x] **Step 2: Confirm expected files exist**
|
||||
|
||||
Run: `ls docs/verification docs/release docs/governance docs/security docs/privacy docs/legal`
|
||||
|
||||
Expected: all DV evidence pack files are listed.
|
||||
|
||||
- [x] **Step 3: Inspect git status and diff**
|
||||
|
||||
Run: `git diff -- docs/verification docs/release docs/governance docs/security docs/privacy docs/legal docs/superpowers/plans/2026-05-29-dv-evidence-pack.md`
|
||||
|
||||
Expected: only intended Markdown additions are present.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
- Spec coverage: covers verification plan set, release decision evidence, waiver register, traceability matrix, and minimum security/privacy/legal gate summaries.
|
||||
- Placeholder scan: plan contains no incomplete instructions.
|
||||
- Type consistency: document paths match the README-advertised folders and task file list.
|
||||
@@ -0,0 +1,79 @@
|
||||
# Finish DV Document Tree 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:** Fill the README-advertised document tree with baseline candidate documents so DV reviewers can navigate all required gates.
|
||||
|
||||
**Architecture:** Keep canonical large baselines at current root paths and add README-path stubs or summaries where needed. Governance, release, security, privacy, legal, UI/UX, i18n, and references each get explicit baseline documents that state current evidence and open gates honestly.
|
||||
|
||||
**Tech Stack:** Markdown documentation aligned to SysRS, SysDes, SRS, SAD, SDD, verification, release, and implementation status.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Add Requirements Path Wrappers
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/requirements/sysrs.md`
|
||||
- Create: `docs/requirements/srs.md`
|
||||
|
||||
- [x] **Step 1: Create README entry records that point to canonical root documents and summarize DV review anchors**
|
||||
|
||||
These wrappers preserve README paths without duplicating the canonical baselines.
|
||||
|
||||
### Task 2: Add Governance Baselines
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/governance/document-index.md`
|
||||
- Create: `docs/governance/document-naming-convention.md`
|
||||
- Create: `docs/governance/baseline-approval-record.md`
|
||||
- Create: `docs/governance/baseline-candidate-validation-report.md`
|
||||
- Create: `docs/governance/document-review-report.md`
|
||||
- Create: `docs/governance/product-decision-register.md`
|
||||
- Create: `docs/governance/decision-impact-assessment.md`
|
||||
- Create: `docs/governance/git-commit-message-convention.md`
|
||||
- Create: `docs/governance/repo-format-validation-report.md`
|
||||
- Create: `docs/governance/path-migration-map.md`
|
||||
|
||||
- [x] **Step 1: Write governance records**
|
||||
|
||||
Each record summarizes status for DV, identifies owner expectations, and avoids claiming final release approval.
|
||||
|
||||
### Task 3: Add Remaining Release, Security, UI/UX, I18n, Reference Docs
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/release/platform-release-policy.md`
|
||||
- Create: `docs/security/threat-model.md`
|
||||
- Create: `docs/security/secure-storage-audit-report.md`
|
||||
- Create: `docs/security/diagnostic-redaction-audit-report.md`
|
||||
- Create: `docs/ui-ux/material3-guideline.md`
|
||||
- Create: `docs/ui-ux/material3-design-tokens.md`
|
||||
- Create: `docs/ui-ux/material3-component-catalog.md`
|
||||
- Create: `docs/ui-ux/adaptive-layout-platform-guide.md`
|
||||
- Create: `docs/i18n/localization-architecture.md`
|
||||
- Create: `docs/references/external-references.md`
|
||||
- Create: `docs/references/aspice-swe2-swe3-integration-note.md`
|
||||
|
||||
- [x] **Step 1: Write remaining baseline docs**
|
||||
|
||||
Use concise DV-ready records that reference current implementation and open gaps.
|
||||
|
||||
### Task 4: Verify Complete Tree
|
||||
|
||||
**Files:**
|
||||
- Inspect all created documents.
|
||||
|
||||
- [x] **Step 1: Check README paths exist**
|
||||
|
||||
Run a shell `test -f` command over every README-advertised path.
|
||||
|
||||
- [x] **Step 2: Sentinel-language scan**
|
||||
|
||||
Run the sentinel-language scan over `docs/requirements`, `docs/architecture`, `docs/verification`, `docs/release`, `docs/security`, `docs/privacy`, `docs/legal`, `docs/ui-ux`, `docs/i18n`, `docs/governance`, and `docs/references`; expect no matches.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
- Spec coverage: fills all README-advertised document paths except already existing files.
|
||||
- Placeholder scan: plan contains no incomplete document instructions.
|
||||
- Type consistency: file paths match README tree.
|
||||
@@ -0,0 +1,108 @@
|
||||
# State Sync and UI Settings Validation 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:** Complete validation-backed state-sync evidence and UI settings persistence while updating DV documents.
|
||||
|
||||
**Architecture:** State reducer work stays in `crates/chanora_state/src/lib.rs` with Rust unit tests. UI settings persistence stays in `apps/chanora_flutter/lib/services/ui_preferences_service.dart` with Flutter service tests; app-level theme application is wired in `apps/chanora_flutter/lib/main.dart` only if needed by the persisted setting.
|
||||
|
||||
**Tech Stack:** Rust/cargo tests, Flutter/Dart, shared_preferences, Markdown documentation.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: State Reducer Validation
|
||||
|
||||
**Files:**
|
||||
- Modify: `crates/chanora_state/src/lib.rs`
|
||||
|
||||
- [x] **Step 1: Write failing regression test**
|
||||
|
||||
Add `channel_delete_removes_clients_in_deleted_channel` proving channel deletion removes clients assigned to that channel and emits client-removal deltas before the channel-removal delta.
|
||||
|
||||
- [x] **Step 2: Verify RED**
|
||||
|
||||
Run: `cargo test -p chanora_state channel_delete_removes_clients_in_deleted_channel --locked`
|
||||
|
||||
Expected: FAIL because deleted-channel clients remain in state.
|
||||
|
||||
- [x] **Step 3: Implement minimal reducer fix**
|
||||
|
||||
In `StateEvent::ChannelDeleted`, collect clients whose `client.channel == id`, remove them from `clients` and `client_order`, then emit deterministic `ClientRemoved` deltas before `ChannelRemoved`.
|
||||
|
||||
- [x] **Step 4: Verify GREEN**
|
||||
|
||||
Run: `cargo test -p chanora_state channel_delete_removes_clients_in_deleted_channel --locked`
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
- [x] **Step 5: Run full state crate tests**
|
||||
|
||||
Run: `cargo test -p chanora_state --locked`
|
||||
|
||||
Expected: all state crate tests pass.
|
||||
|
||||
### Task 2: UI Settings Persistence
|
||||
|
||||
**Files:**
|
||||
- Modify: `apps/chanora_flutter/lib/services/ui_preferences_service.dart`
|
||||
- Modify: `apps/chanora_flutter/test/services/ui_preferences_service_test.dart`
|
||||
- Modify: `apps/chanora_flutter/lib/main.dart`
|
||||
|
||||
- [x] **Step 1: Add failing tests for theme persistence**
|
||||
|
||||
Add tests for default `system` theme mode, saving `dark`, saving `light`, and invalid stored value fallback to `system`.
|
||||
|
||||
- [x] **Step 2: Verify RED**
|
||||
|
||||
Run: `flutter test test/services/ui_preferences_service_test.dart`
|
||||
|
||||
Expected: FAIL because `UiThemeMode`, `themeMode`, and `saveThemeMode` do not exist.
|
||||
|
||||
- [x] **Step 3: Implement minimal service changes**
|
||||
|
||||
Add `UiThemeMode`, `UiSettings.themeMode`, persisted key `ui.theme_mode`, and `saveThemeMode`.
|
||||
|
||||
- [x] **Step 4: Verify GREEN**
|
||||
|
||||
Run: `flutter test test/services/ui_preferences_service_test.dart`
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
- [x] **Step 5: Wire app theme mode**
|
||||
|
||||
Make `ChanoraApp` load persisted theme mode and pass `themeMode` into `MaterialApp`.
|
||||
|
||||
- [x] **Step 6: Run focused Flutter tests**
|
||||
|
||||
Run: `flutter test test/services/ui_preferences_service_test.dart`
|
||||
|
||||
Expected: PASS.
|
||||
|
||||
### Task 3: Documentation Updates
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/implementation-status-2026-05-28.md`
|
||||
- Modify: `docs/release/dv-waiver-register.md`
|
||||
- Modify: `docs/verification/swe4-unit-verification-plan.md`
|
||||
- Modify: `docs/verification/swe6-software-verification-plan.md`
|
||||
- Modify: `docs/architecture/sdd.md`
|
||||
|
||||
- [x] **Step 1: Update implementation status**
|
||||
|
||||
Mark `chanora_state` scaffold statement as superseded by reducer implementation/tests and mark UI settings persistence implemented for SharedPreferences scope.
|
||||
|
||||
- [x] **Step 2: Update waiver and verification docs**
|
||||
|
||||
Record reducer evidence and leave event replay as the remaining P1 state-sync gap.
|
||||
|
||||
- [x] **Step 3: Verify docs**
|
||||
|
||||
Run sentinel-language scan over edited docs.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
- Spec coverage: covers reducer evidence, UI settings persistence, and document updates.
|
||||
- Placeholder scan: plan contains no incomplete implementation instructions.
|
||||
- Type consistency: `UiThemeMode`, `themeMode`, and `saveThemeMode` names are used consistently.
|
||||
@@ -0,0 +1,68 @@
|
||||
# SWE.2/SWE.3 Baselines 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:** Add reviewable SWE.2/SAD and SWE.3/SDD baselines so the DV document chain is no longer missing the architecture and detailed design layers.
|
||||
|
||||
**Architecture:** Keep SWE.2 in `docs/architecture/sad.md` and SWE.3 in `docs/architecture/sdd.md`, matching the README document tree. Update DV traceability and verification-plan wording to consume these baselines while preserving honest limitations for areas that still need deeper detail.
|
||||
|
||||
**Tech Stack:** Markdown, existing SysDes/SRS baselines, current Flutter/Rust workspace structure.
|
||||
|
||||
---
|
||||
|
||||
### Task 1: Write SWE.2 SAD Baseline
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/architecture/sad.md`
|
||||
|
||||
- [x] **Step 1: Create SAD with architecture views**
|
||||
|
||||
Write sections for purpose, upstream sources, components, static view, runtime flows, interface catalogue, dependency rules, non-functional allocation, architectural decisions, verification handoff, traceability, and open architecture risks.
|
||||
|
||||
### Task 2: Write SWE.3 SDD Baseline
|
||||
|
||||
**Files:**
|
||||
- Create: `docs/architecture/sdd.md`
|
||||
|
||||
- [x] **Step 1: Create SDD with module designs**
|
||||
|
||||
Write sections for purpose, upstream sources, module catalogue, detailed API/data/state design, persistence, diagnostics, platform adapters, build/release design, verification hooks, traceability, and open detailed-design risks.
|
||||
|
||||
### Task 3: Update DV Traceability
|
||||
|
||||
**Files:**
|
||||
- Modify: `docs/governance/traceability-matrix.md`
|
||||
- Modify: `docs/verification/verification-master-plan.md`
|
||||
|
||||
- [x] **Step 1: Remove SAD/SDD missing limitation**
|
||||
|
||||
Update traceability text so it says SAD and SDD baselines exist, with known depth limitations instead of missing-document limitations.
|
||||
|
||||
- [x] **Step 2: Update verification plan inputs**
|
||||
|
||||
Update verification master plan to reference SAD and SDD as current inputs for SWE.4/SWE.5.
|
||||
|
||||
### Task 4: Verify SWE.2/SWE.3 Pack
|
||||
|
||||
**Files:**
|
||||
- Inspect created and updated docs.
|
||||
|
||||
- [x] **Step 1: Sentinel-language scan**
|
||||
|
||||
Run the sentinel-language scan over `docs/architecture`, `docs/governance`, and `docs/verification`.
|
||||
|
||||
Expected: no matches introduced by this baseline pack.
|
||||
|
||||
- [x] **Step 2: File presence check**
|
||||
|
||||
Run: `ls docs/architecture`
|
||||
|
||||
Expected: `sad.md` and `sdd.md` are listed.
|
||||
|
||||
---
|
||||
|
||||
## Self-Review
|
||||
|
||||
- Spec coverage: creates SAD and SDD baselines and updates DV traceability consumers.
|
||||
- Placeholder scan: no incomplete instructions are present.
|
||||
- Type consistency: document names match README paths.
|
||||
Reference in New Issue
Block a user