create-ccc-tutor 0.1.0

package/template/codex.md

@@ -0,0 +1,39 @@
+# CCC-tutor — Codex 入口指引
+
+> 本文件是 Codex 的"指路牌"。Codex 的实际项目入口是 **`AGENTS.md`**（+ `.codex/config.toml`、`.codex/hooks.json`）。
+> 宪法 §3 红线 #1 要求本项目同时支持 Claude 与 Codex；本文件保证 Codex 一侧也有明确入口。
+
+## Claude 与 Codex 的关键差异（务必理解）
+
+| | Claude Code | Codex |
+|---|---|---|
+| 自定义功能机制 | **斜杠命令** `.claude/commands/<名>.md` | **技能** `~/.codex/skills/<名>/SKILL.md` |
+| 怎么触发 | 打 `/<名>`（如 `/slide`） | **不打斜杠**；模型按技能的 `description` **自动判断何时调用**，你用自然语言问即可 |
+| 发现位置 | 直接读项目 `.claude/commands/` | 只读 `~/.codex/skills/`，**不读项目级** → 需安装脚本复制过去 |
+
+> ⚠️ 在 Codex 里**没有 `/slide` 这个斜杠命令**（打了会报 "Unrecognized command"）。正确用法见下。
+
+## 用 Codex 运行本项目
+
+1. **首次（或改了技能后）先安装技能**：`bash .codex/install-skills.sh`
+   - 把项目 `.codex/skills/*` 复制到 `~/.codex/skills/`（Codex 只从这里加载技能）。
+   - 项目里的 `.codex/skills/<名>/SKILL.md` 是单一事实源；改完重跑脚本 + 重启 Codex 生效。
+2. 在项目根目录运行 `codex`。
+3. **先告诉它科目**（如 `course_code(example)`）；没说且有多个科目时它会先问，单科目直接用。当前会话科目记在 `.harness/state/current-subject.txt`，除非更换整段会话沿用。
+4. **用自然语言提问**触发技能，例如：
+   - 查知识点 → `根据课件回答：什么是置信区间？` → Codex 调用 **slide** 技能：只查当前科目 `course/<科目>/slide/` 的 PDF、标出处、找不到先问再补充。
+   - 解题目 → `看 <文件名> 里的第3题` 或直接说要解某文件的某题 → Codex 调用 **exam** 技能：在 `course/<科目>/exam/` 里定位题目并解答，依据优先引用课件。
+
+## 已有功能（Claude ↔ Codex 对照）
+
+| 功能 | Claude 版（打 `/命令`） | Codex 版（自然语言触发） |
+|---|---|---|
+| 课件查询 slide | `.claude/commands/slide.md` | `.codex/skills/slide/SKILL.md` → 装到 `~/.codex/skills/slide/` |
+| 题目解答 exam | `.claude/commands/exam.md` | `.codex/skills/exam/SKILL.md` → 装到 `~/.codex/skills/exam/` |
+
+## 规格来源（与 AI 无关，单一事实源）
+
+- 每个功能的行为规格：`docs/features/<name>.md`
+- 例：课件查询见 `docs/features/slide-query.md`
+
+> 注意：Claude 的 Read 工具能直接渲染 PDF；Codex 需用 shell（`pdftotext` 或 `python3 + pypdf`）抽取 PDF 文字。两侧行为规则相同，仅"读 PDF 的手段"不同。

package/template/constitution.md

@@ -0,0 +1,164 @@
+# CCC-tutor — Constitution
+
+<!-- Sync Impact Report
+Version: 1.0.0 → 1.1.0 (MINOR — add Section 3 clause #1: 双系统 · 双 AI 兼容)
+Modified items:
+  - Section 3 — added clause #1: 双系统 · 双 AI 兼容（Mac/Windows × Claude/Codex）
+Templates needing update:
+  - N/A
+Generated: 2026-06-09T01:03:04Z
+-->
+
+<!-- This file is the PROJECT CONSTITUTION. It is loaded by every agent
+     (planner / programmer / reviewer / junior reviewers) BEFORE any
+     other harness file. It contains the things that, if violated,
+     mean this is no longer THIS project.
+
+     Three sections:
+       Section 1 — Universal core (harness-guaranteed; can't be removed)
+       Section 2 — Project identity (filled at /init; edit via /constitution-edit)
+       Section 3 — Project-specific red lines (starts empty; grows via /add-constitution-clause)
+
+     CLAUDE.md describes HOW to work (workflow, lanes, tools).
+     This file describes WHAT this project stands for. -->
+
+<!-- ============================================================
+SLOT REGISTRY (single source of truth for the whole harness)
+
+Format: slot_name | level | source(s) | description
+
+# L0 — must be filled before any work begins
+project_name              | L0 | AUTO(manifest:name) → ASK_USER  | Project name
+project_description       | L0 | ASK_USER                         | One-sentence project intro (plain language)
+project_stage             | L0 | ASK_USER                         | early / beta / prod / scale
+project_scale_target      | L0 | ASK_USER                         | Target scale
+team_size                 | L0 | DEFAULT(solo) → ASK              | solo / small / large
+primary_concern           | L0 | ASK_USER                         | What the harness is primarily responsible for
+out_of_scope_items        | L0 | ASK_USER (list)                  | What the harness should NOT care about
+auditor_model             | L0 | DEFAULT(Codex) → ASK             | Cross-model auditor display name; None = single-engine
+auditor_model_id          | L1 | DEFAULT(gpt-5.5)                   | Cross-model auditor version string (for CLI config; change via /constitution-edit)
+language_mode             | L0 | DEFAULT(plain) → ASK             | plain / professional
+spec_dir                  | L0 | DEFAULT(docs/features/)          | Spec directory
+implementation_dir        | L0 | DEFAULT(docs/features/)          | Implementation directory
+
+# L0 — Constitution Section 2 identity slots
+project_audience          | L0 | ASK_USER                         | Who we serve (one sentence)
+project_non_goals         | L0 | ASK_USER                         | What we deliberately do NOT do
+project_compliance        | L0 | ASK_USER                         | Compliance floors (GDPR/HIPAA/PCI/none/other)
+project_performance_floor | L0 | ASK_USER                         | Performance floors
+project_identity_other    | L0 | OPTIONAL                         | Other identity-level statements
+
+# L1 — filled at appropriate stages
+tech_stack                | L1 | AUTO(scan manifests)              | Primary tech stack
+repo_structure            | L1 | AUTO(scan fs) → CONFIRM           | Repo structure
+dependency_flow           | L1 | ASK (optional)                    | Module dependency order
+release_lanes             | L1 | DEFAULT([git-push]) → ASK         | Release lanes
+backend_change_lane       | L1 | OPTIONAL                          | Backend change lane
+error_tracker             | L1 | ASK                                | Error tracker
+test_required             | L1 | DEFAULT(true) → ASK                | Whether automated tests are enabled
+junior_reviewers          | L1 | EXAMPLES → ASK                     | Which rule-enforcement reviewers to enable
+rule_sources              | L1 | EMPTY → GROW                       | Index of per-domain rule files
+supported_locales         | L1 | DEFAULT(["zh-Hans","en","ko"]) → ASK | Project-supported locales (i18n)
+edge_case_categories      | L1 | DEFAULT(5 universal) + 3 user     | Edge-case round category list
+test_framework            | L1 | AUTO(scan deps) → CONFIRM         | Test framework (jest/vitest/pytest, etc.)
+test_runner_command       | L1 | AUTO(scan scripts)                | Test runner command
+feature_folder_pattern    | L1 | AUTO(scan fs) → CONFIRM           | Feature folder pattern
+client_code_paths         | L1 | AUTO(scan fs) → CONFIRM           | Frontend code path patterns (used to trigger reviewers)
+backend_code_paths        | L1 | OPTIONAL                          | Backend code path patterns (skipped if no backend)
+backend_db_type           | L1 | OPTIONAL                          | Database type; projects without a backend skip db-schema
+high_trap_libraries       | L1 | EXAMPLES → ASK                     | High-risk libraries requiring context7 version verification
+migration_dir             | L1 | OPTIONAL                          | Migration files directory (only if backend_db_type is set; typical default supabase/migrations/)
+pii_columns               | L1 | DEFAULT([phone,email,name,address,payment]) → ASK | PII column list (used by db-schema / security-reviewer)
+rls_auth_function         | L1 | OPTIONAL                          | Access-control auth-context expression (e.g., Postgres+RLS: (SELECT auth.uid()))
+
+# L2 — grow over time
+anti_flag_rules           | L2 | EXAMPLES_AS_SEED + GROW           | Anti-flag rules (in AGENTS.md)
+project_red_lines         | L2 | EMPTY → GROW                       | See Section 3 of this file
+============================================================ -->
+
+---
+
+## Section 1 — Universal core
+
+> **Shipped with the harness. These items are this harness's load-bearing invariants. They cannot be removed, overridden, or carved out — not by lane choice, not by direct CEO instruction, not under any circumstances. The harness exists to enforce these; remove them and the harness is no longer the harness. The CEO can ADD to them but cannot REMOVE them, even by direct instruction.**
+
+### 1. Cross-model audit is mandatory
+
+Every code change passes the auditor (Codex) audit at the appropriate gate. No lane exemption, no surface exemption. The auditor is independent of the implementer — that independence is the point.
+
+**Single-engine fallback:** if `auditor_model = None`, the audit step still runs but uses a fresh-context invocation of the same model. Bias-cancellation guarantee weakens; the discipline of a second look remains.
+
+Pure documentation, comment-only, formatting-only, and meta-file changes are exempt.
+
+### 2. Data ownership red line
+
+User data never leaks into logs, errors, cache, or cross-user responses. Server-side access control enforces; client trust never substitutes for enforcement. Keeping PII out of telemetry is non-negotiable.
+
+### 3. CEO has final authority — except on Universal Core
+
+The CEO has the final word on intent, scope, and lane. STRONG operating preferences (see `CLAUDE.md § Operating Principles`) ARE overridable by CEO with reasoning recorded in `## Decision history`.
+
+**Exception:** Universal Core items (Section 1 of this file) are NOT overridable, even by direct CEO instruction. The CEO cannot direct a PII leak, cannot direct skipping the auditor, cannot direct shipping without smoke test, cannot direct removing this section. If a CEO instruction would violate a Universal Core item, the manager surfaces the conflict and the instruction must be reformulated; it cannot be carried out as-stated.
+
+Authority rules:
+- A CEO rejection on a STRONG item is final; no reason required.
+- A CEO decision is followed; the manager (Tech Lead / Main Claude) carries it out.
+- The manager may surface risks ("CEO, this carries X risk"); after the CEO decides, the discussion ends.
+- A CEO decision stands even when the manager finds it illogical — surface the disagreement, then carry out the decision.
+- A CEO approval scopes only what was actually requested. It does not authorize related actions, broader changes, or repeat application in future contexts.
+
+### 4. Real-human smoke test is mandatory
+
+AI's self-report of "done" does not count. Before any push to GitHub, the real-human user (CEO) must run the application manually against the spec's smoke-test procedures (Stage 7 of `CLAUDE.md § Workflow`).
+
+This step cannot be skipped, cannot be AI-substituted, and cannot be bypassed via any lane — with one narrow exception: the Trivial-change lane may skip Stage 7 for pure copy/text/translation changes (spot-check still required for any logic change).
+
+### 5. Spec and reality stay in sync
+
+User-visible behavior changes update the corresponding `docs/features/<name>.md` in the same commit. State-coordination invariants update `docs/features/<name>-implementation.md` in the same commit.
+
+Spec-vs-code drift makes the project lie about itself. Drift is caught by `/audit-spec`; correction is mandatory at the commit gate.
+
+---
+
+## Section 2 — Project identity
+
+> **Filled at `/init` via 3-5 plain-language questions. Edit via `/constitution-edit`.**
+
+**Who do we serve?**
+
+使用本工具复习课程的学生（主要是项目作者本人）
+
+**What do we deliberately NOT do?**
+
+不替代课件本身；不回答课件之外或无依据的问题；不编造课件中不存在的内容
+
+**Compliance / legal floors:**
+
+none（无合规要求）
+
+**Performance floors that cannot be crossed:**
+
+暂无正式性能底线
+
+**Other "if-violated-it's-not-this-project-anymore" statements:**
+
+所有回答必须可追溯到课件来源；课件中查不到时必须如实告知，绝不编造
+
+---
+
+## Section 3 — Project-specific red lines
+
+> **Starts empty. Grows via `/add-constitution-clause`.**
+
+A rule should only be promoted to this section if it meets ALL THREE:
+
+- **Project-wide scope** (not area-specific — area rules belong in rule sources)
+- **Absolute** (no exceptions, no lane override)
+- **Identity-changing** (violating it makes this no longer this project)
+
+Most rules should stay in rule sources or anti-flag rules. Only promote here when the bar above is met.
+
+### 1. 双系统 · 双 AI 兼容（Mac/Windows × Claude/Codex）
+
+本项目必须始终能在 **macOS 与 Windows** 两种系统上运行，并且必须同时支持 **Claude 与 Codex** 两套 AI harness。用 Claude 运行时，Claude Code CLI 读取 `CLAUDE.md` 即可丝滑运行并输出；用 Codex 运行时，Codex 读取其入口（`AGENTS.md`，并以 `codex.md` 作为指路文件）即可同样丝滑运行。首次架构由 Claude 搭建；此后每完成一个功能，必须同步交付一份 Codex 可无缝启动的等价实现（例如 Claude 的 `.claude/commands/<name>.md` 对应 Codex 的 `.codex/prompts/<name>.md`），不得只交付单一 AI 或单一系统的版本。

package/template/course/README.md

@@ -0,0 +1,15 @@
+# course/ — 你的科目放这里
+
+每个科目一个文件夹,文件夹名建议用课程代码(如 `ECON-10005`)。结构:
+
+```
+course/
+  <课程代码>/
+    slide/   ← 课件 PDF(/slide 在这里查知识点)
+    exam/    ← 题目文件(/exam 在这里找题、解答)
+```
+
+`course_code(example)/` 是示例,放了两个示例课件。用法:
+1. 复制这个文件夹,改成你的课程代码;
+2. 把课件 PDF 放进 `slide/`,题目文件放进 `exam/`;
+3. 打开 Claude Code,告诉它科目 + 问题,或用 `/slide` `/exam`。

package/template/course/course_code(example)/exam/README.md

@@ -0,0 +1,2 @@
+把这个科目的题目文件(PDF / 文本)放进本文件夹。
+然后用 /exam 或直接说"看 <文件名> 里的第N题",AI 会定位题目并按课件优先解答。

package/template/course/course_code(example)/slide/slide_example-1.pdf

@@ -0,0 +1,40 @@
+%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R] /Count 1 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>
+endobj
+4 0 obj
+<< /Length 315 >>
+stream
+BT /F1 16 Tf 72 740 Td 20 TL
+(Lecture 1: Example Slide \(Opportunity Cost\)) Tj
+T* () Tj
+T* (Opportunity cost is the value of the next-best) Tj
+T* (alternative you give up when you make a choice.) Tj
+T* () Tj
+T* (This is an EXAMPLE file. Replace it with your real) Tj
+T* (course slides in this slide/ folder.) Tj
+ET
+endstream
+endobj
+5 0 obj
+<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+endobj
+xref
+0 6
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+0000000241 00000 n 
+0000000607 00000 n 
+trailer
+<< /Size 6 /Root 1 0 R >>
+startxref
+677
+%%EOF

package/template/course/course_code(example)/slide/slide_example-2.pdf

@@ -0,0 +1,40 @@
+%PDF-1.4
+1 0 obj
+<< /Type /Catalog /Pages 2 0 R >>
+endobj
+2 0 obj
+<< /Type /Pages /Kids [3 0 R] /Count 1 >>
+endobj
+3 0 obj
+<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Contents 4 0 R /Resources << /Font << /F1 5 0 R >> >> >>
+endobj
+4 0 obj
+<< /Length 326 >>
+stream
+BT /F1 16 Tf 72 740 Td 20 TL
+(Lecture 2: Example Slide \(Confidence Interval\)) Tj
+T* () Tj
+T* (A 95% confidence interval is a range that would) Tj
+T* (contain the true parameter in 95% of repeated samples.) Tj
+T* () Tj
+T* (This is an EXAMPLE file. Replace it with your real) Tj
+T* (course slides in this slide/ folder.) Tj
+ET
+endstream
+endobj
+5 0 obj
+<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>
+endobj
+xref
+0 6
+0000000000 65535 f 
+0000000009 00000 n 
+0000000058 00000 n 
+0000000115 00000 n 
+0000000241 00000 n 
+0000000618 00000 n 
+trailer
+<< /Size 6 /Root 1 0 R >>
+startxref
+688
+%%EOF

package/template/docs/features/slide-query-implementation.md

@@ -0,0 +1,79 @@
+# 课件查询 /slide — Implementation Notes
+
+**Spec:** docs/features/slide-query.md (canonical, CEO domain)
+**This file:** technical detail, manager domain.
+
+## Overview
+
+`/slide` is implemented in two parallel forms (Constitution §3 red line #1 — every feature ships a Claude version AND a Codex version):
+- **Claude:** a slash command / prompt file at `.claude/commands/slide.md`.
+- **Codex:** a skill at `.codex/skills/slide/SKILL.md`, installed to `~/.codex/skills/slide/` via `.codex/install-skills.sh` (Codex auto-triggers it from the `description`, no `/` syntax).
+
+Neither is a separate application. The command/skill instructs the assistant to answer ONLY from the **current subject's** PDF course materials in `course/<subject>/slide/`, with mandatory source citations.
+
+No build step, no runtime, no dependencies beyond Claude Code / Codex itself.
+
+## Multi-subject architecture (2026-06-10)
+
+- Materials live under `course/<subject>/slide/`; problem files under `course/<subject>/exam/` (sibling feature `/exam`). One folder per subject (e.g. `course_code(example)`, `course_code(example)`).
+- **Subject resolution** (same logic in slide + exam, Claude + Codex):
+  1. `ls -d course/*/` to enumerate subjects.
+  2. Read current session subject from `.harness/state/current-subject.txt` (may not exist).
+  3. If the user names a subject → use it and write it to the state file. Else if state has one → reuse. Else if exactly one subject folder → use it (and write state). Else (multiple, none chosen) → **ask the user** and wait. Switching subject overwrites the state file.
+- The state file `.harness/state/current-subject.txt` is runtime/personal — gitignored, not committed.
+
+## Not-found behavior (2026-06-10 — "ask before supplementing")
+
+Replaces the old "never supplement" red line. When the answer is absent from the current subject's `slide/`: state plainly it is not in the materials, **then ask** whether the user wants an outside (web-search / model-known) supplement, and wait. Only on user consent, supplement with a whole-block label "⚠️ non-courseware, external source, verify yourself" (attach source links if web-searched). Courseware remains the sole primary source; never supplement without consent.
+
+## Functional requirements (EARS)
+
+- **WHEN** the user invokes `/slide` with a non-empty question **THE SYSTEM SHALL** read the PDF files under the current subject's `course/<subject>/slide/`, locate relevant content, and answer in Chinese with proper nouns kept in English, an original-text excerpt, and a source citation in the form `（第N讲 第M页）`.
+- **WHEN** the answer content is found across multiple PDFs **THE SYSTEM SHALL** synthesize a single coherent answer and attach a separate citation to each contributing part.
+- **WHEN** the question's answer is not present in the current subject's course material **THE SYSTEM SHALL** state plainly that the materials do not contain it, **then ask the user whether to supplement from outside (web/model knowledge), and wait** — supplementing only on consent and only with a whole-block "non-courseware / external / verify yourself" label. It SHALL NOT supplement without consent. *(2026-06-10: relaxes the prior absolute "never supplement" red line into "ask-then-supplement"; courseware stays the sole primary source.)*
+- **WHEN** only related-but-not-direct content exists **THE SYSTEM SHALL** return the related content, label it explicitly as not a direct answer, and cite its source.
+- **WHEN** the current subject's `course/<subject>/slide/` folder contains no readable course material **THE SYSTEM SHALL** tell the user to add materials and SHALL NOT fabricate an answer.
+- **WHEN** a PDF's internal lecture number cannot be determined **THE SYSTEM SHALL** fall back to citing by `文件名 + 页码` and note the lecture number is uncertain.
+- **WHEN** a PDF cannot be read as text (scanned image / encrypted / corrupted) **THE SYSTEM SHALL** name the unreadable file and continue answering from the remaining readable materials.
+- **IF** the user invokes `/slide` with no question **THEN THE SYSTEM SHALL** prompt for a question rather than answering.
+- **WHEN** two or more course materials give conflicting statements about the same question **THE SYSTEM SHALL** present each statement with its own citation, flag the disagreement, and SHALL NOT merge or adjudicate beyond what the materials support.
+- **WHEN** the lecture number or page of a cited fragment cannot be reliably determined **THE SYSTEM SHALL** mark the citation as uncertain rather than presenting a fabricated exact reference.
+- **WHEN** the question is too broad, ambiguous, or relies on missing prior context (stateless follow-up) **THE SYSTEM SHALL** ask the user to restate it concretely rather than guessing intent, optionally returning clearly-labeled related material.
+
+## Command / skill files
+
+- Claude: `.claude/commands/slide.md`; `$ARGUMENTS` carries `[subject] <question>`.
+- Codex: `.codex/skills/slide/SKILL.md` (installed to `~/.codex/skills/slide/`).
+- Shape: defines subject resolution, the role ("answer ONLY from the current subject's `slide/` PDFs, always cite, never fabricate"), citation format, language rule (Chinese + English proper nouns + original excerpt), and the not-found(ask-then-supplement) / partial-match / unreadable-file behaviors.
+
+## PDF reading approach
+
+- Source folder: `course/<subject>/slide/`. Claude renders PDFs with the Read tool (`pages` param). Codex has no built-in PDF rendering — it extracts text via `pdftotext -layout` or `pypdf` in shell.
+- Reading: Claude Code's Read tool can render PDF pages. Per-request page limits apply (the tool reads up to ~20 pages/request and requires an explicit page range for large PDFs).
+- ~10 PDFs × 1.5–3.5MB each. Reading all pages of all PDFs for every query is potentially heavy. **Open implementation decision (deferred per spec §6):** whether to read on-demand (let the assistant open relevant PDFs/pages per question) vs. maintain a lightweight index. Start simple: on-demand reading, let the model decide which files/pages to open based on the question. Revisit if latency/cost is a problem.
+
+## Citation derivation
+
+- Lecture number ("第N讲" / "slide N"): derived by reading the PDF's internal title/header text (CEO choice C). Fallback chain: PDF internal title → filename pattern (if it encodes a number) → "讲次未确定 + 文件名".
+- Page number: from the PDF page where the cited content appears.
+
+## Testing strategy (deferred — spec §6)
+
+Testing an LLM-driven command is non-traditional. No conventional unit-test framework applies directly. Candidate approach: an **eval-style harness** with a few small fixture PDFs and a question set, asserting:
+1. Found-in-materials questions → answer includes a citation.
+2. Not-in-materials questions → answer says "课件里没有", no fabricated content.
+3. Partial-match questions → answer carries the "非直接回答" label.
+
+To be finalized at Stage 4/6. `test_required = true` at project level, but the concrete framework (`test_framework = 待定`) is unresolved.
+
+## File locations
+
+- `.claude/commands/slide.md` — Claude command definition
+- `.codex/skills/slide/SKILL.md` — Codex skill definition (installed via `.codex/install-skills.sh`)
+- `course/<subject>/slide/` — user's PDF course materials per subject (user-provided, not committed unless user chooses)
+- `.harness/state/current-subject.txt` — current session subject (runtime, gitignored)
+- `docs/features/slide-query.md` — CEO spec
+
+## Scenario → automated test map
+
+*(Empty stub — fills in at Stage 6.)*

package/template/docs/features/slide-query.md

@@ -0,0 +1,211 @@
+# Feature: 课件查询 /slide
+
+## Status: DRAFT 2026-06-09 · 架构更新 2026-06-10（多科目 + 先问再补充）
+
+## 0. 架构更新（2026-06-10）
+
+本功能从“单一课件文件夹”升级为“多科目”结构：
+
+- 课件不再放在根目录的 `课件/`，而是放在 `course/<科目>/slide/`（每个科目一个文件夹）。同级还有 `course/<科目>/exam/` 放题目（见姊妹功能 `/exam`）。
+- 用户先告诉助手是哪个科目；没说且有多个科目时，助手**先问**；只有一个科目时直接用。当前会话科目记在 `.harness/state/current-subject.txt`，除非用户更换，整段会话沿用同一科目。
+- **核心红线放宽（见 3.4 新版）**：课件里找不到时，助手**先如实说“课件里没有”，再问用户要不要用课件外（联网/AI 已知）知识补充**；用户同意才补充，且补充内容整段标注“非课件、来自外部、请自行核对”。课件依然是绝对的一手资料；未经用户同意绝不补充外部知识。
+
+下文 1–9 节里凡是写“课件文件夹 / 课件/”的，均指当前科目的 `course/<科目>/slide/`。
+
+## 1. What this feature is for
+
+给正在复习课程的同学用的一个命令。用户在课程文件夹里启动助手后，先确定科目，再输入 `/slide` 加上自己的问题，助手只翻阅该科目 `course/<科目>/slide/` 里的课程材料来回答，并且每次回答都标明出处（第几讲、第几页）。它的价值在于：复习时能快速从一堆课件里找到答案，而且每个说法都能追溯到原始课件，绝不凭空编造——让用户可以放心地信任答案。课件查不到时，先如实告知再按需补充。
+
+## 2. Happy path
+
+### 2.1 提一个问题，得到带出处的答案
+
+当用户输入 `/slide` 加一个问题（例如“什么是机会成本”），助手会翻阅“课件”文件夹里的课程材料，找到相关内容后用中文回答。回答里：
+
+- 专有名词保留英文原词（例如“机会成本（opportunity cost）”）
+- 附上课件里的原文片段，方便用户核对
+- 每个说法后面标注出处，格式形如 `（第9讲 第13页）`
+
+### 2.2 跨多个课件融会贯通
+
+当一个问题的答案分散在多个课件里时，助手把它们综合成一个连贯的回答，并在每一部分后面分别标注各自的出处。例如：“……（第9讲 第13页）……（第5讲 第21页）”。
+
+### 2.3 一次一问
+
+每次 `/slide` 处理一个问题。用户想再问，就再输入一次 `/slide` 加新问题。助手不进入“连续问答”状态。
+
+## 3. Edge-case behavior
+
+### 3.1 问题里没有内容（只输入了 /slide）
+
+#### Behavior (CEO sign-off)
+- 当用户只输入 `/slide`、后面没有跟问题
+- 助手不乱猜，而是提示用户“请在 /slide 后面写上你想问的问题”
+- 用户看到一句友好的提示
+
+#### Classification
+[Smoke test only]
+
+#### Smoke test procedure
+**Reproduce:** 输入 `/slide`，不带任何问题。
+**Pass criteria:** 助手提示需要补充问题，没有瞎编答案。
+**Failure signals:** 助手凭空给出一个不存在的问题的答案。
+
+### 3.2 课件文件夹是空的 / 里面没有可用课件
+
+#### Behavior (CEO sign-off)
+- 当“课件”文件夹里没有任何课程材料
+- 助手如实告知“课件文件夹里还没有课件，请先把课件放进去”
+- 不编造任何答案
+
+#### Classification
+[Required automated test]
+
+#### Smoke test procedure
+**Reproduce:** 清空课件文件夹，输入 `/slide 任意问题`。
+**Pass criteria:** 助手提示没有课件，不给出任何虚构答案。
+**Failure signals:** 助手在没有课件的情况下仍然“回答”了问题。
+
+### 3.3 答案在课件里能找到
+
+#### Behavior (CEO sign-off)
+- 当问题的答案确实在某个课件里
+- 助手用中文回答，保留专有名词英文，附课件原文片段，并标注出处（第几讲第几页）
+- 用户看到答案 + 可核对的原文 + 出处
+
+#### Classification
+[Required automated test]
+
+### 3.4 答案在课件里找不到（核心红线 · 2026-06-10 改为“先问再补充”）
+
+#### Behavior (CEO sign-off)
+- 当问题的答案在当前科目所有课件里都找不到
+- 助手**先**明确说明“课件里没有这个内容”，**绝不在用户同意前编造或擅自用课件外知识补充**
+- 然后助手**问用户**：“要不要我用课件之外的知识（联网搜索 / 我已知的知识）补充一下？”——停下来等用户回答
+- **只有用户同意后**才补充；补充内容整段标注“⚠️ 非课件内容、来自外部，请自行核对”（联网搜到的附来源链接）。用户不要补充则到此为止
+- 如果同时有课件读不出来（见 3.8），措辞要收紧为“在**能读取的**课件里没找到；文件 xxx 没读出来、未纳入判断”，不把它说成绝对的“全部课件里都没有”
+- 用户先看到诚实的“未找到”，再自主决定是否要外部补充——绝不会拿到一个看似来自课件其实没依据的答案
+
+#### Classification
+[Required automated test]
+
+### 3.5 课件里只有“相关但不完全对应”的内容
+
+#### Behavior (CEO sign-off)
+- 当课件里没有问题的直接答案，但有相关内容
+- 助手把相关内容给出来，并明确标注“这是相关内容，课件里没有直接回答你这个问题”，同时给出出处
+- 用户能区分“直接答案”和“仅供参考的相关内容”
+
+#### Classification
+[Required automated test]
+
+### 3.6 出处的讲次或页码无法确定
+
+#### Behavior (CEO sign-off)
+- 当某个课件内部没有写清楚是第几讲，或某段内容对应的页码无法确定
+- 助手退回用“文件名 + 页码”来标注出处；若连页码也没把握，就明确标注“出处不确定”，绝不假装精确
+- 用户仍然能定位到具体文件，并清楚哪些出处是确定的、哪些是不确定的
+
+#### Classification
+[Smoke test only]
+
+#### Smoke test procedure
+**Reproduce:** 放入一个内部没有讲次编号的课件，提一个答案在其中的问题。
+**Pass criteria:** 助手用文件名+页码标注；讲次或页码没把握时明确说“不确定”，不凭空编一个精确编号。
+**Failure signals:** 助手凭空编一个讲次或页码编号，并把它当成精确出处呈现。
+
+### 3.7 问的是和课程无关的问题
+
+#### Behavior (CEO sign-off)
+- 当用户问的内容和课程课件无关
+- 助手按“课件里没有”处理，如实说明
+- 不用课程之外的常识去回答
+
+#### Classification
+[Smoke test only]
+
+#### Smoke test procedure
+**Reproduce:** 输入一个明显与课程无关的问题（例如“今天天气怎么样”）。
+**Pass criteria:** 助手说明这不在课件范围内，不作答。
+**Failure signals:** 助手当成普通聊天回答了。
+
+### 3.8 某个课件读不出来（例如是扫描图片、无法提取文字）
+
+#### Behavior (CEO sign-off)
+- 当某个课件文件无法读取出文字内容
+- 助手告知用户“某个文件读不出文字内容（文件名：xxx）”，并基于其余能读的课件继续回答
+- 用户知道哪个文件没被纳入
+
+#### Classification
+[Smoke test only]
+
+#### Smoke test procedure
+**Reproduce:** 放入一个扫描版（纯图片）PDF，提一个其内容相关的问题。
+**Pass criteria:** 助手指出该文件读不出文字，不假装读到了。
+**Failure signals:** 助手编造该文件的内容。
+
+### 3.9 多个课件内容互相矛盾
+
+#### Behavior (CEO sign-off)
+- 当不同课件对同一问题给出不一致的说法
+- 助手**不替用户裁决、不强行合并成一个答案**，而是分别如实列出每份课件的说法和各自出处，并指出“这两处课件说法不一致”
+- 用户看到双方原始说法 + 出处，自己判断
+
+#### Classification
+[Required automated test]
+
+### 3.10 问题太宽泛、模糊、或缺上下文（含追问类）
+
+#### Behavior (CEO sign-off)
+- 当问题太笼统、含义不清，或是依赖上文的追问（例如“上一个概念有什么例子”——但每次 `/slide` 不记得上文）
+- 助手**不猜测用户到底想问什么**，而是请用户把问题说完整（例如把“上一个概念”换成具体名词）
+- 在能给出明确标注的相关内容时，可一并给出，但要标注“这是相关内容、非直接回答”
+- 用户得到的是“请说清楚”的引导，而不是一个基于猜测的答案
+
+#### Classification
+[Smoke test only]
+
+#### Smoke test procedure
+**Reproduce:** 输入一个模糊或缺上下文的问题，例如 `/slide 这个怎么算`。
+**Pass criteria:** 助手请用户补充清楚，而不是猜一个具体问题来回答。
+**Failure signals:** 助手自行假设用户想问什么并直接作答。
+
+## 4. Who can use this
+
+- 任何在本课程文件夹里运行助手的人（本地使用，无需登录）
+- 前提是“课件”文件夹里已放入课程材料
+- 没有课件时，功能会提示先放入课件
+
+## 5. External dependencies (plain language)
+
+- 依赖助手本身读取 PDF 文件的能力
+- 当某个 PDF 是扫描图片、加密、或损坏而读不出文字时：按 3.8 处理，告知用户该文件无法读取，用其余课件继续回答
+
+## 6. Deferred / unresolved
+
+- **自动化测试方式待定**：这个功能本质是“让助手按规则回答”，怎么自动化地验证“引用准确、找不到时如实说”需要在实现阶段确定测试做法（可能以少量样例课件做评测式测试为主）。已记录，留到实现阶段解决。
+- 课件较多/较大时，一次能否全部读入、是否需要分批，留到实现阶段评估（属技术细节）。
+
+## 7. Out of scope
+
+- 题目问答（`/exam`）——已作为姊妹功能落地（在 `course/<科目>/exam/` 里找题目并解答），规则见 `.claude/commands/exam.md` / `.codex/skills/exam/SKILL.md`
+- 未经用户同意，回答课件范围之外的任何内容
+- 修改、整理或总结课件本身（只做查询问答）
+
+## 8. Decision history
+
+- 2026-06-09 CEO：采用“一次一问”形式（`/slide 问题`），不做持续问答模式。
+- 2026-06-09 CEO：每次回答必须标注出处（第几讲第几页），并支持跨多个课件综合回答。
+- 2026-06-09 CEO：出处的讲次通过读取 PDF 内部标题/内容判断；无法判断时退回文件名+页码并说明不确定。
+- 2026-06-09 CEO：回答用中文，保留专有名词英文原词，并附课件原文片段供核对。
+- 2026-06-09 CEO：课件里只有相关内容时，给出相关内容并明确标注“非直接回答”。
+- 2026-06-09 CEO：核心红线——课件里找不到就如实说“没有”，绝不编造、绝不用课件外知识补充。
+- 2026-06-09 CEO（采纳 Codex 审计）：课件之间说法矛盾时，分别列出各自说法和出处，不替用户裁决、不强行合并（见 3.9）。
+- 2026-06-09 CEO（采纳 Codex 审计）：出处的讲次或页码没把握时，明确标注“不确定”，不假装精确（见 3.6）。
+- 2026-06-09 CEO（采纳 Codex 审计）：问题模糊或缺上下文（含追问类）时，请用户说清楚，不猜测意图（见 3.10）。
+- 2026-06-10 CEO：项目改名 CCC-tutor，升级为多科目架构——课件放 `course/<科目>/slide/`、题目放 `course/<科目>/exam/`；用户先定科目，没说且多科目时先问，单科目直接用，会话内沿用（记于 `.harness/state/current-subject.txt`）。
+- 2026-06-10 CEO：核心红线放宽——课件查不到时不再“绝不补充”，而是“先如实说没有、再问用户、用户同意后才用外部知识补充并整段标注非课件来源”（见 3.4 新版）。
+- 2026-06-10 CEO：新增姊妹功能 `/exam`——在 `course/<科目>/exam/` 里定位指定文件中的指定题目并解答，解题依据优先引用同科目 slide 课件并标出处。
+
+## 9. (Audit mode only — leave empty in new-feature mode) Code vs spec delta
+```

package/template/docs-harness/README.md

@@ -0,0 +1,42 @@
+# Framework Meta-Docs (`outcome/docs-harness/`)
+
+This directory holds the harness's **own design docs** — not project-feature docs (those live at `{{spec_dir}}`), and not operational rules (those live in `CLAUDE.md` / `AGENTS.md`). The files here explain **why** the harness is designed the way it is, and how to adopt it.
+
+## What's in here
+
+| File | Purpose | When to read |
+|------|---------|--------------|
+| `design-spec.md` | Architectural rationale — the WHY behind the operating model, cross-model audit, two-file spec, lanes, etc. | Onboarding; before extending the harness |
+| `adoption-playbook.md` | Step-by-step guide for installing the harness in a new or existing project | When `/init` is too narrow and you want the full playbook |
+| `retrospective-notes.md` | Generalized lessons from real-world use (LLM-workflow patterns, sweep methodology, when to delete vs fix) | Periodically; before non-trivial feature work |
+| `context-architecture-v2.md` | 3-tier memory layout (working / recall / archival), AI calling rules, snapshot schema, trigger surfaces | Before touching `memory-*.sh`, `scratchpad-*.sh`, `/handoff`, `/recall`, or `/offload` |
+
+## What was removed from the original
+
+The original harness shipped 5 files in this directory totaling 3382 lines. Two were **deleted entirely** in the generic harness:
+
+- **`current-state.md` (1113 lines)** — A snapshot of the *original* project's harness state at one point in time. Becomes obsolete the moment the harness moves forward. For the generic harness, current state is read from the code, not from a doc that drifts. Use `/audit-spec` to produce a fresh as-built reading whenever needed.
+
+- **`double-check.md` (98 lines)** — A checklist of project-specific pitfalls. 95% duplicated content already in `design-spec.md § Scenario classification` and similar sections, and the remaining 5% was tightly coupled to one project's file paths.
+
+The other three files were **kept and generalized** — project-specific examples replaced with abstract pattern descriptions, project terminology replaced with the harness's standard vocabulary, and Korean shorthand translated to English to match the rest of the harness.
+
+## Reading order
+
+If you're new to the harness:
+
+1. **Constitution** (`outcome/constitution.md`) — read first; the universal-core invariants and project identity.
+2. **CLAUDE.md** (`outcome/CLAUDE.md`) — the operating manual for day-to-day work.
+3. **`design-spec.md`** (this directory) — the architectural rationale behind both files above.
+4. **`adoption-playbook.md`** — when ready to install the harness in a project.
+5. **`retrospective-notes.md`** — once you've shipped your first feature through the harness.
+
+If you're extending the harness:
+
+1. **`design-spec.md`** — to understand the load-bearing invariants you can't break.
+2. **`outcome/agents/README.md`** — for the plugin pattern.
+3. **`outcome/skills/<skill>/SKILL.md`** — for examples of how a skill is shaped.
+
+## Why this directory exists at all
+
+The harness's design has nontrivial structure (CEO/manager domain split, cross-model audit invariant, scenario-ID-to-test mapping, lane classification, etc.). Without a single document explaining the **why**, the structure looks arbitrary — and a contributor (human or AI) who doesn't understand the rationale will rationalize past invariants that exist for non-obvious reasons. `design-spec.md` is that document.