250 lines
11 KiB
Markdown
250 lines
11 KiB
Markdown
# 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-approved 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.
|