the-mindscape-of-bro-tsong/docs/superpowers/plans/2026-06-16-model-extraction-contract-and-workflow.md

# Model Extraction Contract and Workflow Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Turn the GPT planning document into local executable rules, schemas, indexes, workflow gates, and validation tools before revising QPI or Intellectual Archaeology content.

**Architecture:** Treat GPT planning documents as upstream planning inputs, not direct implementation instructions. The repository must first convert them into local contracts, indexes, validators, and workflow gates; only after owner review should content extraction or model asset repair continue.

**Tech Stack:** Markdown documentation, JSON Schema draft 2020-12, Python standard library validation scripts, file-first JSON indexes.

---

## Scope

This plan covers the process and tooling foundation for future model extraction.

It does not repair the current QPI or Intellectual Archaeology model contents yet. Those repairs happen only after the rules, schemas, indexes, workflow, and validators are written and reviewed.

## Source Planning Document

Read this first:

```text
C:\Users\wangq\Documents\Codex\knowledge-vault\work\internal\强哥的思想宇宙\GPT成果\2026-06-16-核心模型抽取样板 v0.1.md
```

Use it as an upstream plan. Do not treat it as already-local repository law until the relevant parts are converted into this repository.

## Required Local Outputs

Create or update these files:

- Create: `docs/MODEL_EXTRACTION_RULES.md`
- Create: `docs/MODEL_CARD_CONTRACT.md`
- Create: `docs/MODEL_EXTRACTION_WORKFLOW.md`
- Create: `docs/GPT_PLAN_LOCALIZATION_PROTOCOL.md`
- Create: `schemas/model_card.schema.json`
- Modify: `schemas/source_article.schema.json`
- Modify: `schemas/source_excerpt.schema.json`
- Modify: `schemas/regression_case.schema.json`
- Create: `models/model_index.json`
- Create: `cards/card_index.md`
- Create: `schemas/model_index.schema.json`
- Create: `schemas/card_index.schema.json`
- Modify: `scripts/validate_model_library.py`
- Create: `scripts/check_card_contract.py`
- Create: `scripts/run_selector_demo.py`
- Create: `reports/GPT规划落地差异检查_v0.1.md`
- Modify: `docs/DECISIONS.md`
- Modify: `README.md`
- Modify: `docs/WORKFLOW.md`
- Modify: relevant folder README files

## Index Decision

Two indexes are required because model JSON and Markdown cards serve different consumers.

`models/model_index.json` is the machine-readable model index. It supports validation, selector routing, model lookup, model status tracking, and future application integration.

`cards/card_index.md` is the human-readable card index. It supports owner review, editorial navigation, extraction status review, and handoff.

Index maintenance policy for v0.1:

- During early MVP with two models, update indexes manually and validate references.
- When model count grows beyond roughly 8-10 core models, add an optional full rebuild script.
- Do not require full rebuild on every small edit in v0.1.
- Full extraction from files is acceptable on demand because the repository is file-first and small, but it should become a tool only when manual maintenance becomes costly or error-prone.

## Workflow Gates

This repository must use these gates for every future GPT-provided planning document:

1. GPT plan intake.
2. Local plan creation.
3. Owner review of local plan.
4. Rules/schema/index/workflow implementation.
5. Validation of rules/schema/index/workflow.
6. Owner review of the foundation.
7. Content extraction or content repair.
8. Validation and audit report.
9. Owner content review.

No model content extraction should happen before gate 6 unless the owner explicitly overrides the gate.

---

### Task 1: Localize GPT Plan Into Repository Rules

**Files:**
- Create: `docs/GPT_PLAN_LOCALIZATION_PROTOCOL.md`
- Create: `docs/MODEL_EXTRACTION_RULES.md`
- Create: `reports/GPT规划落地差异检查_v0.1.md`
- Modify: `docs/DECISIONS.md`

- [ ] **Step 1: Write GPT plan localization protocol**

Create `docs/GPT_PLAN_LOCALIZATION_PROTOCOL.md` with these sections:

```markdown
# GPT Plan Localization Protocol

## Purpose

GPT planning documents are upstream planning inputs. They are not directly executable repository rules.

Before Codex implements content from a GPT plan, Codex must convert the plan into local rules, schemas, workflow steps, tools, and validation criteria.

## Required Intake Steps

1. Read the GPT planning document completely enough to extract fields, tasks, non-goals, workflow requirements, tooling expectations, and acceptance criteria.
2. Compare the GPT plan against local repository rules in `AGENTS.md`, `README.md`, `docs/DATA_CONTRACT.md`, `docs/WORKFLOW.md`, and `PROJECTS.md`.
3. Identify conflicts, missing local contracts, missing schemas, missing validators, missing indexes, and missing workflow gates.
4. Write a local execution plan.
5. Ask the project owner to review the local execution plan.
6. Only after owner approval, implement local rules/schema/workflow/tooling.
7. Ask the project owner to review the foundation before content extraction begins.

## Prohibited Shortcut

Do not directly create or repair model content from a GPT planning document before local rules, schemas, workflow, and validation expectations are confirmed.

## Required Report

Each localization pass must produce a report under `reports/` that lists:

- GPT plan source path
- Local files created or modified
- Fields adopted
- Fields rejected or deferred
- Workflow gates added
- Tooling needs identified
- Open owner questions
```

- [ ] **Step 2: Write model extraction rules**

Create `docs/MODEL_EXTRACTION_RULES.md` with these sections:

```markdown
# Model Extraction Rules

## Language Rule

JSON field names use English.

JSON field values and Markdown card contents should remain Chinese when the source material is Chinese. English terms may be preserved as aliases, IDs, or source terms.

## Source Traceability Rule

Every model must reference source article IDs and source evidence excerpt IDs.

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

Do not invent evidence excerpt IDs without matching records in `sources/source_excerpts.json`.

Placeholder excerpts must be marked clearly and must not be treated as verified evidence.

## Model Extraction Is Not Article Summary

Article summary answers what the article says.

Model extraction answers:

- What reusable cognitive mechanism exists?
- What input does it handle?
- What output does it produce?
- When should it be called?
- When should it not be called?
- How can misuse be detected?
- How can stability be tested?

## Required Model Asset Chain

For each core model:

1. Source article record
2. Source evidence excerpts
3. Human-readable Markdown card
4. Machine-readable JSON model card
5. Regression cases
6. Selector examples or routing rules
7. Validation report

## Required Model JSON Fields

Model JSON must include the required fields from `schemas/model_card.schema.json`.

Recommended fields from the GPT plan should be included for v0.1 unless a field is explicitly deferred in the localization report.

## Stability Assessment

Each model must include stability assessment across:

- 概念清晰度
- 机制稳定性
- 边界清晰度
- 来源证据质量
- 回归测试表现

Each model must record:

- `stability_level`
- `reason`
- `next_stabilization_action`

## Index Rule

Machine-readable model assets are indexed in `models/model_index.json`.

Human-readable cards are indexed in `cards/card_index.md`.

Both indexes must be updated whenever a model or card is added, renamed, deprecated, or materially reclassified.
```

- [ ] **Step 3: Write localization diff report**

Create `reports/GPT规划落地差异检查_v0.1.md` with these sections and fill it from the GPT planning document:

```markdown
# GPT 规划落地差异检查 v0.1

## Source Plan

`C:\Users\wangq\Documents\Codex\knowledge-vault\work\internal\强哥的思想宇宙\GPT成果\2026-06-16-核心模型抽取样板 v0.1.md`

## Adopted Into Local Rules

## Adopted Into Local Schema

## Adopted Into Local Workflow

## Adopted Into Tooling Plan

## Differences From Current Repository

## Deferred Items

## Owner Review Questions
```

- [ ] **Step 4: Record decision**

Append to `docs/DECISIONS.md`:

```markdown
## 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, workflow, tooling expectations, and validation gates before implementing content.
```

---

### Task 2: Define Model Card Contract And Schema

**Files:**
- Create: `docs/MODEL_CARD_CONTRACT.md`
- Create: `schemas/model_card.schema.json`
- Modify: `schemas/README.md`

- [ ] **Step 1: Write Markdown card contract**

Create `docs/MODEL_CARD_CONTRACT.md` with exactly these required card sections:

```markdown
# Model Card Contract

Each human-readable model card in `cards/` must include these sections in Chinese content:

## 模型名称
## 模型 ID
## 一句话定义
## 模型类型
## 所在流程位置
## 来源文章
## 来源证据片段
## 核心问题
## 核心机制
## 输入类型
## 输出类型
## 适用场景
## 不适用场景
## 调用关键词
## 负向触发条件
## 相关模型
## 冲突模型
## 学科底座关联
## 常见误用
## 失败信号
## 可信度等级
## 稳固性状态
## 稳定性评估
## 回归测试状态
## 示例输入
## 示例输出
## 输出契约
## 深度控制
## 产品化建议
## 版本信息

Cards may include additional explanatory sections after the required sections.

Required sections may contain `无` only when the model genuinely has no value for that field, and the reason must be clear.
```

- [ ] **Step 2: Create full model card JSON schema**

Create `schemas/model_card.schema.json` based on the GPT plan's schema, with these additions:

- Add Chinese `description` to every property.
- Include recommended fields: `trigger_keywords`, `negative_triggers`, `related_models`, `conflicting_models`, `disciplinary_anchors`, `example_inputs`, `example_outputs`, `output_contract`, `depth_control`, `stabilization_path`, `version`, `last_updated`.
- Use enum values from the GPT plan:
  - `model_type`: `routing_model`, `deep_modeling_model`, `lens_model`, `diagnostic_model`, `evaluation_model`, `generation_model`, `conflict_resolution_model`, `stabilization_model`
  - `pipeline_position`: `pre_analysis`, `analysis`, `deep_analysis`, `synthesis`, `red_team`, `evaluation`, `post_processing`
  - `confidence_level`: `high`, `medium`, `low`
  - `regression_status`: `not_started`, `pending`, `in_progress`, `passed`, `failed`, `needs_rebuild`
- Set `selection_priority` minimum 1 and maximum 10.
- Require `stability_profile.stability_level`, `stability_profile.needs_stabilization`, `stability_profile.main_risks`, `stability_profile.reason`, and `stability_profile.next_stabilization_action`.

- [ ] **Step 3: Update schema README**

Update `schemas/README.md` so it lists `model_card.schema.json` as the authoritative schema for machine-readable model cards.

---

### Task 3: Define Source, Regression, And Index Schemas

**Files:**
- Modify: `schemas/source_article.schema.json`
- Modify: `schemas/source_excerpt.schema.json`
- Modify: `schemas/regression_case.schema.json`
- Create: `schemas/model_index.schema.json`
- Create: `schemas/card_index.schema.json`

- [ ] **Step 1: Add descriptions to existing schemas**

For `source_article.schema.json`, `source_excerpt.schema.json`, and `regression_case.schema.json`, add Chinese `description` fields for every property.

- [ ] **Step 2: Strengthen regression schema**

Update `schemas/regression_case.schema.json` so `case_type` uses enum:

```json
["positive", "boundary", "misuse"]
```

- [ ] **Step 3: Create model index schema**

Create `schemas/model_index.schema.json` with this structure:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Model Index",
  "type": "object",
  "required": ["index_version", "last_updated", "models"],
  "properties": {
    "index_version": {
      "type": "string",
      "description": "索引版本。"
    },
    "last_updated": {
      "type": "string",
      "description": "索引最后更新时间。"
    },
    "models": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "model_id",
          "model_name",
          "model_type",
          "pipeline_position",
          "model_file",
          "card_file",
          "source_article_count",
          "source_evidence_count",
          "regression_case_count",
          "stability_level",
          "regression_status",
          "status"
        ],
        "properties": {
          "model_id": {"type": "string", "description": "模型 ID。"},
          "model_name": {"type": "string", "description": "模型中文名称。"},
          "model_type": {"type": "string", "description": "模型类型。"},
          "pipeline_position": {"type": "string", "description": "模型所在流程位置。"},
          "model_file": {"type": "string", "description": "模型 JSON 文件路径。"},
          "card_file": {"type": "string", "description": "Markdown 模型卡文件路径。"},
          "source_article_count": {"type": "integer", "description": "引用来源文章数量。"},
          "source_evidence_count": {"type": "integer", "description": "引用证据片段数量。"},
          "regression_case_count": {"type": "integer", "description": "回归测试用例数量。"},
          "stability_level": {"type": "string", "description": "稳固性等级。"},
          "regression_status": {"type": "string", "description": "回归测试状态。"},
          "status": {"type": "string", "description": "索引条目状态，例如 draft、active、deprecated。"}
        }
      }
    }
  }
}
```

- [ ] **Step 4: Create card index schema**

Create `schemas/card_index.schema.json` with this structure:

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Card Index Metadata",
  "type": "object",
  "required": ["index_version", "last_updated", "required_columns"],
  "properties": {
    "index_version": {"type": "string", "description": "卡片索引版本。"},
    "last_updated": {"type": "string", "description": "最后更新时间。"},
    "required_columns": {
      "type": "array",
      "description": "card_index.md 表格必须包含的列名。",
      "items": {"type": "string"}
    }
  }
}
```

---

### Task 4: Define Model Extraction Workflow

**Files:**
- Create: `docs/MODEL_EXTRACTION_WORKFLOW.md`
- Modify: `docs/WORKFLOW.md`

- [ ] **Step 1: Write model extraction workflow**

Create `docs/MODEL_EXTRACTION_WORKFLOW.md` with these stages:

```markdown
# Model Extraction Workflow

## Stage 0: GPT Plan Intake

Input from user:

- GPT planning document path
- Source article paths
- Existing model/application material paths
- Target model IDs
- Whether placeholder evidence is allowed
- Whether the goal is rules only, content extraction, or full chain

Output:

- Local execution plan
- Open questions
- Owner review gate

## Stage 1: Rules, Schema, Index, And Workflow Foundation

Codex actions:

- Convert GPT planning document into local rules.
- Define or update schemas.
- Define or update indexes.
- Define workflow gates.
- Define validation expectations.

Output:

- Rules docs
- Schema files
- Index contracts
- Workflow docs
- Difference report

Owner confirmation:

- Owner reviews rules/schema/workflow before content extraction.

## Stage 2: Source And Evidence Preparation

Codex actions:

- Register source articles.
- Extract source evidence excerpts.
- Mark placeholder evidence explicitly if source text is unavailable or insufficient.

Output:

- `sources/source_articles.json`
- `sources/source_excerpts.json`

Checks:

- Every excerpt references a known source article.
- Every source ID is unique.

## Stage 3: Model Asset Extraction

Codex actions:

- Write machine-readable model JSON.
- Write human-readable Markdown card.
- Update model and card indexes.

Output:

- `models/<model_id>.model.json`
- `cards/<model_id>.md`
- `models/model_index.json`
- `cards/card_index.md`

Checks:

- JSON passes schema.
- Markdown card contains required sections.
- Source references resolve.

## Stage 4: Regression And Selector Preparation

Codex actions:

- Write at least five regression cases per core model.
- Include positive, boundary, and misuse cases.
- Add selector rules and selector examples.

Output:

- Regression case files or consolidated regression case JSON.
- Selector rules.
- Selector examples.

Checks:

- Every core model has at least five cases.
- Each model has positive, boundary, and misuse cases.
- Selector examples return model IDs and reasons.

## Stage 5: Validation And Audit

Codex actions:

- Run local validation scripts.
- Generate validation report.
- Generate extraction audit report.

Output:

- `reports/validation_report.md`
- `reports/<model_id>_extraction_audit.md` or session-level audit report.

## Stage 6: Owner Review

Owner reviews:

- Model definition
- Field completeness
- Evidence quality
- Boundary and misuse cases
- Selector behavior
- Open questions

Content is not considered stable until owner review completes.
```

- [ ] **Step 2: Link workflow from existing workflow doc**

Add a short reference in `docs/WORKFLOW.md`:

```markdown
For detailed model extraction gates, see `docs/MODEL_EXTRACTION_WORKFLOW.md`.
```

---

### Task 5: Add Index Files

**Files:**
- Create: `models/model_index.json`
- Create: `cards/card_index.md`
- Modify: `models/README.md`
- Modify: `cards/README.md`

- [ ] **Step 1: Create machine-readable model index**

Create `models/model_index.json` with current two models:

```json
{
  "index_version": "0.1",
  "last_updated": "2026-06-16",
  "models": [
    {
      "model_id": "qpi",
      "model_name": "QPI 三元定性模型",
      "model_type": "routing_model",
      "pipeline_position": "pre_analysis",
      "model_file": "models/qpi.model.json",
      "card_file": "cards/qpi.md",
      "source_article_count": 2,
      "source_evidence_count": 5,
      "regression_case_count": 5,
      "stability_level": "B",
      "regression_status": "pending",
      "status": "draft"
    },
    {
      "model_id": "intellectual_archaeology",
      "model_name": "思想考古学",
      "model_type": "deep_modeling_model",
      "pipeline_position": "deep_analysis",
      "model_file": "models/intellectual_archaeology.model.json",
      "card_file": "cards/intellectual_archaeology.md",
      "source_article_count": 2,
      "source_evidence_count": 5,
      "regression_case_count": 5,
      "stability_level": "B",
      "regression_status": "pending",
      "status": "draft"
    }
  ]
}
```

- [ ] **Step 2: Create human-readable card index**

Create `cards/card_index.md`:

```markdown
# Card Index

| Model ID | 模型名称 | 类型 | 流程位置 | Card | Model JSON | 稳固性 | 回归状态 | 状态 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| qpi | QPI 三元定性模型 | routing_model | pre_analysis | `cards/qpi.md` | `models/qpi.model.json` | B | pending | draft |
| intellectual_archaeology | 思想考古学 | deep_modeling_model | deep_analysis | `cards/intellectual_archaeology.md` | `models/intellectual_archaeology.model.json` | B | pending | draft |
```

- [ ] **Step 3: Update README files**

Update `models/README.md` to state:

```markdown
`model_index.json` is the machine-readable model registry.
```

Update `cards/README.md` to state:

```markdown
`card_index.md` is the human-readable model card registry.
```

---

### Task 6: Upgrade Validation Tools

**Files:**
- Modify: `scripts/validate_model_library.py`
- Create: `scripts/check_card_contract.py`
- Test: `tests/test_validate_model_library.py`
- Create or modify: `tests/test_card_contract.py`

- [ ] **Step 1: Add failing tests for schema expectations**

Add tests that expect validation to fail when:

- Model JSON omits `trigger_keywords`.
- Model JSON has `selection_priority` outside 1-10.
- Model JSON uses `model_type` outside the enum.
- `stability_profile` omits `reason`.
- `models/model_index.json` references a missing model file.
- `cards/card_index.md` omits a known model.

- [ ] **Step 2: Add failing tests for card sections**

Create tests that expect `check_card_contract.py` to report a missing required heading when a card lacks `## 调用关键词`.

- [ ] **Step 3: Implement schema validation**

Update `scripts/validate_model_library.py` to:

- Load JSON schemas from `schemas/`.
- Validate model JSON against `schemas/model_card.schema.json`.
- Validate source articles, source excerpts, regression cases, and model index.
- Check model index file paths exist.
- Check every model appears in `models/model_index.json`.
- Check every card appears in `cards/card_index.md`.
- Keep existing reference checks.

If the standard library is insufficient for full JSON Schema validation, implement the local subset required by current schemas and record that limitation in `reports/validation_report.md`.

- [ ] **Step 4: Implement card contract checker**

Create `scripts/check_card_contract.py` to:

- Read `docs/MODEL_CARD_CONTRACT.md`.
- Extract required `##` headings.
- Check each `cards/*.md` file except `card_index.md`.
- Print missing headings.
- Return non-zero on missing headings.

- [ ] **Step 5: Verify tests**

Run:

```powershell
python -m unittest discover -s tests -p "test*.py" -v
```

Expected:

```text
OK
```

---

### Task 7: Add Selector Demo Plan And Minimal Script

**Files:**
- Create: `scripts/run_selector_demo.py`
- Modify: `selector/selector_rules.json`
- Modify: `selector/selector_examples.json`
- Test: add selector tests if practical

- [ ] **Step 1: Align selector output shape**

Ensure selector demo outputs:

```json
{
  "recommended_models": [
    {
      "model_id": "qpi",
      "score": 0.92,
      "reason": "输入包含问题定性需求。"
    }
  ],
  "not_recommended_models": [],
  "routing_notes": "先用 QPI 判断问题类型。"
}
```

- [ ] **Step 2: Implement no-LLM selector demo**

Create `scripts/run_selector_demo.py` using only Python standard library.

Scoring rules:

- trigger keyword hit: `+0.2`
- input type match: `+0.2`
- pipeline stage match: `+0.2`
- complexity signals: `+0.2`
- selection priority contribution: `selection_priority / 100`
- negative trigger hit: `-0.3`
- do_not_call_when hit: `-0.5`

The script must read model JSON and selector examples from local files.

- [ ] **Step 3: Add README command**

Document:

```powershell
python scripts\run_selector_demo.py
```

---

### Task 8: Owner Review Gate

**Files:**
- Modify: `reports/GPT规划落地差异检查_v0.1.md`
- Create: `reports/规则Schema工作流检查摘要_v0.1.md`

- [ ] **Step 1: Write foundation check summary**

Create `reports/规则Schema工作流检查摘要_v0.1.md` with:

```markdown
# 规则 Schema 工作流检查摘要 v0.1

## Completed

## Files Changed

## Checks Run

## Known Limits

## Owner Review Checklist

- GPT 规划是否已正确本地化？
- card contract 是否覆盖模型卡样例？
- model schema 是否覆盖机器 JSON 样例？
- index 设计是否满足当前和未来扩展？
- 工作流 gate 是否足以防止直接跳内容？
- 工具需求是否足够但不过度？

## Do Not Proceed Before Owner Confirms

Do not repair QPI or Intellectual Archaeology content until this foundation is reviewed.
```

- [ ] **Step 2: Stop for owner review**

After validation passes, stop and ask the owner to review the foundation. Do not continue to model content repair in the same step unless the owner explicitly says to continue.

---

## Verification Commands

Run these before claiming the foundation is ready:

```powershell
python -m unittest discover -s tests -p "test*.py" -v
python scripts\check_card_contract.py
python scripts\validate_model_library.py
python scripts\run_selector_demo.py
```

Expected:

- Unit tests pass.
- Card contract check passes after cards are brought into contract, or reports known current failures before content repair.
- Model library validation reports schema/index status clearly.
- Selector demo returns recommended models with score, reason, and routing notes.

## Self-Review Checklist

- The plan blocks content repair until rules/schema/workflow/index foundation is reviewed.
- GPT planning document is treated as upstream input, not direct implementation law.
- Both machine and human indexes are defined.
- Index maintenance policy is explicit.
- The dual-track model is represented:
  - workflow/tooling track
  - content extraction track
- Every new tool has a clear reason.
- No database, backend, frontend, RAG, or platform scope is introduced.