Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
166 changes: 166 additions & 0 deletions docs/superpowers/plans/2026-09-25-query-src-migration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,166 @@
# Query Source Package Migration 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:** Convert `query-` into an installable source-layout package while preserving all current root CLIs through compatibility wrappers and behavior-parity tests.

**Architecture:** Canonical implementation moves into `src/universal_law_query/`. Root scripts remain thin wrappers during migration. Runtime stays standard-library only and independent of every other repository; trial performs cross-repo install/federation tests.

**Tech Stack:** Python >=3.11, setuptools.build_meta, pyproject.toml, standard library, unittest.

**Spec:** `docs/superpowers/specs/2026-09-25-cross-repo-source-architecture-design.md`

**Prerequisite:** Source Contracts and Architecture Conformance plan reviewed cleanly.

## Global Constraints

- Scientific effect: NONE.
- Zero runtime dependencies.
- No runtime cross-repository imports.
- No PyPI publication.
- Existing root commands remain behavior-compatible.
- Catalog schema_version 1 remains accepted unchanged.
- Unknown keys/malformed identities fail closed.
- A catalog hit remains explicitly non-acceptance.
- Private sandbox artifacts remain rejected.
- No proof/review/scientific-status modifications.

## Review Focus

1. Root wrapper must work from an uninstalled source checkout.
2. Installed CLI must work in a clean environment without sibling repos.
3. Duplicate JSON keys/path traversal/symlink payloads must remain refused.
4. Wrapper and package CLI must match exit status and JSON/refusal behavior.
5. Source archive must exclude caches/private paths and be deterministic.

---

### Task 1: Package skeleton and CLI extraction

**Files:**
- Create: `query-/pyproject.toml`
- Create: `query-/src/universal_law_query/__init__.py`
- Create: `query-/src/universal_law_query/catalog.py`
- Create: `query-/src/universal_law_query/cli.py`
- Create: `query-/tests/test_catalog.py`
- Create: `query-/tests/test_cli.py`
- Modify: `query-/research_query.py`

**Interfaces:**
- `CatalogError`
- `load_catalog(path: Path) -> dict`
- `lookup(data: dict, key: str) -> dict`
- `verify(data: dict, workspace: Path) -> dict`
- `main(argv: list[str] | None = None) -> int`

- [ ] Add failing package tests by porting current behavior tests without changing expected semantics.
- [ ] Observe RED because package is absent.
- [ ] Implement package modules by moving current logic with minimal semantic change.
- [ ] Turn root `research_query.py` into a thin wrapper that prepends local `src` only when running from an uninstalled checkout and imports `universal_law_query.cli.main`.
- [ ] Run old tests plus new package tests; obtain GREEN.
- [ ] Add a parity test comparing old wrapper vs `python -m universal_law_query.cli` for list, lookup, verify and refusal paths.
- [ ] Commit.

### Task 2: Catalog-entry helper extraction

**Files:**
- Create: `query-/src/universal_law_query/catalog_entry.py`
- Create: `query-/tests/test_catalog_entry.py`
- Modify: `query-/catalog_entry_helper.py`

**Interfaces:**
- `HelperError`
- `valid_repo_path(text: str)`
- `read_public_bytes(path: Path) -> bytes`
- `resolve_commit(file_path: Path, explicit: str | None) -> str`
- `build_entry(...) -> dict`
- helper CLI `main(argv=None) -> int`

- [ ] Port current tests into package-targeted failing tests.
- [ ] Observe RED.
- [ ] Move implementation into package.
- [ ] Replace root helper with thin wrapper.
- [ ] Verify sandbox/symlink/traversal/mutable-commit refusals and wrapper parity.
- [ ] Commit.

### Task 3: Portable-stub verifier extraction

**Files:**
- Create: `query-/src/universal_law_query/stub_verify.py`
- Create: `query-/tests/test_stub_verify.py`
- Modify: `query-/verify_portable_stubs.py`

**Interfaces:**
- Preserve `load_candidates`, `validate_row`, `fetch_raw`, `check_math_tip_drift`, and `main(argv=None)`.

- [ ] Add failing package tests.
- [ ] Observe RED.
- [ ] Move code with no semantic broadening.
- [ ] Replace root script with thin wrapper.
- [ ] Run old/new tests and parity cases.
- [ ] Commit.

### Task 4: Clean-install and source-layout compatibility

**Files:**
- Modify: `query-/pyproject.toml`
- Create: `query-/tests/test_install_contract.py`
- Modify: `query-/README.md`
- Modify: `query-/AGENTS.md`

- [ ] Add failing test that installs the local package into a temporary virtual environment without dependencies and runs the console command.
- [ ] Observe RED before console entry point exists.
- [ ] Add `project.scripts.universal-law-query = "universal_law_query.cli:main"`.
- [ ] Verify clean install and CLI output.
- [ ] Document canonical source package vs compatibility wrappers.
- [ ] Update AGENTS with canonical paths and verification command.
- [ ] Commit.

### Task 5: Deterministic source manifest and archive builder

**Files:**
- Create: `query-/scripts/build_source_release.py`
- Create: `query-/tests/test_source_release.py`
- Create: `query-/SOURCE_MANIFEST.json` only if the spec's generated-view check concludes checked-in latest manifest is useful; otherwise keep manifest in release output only.

**Interfaces:**
- `build_source_archive(repo_root: Path, output: Path, source_date_epoch: int) -> dict`

- [ ] Add failing tests for sorted paths, fixed mtimes, no `.git`/cache/private path, embedded manifest, and identical archive SHA across two builds.
- [ ] Observe RED.
- [ ] Implement deterministic tar.gz or tar archive builder with normalized metadata.
- [ ] Run tests twice and assert byte-identical output.
- [ ] Do not create a GitHub Release yet; this is a dry-run artifact.
- [ ] Commit.

### Task 6: Trial federation install/parity test

**Files:**
- Modify: `trial/federation/test_federation.py`
- Create: `trial/federation/test_query_package.py` if separation keeps the file focused.

- [ ] Add failing test that installs query from sibling checkout and performs lookup/verification on synthetic catalog.
- [ ] Observe RED against pre-migration query main.
- [ ] Update fixture/import logic to prefer installed package but retain old-wrapper parity checks.
- [ ] Run full federation suite.
- [ ] Commit trial integration update.

### Task 7: Hosted CI, metrics and independent review

- [ ] Run query local legacy + package suites.
- [ ] Run clean-install test.
- [ ] Run trial federation suite.
- [ ] Inspect exact-head hosted CI logs.
- [ ] Record before/after: test runtime, files read for contribution, duplicate implementation count, wrapper count.
- [ ] Request fresh engineering review on query and trial exact heads.
- [ ] Fix Critical/Important findings with RED→GREEN.
- [ ] Mark query source package ready for first GitHub source-release plan only after review.

### Task 8: Release dry-run gate

- [ ] Produce deterministic archive twice from the same exact commit.
- [ ] Verify identical SHA256.
- [ ] Verify embedded source manifest.
- [ ] Verify no sandbox/private paths.
- [ ] Publish **no** external package registry artifact.
- [ ] Record exact commit/archive identity for later GitHub Release publication.
131 changes: 131 additions & 0 deletions docs/superpowers/plans/2026-09-25-source-contracts-conformance.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Source Contracts and Architecture Conformance 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:** Establish versioned cross-repository data contracts and a read-only conformance checker before any production source code is moved.

**Architecture:** `meta-framework` owns normative JSON contract schemas **and** the read-only architecture conformance checker/tests. `trial` owns only cross-repository rehearsal/install fixtures and must not be a runtime dependency of the checker. Production packages remain runtime-independent and this plan has no scientific promotion authority.

**Tech Stack:** Python >=3.11, standard library runtime, JSON/JSON Schema documents, unittest.

**Spec:** `docs/superpowers/specs/2026-09-25-cross-repo-source-architecture-design.md`

## Global Constraints

- Scientific effect: NONE.
- No theorem/proof/review body moves.
- No package runtime dependency across repositories.
- `sandbox` stays private and cannot appear as a public artifact source.
- Git source refs require immutable 40-hex commits and exact byte identity.
- Unknown major contract versions fail closed.
- Hashes establish identity only.
- No PyPI/npm publication.
- No changes to scientific dispositions or claim graph state.
- Existing research/review lanes remain untouched.

## Review Focus

1. Wrong repository with a valid-looking path must fail instead of binding locally.
2. A public manifest containing a sandbox path must fail.
3. Unknown schema major version must fail closed.
4. Derived navigation must not claim canonical scientific authority.
5. Workspace snapshots must reject mutable refs.

---

### Task 1: Source-reference and repository-role contracts

**Files:**
- Create: `meta-framework/schemas/source_ref.schema.json`
- Create: `meta-framework/schemas/repository_role.schema.json`
- Create: `meta-framework/examples/source_ref.git.json`
- Create: `meta-framework/examples/source_ref.drive.json`
- Create: `meta-framework/examples/repository_role.json`
- Modify: `meta-framework/README.md`
- Create: `meta-framework/tools/contract_validation.py`
- Create: `meta-framework/tests/test_source_contracts.py`

**Interfaces:**
- Produces `validate_source_ref(data, public=True)` and `validate_repository_role(data)`.

- [ ] Write failing tests for immutable commit, owner/repository, safe path, sandbox refusal, external frozen source, role fields, and major-version refusal.
- [ ] Run `python -B -S -m unittest -v tests.test_source_contracts` and observe RED.
- [ ] Add version 1.0 source-ref and role schemas/examples.
- [ ] Implement test/integration validator functions in trial.
- [ ] Re-run the tests and obtain GREEN.
- [ ] Document schema authority and non-scientific-status semantics in meta README.
- [ ] Commit meta and trial changes independently.

### Task 2: Source-manifest and workspace-snapshot contracts

**Files:**
- Create: `meta-framework/schemas/source_manifest.schema.json`
- Create: `meta-framework/schemas/workspace_snapshot.schema.json`
- Create: `meta-framework/examples/source_manifest.json`
- Create: `meta-framework/examples/workspace_snapshot.json`
- Modify: `meta-framework/tools/contract_validation.py`
- Modify: `meta-framework/tests/test_source_contracts.py`

**Interfaces:**
- Produces `validate_source_manifest(data)` and `validate_workspace_snapshot(data)`.

- [ ] Add failing tests for duplicate repos, mutable refs, private-path leakage, manifest file hashes/sizes, and `scientific_status_authority=false`.
- [ ] Observe RED.
- [ ] Add schemas/examples and validator functions.
- [ ] Obtain GREEN.
- [ ] Commit independently.

### Task 3: Read-only architecture conformance checker

**Files:**
- Create: `meta-framework/tools/architecture_conformance.py`
- Create: `meta-framework/tests/test_architecture_conformance.py`

**Interfaces:**
- Consumes a sibling-repository workspace root.
- Produces `check_workspace(root: Path) -> dict` and CLI exit 0/2.

- [ ] Write failing synthetic-workspace tests for valid roles, wrong owner, sandbox leak, mutable snapshot, and derived status-authority violation.
- [ ] Observe RED.
- [ ] Implement offline read-only checker.
- [ ] Add clean CLI refusal behavior without tracebacks.
- [ ] Obtain GREEN.
- [ ] Run against the current multi-repo fixture where available; record real violations without weakening rules.
- [ ] Commit.

### Task 4: Hosted CI, mutation controls, and trial rehearsal

**Files:**
- Create or modify: `meta-framework/.github/workflows/contracts.yml`
- Modify: `meta-framework/tests/test_source_contracts.py`
- Modify: `meta-framework/tests/test_architecture_conformance.py`
- Modify: `trial/federation/test_federation.py` only to invoke the meta checker as a subprocess/CLI against the sibling fixture; do not import meta Python modules.

- [ ] Add semantic mutations for mutable commit, wrong owner, sandbox source, major-version bump, duplicate repository.
- [ ] Run complete local federation tests.
- [ ] Ensure Actions are SHA-pinned, contents-read only, no `pull_request_target`.
- [ ] Push exact heads and inspect hosted logs.
- [ ] Commit CI update.

### Task 5: Independent engineering review and Phase-A gate

- [ ] Request a fresh reviewer on exact meta/trial heads.
- [ ] Resolve any Critical/Important findings with RED→GREEN fixes.
- [ ] Record CI/runtime/complexity metrics.
- [ ] Proceed to query migration only if hosted tests and review are clean.


### Task 6: Authority-map compatibility assertions

**Files:**
- Modify: `meta-framework/tests/test_architecture_conformance.py`
- Modify: `meta-framework/tools/architecture_conformance.py`

**Interfaces:**
- Consumes the active-base authority semantics without importing main runtime code.

- [ ] Add fixtures asserting the architecture layer never owns `classification`, `controlling`, `terminality` or `reverse_impact_revalidation`.
- [ ] Add a fixture asserting public registry artifact rows refuse `status`, `grade`, `classification`, and `disposition` fields.
- [ ] Add a fixture distinguishing landing `REVIEWED_SCOPED` from gate `PROVED_REVIEWED`.
- [ ] Run tests RED→GREEN.
- [ ] Commit and include these checks in the fresh engineering review.
Loading
Loading