TokenDanceLab · DeliciousBuding · Jun 27, 2026 · Jun 27, 2026
diff --git a/docs/analysis/module-inventory.md b/docs/analysis/module-inventory.md
@@ -0,0 +1,19 @@
+# Module Inventory
+
+| Module | Responsibility | Cleanup Pressure | S.U.P.E.R Notes |
+|---|---|---|---|
+| `AGENTS.md` | Single project rule surface | Keep, update only if durable workflow rules change | S/U/R: good; avoid moving rules into plan docs |
+| `docs/README.md` / `docs/roadmap.md` / `docs/architecture.md` | Active docs navigation, product roadmap, architecture entry | Keep short; update links after archive/ADR migration | S/U: good after prior cleanup |
+| `docs/architecture/` | Current module architecture | Keep active | P/E: owns current contracts and evidence wording |
+| `docs/governance/` | Current governance/security/threat docs | Keep active, no dated evidence | S: good if only owner docs remain |
+| `docs/reference/` | Small current reference docs | Keep active | R: should stay short and link to external archive when history moves |
+| `docs/archive/` | Historical longform and dated material | Move to external TokenDance docs archive; replace with `docs/history.md` | S: currently mixed into source repo |
+| `docs/archives/` | Completed SPEC artifacts and archived skills | Move to external TokenDance docs archive; keep history index only | R: currently large but useful as history |
+| `docs/adr/` | ADR body files and README summary | Compress to `docs/decisions.md`; old bodies move external | S/R: active summary is useful, body sprawl is not |
+| `scripts/` | Developer, verify, smoke, release, package, evidence helpers | Reorganize wrapper-first into typed subdirs | R: many direct references require staged migration |
+| `scripts/evidence/` | Evidence helper scripts | Preserve under `scripts/lib/` or `scripts/verify/` based on owner | P/R: avoid breaking approved-real scripts |
+| `scripts/git-hooks/` | Local git hook helpers | Likely keep under `scripts/dev/git-hooks/` or `scripts/lib/git-hooks/` with wrapper | E/R: path used by hook docs/scripts |
+| `tests/fixtures/` | Deterministic fixtures | Keep stable or update references | P: already target shape |
+| `tests/scripts/` | Script contract tests and approved-real fixtures | Move to `tests/contract/scripts/` with workflow/test updates | P/R: release-readiness currently watches old path |
+| `.github/workflows/` | CI and release-readiness path contracts | Update only with wrappers and verifier coverage | E/R: validates migration |
+| `app/desktop/src-tauri` + Desktop tests | Readiness script path contract | Update only if wrappers or new path are proven | P/E: hard-coded `scripts/verify-edge-cli-real-readiness.ps1` appears in source and tests |
diff --git a/docs/analysis/project-overview.md b/docs/analysis/project-overview.md
@@ -0,0 +1,26 @@
+# Project Overview
+
+## Scope
+
+This SPEC cleans repository structure, active documentation, archive ownership, scripts, tests, and root evidence artifacts. It does not change product behavior, UI runtime logic, Hub/Edge APIs, or Mobile implementation.
+
+## Current Shape
+
+| Area | Current Finding |
+|---|---|
+| Active docs | `docs/README.md`, `docs/roadmap.md`, `docs/architecture.md`, `docs/architecture/`, `docs/governance/`, `docs/reference/`, and `docs/adr/` are active. |
+| Historical docs | `docs/archive/` has 131 Markdown files; `docs/archives/` has 41 Markdown files. |
+| ADR | `docs/adr/` has 16 ADR body files plus `README.md`; several code comments still mention ADR IDs. |
+| Scripts | Root `scripts/` has many direct CI, docs, package, Desktop, and test references; `scripts/evidence/` and `scripts/git-hooks/` already exist. |
+| Tests | Root `tests/` currently has `fixtures/` and `scripts/`; release-readiness triggers on `tests/scripts/**`. |
+| Root artifacts | `css-audit-results.json` is tracked at repo root and appears to be one-off CSS audit evidence. |
+| External archive target | `D:\Code\TokenDance\docs` is an independent Git repo and currently dirty. Use an isolated receiver branch/worktree before adding AgentHub archive files. |
+| GitHub mode | `GITHUB_STANDARD`; `gh project` lacks `read:project` scope, so no project board. |
+
+## Implementation Boundaries
+
+- Baseline branch: `dev/delicious233`.
+- Worktrees: project-local `.worktrees/` for AgentHub; external docs must use an isolated docs repo branch/worktree or an explicitly staged-only commit.
+- No bulk delete before reference graph and verifier updates.
+- Mobile deep UI/native work is out of scope.
+- `real_tested=false` remains required for stubbed/fixture/readiness-only evidence.
diff --git a/docs/analysis/risk-assessment.md b/docs/analysis/risk-assessment.md
@@ -0,0 +1,26 @@
+# Risk Assessment
+
+## Plan Revisions After Inventory
+
+| Original Plan Point | Revision |
+|---|---|
+| Move archives directly to `D:\Code\TokenDance\docs` | Do not write to the dirty main checkout directly. Use an isolated docs repo worktree/branch, or stage only new archive files with explicit status checks. |
+| Delete `docs/archive`, `docs/archives`, `docs/adr` after migration | Only after links, verifiers, and `docs/history.md` / `docs/decisions.md` are in place. |
+| Move scripts into subdirectories | Must be wrapper-first. CI, docs, tests, Desktop readinessScript, and package scripts reference root script paths. |
+| Move `tests/scripts` | Must update release-readiness workflow path filters and script contract tests. |
+| Root artifact cleanup | `css-audit-results.json` should move to historical evidence unless a current owner is discovered. |
+
+## Primary Risks
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Broken CI path references after script moves | High | First PR moves implementations and keeps root wrappers; second PR deletes wrappers after reference scan passes. |
+| Broken Desktop readiness path | High | Preserve `scripts/verify-edge-cli-real-readiness.ps1` wrapper until Desktop source/tests are intentionally updated. |
+| External docs repo dirty state absorbs unrelated changes | High | Use isolated docs worktree/branch and commit only AgentHub archive additions. |
+| Archive migration breaks historical links | Medium | Keep `docs/history.md` with stable external path and update active docs to point to it. |
+| ADR compression loses current decisions | Medium | `docs/decisions.md` keeps ID, status, current conclusion, owner, and validity; old bodies are archived externally. |
+| Verifier drift | Medium | Update `verify-doc-ssot`, `verify-ci-gates`, project-skill verifier, and release-readiness path checks in the same PRs as path changes. |
+
+## Evidence Boundaries
+
+This cleanup proves repository organization, documentation ownership, wrapper path compatibility, and CI/path contract health. It does not prove real login, real model/API spend, packaged Desktop sidecars/icons/installers, signing, release upload, or production deployment.
diff --git a/docs/plan/dependency-graph.md b/docs/plan/dependency-graph.md
@@ -0,0 +1,25 @@
+# Dependency Graph
+
+```mermaid
+flowchart TD
+  subgraph "Phase 1: Design"
+    T11["T1.1 SPEC + tracking"]
+    T12["T1.2 external archive receiver design"]
+  end
+  subgraph "Phase 2: Docs"
+    T21["T2.1 migrate archive trees"]
+    T22["T2.2 decisions.md ADR compression"]
+  end
+  subgraph "Phase 3: Scripts/Tests"
+    T31["T3.1 scripts wrapper-first"]
+    T32["T3.2 tests contract path"]
+  end
+  subgraph "Phase 4: Final Hygiene"
+    T41["T4.1 remove wrappers + root evidence"]
+  end
+  subgraph "Phase 5: Acceptance"
+    T51["T5.1 gates + archive SPEC"]
+  end
+
+  T11 --> T12 --> T21 --> T22 --> T31 --> T32 --> T41 --> T51
+```
diff --git a/docs/plan/milestones.md b/docs/plan/milestones.md
@@ -0,0 +1,9 @@
+# Milestones
+
+| Phase | Milestone | Exit Criteria |
+|---|---|---|
+| 1 | Design and Reference Graph Baseline | SPEC docs and GitHub tracking are complete; no destructive cleanup. |
+| 2 | Docs Archive and ADR Migration | External archive receives history; AgentHub keeps `docs/history.md` and `docs/decisions.md`. |
+| 3 | Scripts and Tests Wrapper Migration | New script/test layout works with wrappers and updated CI/readiness paths. |
+| 4 | Final Wrapper and Root Hygiene Cleanup | No old wrapper references remain; root evidence artifact handled. |
+| 5 | Acceptance and SPEC Archive | Required gates and CI pass; SPEC artifacts archived; milestones closed. |
diff --git a/docs/plan/repo-structure-doc-tooling-cleanup-spec.md b/docs/plan/repo-structure-doc-tooling-cleanup-spec.md
@@ -0,0 +1,79 @@
+# Repo Structure Doc Tooling Cleanup SPEC
+
+> Initial plan written before source/doc inventory. This file must be validated against current repository references before any destructive cleanup.
+
+## Objective
+
+Converge AgentHub back to a current product source repository: active docs stay short and canonical; historical longform, old ADR bodies, one-off evidence, and stale SPEC artifacts move to the cross-repository archive under `D:\Code\TokenDance\docs`; scripts and tests are reorganized only through a reference-safe migration.
+
+## Non-Negotiable Order
+
+1. Do not batch delete directories before the reference graph is known.
+2. Keep `dev/delicious233` as the baseline and work only from isolated worktrees.
+3. Treat `D:\Code\TokenDance\docs` as a separate Git repository; inspect and isolate its dirty state before moving archive material.
+4. Keep old script paths as wrappers for one migration PR cycle, then delete wrappers only after no references remain.
+5. Do not reintroduce a giant active rule document. Stable project rules live in `AGENTS.md`; current SPEC progress lives in `docs/progress/MASTER.md`; overall roadmap lives in `docs/roadmap.md`.
+
+## Target Shape
+
+Active AgentHub `docs/` should converge toward:
+
+```text
+docs/
+├── README.md
+├── roadmap.md
+├── architecture.md
+├── decisions.md
+├── history.md
+├── architecture/
+├── governance/
+└── reference/
+```
+
+Migration targets:
+
+- Move AgentHub `docs/archive/` and `docs/archives/` history to `D:\Code\TokenDance\docs\archive\agenthub\`.
+- Replace in-repo archive trees with a short `docs/history.md` index.
+- Compress `docs/adr/` into `docs/decisions.md`; move old ADR full text to the external archive.
+- Reshape `scripts/` into `scripts/verify/`, `scripts/dev/`, `scripts/release/`, `scripts/smoke/`, and `scripts/lib/` with compatibility wrappers first.
+- Reshape `tests/` into `tests/fixtures/`, `tests/contract/`, and `tests/integration/`.
+- Classify `css-audit-results.json` as either active owner artifact or historical evidence.
+
+## Proposed Phases
+
+| Phase | Goal | Destructive? |
+|---|---|---|
+| 1 | Inventory and migration design | No |
+| 2 | External archive boundary and link plan | No |
+| 3 | Docs archive/ADR migration with short indices | Yes, after links/verifiers are updated |
+| 4 | Scripts/tests staged restructure with wrappers | Yes, wrapper-first |
+| 5 | Wrapper removal and final hygiene | Yes, after reference graph is clean |
+| 6 | Acceptance, E2E/contract verification, archive SPEC | No |
+
+## Required Acceptance
+
+- `git diff --check`
+- `pwsh ./scripts/verify-doc-ssot.ps1`
+- `pwsh ./scripts/verify-project-skills.ps1`
+- `pwsh ./scripts/verify-real-e2e-contract.ps1`
+- For scripts/tests reshape: CI `validate`, Web/Desktop frontend gates, `go test ./tests/teamrun -count=1`, release-readiness path checks.
+- For archive migration: `rg "docs/archive|docs/archives|docs/adr|ADR-"` with only allowed current-index references remaining.
+- Final: AgentHub active markdown is limited to current owner entrypoints; no tracked one-off evidence remains at root; CI is green; `D:\Code\TokenDance\docs` receives the corresponding archive commit.
+
+## Information To Collect Before Finalizing
+
+- Current AgentHub root/docs/scripts/tests inventory and tracked root artifacts.
+- Reference graph for `docs/archive`, `docs/archives`, `docs/adr`, `ADR-`, script paths, and `tests/` paths.
+- Current verifier and CI references to script/test/doc paths.
+- Current state of `D:\Code\TokenDance\docs` and whether a clean receiver branch/worktree is required.
+- Current GitHub tracking mode, milestone/issue plan, and project-scope availability.
+
+## Initial Risk Register
+
+| Risk | Mitigation |
+|---|---|
+| Breaking CI by moving scripts | Move implementation first, keep wrappers, update references in small PRs. |
+| Breaking docs links by moving archive material | Generate reference graph and update links before deleting in-repo archive trees. |
+| Polluting external docs repo | Inspect `D:\Code\TokenDance\docs` status first; use an isolated branch/worktree or stop if it cannot be isolated. |
+| Losing audit trace | Move history to external archive and leave `docs/history.md` with durable pointers. |
+| Creating another docs giant | Keep active docs as indices and owner summaries only. |
diff --git a/docs/plan/task-breakdown.md b/docs/plan/task-breakdown.md
@@ -0,0 +1,34 @@
+# Task Breakdown
+
+> Spec: repo-structure-doc-tooling-cleanup
+> Tracking mode: `GITHUB_STANDARD`
+
+## Phases
+
+| Phase | Goal | Tasks |
+|---|---|---|
+| 1 | Design and reference graph baseline | T1.1, T1.2 |
+| 2 | Docs archive and ADR migration | T2.1, T2.2 |
+| 3 | Scripts/tests wrapper-first migration | T3.1, T3.2 |
+| 4 | Final wrapper/root hygiene cleanup | T4.1 |
+| 5 | Acceptance and SPEC archive | T5.1 |
+
+## Tasks
+
+| ID | Task | Priority | Size | Depends | S.U.P.E.R | Acceptance |
+|---|---|---|---|---|---|---|
+| T1.1 | Finalize SPEC docs, GitHub tracking, and reference graph | P0 | M | none | S/U/R | `docs/analysis`, `docs/plan`, and `docs/progress/MASTER.md` exist; GitHub milestones/issues exist; no destructive cleanup. |
+| T1.2 | Prepare external docs archive receiver design | P0 | M | T1.1 | S/E/R | External docs dirty state is handled by isolated worktree/branch plan; target archive layout is documented before migration. |
+| T2.1 | Migrate `docs/archive` and `docs/archives` externally with `docs/history.md` | P0 | L | T1.2 | S/U/R | External archive commit receives history; AgentHub has short history index; active docs and verifiers stop depending on in-repo archive trees. |
+| T2.2 | Compress `docs/adr` into `docs/decisions.md` | P0 | M | T2.1 | S/P/R | Current decisions summary exists; old ADR bodies are in external archive; active references point to `docs/decisions.md` or specific current owner docs. |
+| T3.1 | Reorganize `scripts/` wrapper-first | P0 | L | T2.2 | R/E | Implementations move to `scripts/verify`, `scripts/dev`, `scripts/release`, `scripts/smoke`, `scripts/lib`; old root script paths remain wrappers and tests pass. |
+| T3.2 | Reorganize `tests/scripts` to `tests/contract/scripts` | P1 | M | T3.1 | P/R | Release-readiness, verifier tests, and fixtures point to the new contract path; compatibility is documented for one PR cycle. |
+| T4.1 | Remove migration wrappers and root one-off evidence | P0 | M | T3.2 | S/R | Reference graph has no old wrapper dependencies; root `css-audit-results.json` is archived or owner-justified; wrappers removed. |
+| T5.1 | Run acceptance, close milestones, archive SPEC | P0 | L | T4.1 | P/E/R | Required local gates and CI pass; external archive commit is recorded; active SPEC artifacts are archived. |
+
+## Test Expectations
+
+- Every PR: `git diff --check`, `pwsh ./scripts/verify-doc-ssot.ps1`, `pwsh ./scripts/verify-project-skills.ps1`, `pwsh ./scripts/verify-real-e2e-contract.ps1`, OpenAPI YAML parse when active docs/verifiers change.
+- Scripts/tests PRs: CI `validate`, frontend Desktop/Web gates, `go test ./tests/teamrun -count=1`, release-readiness path checks, and script contract tests.
+- Archive PRs: `rg "docs/archive|docs/archives|docs/adr|ADR-"` must show only allowed index/history/code-comment references.
+- Final acceptance: AgentHub active markdown limited to owner entrypoints, no tracked one-off evidence at root, CI green, external TokenDance docs archive commit exists.
diff --git a/docs/progress/MASTER.md b/docs/progress/MASTER.md
@@ -0,0 +1,84 @@
+# Repo Structure Doc Tooling Cleanup - Progress Tracker
+
+> **Task**: Converge AgentHub repo docs, archives, scripts, tests, and root evidence artifacts into a clean current-source layout.
+> **Started**: 2026-06-28
+> **Last Updated**: 2026-06-28
+> **Mode**: GITHUB_STANDARD
+> **Repo**: TokenDanceLab/AgentHub
+> **Baseline**: `dev/delicious233`
+
+## References
+
+- [Initial SPEC](../plan/repo-structure-doc-tooling-cleanup-spec.md)
+- [Project Overview](../analysis/project-overview.md)
+- [Module Inventory](../analysis/module-inventory.md)
+- [Risk Assessment](../analysis/risk-assessment.md)
+- [Task Breakdown](../plan/task-breakdown.md)
+- [Dependency Graph](../plan/dependency-graph.md)
+- [Milestones](../plan/milestones.md)
+
+## GitHub Resources
+
+- Tracking mode: `GITHUB_STANDARD`; no project board because the current token lacks project scope.
+- All issues: `gh issue list -R TokenDanceLab/AgentHub --label "spec:repo-structure-doc-tooling-cleanup" --state all`
+
+## Milestones
+
+| Phase | Milestone | URL | Open | Closed |
+|---|---|---|---:|---:|
+| 1 | Design and Reference Graph Baseline | https://github.com/TokenDanceLab/AgentHub/milestone/12 | 2 | 0 |
+| 2 | Docs Archive and ADR Migration | https://github.com/TokenDanceLab/AgentHub/milestone/13 | 2 | 0 |
+| 3 | Scripts and Tests Wrapper Migration | https://github.com/TokenDanceLab/AgentHub/milestone/14 | 2 | 0 |
+| 4 | Final Wrapper and Root Hygiene Cleanup | https://github.com/TokenDanceLab/AgentHub/milestone/15 | 1 | 0 |
+| 5 | Acceptance and SPEC Archive | https://github.com/TokenDanceLab/AgentHub/milestone/16 | 1 | 0 |
+
+## Phase Checklist
+
+- [ ] Phase 1: Design and Reference Graph Baseline (0/2 tasks)
+- [ ] Phase 2: Docs Archive and ADR Migration (0/2 tasks)
+- [ ] Phase 3: Scripts and Tests Wrapper Migration (0/2 tasks)
+- [ ] Phase 4: Final Wrapper and Root Hygiene Cleanup (0/1 tasks)
+- [ ] Phase 5: Acceptance and SPEC Archive (0/1 tasks)
+
+## Issue Mapping
+
+| Task ID | Issue | Status |
+|---|---|---|
+| T1.1 | #360 | in progress |
+| T1.2 | #361 | pending |
+| T2.1 | #362 | pending |
+| T2.2 | #363 | pending |
+| T3.1 | #364 | pending |
+| T3.2 | #365 | pending |
+| T4.1 | #366 | pending |
+| T5.1 | #367 | pending |
+
+## Current Status
+
+**Active Phase**: Phase 1 - Design and Reference Graph Baseline
+
+**Active Task**: T1.1 - Finalize SPEC docs, GitHub tracking, and reference graph.
+
+**Current Focus**: Finish non-destructive SPEC setup, create GitHub milestones/issues, then merge this planning baseline before destructive archive/script/test moves.
+
+## Governance Status
+
+**Shared instruction surface**: `AGENTS.md`
+
+**Platform-specific instruction surfaces**: none
+
+**Memory surface**: native Codex memory; no repo fallback selected
+
+## Execution Telemetry
+
+- T1.1 started after previous repo governance SPEC was archived and all its milestones closed.
+- Initial reference graph found direct active references to `docs/archive`, `docs/archives`, `docs/adr`, root `scripts/*.ps1|sh`, `tests/scripts/**`, and Desktop readiness script paths.
+
+## Quick Status Commands
+
+```powershell
+gh issue list -R TokenDanceLab/AgentHub --label "spec:repo-structure-doc-tooling-cleanup" --state all
+gh api repos/TokenDanceLab/AgentHub/milestones --jq '.[] | select(.title | startswith("Repo Structure Cleanup")) | "\(.title): \(.open_issues) open, \(.closed_issues) closed"'
+git status --short --branch
+git worktree list
+```