Skip to content

Organize repository root and preserve historical experiment assets - #614

Merged
EmergentMonk merged 2 commits into
mainfrom
chore/preservation-first-root-cleanup
Oct 20, 2026
Merged

EmergentMonk merged 2 commits into
mainfrom
chore/preservation-first-root-cleanup

Conversation

@EmergentMonk

@EmergentMonk EmergentMonk commented Oct 20, 2026 •

Copy link
Copy Markdown
Member

Summary

  • Reduce root from 101 tracked files to 14 practical package/build/test/legal entry points, including new AGENTS.md.
  • Relocate 88 files: sonification media, opaque ZIP corpus, historical docs/tools/reports, active docs, maintenance scripts and environment profiles. All archives and requirements retain exact original bytes; 81 moves are byte-identical, seven live relocated files receive only path-reference repairs.
  • Record original paths, Git blobs, modes, SHA-256 and destinations in archive/root-cleanup-manifest.json. Preserve every existing historical fixture/receipt and leave immutable qec_data_prepared.csv at root.
  • Replace active CLAUDE guidance with current AGENTS instructions; archive original CLAUDE unchanged. Do not assume automatic Claude fallback. Keep .claude bootstrap.
  • Update audio, docs, installer verification, CI, requirements, release-history and evidence bundle paths. Preserve historical NVIDIA path verification/replay and exact-source acoustic verification.

Validation

  • Independent review completed; reported path/skipping/staging issues fixed.
  • Requirements/NVIDIA/interop/acoustic: 793 passed, 12 environment skips; quick bootstrap: 15 passed.
  • Initial path-sensitive checks: 257 passed; corrected legacy audio + layout tests: 92 passed with no skips.
  • npm test and npm run check passed.
  • Wheel built, installed into an isolated target, and installed qutrit demo passed.
  • All 88 destinations tracked; original archive/profile bytes and modes verified. Existing historical fixtures, artifacts, benchmark evidence and archived tests unchanged.
  • New-path NVIDIA bundle integrity plus old-path verification/replay tests pass. Actual local GPU dependencies are absent; no new GPU-success claim is made.
  • Full local pytest suite passed: 21,361 passed, 26 skipped, 4 warnings, 4 subtests passed in 729.92 seconds.
  • Previous head 98dcca0cdcb3a3c1cbed8fb92e737c42c1edfc5a: all 20 GitHub checks passed. Current P2 link-fix head 8be76f8e8ba5ffeb3d0592eb8cb34a2135246b3c: seven layout tests passed; independent review verified all 22 local overview links resolve and prose is unchanged. All 20 exact-head CI checks passed on 8be76f8e8ba5ffeb3d0592eb8cb34a2135246b3c, including full repository, container and acoustic regressions. GitHub currently reports this PR ready for review; this correction did not change its review state or merge it.
  • Fresh clean-checkout NVIDIA CPU/Stim bundle records the earlier cleanup head 98dcca0cdcb3a3c1cbed8fb92e737c42c1edfc5a; stdlib integrity verification passed there. It was not rerun for the subsequent documentation-and-link-test-only head 8be76f8e8ba5ffeb3d0592eb8cb34a2135246b3c. GPU commands correctly fail for absent GPU dependencies, so this is not new GPU validation.

Boundaries

No scientific algorithm, decoder, dependency pin or historical receipt changes. ZIPs remained opaque: no extraction or execution. Historical commands and newly archived source documents remain byte-preserved; the migration index supplies current paths. The user-requested P2 correction rebases nine navigation links in the pre-existing historical overview without altering its prose; a bounded migration-link regression guards them. No merge or release requested.

Summary by Sourcery

Organize the repository into focused package, documentation, dependency, script, and archive areas while preserving historical assets and their provenance.

New Features:

  • Add repository-wide AGENTS.md contributor guidance and an archive index for preserved historical material.

Bug Fixes:

  • Repair documentation, script, workflow, installer, release, audio, and evidence paths after reorganizing repository files.
  • Preserve compatibility with historical NVIDIA evidence bundles that use legacy requirement paths.

Enhancements:

  • Organize documentation, dependency profiles, maintenance tools, media, experiment assets, reports, and opaque archives into purpose-specific directories.
  • Add a root-cleanup manifest and automated checks covering moved-file provenance, byte integrity, executable modes, immutable baseline data, and repository layout.

Build:

  • Relocate requirement profiles into requirements/ while preserving their contents and dependency pins.

CI:

  • Update CI workflow triggers and installation commands to use the organized requirement and roadmap paths.

Documentation:

  • Update README and related documentation to reflect the new repository layout, current contributor guidance, relocated guides, and archive boundaries.

Tests:

  • Update path-sensitive tests and add repository layout preservation tests.

Chores:

  • Keep historical assets, fixtures, receipts, archives, and source metadata intact while reducing repository-root clutter.

@sourcery-ai

sourcery-ai Bot commented Oct 20, 2026

Copy link
Copy Markdown

Reviewer's Guide

This draft PR cleans the repository root by categorizing 88 relocated assets and updating all active consumers, CI, documentation, and tests to the new layout, while using a hash/blob manifest and preservation checks to retain historical bytes, provenance, fixtures, and evidence boundaries.

Sequence diagram for relocated dependency profiles in CI

sequenceDiagram
    participant CI as GitHub Actions CI
    participant Workflow as Workflow definition
    participant Profile as requirements/ profiles
    participant Tests as Targeted pytest checks

    CI->>Workflow: Trigger on repository path changes
    Workflow->>Profile: Install selected profile
    Profile-->>Workflow: Pinned environment dependencies
    Workflow->>Tests: Run interop and memory validation
    Tests-->>CI: Report pass or environment skip
Loading

Flow diagram for path migration and preservation validation

flowchart TD
    Old[Root-level files and assets]
    Classify[Categorize files by role]
    Move[Relocate 88 files]
    Repair[Repair references in live consumers]
    Record[Record paths blobs modes and SHA-256]
    Verify[Run layout byte and path-integrity checks]
    Preserve[Historical bytes fixtures and receipts preserved]

    Old --> Classify
    Classify --> Move
    Move --> Repair
    Move --> Record
    Repair --> Verify
    Record --> Verify
    Verify --> Preserve
Loading

File-Level Changes

Change Details Files
Reorganize the repository into a smaller operational root while preserving historical assets and provenance.
  • Move media, opaque ZIPs, historical documents/tools/reports, active documentation, scripts, and requirement profiles into categorized directories.
  • Add a manifest recording original paths, destinations, Git blobs, modes, sizes, hashes, and byte-identity status.
  • Keep the immutable root CSV baseline and historical fixtures/receipts unchanged; retain moved archive bytes without extraction or execution.
  • Add repository layout and preservation tests covering manifest integrity, root cleanliness, audio resolution, baseline hashing, release-history loading, and archive-safe outputs.
AGENTS.md
archive/README.md
archive/root-cleanup-manifest.json
archive/**
docs/**
examples/plotly_example.py
requirements/**
scripts/maintenance/**
tests/test_repository_layout.py
tests/**
Update live code, documentation, tests, and CI to resolve resources from their new paths.
  • Repair README, guide, roadmap, architecture, lab, installer, release-history, acoustic, audio, and maintenance-script references.
  • Update NVIDIA, memory, and interop workflows and commands to use organized requirement profiles.
  • Adjust runtime and regression tests for relocated audio, roadmap, scripts, guides, and release metadata.
  • Preserve compatibility with historical NVIDIA bundle member paths while validating new-path bundles.
.github/workflows/nvidia-coherent-memory.yml
.github/workflows/surface-memory-correlation.yml
.github/workflows/telecom-switching.yml
README.md
docs/**
examples/mirror_repos_example.sh
scripts/generate_acoustic_trial_evidence.py
scripts/run_bot.py
scripts/run_nvidia_pilot.py
scripts/run_sonic_analysis.py
scripts/test_quick.sh
scripts/update_release_notes.py
src/qec/orchestration/proof_carrying_agent_action_capsule.py
src/qec/verification/release_integrity.py
tests/**
tui/install.sh
Replace active contributor guidance with AGENTS.md while archiving the former CLAUDE guidance unchanged.
  • Make AGENTS.md the current repository-wide workflow, architecture, deterministic-contract, validation, and archive-preservation entry point.
  • Archive CLAUDE.md as historical context without assuming automatic fallback and retain the independent .claude bootstrap.
  • Document root layout, optional environment boundaries, GPU-claim limitations, and opaque-corpus handling.
AGENTS.md
archive/docs/CLAUDE.md
archive/README.md
src/qec/orchestration/proof_carrying_agent_action_capsule.py

Tips and commands

Interacting with Sourcery

  • Trigger a new review: Comment @sourcery-ai review on the pull request.
  • Continue discussions: Reply directly to Sourcery's review comments.
  • Generate a GitHub issue from a review comment: Ask Sourcery to create an
    issue from a review comment by replying to it. You can also reply to a
    review comment with @sourcery-ai issue to create an issue from it.
  • Generate a pull request title: Write @sourcery-ai anywhere in the pull
    request title to generate a title at any time. You can also comment
    @sourcery-ai title on the pull request to (re-)generate the title at any time.
  • Generate a pull request summary: Write @sourcery-ai summary anywhere in
    the pull request body to generate a PR summary at any time exactly where you
    want it. You can also comment @sourcery-ai summary on the pull request to
    (re-)generate the summary at any time.
  • Generate reviewer's guide: Comment @sourcery-ai guide on the pull
    request to (re-)generate the reviewer's guide at any time.
  • Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
    pull request to resolve all Sourcery comments. Useful if you've already
    addressed all the comments and don't want to see them anymore.
  • Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
    request to dismiss all existing Sourcery reviews. Especially useful if you
    want to start fresh with a new review - don't forget to comment
    @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

  • Enable or disable review features such as the Sourcery-generated pull request
    summary, the reviewer's guide, and others.
  • Change the review language.
  • Add, remove or edit custom review instructions.
  • Adjust other review settings.

Getting Help

@EmergentMonk
EmergentMonk marked this pull request as ready for review October 20, 2026 09:56
@sourcery-ai

sourcery-ai Bot commented Oct 20, 2026

Copy link
Copy Markdown

Sorry @EmergentMonk, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 20 hours and 55 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 20, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-20T10:18:17.527804Z 8be76f8 Manual request
🔒 Security Review ✅ Completed 2026-10-20T10:00:03.022847Z 98dcca0 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 98dcca0cdc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread README.md
- [Commands and capability metadata](docs/CAPABILITIES.md) · [IRC operator guide](docs/IRC_BOT_GUIDE.md)
- [Qutrit construction benchmark and limits](docs/QUTRIT_CONSTRUCTION_BENCHMARK.md)
- [Roadmap](ROADMAP.md) · [Detailed historical overview](docs/archive/README_BEFORE_V177_1_CLEANUP.md)
- [Roadmap](docs/roadmap/ROADMAP.md) · [Detailed historical overview](docs/archive/README_BEFORE_V177_1_CLEANUP.md)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Rebase links in the historical overview

After relocating the root documentation, the historical overview linked here still points to ../../ROADMAP.md, ../../INSTALL.md, ../../DOCUMENTATION.md, and ../../USAGE.md. Those files no longer exist at the repository root, so readers following its roadmap, setup, documentation, and TUI links receive 404s; rebase them to the new docs/roadmap, docs/guides, and docs/README.md locations.

AGENTS.md reference: AGENTS.md:L96-L99

Useful? React with 👍 / 👎.

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sourcery assessment

Approved.

@EmergentMonk

Copy link
Copy Markdown
Member Author

@codex Please Review this exact SHA 8be76f8 against the existing contract. Report only actionable correctness defects, with a minimal reproduction, expected versus actual behavior, and affected lines. State whether each reproduction was executed or statically inferred. Don’t repeat fixed findings without a new failing case. Keep architectural suggestions separate and non-blocking.

@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. Keep it up!

Reviewed commit: 8be76f8e8b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@EmergentMonk
EmergentMonk merged commit 4ad5533 into main Oct 20, 2026
20 checks passed
@EmergentMonk
EmergentMonk deleted the chore/preservation-first-root-cleanup branch October 20, 2026 10:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant