@@ -123,11 +123,17 @@ deferred promotions are recurrence-gated — see [panel backlog](plans/multi-age
 - Evidence: [plans/pstack-survey-2026-09-22.md](plans/pstack-survey-2026-09-22.md) (full arm×scenario matrix, 10 fresh-agent runs on wsgiLite.js; second product fpGo — 3 arms, unlabeled seeded bug caught, spec-oracle error classified; library products: the test suite is the oracle, the map routes features → `-run` regexes and captures environment quirks)
 - Review trigger: fired twice — fpGo (second product) and fpEs/fpRust (third/fourth, repeated demand) adopted and confirmed the pattern across curl, `go test`, mocha, and cargo surfaces. Promoted to domain-pack skill `verification-map-generator` (registered 2026-09-23). Next trigger: a run showing the four-way classification misrouting repairs, or a product shape the recipe cannot cover (no executable check surface).
 
+### Lesson: Handover documentation separates contract from implementation and writes pitfalls as guards
+- Pattern: the `~/dev/handover-docs/` kit (surveyed 2026-09-23) codifies five documentation contracts that transfer to TeaPrompt records: (1) every doc splits **contract layer** (semantics a rebuild must preserve — business rules, 口徑, invariants) from **implementation layer** (disposable current practice); (2) snapshot docs carry a date and point to where live truth lives; (3) every decision cites provenance — never "據說"; (4) pitfalls are written as **guards** (code checks, fail-loud validators) cross-referenced from docs — 「無停止力的警告等於不存在」, a warning without stopping power doesn't exist; (5) acceptance is numbers ("these queries return these values"), never "looks right". Incident records separate symptom from root cause ("why the design allowed it"), treat detection delay as a signal, and name the defense layer by file:test — a doc-only defense is flagged as insufficient.
+- Evidence: [plans/handover-docs-survey-2026-09-23.md](plans/handover-docs-survey-2026-09-23.md) (all 15 kit files read; nine concepts mapped; five adopted here)
+- Review trigger: a TeaPrompt doc that violates a principle — an undated snapshot, a warning-only pitfall, an acceptance criterion that isn't a verifiable value; or a project that needs the full nine-volume handbook structure.
+
 ## Decision Index
 
 > Pointers to the causal trail — plans, reflections, tests, commits. Detail is
 > not duplicated here; this is a map, not an archive. Mechanical panel rounds
 > are rolled up; the round-by-round trail lives in the panel record.
+- 2026-09-23 handover-docs methodology survey — user direction "Learn from @~/dev/handover-docs/ … record non-sensitive into docs or skills if worth it"; local kit (15 template files, no sensitive values); five documentation-contract principles adopted as durable lesson; no skill installed → [record](plans/handover-docs-survey-2026-09-23.md)
 - 2026-09-23 fpGo second-product verification — user direction "do experiments on @~/dev/fpGo/"; VERIFY.md + features/ + locked-spec pattern applied to a Go library (control surface = `go test -mod=mod` + scratch drivers; stale vendor/ documented as environment quirk). Three fresh-agent arms: baseline 1013/1013 in 1m42s; unlabeled seeded `Distinct` bug → product regression; wrong spec → spec-oracle error. Committed to fpGo `generics` branch `1f20bc4` (local, not pushed) → [record](plans/pstack-survey-2026-09-22.md#second-product-fpgo-2026-09-23)
 - 2026-09-23 fpEs + fpRust third/fourth-product verification — user direction "you can do in these repos: @~/dev/fpEs @~/dev/fpRust/"; pattern replicated on mocha (528 tests) and cargo (144 tests) surfaces; unlabeled seeded bugs → product regression; wrong specs → spec-oracle error; agents caught doc drift in the generator's own VERIFY.md. Recurrence gate satisfied → domain-pack skill `verification-map-generator` registered → [record](plans/pstack-survey-2026-09-22.md#third-and-fourth-products-fpes--fprust-2026-09-23)
 
 
@@ -1,6 +1,6 @@
 {
   "version": "1.0",
-  "generated_at": "2026-09-23T10:46:03.819472",
+  "generated_at": "2026-09-23T11:48:11.778645",
   "repo_root": ".",
   "categories": {
     "prompt-library": {
@@ -53,6 +53,7 @@
             "agent-governance-scaffold-field-use-panel-2026-07-17.md",
             "routing-holdout-plan-2026-07-11.md",
             "astra-efficiency-rules-survey-2026-09-10.md",
+            "handover-docs-survey-2026-09-23.md",
             "vllm-micro-agent-technical-brief-2026-06-30.md",
             "hotline-verification-redundancy-survey-2026-09-22.md",
             "knowie-project-knowledge-reflection-2026-06-17.md",
@@ -2733,6 +2734,64 @@
       "line_count": 128,
       "char_count": 34381
     },
+    {
+      "path": "reflective-prompt-library/plans/handover-docs-survey-2026-09-23.md",
+      "type": "prompt",
+      "category": "prompt-library",
+      "subcategory": "plans",
+      "name": "handover-docs-survey-2026-09-23",
+      "description": "",
+      "frontmatter": {},
+      "dependencies": {
+        "ref_file": [],
+        "ref_snippet": [],
+        "markdown_links": []
+      },
+      "structure": [
+        {
+          "level": 1,
+          "text": "Handover-Docs Methodology Survey — 2026-09-23"
+        },
+        {
+          "level": 2,
+          "text": "Research Question"
+        },
+        {
+          "level": 2,
+          "text": "Direct Recommendation (as of 2026-09-23)"
+        },
+        {
+          "level": 2,
+          "text": "Method"
+        },
+        {
+          "level": 2,
+          "text": "Concept Map"
+        },
+        {
+          "level": 2,
+          "text": "Candidate Adoption Ledger"
+        },
+        {
+          "level": 2,
+          "text": "Evidence vs Inference"
+        },
+        {
+          "level": 2,
+          "text": "Evidence Actually Checked"
+        },
+        {
+          "level": 2,
+          "text": "Falsifiability"
+        },
+        {
+          "level": 2,
+          "text": "Completion Ledger"
+        }
+      ],
+      "line_count": 73,
+      "char_count": 7455
+    },
     {
       "path": "reflective-prompt-library/plans/vllm-micro-agent-technical-brief-2026-06-30.md",
       "type": "prompt",
@@ -15547,5 +15606,5 @@
       "char_count": 19884
     }
   ],
-  "total_files": 173
+  "total_files": 174
 }
@@ -0,0 +1,73 @@
+# Handover-Docs Methodology Survey — 2026-09-23
+
+> **Status: decided — record-only; one durable lesson adopted into PROJECT_KNOWLEDGE.md, no skill or wording installed.** The object is `~/dev/handover-docs/` — a local, reusable **project handover documentation kit** (15 markdown files: README methodology, 9-volume handbook, ops SOPs, templates, glossary) written in Traditional Chinese. Its goal: a successor engineer with **no oral handover and no live support from the original team** can understand the system, operate it safely, and rebuild from zero using only repo docs. All content is templates and placeholders — no credentials, hosts, or real values exist in the kit; nothing sensitive was recorded. Guard: `plans/tests/test_handover_docs_survey_record.py`.
+
+## Research Question
+
+User instruction: "Learn from @~/dev/handover-docs/ and beware about sensitive keywords (avoid recording them). Learn key knowledge from them" — then "record non-sensitive into docs or skills if worth it". Questions: (1) what the kit teaches that generalizes; (2) whether any pattern exposes a gap on an installed TeaPrompt surface; (3) what is worth recording and where.
+
+## Direct Recommendation (as of 2026-09-23)
+
+- **Adopt — one durable lesson into PROJECT_KNOWLEDGE.md.** The kit's five design principles are documentation-engineering contracts that transfer directly to how TeaPrompt writes and reviews records: contract-layer vs implementation-layer separation, snapshot dating with live-truth pointers, decision provenance, pitfalls-as-guards, plain-text artifacts.
+- **No new skill.** The kit is a *documentation structure*, not an executable workflow; TeaPrompt's `reflective-handoff-retro` already owns session-transfer, and the kit's task-card/agent-memory formats overlap with existing memory conventions. A skill would duplicate structure without a named local failure.
+- **Candidate for later:** if TeaPrompt ever produces handover docs for a product repo, the kit's nine-volume handbook order (01 business → 02 architecture → 03 data → 04 pipelines → 05 ops → 09 tests → 06 decisions → 07 state → 08 rebuild) is the proven sequence.
+
+## Method
+
+Coordinator read all 15 files in full (2026-09-23): `README.md`, `glossary.md`, `handbook/01-09`, `ops/secrets-management.md`, `ops/offsite-backup.md`, `templates/{task-card,incident-entry,agent-memory}.md`. No scouts, no panel. Sensitive-keyword audit: every file is template/placeholder text; no real values present.
+
+## Concept Map
+
+| ID | Concept | TeaPrompt coverage | Disposition |
+| --- | --- | --- | --- |
+| HD-1 | Contract-layer vs implementation-layer separation — every doc marks what a rebuild must preserve vs what can be dropped | `reflective-spec-plan` spec-vs-impl; verification-map `source_commit`/`last_verified_at` metadata | Adopted into PK lesson |
+| HD-2 | Snapshot docs carry 快照日期 + pointer to live truth (task-card `status:`) | PK lessons carry review triggers; Decision Index is the live pointer | Adopted into PK lesson |
+| HD-3 | Pitfalls written as guards, not warnings — 「無停止力的警告等於不存在」; silent failures get code guards cross-referenced from docs | `reflective-implement` Verification; ROUTE gates made failable 2026-09-23 (same principle) | Adopted into PK lesson |
+| HD-4 | Incident record: symptom ≠ root cause; root cause = "why the design allowed it"; detection delay is signal; 防護落點 names file:test | `06-repo/AGENTS.md` falsifiability; record-hygiene validator | Adopted into PK lesson |
+| HD-5 | Task cards: plain markdown, `status:` is live truth, `depends_on` graph, blocked names the specific external input, comments carry decision context | `plans/` records + Decision Index; no card system installed | No change — overlaps existing convention |
+| HD-6 | Acceptance as numbers — rebuild phases verify "these queries return these values", never "looks right"; un-rebuildable provenance declared | Verification-map acceptance.yaml; record-hygiene falsifiability | Adopted into PK lesson |
+| HD-7 | Secrets docs write location+procedure, never values; mount dirs not files (inode pinning); dual-source mismatch fails loud | Out of scope — TeaPrompt holds no secrets | No change (out of scope) |
+| HD-8 | Test-safety doc: danger declaration first, guard + bypass documented, disposable/live layering, test-data pollution policy | `09-running-tests.md` pattern; TeaPrompt tests are doc-only, no live env | No change — no live surface |
+| HD-9 | Agent-memory format: feedback/project/reference triage; write-in triggers; don't duplicate handbook knowledge | Mnemopi memory + `learn`/`retain` already serve this | No change — installed equivalent exists |
+
+## Candidate Adoption Ledger
+
+| ID | Candidate | Status | Evidence | Reopen trigger |
+| --- | --- | --- | --- | --- |
+| HD-1..4,6 | Five documentation-contract principles | Adopted — PK durable lesson | This record; PK lesson entry | A TeaPrompt doc that violates a principle (e.g. a warning-only pitfall, an undated snapshot) |
+| HD-5 | Task-card system | No change | `plans/` + Decision Index already provide provenance + live status | A project needing per-task cards outside the plans/ convention |
+| HD-7 | Secrets-management SOP | No change (out of scope) | TeaPrompt holds no credentials | TeaPrompt gains a secret-bearing surface |
+| HD-8 | Test-safety doc pattern | No change | No live-environment test surface exists | A test suite that can touch a live system |
+| HD-9 | Agent-memory format | No change | Mnemopi `retain`/`learn` + managed skills cover it | A gap in current memory conventions |
+
+## Evidence vs Inference
+
+| Claim | Status | Basis |
+| --- | --- | --- |
+| Kit structure and all quoted principles | Observed | All 15 files read in full, 2026-09-23 |
+| No sensitive values present | Observed | Every file is template/placeholder text |
+| HD-3 matches TeaPrompt's failable-gates principle | Observed | ROUTE gate fix commit 6b31ab1 same day |
+| The nine-volume order is "proven" | `[INFERENCE]` | README asserts it; no external validation of the ordering claim |
+| Kit's target audience is a no-oral-handover successor | Observed | README line 3–5 |
+
+## Evidence Actually Checked
+
+- `~/dev/handover-docs/` — all 15 files read in full, 2026-09-23.
+- TeaPrompt installed surfaces checked for overlap: `reflective-handoff-retro`, `reflective-spec-plan`, `reflective-implement` Verification, `validate_record_hygiene.py`, `PROJECT_KNOWLEDGE.md` lesson format.
+- Not done: no external validation of the methodology against a real handover; the kit is self-described.
+
+## Falsifiability
+
+- Wrong about "no sensitive values" if any file contains a real credential/host — all files read; all fields are placeholders.
+- Wrong about HD-5 overlap if `plans/` records lack live-status or provenance — both are enforced by `validate_record_hygiene.py` and the Decision Index.
+- The PK lesson is wrong if its principles contradict an installed contract — all five are consistent with existing verification/record conventions.
+
+## Completion Ledger
+
+| Item | Status | Evidence |
+| --- | --- | --- |
+| Kit read in full; sensitive-keyword audit clean | done | Method; Evidence vs Inference |
+| Nine concepts mapped; five adopted into PK lesson | done | Concept Map; Candidate Adoption Ledger |
+| PK durable lesson written | done | `PROJECT_KNOWLEDGE.md` |
+| Guard written | done | `plans/tests/test_handover_docs_survey_record.py` |
+| Full repository gate | done | `make all` from the repository root |
@@ -0,0 +1,56 @@
+"""Guard the handover-docs survey record (2026-09-23) at its surfaces."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+from prompt_eval_helpers import PROMPT_LIBRARY_ROOT  # noqa: E402
+
+PLANS = PROMPT_LIBRARY_ROOT / "plans"
+RECORD = PLANS / "handover-docs-survey-2026-09-23.md"
+PK = PROMPT_LIBRARY_ROOT / "PROJECT_KNOWLEDGE.md"
+
+# Decision content the record must keep — the five adopted principles and the
+# sensitive-keyword audit result.
+REQUIRED = (
+    "contract-layer vs implementation-layer",
+    "快照日期",
+    "無停止力的警告等於不存在",
+    "no credentials, hosts, or real values",
+    "Candidate Adoption Ledger",
+    "Falsifiability",
+    "HD-1",
+    "HD-9",
+)
+
+
+def _read(path: Path) -> str:
+    assert path.is_file(), f"missing {path}"
+    return path.read_text(encoding="utf-8")
+
+
+def test_record_exists_with_required_content():
+    text = _read(RECORD)
+    for needle in REQUIRED:
+        assert needle in text, f"record lost {needle!r}"
+
+
+def test_record_status_is_record_only():
+    text = _read(RECORD)
+    assert "**Status: decided — record-only" in text
+
+
+def test_pk_lesson_exists_and_references_record():
+    pk = _read(PK)
+    assert "Handover documentation separates contract from implementation" in pk
+    assert "handover-docs-survey-2026-09-23.md" in pk
+    assert "Review trigger" in pk
+
+
+def test_no_sensitive_values_in_record():
+    # The kit is all placeholders; the record must not invent or embed any
+    # credential-shaped content.
+    text = _read(RECORD).lower()
+    for forbidden in ("password", "secret_key", "api_key=", "bearer ", "-----begin"):
+        assert forbidden not in text, f"record contains sensitive-shaped token {forbidden!r}"