25 KiB

Raw Blame History

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:

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:

GPT plan intake.
Local plan creation.
Owner review of local plan.
Rules/schema/index/workflow implementation.
Validation of rules/schema/index/workflow.
Owner review of the foundation.
Content extraction or content repair.
Validation and audit report.
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:

# 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:

# 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:

# 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:

## 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:

# 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:

["positive", "boundary", "misuse"]

Step 3: Create model index schema

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

{
  "$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:

{
  "$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:

# 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:

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:

{
  "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:

# 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:

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

Update cards/README.md to state:

`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:

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

Expected:

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:

{
  "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:

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:

# 规则 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:

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.

25 KiB Raw Blame History

Model Extraction Contract and Workflow Implementation Plan

Scope

Source Planning Document

Required Local Outputs

Index Decision

Workflow Gates

Task 1: Localize GPT Plan Into Repository Rules

Task 2: Define Model Card Contract And Schema

Task 3: Define Source, Regression, And Index Schemas

Task 4: Define Model Extraction Workflow

Task 5: Add Index Files

Task 6: Upgrade Validation Tools

Task 7: Add Selector Demo Plan And Minimal Script

Task 8: Owner Review Gate

Verification Commands

Self-Review Checklist

25 KiB

Raw Blame History