156 lines
5.3 KiB
Markdown
156 lines
5.3 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/`.
|