the-mindscape-of-bro-tsong/docs/DECISIONS.md

# Decision Log

## Decision 001: File-first architecture

Status: Accepted

Reason:

The MVP should remain simple, local, transparent, and easy to inspect.

A database is unnecessary before the model card schema and extraction protocol are stable.

## Decision 002: JSON for machine-readable model data

Status: Accepted

Reason:

JSON is easy to validate with JSON Schema and suitable for later integration into scripts, selectors, or applications.

## Decision 003: Markdown for human-readable model cards

Status: Accepted

Reason:

Markdown is easier for the project owner to read, edit, and review.

## Decision 004: QPI and Intellectual Archaeology as first sample models

Status: Accepted

Reason:

QPI represents a routing model.

Intellectual Archaeology represents a deep modeling model.

Together they test two different kinds of model structures.

## Decision 005: Rule-based selector in v0.1

Status: Accepted

Reason:

The first selector should validate data structure and model routing logic without relying on LLM calls.

## Decision 006: Use product root instead of a nested phase directory

Status: Accepted

Reason:

`the-mindscape-of-bro-tsong` is the product and system boundary.

`model_library_mvp` is the current phase and subsystem goal, not a separate root project.

The repository should not start as `the-mindscape-of-bro-tsong/model_library_mvp/` because that would add unnecessary root-vs-subproject ambiguity before the product needs a monorepo layout.

## Decision 007: Use supplier request channels for CCPE and skills-vault

Status: Accepted

Reason:

This repository is a product and application workspace. It should not silently absorb expert-agent specification work or reusable automation Skill source work.

Requests for agents, runtimes, model governance, invocation protocols, evaluation rules, and integration registrations should be recorded under `requirements/ccpe/`.

Requests for deterministic reusable automation tools and installable Skills should be recorded under `requirements/skills-vault/`.

If a supplier capability blocks model extraction, the dependent extraction step should pause unless the project owner explicitly says to solve the need locally.

## Decision 008: Third-party frameworks belong to product implementation, not CCPE or skills-vault

Status: Accepted

Reason:

Frameworks such as CrewAI and LangGraph may be useful later for implementing product behavior. The concrete application adapters, state, deployment, and product runtime belong in this repository.

CCPE may define the agent contract, runtime governance, authority, evaluation, and integration registration.

skills-vault may provide reusable deterministic helper Skills discovered during implementation.

## Decision 009: Use `intellectual_archaeology` as the machine model ID

Status: Accepted

Reason:

The source article names the model **“思想考古学”（Intellectual Archaeology）**.

The machine-readable ID should use the stable English snake_case form `intellectual_archaeology`, while the human-facing model name remains Chinese.

## Decision 010: Keep field names English and field content Chinese

Status: Accepted

Reason:

English field names make JSON easier to validate and integrate.

Chinese field values preserve source-language meaning and avoid translation drift during model extraction.

## Decision 011: GPT plans must be localized before implementation

Status: Accepted

Reason:

GPT planning documents may not know the current local repository state, existing constraints, missing contracts, or prior owner decisions.

Codex must first convert each GPT plan into local rules, schemas, indexes, workflow, tooling expectations, and validation gates before implementing content.

Content extraction or content repair must not begin from a GPT plan until the local foundation has been reviewed, unless the project owner explicitly overrides the gate.

## Decision 012: Maintain indexes by script-backed synchronization

Status: Accepted

Reason:

`models/model_index.json` is the machine discovery entrypoint, and `cards/card_index.md` is the human review entrypoint.

They should follow source assets instead of becoming separate hand-maintained content sources.

Every asset change must incrementally synchronize the indexes, and handoff or release points must run a full rebuild or consistency check.

The current rule is:

```text
incremental update on every model/card/source/test change
+
full rebuild or full reconciliation at release, handoff, schema migration, batch expansion, or validation drift
```

Model status remains an owner / ChatGPT / CCRA decision; validation and index rebuilds must not upgrade `draft` to a stronger state automatically.

## Decision 013: Archive CCRA review bundles by round

Status: Accepted

Reason:

The first compressed CCRA review bundle was generated as flat files under `ccra_review_bundle/`. That works for a single handoff, but it becomes ambiguous once later rounds produce new `00_OPEN_THIS_FIRST_CCRA_REVIEW_BRIEF.md`, command logs, diffs, and raw changed files.

`ccra_review_bundle/` is now the archive root. Each review round must live in a dated subdirectory:

```text
ccra_review_bundle/round-NN_YYYY-MM-DD_topic/
```

This keeps second-round and third-round materials comparable without overwriting prior evidence. Temporary review bundles remain session evidence and should not be copied into `knowledge_assets/`.

Round 03.1 added two bundle hygiene rules:

- `optional_raw_changed_files_<round-version>.zip` must preserve source-relative paths. Do not create flat archives that can collide on names such as `README.md`.
- `knowledge_assets/` is excluded from review bundles by default because the project owner manually syncs stable long-term knowledge assets into GPT knowledge storage. Include it only when the current review explicitly targets the knowledge asset itself.

Round 03.2 added one ChatGPT upload hygiene rule:

- Every file intended for GPT / CCRA upload inside a review bundle must include the round version in the filename, such as `_03.2` or `03.2`, because uploading same-named files from multiple rounds in one Web ChatGPT conversation can cause file-reading ambiguity. This applies especially to raw changed-file zip archives, e.g. `optional_raw_changed_files_03.2.zip`.
- The version suffix belongs to the bundle file names. Zip entries should still preserve source-relative repository paths so reviewers can inspect actual changed files without flattening path context.

## Decision 014: Treat explicit model refusal as model-level hard exclusion

Status: Accepted

Reason:

Round 03.1 fixed QPI default over-selection, but GPT review found that explicit Intellectual Archaeology refusal phrases such as `先不要思想考古` could still lose to positive IA signals and QPI-completed bonuses.

A user instruction that names a model and refuses it should not be represented as a normal score penalty. It must hard-exclude that model unless a later Owner-confirmed rule defines an explicit reversal phrase.

The current Round 03.2 implementation keeps this scoped:

- It rejects only the explicitly refused model.
- It does not create a global no-call.
- It does not add an LLM selector, RAG, database, service, frontend, backend, or third model.
- It preserves QPI explicit-analysis override, but QPI selection does not re-enable IA when IA is explicitly refused.
- Generic bare QPI gate words such as `如何` and `判断` are removed in favor of compound problem-definition phrases.

## Decision 015: Treat depth-limiting QPI requests as scoped analysis, not global no-call

Status: Accepted

Reason:

Round 03.2 review found that global hard no-call phrases such as `不要展开` and `不要深入分析` could incorrectly block QPI when the user also asked for a limited QPI action such as `只做 QPI`, `只做问题定性`, or `只判断主导稀缺`.

The correct interpretation is scoped depth control:

- `不要展开` or `不要深入分析` alone remains a no-call / low-depth signal.
- When paired with explicit QPI-limited intent, it means do not enter deeper models such as Intellectual Archaeology.
- QPI may still be selected for problem definition, problem-type judgment, or dominant-scarcity judgment.
- IA remains rejected through model-level hard exclusion.

This remains a selector precedence rule only. It does not add a new model, lifecycle upgrade, LLM selector, RAG, database, service, frontend, backend, user system, or Round 04 blind-test behavior.

## Decision 016: Close Round 03 after the Round 03.2a pass decision

Status: Accepted

Reason:

The Round 03.2a review accepted the depth-limiting QPI override patch and confirmed that Round 03 can close.

Closure statement:

- Round 03 is closed.
- QPI and Intellectual Archaeology remain `draft / B / pending`.
- QPI is accepted as a draft-callable routing asset at report level only; this does not change JSON model lifecycle status.
- Selector v0.2 passes no-call, calibration smoke, model-level exclusion, QPI-before-IA, and depth-limiting override gates.
- Round 04 blind input routing evaluation is the next candidate phase, but it is not started by this closure.

## Decision 017: Treat Round 04.1 as selector rule patch verification, not a second blind test

Status: Accepted

Reason:

Round 04 first-run blind routing evaluation found review-approved selector failures:

- R04-BI-002: translation task over-selected QPI because payload text contained `模型`.
- R04-BI-024: explicit `不要进入思想考古` did not hard-exclude Intellectual Archaeology.
- R04-BI-035 / R04-BI-036: depth-limiting phrases blocked lightweight QPI scarcity judgment.

Round 04.1 therefore patches selector rules and verifies the patch against frozen Round 04 inputs. It is not a second blind test because expected labels now exist for the four owner / GPT reviewed target cases.

The patch remains scoped:

- It adds translation / direct transformation no-call coverage.
- It separates task instruction from payload for no-call matching before payload complexity scoring.
- It expands IA model-level hard exclusion variants.
- It expands depth-limiting QPI override phrases for `主导稀缺` and `缺信息 / 缺路径 / 缺共识`.
- It does not add a new model, lifecycle upgrade, LLM selector, RAG, database, service, frontend, backend, user system, or QA product.

QPI and Intellectual Archaeology remain `draft / B / pending`.

Closeout:

- GPT review accepted Round 04.1 and did not request a 04.2 selector patch.
- `R04-BI-022` is documented as an accepted collateral behavior change: it moved from no-call to lightweight QPI after the depth-limiting override patch.
- This is not a new failure because the user rejects deeper IA-style expansion but asks for dominant-scarcity judgment.
- IA remains rejected for `R04-BI-022`.
- `R04-BI-022` is added to selector regression as a QPI gate / IA anti-recall trap.
- Closing Round 04.1 does not upgrade either model lifecycle status.

## Decision 018: Keep Local CCRA review runs inside this project

Status: Accepted

Reason:

The first Local CCRA version serves only `the-mindscape-of-bro-tsong`.

Creating a separate reviewer project would add synchronization cost before there is a cross-project review workload. The useful separation is runtime isolation, not directory isolation.

This repository therefore records Local CCRA review runs under:

```text
local_ccra_reviews/<public-round>/<local-pass>/
```

The public round label follows Owner / Web CCRA round versions such as `round-05`, `round-04.1`, or `round-03.2a`. The local pass number records repeated internal review passes, such as `01/` and `02/`.

Local CCRA output is formal local first review, but it does not replace Owner judgment or Web CCRA judgment at key product and lifecycle gates.

Formal Web CCRA bundles under `ccra_review_bundle/` exclude `04_LOCAL_CCRA_REVIEW_REPORT.md` by default. The local report is included only when the owner explicitly asks Web CCRA to review local findings.

## Decision 019: Route Local CCRA Agent Runtime and companion capability classification to CCPE first

Status: Accepted

Reason:

Local CCRA requires a real child review session, runtime session continuation, a reviewer role contract, review rubric, lifecycle guard policy, and file-first invocation protocol.

These are CCPE responsibilities, not product-local implementation details and not automatically `skills-vault` automation.

This repository will request a `ccra-local-reviewer` Agent Spec and Runtime protocol from `ccpe-system`. Companion capabilities such as routing diff audit, review bundle audit, lifecycle guard scan, round initialization context building, and regression gate running should be classified by CCPE first.

Only capabilities that are abstracted into reusable deterministic operations should be routed to `skills-vault`. Reusable Skill names should describe the generic operation, as with `bundle-zip`, rather than this project's review context.

## Decision 020: Treat Local CCRA v0.1.1 as usable for formal local first review with non-blocking Patch 2 hardening

Status: Accepted

Reason:

Round 04 Local CCRA `pilot-02` tested CCPE Patch 1 with a real child session and the same historical Round 04 materials.

The same child session completed both required turns:

- `review_turn`: produced `local_ccra_reviews/round-04/pilot-02/04_LOCAL_CCRA_REVIEW_REPORT.md`.
- `planning_turn`: produced `local_ccra_reviews/round-04/pilot-02/next-review-requirements.md`.

The three-way comparison against Web CCRA baseline and `pilot-01` showed that Patch 1 fixed the main Local CCRA gap: the reviewer now combines Web-style issue mechanism diagnosis with local full-file audit.

Decision:

- Local CCRA v0.1.1 can be used as this project's formal local first-review lane after Owner and Web CCRA define the next round's work.
- It does not replace Owner judgment, Web CCRA final review, or lifecycle authority.
- Patch 2 is still needed as runtime/helper hardening, but it is non-blocking if Patch 1 behavior remains intact.
- A third historical pilot is not required unless CCPE changes mechanism diagnosis, patch scope judgment, same-child-session continuation, mandatory knowledge-base use, or authority boundaries.
- Full Round-level automation is a separate workflow/orchestrator design problem and should not be mixed into the `ccra-local-reviewer` reviewer contract.

Patch 2 should focus on:

- CCRA-aware review bundle audit profile.
- Explicit gate-runner `dry_run / run / owner_waived / not_applicable` policy.
- Mandatory routing behavior diff when before/after patch evidence exists.
- Scoped lifecycle/status scan and triage.
- Short Owner-facing `returned-output.md` summary.

## Decision 021: Adopt Local CCRA v0.1.2 helper/runtime policy contract

Status: Accepted

Reason:

CCPE completed Patch 2 and advanced `ccra-local-reviewer` / `ccra-local-review` to v0.1.2.

Patch 2 did not change the core reviewer behavior accepted after `pilot-02`:

- issue mechanism diagnosis;
- patch scope judgment;
- same-child `review_turn` and `planning_turn`;
- mandatory `knowledge_assets/` knowledge base;
- Owner / Web CCRA / lifecycle authority boundaries.

It hardens the local runtime contract around helper reliability and return shape.

Decision:

- Future Local CCRA runs should follow CCPE v0.1.2.
- `review-metadata.json` or `agent-invocation-packet.md` should declare `bundle_audit_profile`, `gate_execution_mode`, `routing_diff_policy`, and `lifecycle_scan_scope`.
- `returned-output.md` should contain the compact Owner-facing summary expected by v0.1.2.
- A third historical pilot is not required for this patch because the core reviewer behavior did not change.
- The next Owner / Web CCRA-defined Local CCRA run should serve as live validation for v0.1.2.

The historical `pilot-01` and `pilot-02` records remain unchanged because they preserve the actual v0.1.1-era test evidence.

## Decision 022: Add a project-local Round Conductor protocol before Round 05

Status: Owner-agreed for Round 05 trial

Reason:

The project needs to reduce manual review-loop labor before scaling from two model assets to a much larger model library.

Local CCRA v0.1.2 is ready for formal local first review with conditions, but the Local CCRA reviewer contract intentionally does not define full Round-level automation or authorize repairs.

Decision:

- Add `docs/ROUND_AUTOMATION_PROTOCOL.md` as the project-local Round Conductor protocol.
- Use Round automation v0.1 for Local CCRA orchestration, helper execution, real child-session submission, and Chinese `findings-confirmation.md` extraction.
- Use Round automation v0.2 after Owner decision to let Codex repair only findings marked `accept_for_codex_fix`.
- Require `owner-decision.md` before any repair starts.
- Keep `ccra-local-reviewer` read-only; the main Codex session remains the implementer after Owner decision.
- Do not create a generic reusable Skill yet. Reusable automation should be extracted only after repeated project use proves a deterministic cross-project operation.
- Keep formal Web CCRA bundle rules unchanged: exclude `04_LOCAL_CCRA_REVIEW_REPORT.md` by default and include it only when Owner explicitly asks Web CCRA to review local findings.

The initial Round 05 use should validate whether the protocol reduces transfer work without weakening Owner / Web CCRA authority boundaries.