refactor: track architecture migration, integration PRs, and repository layout #372

Status: Proposed. This is a tracking suggestion under #362. It is not an accepted implementation plan, and it does not authorize moves, deletions, or new packages.

Naming note (2026-11-09, Asia/Shanghai): architecture core formerly called Workbench is now Harness (abbrev. H; trio K/H/B). Suggested package path uses src/inferrsi/harness/. The same path already hosts a mixed implementation tree on main; this tracker does not treat that existing tree as the accepted Harness boundary, and it does not authorize moves. Status remains Proposed.

Layout principles (direction recorded 2026-11-09 Asia/Shanghai; not yet implemented)

These are maintainer-direction notes for this tracker. They do not accept the 3+1 PR split, do not authorize file moves, and do not create packages.

• Keep src/ as the distribution root. Repo-root tests/ and tools/ stay at the root.
• Target sibling packages under src/inferrsi/: knowledge/, harness/ (formerly Workbench), benchmark/, and apps/. The Apps path and package name remain Proposed in #371; do not pre-create an empty apps/ tree for symmetry.
• Do not create empty packages just to make the tree look symmetric. Packages appear when the owning slice is authorized to move code.
• Flat src/inferrsi/data/ is not the long-term home. Knowledge corpus materials are destined for the Knowledge package when that slice moves them. Fine-grained Knowledge taxonomy belongs in a future Knowledge architecture sub-issue (not opened here). Non-corpus artifacts that today sit near data (for example pack runtime descriptions, dashboard view assets) must be attributed by each owning slice; no moves in this tracker.
• Existing on-disk src/inferrsi/harness/ remains a mixed implementation tree and is not automatically the accepted Harness boundary.

Parent: #362. Accepted architecture direction: A–D decision (S1 contract without moving directories, then S2/S3/S4 in parallel, S5 assembly last). Apps design remains the open proposal in #371. Its recorded design assignee is zengchuang-hw. This issue does not change that assignee and does not name any new owner.

Code baseline: main 68dbd5e811a043f113e17e90b3bbe79622cbf7a5 (2026-11-09, docs: add an English Codex plugin installation guide (#330)).

Goal

Track the architecture/integration work only: freeze the public contract and import gate, prove one fake closed loop, then swap in the first real port from each core. Record where repository trees and docs/ should live so later slices do not invent a second layout.

Module behavior stays in the module slices. This issue closes when the integration PRs below are either merged with the acceptance checks, or a maintainer decision cancels a PR and links the follow-up tracker. It does not close when every Knowledge, Harness, Benchmark, or Apps feature is done, and closing does not mean performance targets passed.

In scope

• The integration PR sequence recommended below (3 + 1).
• A target directory rule for source, tests, docs, examples, knowledge corpus, and experiment results.
• A short classification of existing docs and root notes: keep, candidate move, or candidate archive. No path is approved for deletion here.

Out of scope

• Implementing S2, S3, S4 production features, or the task: Apps 应用层详细设计与迁移计划（CLI / Python / Plugin） #371 Apps package.
• Creating inferrsi.apps or any other package name before task: Apps 应用层详细设计与迁移计划（CLI / Python / Plugin） #371 is accepted.
• A shared business contracts package. The existing src/inferrsi/contracts.py is only a RunSpec compatibility re-export. It must not grow into a fourth core.
• Knowledge, Harness, and Benchmark importing one another.
• Moving or deleting campaign evidence, review notes, or skill-library corpus in the first integration PR.
• Adding merge gates onto open PRs such as feat: support shared YAML task input #367 or feat: share RSI optimization management across project and benchmark tasks #338.

Suggested integration PRs

These names are a suggestion, mapped to the accepted S1–S5 order. They are not a new approved plan. The 3+1 cut itself remains pending maintainer confirmation; recording layout principles here does not accept that cut.

S2, S3, and S4 proceed in parallel after PR1, by the people filling those modules. This tracking item does not own their full production delivery. #371 design review can proceed in parallel and does not wait for PR2. Production Apps assembly (S5) waits until #371 is accepted and PR3 has shown the three refs connect; S5 production features are likewise not fully owned here. PR4 can start after PR1 documents the rules; it should not start by relocating files that #367 or tests still import. Immediate moves or deletions are not authorized by opening this issue.

Directory responsibilities

Current tree (fact on this SHA)

src/inferrsi/          # runtime: cli, arguments, harness, infra, model,
                       # knowledge_operations, knowledge_store, catalog, data/
src/inferrsi/data/     # current flat corpus / skill library on main; not the long-term layout (see Layout principles)
src/inferrsi/contracts.py
tests/                 # scaffold and operator tests
docs/                  # operator guides, campaign writeups, reviews, plans,
                       # a few JSON fixtures, engine-repo template
examples/              # three Qwen image scripts
evidence/              # campaign result trees and evidence/README.md
plugins/               # Codex, WorkSwarm, DSH
tools/                 # repo ops and skill-eval helpers, outside the wheel

There is no top-level benchmarks/ tree. Task packages from draft #338 are not on main. There is no inferrsi.apps, inferrsi.knowledge, or inferrsi.benchmark package as architectural cores. src/inferrsi/harness/ already exists on main as a mixed implementation tree; that is not yet confirmation that the target Harness core (formerly Workbench) has been carved out.

Target rule (suggestion, pending confirmation)

Do not create empty directories in PR1. When a slice is authorized to move code, use this rule:

src/inferrsi/                    # one distribution
src/inferrsi/knowledge/          # suggested K package path; pending interface /
                                 # slice confirmation; migrate only with the
                                 # Knowledge slice that owns the move
src/inferrsi/harness/            # suggested H package path (formerly workbench/);
                                 # pending interface / slice confirmation;
                                 # migrate only with the Harness slice that owns
                                 # the move. Distinct from the existing mixed
                                 # implementation tree already at this path on
                                 # main: that tree is not yet the accepted
                                 # Harness module boundary
src/inferrsi/benchmark/          # suggested B package path; pending interface /
                                 # slice confirmation; migrate only with the
                                 # Benchmark slice that owns the move
src/inferrsi/apps/                # sibling target with K/H/B; path/name still
                                 # Proposed in #371 — do not pre-create empty
                                 # apps/ for symmetry
src/inferrsi/data/               # transitional on main only; corpus moves with
                                 # Knowledge slice; not a permanent flat store
tests/                           # stays at repo root; tests and owned fixtures
docs/                            # keep existing flat operator guides and
                                 # docs/architecture.md in place; do not create
                                 # empty docs/architecture/, docs/migration/,
                                 # or per-module handbook directories in PR1
docs/template/                   # copy-out engine repo template; not InferRSI runtime
examples/                        # runnable caller scripts only
evidence/                        # frozen campaign inputs and results; not a scratch archive
plugins/                         # host manifests and launchers
tools/                           # stays at repo root; maintainer/CI helpers, not product import

K, H, and B each own their types. The three core subdirectories above are suggested destinations only; they are created and filled when the owning slice is authorized, not as empty shells in PR1. Apps, once #371 names the package, is the only assembler. No new shared business contracts package.

What docs/ should hold

Keep operator and maintainer prose here:

• Entry and operation: README companions such as docs/quickstart.md, docs/operations.md, plugin guides (docs/codex-plugin.md, docs/workswarm-plugin.md, docs/dsh-plugin.md).
• Architecture and contribution: keep the existing flat docs/architecture.md, plus docs/contributing.md, docs/agent-collaboration.md, docs/privacy-security.md.
• Current module operation notes that describe commands which exist today (docs/knowledge-operations.md, docs/knowledge-store.md, and the skill-eval operator notes). After S2–S5, those notes move only with the slice that changes the command.
• docs/template/: the engine delivery template. It is supposed to contain its own benchmarks/ and evidence/ examples. That does not mean InferRSI itself grows those trees.

Do not treat docs as the store for:

• Skill and knowledge corpus (src/inferrsi/data/).
• Campaign result trees (evidence/).
• Test inputs that CI already executes (see candidates below).
• Generated coverage or wheel contents.

Do not add a new empty docs/architecture/, docs/migration/, or per-module handbook tree in PR1. PR1 may add one short layout section to the existing docs/architecture.md or to this issue. New module docs are written by the slice that creates the behavior.

Classification of existing files

“Candidate” means the in-tree reference check below is incomplete (issues and external blobs can still link the path). None of these rows is a safe deletion.

Open review notes (not accepted by this edit)

Amy's review raised five points that still need maintainer answers before PR1 checkboxes can be honest: (1) tentative ownership for flat top-level modules under src/inferrsi/, (2) a non-vacuous import-gate definition while the tree is still flat (now K/H/B, formerly K/W/B), (3) exact PR4 fixture subpaths under existing tests/fixtures/, (4) keep/owner one-liners for .agents/, AGENTS.md, CHANGELOG.md, MANIFEST.in, (5) freeze the old CLI 0/1/2 command list in PR1 for PR3 compatibility. This issue edit does not decide those points.

Acceptance and close

All boxes stay unchecked until the named evidence exists. Closing this issue does not mean S2–S5 production features or performance targets are finished.

• Maintainers confirm or revise the suggested 3+1 PR split and the directory rule (including sibling knowledge/ / harness/ / benchmark/ / apps/ targets, with apps/ still Proposed in task: Apps 应用层详细设计与迁移计划（CLI / Python / Plugin） #371; layout principles above are direction only).
• PR1: the public contract, direct-import gate (no K/H/B edge; no new shared business contracts package), and directory rule text are merged, or a maintainer comment explicitly adjusts that scope and links the follow-up tracker.
• PR2: test-double success, failure, and recovery path tests for the prepare → archive → bind → execute → offline assess loop are merged, or a maintainer comment explicitly cancels PR2 and links the follow-up tracker.
• PR3: the first real Knowledge read, one Harness CPU/offline record, and one Benchmark offline assessment pass a minimal CPU/offline integration, and old CLI exit codes / behavior remain compatible, or a maintainer comment explicitly cancels PR3 and links the follow-up tracker.
• PR4: every moved file is listed item-by-item with updated in-repo references, and link / fixture / workflow checks pass; no deletion of evidence/, docs/reviews/, or skill-library content, or a maintainer comment explicitly cancels PR4 and links the follow-up tracker.
• task: Apps 应用层详细设计与迁移计划（CLI / Python / Plugin） #371 remains the place that names the Apps package and keeps design assignee zengchuang-hw. This issue does not rename Apps or change that assignee.

Do not close this issue on the weaker rule “PR opened and roughly in scope.” A cancelled PR needs the maintainer decision comment and the follow-up issue link before the related checkbox can be satisfied.

Dependencies

• discussion: Knowledge / Harness / Benchmark 三模块目标架构——现状、原语、交接时序与遗留问题 #362 A–D is already accepted. Further contract edits still follow that comment’s revision clause. Recovery semantics and the five knowledge-status dimensions were accepted with explicit caveats.
• task: Apps 应用层详细设计与迁移计划（CLI / Python / Plugin） #371 must accept the Apps path before any integration PR creates that package. Amy’s review on task: Apps 应用层详细设计与迁移计划（CLI / Python / Plugin） #371 (import side effects, bridge split, archive versus RunStore, unset new exit-code numbers) is still open.
• feat: support shared YAML task input #367 currently edits cli.py, arguments.py, runner.py, and pyproject.toml. PR1 should not edit those files.
• Draft feat: share RSI optimization management across project and benchmark tasks #338 is the engineering-benchmark line. It is not main, and it is not a reason to add a top-level benchmarks/ tree in PR1.
• Open campaign and knowledge PRs are out of scope here.

Non-claims

Layout principles above are direction notes only; they are not an implemented tree and not an accepted 3+1 plan. No source move has been done. No file listed above is certified unused. The 3+1 PR split and the suggested knowledge/ / harness/ / benchmark/ paths are recommendations pending maintainer confirmation, not already-accepted layout decisions. New exit-code numbers, Collection versus search_knowledge, and the Apps directory name are still unset.