# AGENTS.md

## 1. Role

You are Codex working inside the `the-mindscape-of-bro-tsong` repository.

Your role is to implement the engineering structure for a file-first cognitive model library MVP.

You are not responsible for product strategy, marketing, sales, UI design, or broad feature invention.

Product planning decisions come from the project owner and CCRA / ChatGPT-side architecture work.

## 2. Project Goal

Build a minimal, file-first model library system that can represent cognitive models as:

- Human-readable Markdown model cards
- Machine-readable JSON model specs
- Source article records
- Source evidence excerpts
- Regression test cases
- Minimal model selector examples

The current phase is `model_library_mvp`.

The first sample models are:

- QPI
- Intellectual Archaeology

## 3. Core Principle

Do not overbuild.

The goal is not to create a full platform.

The goal is to create a stable model asset foundation.

Prefer:

- JSON over database
- Markdown over UI
- Explicit schema over hidden convention
- Simple scripts over complex services
- Traceability over automation
- Validation over feature expansion

## 4. Non-Goals

Do not implement:

- Full frontend application
- Backend service
- Database
- Vector database
- Full RAG system
- User accounts
- Authentication
- Payment
- Public platform
- Multi-user collaboration
- Complete knowledge graph
- Automatic extraction from all articles
- Full question-answering system

If a task seems to require one of these, stop and ask for product confirmation.

## 5. Repository Layout

Expected layout:

```text
docs/
schemas/
models/
cards/
sources/
tests/
selector/
scripts/
reports/
```

Each folder should contain a README explaining its purpose.

Do not create a nested `model_library_mvp/` directory unless the project owner explicitly changes the repository strategy.

## 6. Data Rules

Machine-readable files should use JSON.

Human-readable model cards and documentation should use Markdown.

Every model must eventually have:

- `model_id`
- `model_name`
- `model_type`
- `pipeline_position`
- `one_sentence_definition`
- `core_question`
- `core_mechanism`
- `source_articles`
- `source_evidence`
- `input_types`
- `output_types`
- `call_when`
- `do_not_call_when`
- `common_misuses`
- `failure_modes`
- `selection_priority`
- `confidence_level`
- `stability_profile`
- `regression_status`
- `productization_notes`

## 7. Source Traceability Rules

Every model should reference source article IDs.

Every model should reference source evidence excerpt IDs.

Do not invent source IDs without adding matching records in `sources/source_articles.json` or `sources/source_excerpts.json`.

If source content is not yet available, use placeholder records with clear notes such as:

```text
raw_excerpt: "待填入原文片段"
```

Do not pretend placeholder excerpts are verified evidence.

## 8. Regression Test Rules

Every core model should have at least five regression cases:

- Positive cases
- Boundary cases
- Misuse cases

Regression tests should check whether the model is being used appropriately.

They are not unit tests for code only. They are also product tests for cognitive model stability.

## 9. Selector Rules

The minimal selector should not call an LLM in v0.1.

It should use simple matching rules:

- Trigger keywords
- Input types
- Negative triggers
- Pipeline position
- Selection priority

The selector should output:

- Recommended model IDs
- Scores
- Reasons
- Routing notes

## 10. Coding Style

Keep scripts simple and readable.

Use Python only if scripts are needed.

Avoid unnecessary dependencies.

If using Python, prefer the standard library first.

If a dependency is necessary, document it in README.

## 11. Validation Expectations

Validation should eventually check:

- JSON schema compliance
- Unique model IDs
- Valid source article references
- Valid evidence excerpt references
- Valid regression test model references
- Required fields
- Enum values

Validation output should be written to:

```text
reports/validation_report.md
```

## 12. Documentation Expectations

When adding or changing structure, update relevant documentation.

At minimum, keep these files consistent:

- `README.md`
- `AGENTS.md`
- `docs/PROJECT_BRIEF.md`
- `docs/DATA_CONTRACT.md`
- `docs/WORKFLOW.md`
- `docs/DECISIONS.md`

## 13. Decision Logging

Any structural decision should be recorded in:

```text
docs/DECISIONS.md
```

Examples:

- Why JSON is used instead of YAML
- Why no database is used in v0.1
- Why QPI and Intellectual Archaeology are the first sample models
- Why selector is rule-based in v0.1
- Why `model_library_mvp` is a phase name rather than a nested repository root

## 14. Definition of Done

A task is done only when:

- Files are created in the expected location
- README or folder README is updated
- JSON files are valid or clearly marked as draft
- References between files are consistent
- Validation status is documented
- Non-goals have not been violated
- Any open questions are listed in the handoff document

## 15. Handoff Requirement

At the end of a work session, create or update:

```text
docs/HANDOFF_TEMPLATE.md
```

or a concrete handoff file such as:

```text
reports/Codex_工程产物摘要_v0.1.md
```

The handoff should include:

- What was completed
- What files changed
- What assumptions were made
- What does not yet work
- What needs product judgment
- Suggested next tasks