184 lines
7.4 KiB
Markdown
184 lines
7.4 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.
|