photon-skills 3.0.3.dev17__tar.gz → 3.0.4.dev0__tar.gz

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/CHANGELOG.md

@@ -6,6 +6,8 @@ The project follows a pragmatic release-note style rather than claiming strict s
 
 ## [Unreleased]
 
+## [3.0.3] - 2026-10-30
+
 ### Added
 
 - **`doctor`, `repair`, `feedback export` (P3).** `doctor` checks the bundled
@@ -19,6 +21,18 @@ The project follows a pragmatic release-note style rather than claiming strict s
   limits: `docs/design/self-repair.md`; `photon-orchestrator` now points at the
   three commands when a skill misfires.
 
+### Changed
+
+- **`doctor` explains drift instead of calling everything an edit.** A copy that
+  differs from the bundle now reports `N changed / N extra / N missing` with an
+  example path, so a template a student added reads as `1 extra` rather than as
+  an edited skill. `repair` also drops profiles from the install state whose home
+  is gone, which used to raise a permanent harmless warning.
+- **`photon-debate-coach` ships an evidence sheet** (`templates/evidence-sheet.md`);
+  Stage A now produces `debate-prep/evidence-sheet.md` when a case rests on
+  numbers — original source, quotable line, denominator, what the evidence does
+  *not* prove, and a 待核查 column that never goes on stage.
+
 ### Documentation
 
 - **README rewritten as a plugin-first guide** (zh + en): the two real install

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: photon-skills
-Version: 3.0.3.dev17
+Version: 3.0.4.dev0
 Summary: Photon — STEAM research, debate, and pitch competition companion for primary/secondary students
 Author-email: Uniterra Solutions Limited <harryw07801@uniterra-solutions.com>
 License-Expression: MIT

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/docs/design/self-repair.md

@@ -39,7 +39,7 @@ state file. `feedback export` only writes the output directory you give it.
 | `bundled skills` | the plugin dir has skills, and each has `SKILL.md` | error |
 | `profile` | the active profile's home exists | error |
 | `skills dir` | `<profile>/skills` exists | error |
-| `skill sync` | bundled skill missing / edited locally / untracked by the manifest / all in sync | error / warn / ok |
+| `skill sync` | bundled skill missing; a copy that differs from the bundle (per-file `N changed / N extra / N missing`, with an example path); untracked by the manifest; all in sync | error / warn / ok |
 | `manifest` | stale entries pointing at removed skills | warn |
 | `manifest version` | manifest records an older plugin version | warn |
 | `extension` | installed payload missing, payload hash changed, extension skills missing; or none installed | warn / ok |
@@ -52,7 +52,8 @@ state file. `feedback export` only writes the output directory you give it.
 
 Local edits are detected by comparing the copy with the **bundle**, not with the
 last recorded hash: adopting an edit as the new baseline (which `sync` does) must
-not make the divergence invisible.
+not make the divergence invisible. The comparison is per file, so an added
+template reads as `1 extra`, not as an edit of the whole skill.
 
 ## What `repair` does
 
@@ -60,6 +61,9 @@ not make the divergence invisible.
 |---|---|---|
 | bundled skill missing | copy it from the bundle, record its hash | same |
 | skill edited locally | keep the edit, update the baseline hash | restore the bundled copy (destructive) |
+| extra file added to a skill copy | keep it | delete it (the copy is restored from the bundle) |
+| file deleted from a skill copy | restored on the next `setup`; `repair` reports it | restored from the bundle |
+| state lists a profile that is not on disk | drop it from the state | same |
 | skill present but untracked | adopt it only when byte-identical to the bundle | same |
 | stale manifest entry (skill no longer bundled) | drop the entry | same |
 | stale `skillset` key in state | drop it | same |

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "photon-skills"
-version = "3.0.3.dev17"
+version = "3.0.4.dev0"
 description = "Photon — STEAM research, debate, and pitch competition companion for primary/secondary students"
 authors = [
     { name = "Uniterra Solutions Limited", email = "harryw07801@uniterra-solutions.com" },

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/src/photon/health.py

@@ -21,6 +21,7 @@ talks to the network, and never deletes a student's project data.
 from __future__ import annotations
 
 import difflib
+import hashlib
 import json
 import shutil
 import subprocess
@@ -67,13 +68,29 @@ def _hash(path: Path) -> str:
 
 
 def _file_sha(path: Path) -> str:
-    import hashlib
-
     digest = hashlib.sha256()
     digest.update(path.read_bytes())
     return digest.hexdigest()
 
 
+def _tree_files(root: Path) -> dict[str, str]:
+    """Relative path → sha256 for every file under ``root``."""
+    out: dict[str, str] = {}
+    for path in root.rglob("*"):
+        if path.is_file():
+            out[path.relative_to(root).as_posix()] = _file_sha(path)
+    return out
+
+
+def _tree_diff(bundle: Path, installed: Path) -> tuple[list[str], list[str], list[str]]:
+    """``(added, removed, changed)`` relative paths, comparing copy to bundle."""
+    a, b = _tree_files(bundle), _tree_files(installed)
+    added = sorted(set(b) - set(a))
+    removed = sorted(set(a) - set(b))
+    changed = sorted(k for k in set(a) & set(b) if a[k] != b[k])
+    return added, removed, changed
+
+
 def _bundled(skills_dir: Path) -> dict[str, Path]:
     return {d.name: d for d in bundled_skill_dirs(skills_dir)}
 
@@ -135,19 +152,32 @@ def run_doctor(
                 f"{len(missing)} bundled skill(s) missing: {', '.join(sorted(missing))}",
                 f"hermes {PLUGIN_NAME} repair",
             )
-        modified = [
-            n
-            for n in bundled
-            if (profile_skills / n).exists()
-            and _hash(profile_skills / n) != _hash(bundled[n])
-        ]
-        if modified:
+        drift: dict[str, tuple[list[str], list[str], list[str]]] = {}
+        for name in bundled:
+            target = profile_skills / name
+            if not target.exists():
+                continue
+            added, removed, changed = _tree_diff(bundled[name], target)
+            if added or removed or changed:
+                drift[name] = (added, removed, changed)
+        if drift:
+            parts: list[str] = []
+            for name, (added, removed, changed) in sorted(drift.items()):
+                counts: list[str] = []
+                if changed:
+                    counts.append(f"{len(changed)} changed")
+                if added:
+                    counts.append(f"{len(added)} extra")
+                if removed:
+                    counts.append(f"{len(removed)} missing")
+                sample = (changed or added or removed)[0]
+                parts.append(f"{name} ({', '.join(counts)}; e.g. {sample})")
             add(
                 "skill sync",
                 "warn",
-                f"{len(modified)} skill(s) edited locally — upstream updates skip them: "
-                + ", ".join(sorted(modified)),
-                f"hermes {PLUGIN_NAME} repair --force (destructive: restores the bundled copy)",
+                f"{len(drift)} skill(s) differ from the shipped copy: " + "; ".join(parts),
+                f"hermes {PLUGIN_NAME} repair --force "
+                "(restores the shipped copy; extra files are deleted)",
             )
         untracked = [
             n for n in bundled if (profile_skills / n).exists() and n not in recorded
@@ -171,7 +201,7 @@ def run_doctor(
                 + ", ".join(sorted(orphans)),
                 f"hermes {PLUGIN_NAME} repair",
             )
-        if not missing and not modified and not untracked and not orphans:
+        if not missing and not drift and not untracked and not orphans:
             add("skill sync", "ok", f"{len(bundled)} skill(s) in sync with the bundle")
 
     if manifest.get("version") and manifest["version"] != version:
@@ -401,6 +431,15 @@ def run_repair(
         state.pop("skillset", None)
         actions.append("removed the stale 'skillset' key from the install state")
 
+    profiles_state = state.get("profiles")
+    if isinstance(profiles_state, dict):
+        for name in sorted(profiles_state):
+            if not _profile_dir(hermes_home, name).exists():
+                profiles_state.pop(name, None)
+                actions.append(
+                    f"dropped profile '{name}' from the install state (not on disk)"
+                )
+
     return {"profile": profile_name, "actions": actions}
 
 

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/src/photon/plugin.yaml

@@ -1,5 +1,5 @@
 name: photon-skills
-version: 3.0.3.dev17
+version: 3.0.4.dev0
 description: >-
   Photon — STEAM project companion for students: research workflow, debate and
   symposium coaching, pitch preparation, and a git-backed project workspace.

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/src/photon/skills/photon-debate-coach/SKILL.md

@@ -65,9 +65,12 @@ metadata:
 4. **預期反對 2-3 個**:每個附一條回應線,並標明它攻擊的是對方哪個假設。
 5. **講稿/大綱**:用學生自己的稿來拋光——口語化、句子短、一段一個重點。
    不要換掉學生的語氣,不要代寫成「AI 腔」。
+6. **證據表(需要引用具體數字/法規時)**:每條證據寫清「原始出處、可引原句、
+   分母、它不證明什麼」,未核實的放進「待核查」欄,不准上台講。用
+   `templates/evidence-sheet.md`。
 
 產出:`debate-prep/motion-brief.md`、`debate-prep/case-map.md`、`debate-prep/outline.md`
-(用 `templates/` 的範本)。
+(用 `templates/` 的範本);有具體數據時另加 `debate-prep/evidence-sheet.md`。
 
 ### Stage B — 對方發言後 / After an opposing speech (或研討會現場提問後)
 
@@ -167,6 +170,7 @@ metadata:
 - `references/format-presets.md` — 已核實的香港/國際賽制 preset(附來源連結與
   `待核查` 標記);實作與回答賽制問題前先讀這一份。
 - `templates/motion-brief.md`、`templates/case-map.md`、`templates/rebuttal-cards.md`、
-  `templates/outline.md`、`templates/post-match.md`、`templates/format.md`
+  `templates/outline.md`、`templates/post-match.md`、`templates/format.md`、
+  `templates/evidence-sheet.md`
   — `debate-prep/` 的檔案範本。
 - `docs/design/debate-coach.md`(repo)— 設計決策與已核實賽制資料。

photon_skills-3.0.4.dev0/src/photon/skills/photon-debate-coach/templates/evidence-sheet.md

@@ -0,0 +1,73 @@
+# Evidence Sheet — 證據表
+
+> 範本。複製到 `debate-prep/evidence-sheet.md` 再填。
+> 上限:______ 條(照賽制/課程要求;寧願少而實,唔好為湊數加未核實的來源)。
+> 每條都要能在 **30 秒內**回答 source challenge。
+
+## 一條好證據的四個條件
+
+1. **原始出處**:法規、監管機構、專業學會、同儕評審期刊、官方統計。二手轉述不算。
+2. **引得出原句**:你講得出「它確實寫了這一句」,而不是「我記得好像有」。
+3. **知分母**:比率講清「per 咩」;人數講清「邊個人口」。
+4. **知它不證明什麼**:寫在「不要說」一欄——這一欄比正文更防失分。
+
+---
+
+## 索引
+
+| # | 一句話事實 | 出處 | 支撐 | 狀態 |
+|---|-----------|------|------|------|
+| E1 | | | | ✅ / ⚠️ |
+| E2 | | | | |
+| E3 | | | | |
+
+---
+
+## 每條的格式(逐條重複)
+
+### E__ · 短標題
+
+**Speakable claim(一句話,講得出):**
+> ...
+
+**精確內容(數字 + 分母 + 範圍):**
+- ...
+
+**出處:**
+- 作者/機構、年份、標題、URL
+- 查閱日期:YYYY-MM-DD
+
+**狀態:** ✅ 已核實(讀過原始出處)/ ⚠️ 待核查(唔可以當證據)/ 🧪 假設例子(要明講)
+
+**用在哪裏:** 哪個論點、哪一段發言
+
+**30 秒 source challenge 防守:**
+> "That's [機構], [年份], [文件名]. It says [exact claim]. Note the denominator: [ ]."
+
+**不要說:** 常見誇大或錯誤講法(寫出來,提醒自己)
+
+---
+
+## 論點 ↔ 證據對應
+
+| 論點 | 主要證據 | 備用 |
+|------|----------|------|
+| A1 | | |
+| A2 | | |
+| A3 | | |
+
+---
+
+## ⚠️ 待核查 — 唔好上台講
+
+| 講法 | 問題 |
+|------|------|
+| | |
+
+> 這一欄要當成護欄:未核實的數字寫進正文,比賽時一定會被追問。
+
+---
+
+## 備用來源(唔計入上限)
+
+- 只用於開場講 stakes、或回答提問;同樣要標狀態。

{photon_skills-3.0.3.dev17 → photon_skills-3.0.4.dev0}/tests/test_health.py

@@ -86,7 +86,10 @@ def test_edited_skill_is_kept_unless_forced(install):
     target.write_text("---\nname: photon-alpha\n---\n\nlocal edit\n", encoding="utf-8")
 
     findings = doctor(install)
-    assert any("edited locally" in f.message for f in findings)
+    assert any(
+        "differ from the shipped copy" in f.message and "1 changed" in f.message
+        for f in findings
+    )
 
     repair(install)
     assert "local edit" in target.read_text(encoding="utf-8")
@@ -167,6 +170,38 @@ def test_feedback_export_writes_diff_and_evidence(install, tmp_path):
     assert manifest["changed_skills"] == ["photon-alpha"]
 
 
+def test_extra_and_missing_files_are_reported(install):
+    home, _plugin_dir, _skills = install
+    skill = home / "skills" / "photon-alpha"
+    (skill / "extra.md").write_text("local only\n", encoding="utf-8")
+    (skill / "SKILL.md").unlink()
+
+    findings = doctor(install)
+    warn = next(f for f in findings if f.check == "skill sync" and f.status == "warn")
+    assert "1 extra" in warn.message
+    assert "1 missing" in warn.message
+    assert "extra.md" in warn.message
+
+    repair(install)
+    assert (skill / "extra.md").exists()
+
+    repair(install, force=True)
+    assert not (skill / "extra.md").exists()
+    assert (skill / "SKILL.md").exists()
+
+
+def test_repair_prunes_missing_profiles(install):
+    home, _plugin_dir, _skills = install
+    state = {"profiles": {"default": {}, "ghost": {}}}
+
+    findings = doctor(install, state=state)
+    assert any("ghost" in f.message for f in findings)
+
+    repair(install, state=state)
+    assert "ghost" not in state["profiles"]
+    assert "default" in state["profiles"]
+
+
 def test_cli_exposes_health_commands():
     parser = argparse.ArgumentParser()
     subs = parser.add_subparsers(dest="cmd")