hermes-task-framework 1.0.0__py3-none-any.whl

task-framework/skills/task-framework/templates/run.py

@@ -0,0 +1,187 @@
+#!/usr/bin/env python3
+"""
+Unified task runner — single entry point for all phases.
+
+Usage:
+    ./run.py                    — auto: find first unchecked item & execute
+    ./run.py phase<N>           — run specific phase
+    ./run.py list               — show checklist status
+
+Auto mode (no args):
+    1. Read TASK.md checklist, find first unchecked item
+    2. If it's a BREAK, mark it done, continue to next Phase(s)
+    3. Execute Phase(s) until next BREAK or end of list
+"""
+
+import sys, os, subprocess, re
+
+TASK_DIR = os.path.dirname(os.path.abspath(__file__))
+TASK_MD = os.path.join(TASK_DIR, "TASK.md")
+SCRIPTS = os.path.join(TASK_DIR, "scripts")
+VENV_PY = os.path.expanduser("~/.venvs/playwright/bin/python")
+PY = VENV_PY if os.path.exists(VENV_PY) else sys.executable
+
+
+# ── Phase runners ──
+
+def run_script(name, label):
+    path = os.path.join(SCRIPTS, name)
+    if not os.path.exists(path):
+        print(f"  ❌ Script not found: {path}")
+        return False
+    print(f"\n{'='*60}")
+    print(f"  {label}")
+    print(f"{'='*60}")
+    return subprocess.run([PY, path], cwd=TASK_DIR).returncode == 0
+
+
+def phase1():
+    return run_script("gen_tts.py", "Phase 1: Text-to-Speech")
+
+
+def phase2():
+    return run_script("record_timeline.py", "Phase 2: Browser Recording")
+
+
+def phase3():
+    # Example: inline call with generate_timeline_chart
+    cmd = [
+        PY, "-c",
+        "import sys, os; "
+        "sys.path.insert(0, os.path.expanduser('~/.hermes/personal-suite/skills/video-audio-compositing/scripts')); "
+        "from utils.timeline import generate_timeline_chart; "
+        "generate_timeline_chart('COMPOSITING.md', 'timeline-chart-xxxxxx/timeline_chart.txt', format='both')"
+    ]
+    print(f"\n{'='*60}")
+    print(f"  Phase 3: Timeline Chart Preview")
+    print(f"{'='*60}")
+    return subprocess.run(cmd, cwd=TASK_DIR).returncode == 0
+
+
+def phase4():
+    return run_script("composite.py", "Phase 4: Compositing")
+
+
+def phase5():
+    print("  ⏭  Phase 5 not implemented yet — skipping")
+    return True
+
+
+def phase6():
+    print("  ⏭  Phase 6 not implemented yet — skipping")
+    return True
+
+
+def phase7():
+    print("  ⏭  Phase 7 not implemented yet — skipping")
+    return True
+
+
+PHASES = {
+    "phase1": phase1, "phase2": phase2, "phase3": phase3,
+    "phase4": phase4, "phase5": phase5, "phase6": phase6, "phase7": phase7,
+}
+
+
+# ── TASK.md checklist helpers ──
+
+def parse_checklist():
+    with open(TASK_MD) as f:
+        lines = f.readlines()
+    items = []
+    for i, line in enumerate(lines):
+        m = re.match(r'^- \[([ x])\] (.+)', line)
+        if m:
+            items.append((i, m.group(2), m.group(1) == 'x'))
+    return items, lines
+
+
+def mark_done(line_idx, lines):
+    lines[line_idx] = lines[line_idx].replace("- [ ]", "- [x]", 1)
+    with open(TASK_MD, 'w') as f:
+        f.writelines(lines)
+    return lines
+
+
+def find_phase_num(text):
+    m = re.search(r'Phase (\d+)', text)
+    return int(m.group(1)) if m else None
+
+
+def is_break(text):
+    return text.strip().startswith("BREAK")
+
+
+# ── Auto mode ──
+
+def run_auto():
+    items, lines = parse_checklist()
+    unchecked = [(idx, txt) for idx, txt, chk in items if not chk]
+    if not unchecked:
+        print("✅ All checklist items completed!")
+        return True
+
+    idx, txt = unchecked[0]
+    print(f"📋 First unchecked: {txt}")
+
+    if is_break(txt):
+        print(f"  → Marking BREAK complete, continuing...")
+        lines = mark_done(idx, lines)
+        items, lines = parse_checklist()
+        unchecked = [(idx, txt) for idx, txt, chk in items if not chk]
+        if not unchecked:
+            print("✅ All items completed after marking BREAK!")
+            return True
+        idx, txt = unchecked[0]
+        print(f"  → Next: {txt}")
+
+    for idx, txt in unchecked:
+        if is_break(txt):
+            print(f"  ⏸  Stopping at BREAK: {txt}")
+            break
+        pnum = find_phase_num(txt)
+        if pnum is None:
+            print(f"  ⏭  Skipping (not a phase): {txt}")
+            continue
+        phase_key = f"phase{pnum}"
+        fn = PHASES.get(phase_key)
+        if fn is None:
+            print(f"  ❌ No runner for {phase_key}")
+            continue
+        print(f"\n  ▶  Running {phase_key}...")
+        ok = fn()
+        if not ok:
+            print(f"  ❌ {phase_key} failed!")
+            return False
+        lines = mark_done(idx, lines)
+
+    print(f"\n{'='*60}")
+    print(f"  ✅ Auto-run complete")
+    print(f"{'='*60}")
+    return True
+
+
+def cmd_list():
+    items, _ = parse_checklist()
+    for _, txt, chk in items:
+        status = "✅" if chk else "⬜"
+        print(f"  {status} {txt}")
+
+
+def main():
+    if len(sys.argv) >= 2:
+        cmd = sys.argv[1].strip().lower()
+        if cmd == "list":
+            cmd_list()
+            return 0
+        fn = PHASES.get(cmd)
+        if fn:
+            return 0 if fn() else 1
+        print(f"❌ Unknown: {cmd}\n")
+        print(__doc__)
+        return 1
+    return 0 if run_auto() else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

task-framework/skills/task-lifecycle-edge-cases/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: task-lifecycle-edge-cases
+description: "Edge-case operations for task lifecycle — TASK.md recovery after loss, task resurrection from artifacts, conflict resolution when phase directories diverge from checklist."
+version: 1.0.0
+author: Hauzer S. Lee
+license: MIT
+category: software-development
+platforms: [linux, macos]
+metadata:
+  hermes:
+    tags: ['task', 'lifecycle', 'recovery', 'edge-case']
+    related_skills: ['task-framework', 'browser-screen-record-task']
+---
+
+# Task Lifecycle Edge Cases
+
+Recurring edge cases in task lifecycle management that the standard `task-framework` workflow doesn't explicitly cover.
+
+## TASK.md Recovery
+
+When a task directory exists but `TASK.md` is missing (deleted, never created, or corrupted), reconstruct it from surrounding artifacts.
+
+### Step 1: Gather evidence
+
+| Source | What it tells you |
+|--------|------------------|
+| `.hermes-task.json` | hash, name, outputs, dependencies |
+| `TASK_MEMORY.md` | last session's state, what was done, what broke, what's next |
+| `input/REQUIREMENTS.md` | original task spec |
+| `output/` | all generated files |
+| `.hermes-task.json` → `outputs` | what was produced and where |
+| Root index (`tasks/index.md`) | aggregated status from last index run |
+
+### Step 2: Identify task type and load its governing skill
+
+**Critical step.** Do NOT guess phase structure from memory or from other similar tasks.
+
+1. Scan directory for type-signature files — `REQUIREMENTS.md` + `RECORDING.md` + `COMPOSITING.md` → video-production task
+2. Load the relevant skill that defines this task type:
+   - Video production → `browser-screen-record-task`
+   - Document analysis → `task-framework`'s `references/task-types/`
+   - Other → the skill used to create the task (check `.hermes-task.json` or TASK_MEMORY.md)
+3. Read the skill's phase/流程/Checklist structure carefully before writing
+
+### Step 3: Map evidence to skill's phase structure
+
+Cross-reference:
+- Phase directories in `output/` → confirm each matches a skill-defined phase
+- Outputs in `.hermes-task.json` → map each to the right phase's product (note: paths may be `output/...` prefixed for post-migration tasks)
+- TASK_MEMORY.md execution notes → confirm sequence matches skill's defined order
+- Parallel deps → check `和 X 同步进行` annotations match skill's flow table
+
+### Step 4: Write TASK.md
+
+Follow the skill's template for:
+- `## Skills` — list all skills the task type requires
+- `## Data Flow` — map skill's phase table to actual directory hashes
+- `## Checklist` — use skill's standard phase names and dependency annotations
+- Mark all verified-completed items `[x]`
+- Add `## Notes` for task-specific context
+
+Key formatting:
+- Phase dirs use `<short-name>-<hash6>/` (from actual dirs or .hermes-task.json)
+- Checklist `()` uses descriptive phase names only, no hashes
+- `和 Phase X 同步进行` for parallel phases
+- `等待 Phase X 完成` for dependency phases
+
+### Step 5: Verify before marking done
+
+Only mark phases `[x]` if the output artifact exists and can be verified (stat the file). If a phase was in-progress but incomplete, mark `[ ]` and note in `## Notes`.
+
+### Step 6: Update indexes
+
+```bash
+python3 ~/.hermes/skills/software-development/task-framework/scripts/update-index.py
+```
+
+## Pitfalls
+
+- 🔴 **Do NOT infer phase structure from prior conversation** — load the domain skill that governs this task type and use its defined phases
+- 🔴 **Do NOT invent phases that don't match the skill's template** — subtitle-compositing and timeline-chart-preview are NOT separate phases in the standard video-production skill; they are subsumed by composite
+- 🔴 **Do NOT reorder phases from the skill's defined sequence** — the skill encodes the correct dependency graph (e.g., timeline-composer must run after TTS to know audio durations, but before recording)
+- 🔴 **Always verify material existence** — directory existing ≠ phase completed; check for the actual output file
+- 🔴 **BREAK placement** — keep BREAKs exactly where the skill template places them, not where you guess they should be

task-framework/skills/task-lifecycle-edge-cases/references/task-5d5a1a-recovery-example.md

@@ -0,0 +1,67 @@
+# Health Sales Demo (5d5a1a) Recovery
+
+Task: `20260605-233355.health-sales-demo-5d5a1a` — 主动健康销售管理系统演示视频
+
+## How TASK.md was lost (historical)
+
+1. Original TASK.md existed on June 7 with full 76-line checklist
+2. During pipeline bug fixing, exclusion-based cleanup was used (instead of `rm -rf output/`)
+3. TASK.md was accidentally caught in the cleanup
+4. Discovered missing on June 10 — agent noted it was gone but did NOT regenerate
+5. Remained missing until June 11 when user explicitly asked for it
+
+## Recovery process (June 11)
+
+1. Searched filesystem — no TASK.md found in task directory
+2. Read REQUIREMENTS.md → extracted timeline, language, viewport
+3. Read TASK_MEMORY.md (was already a symlink, content preserved) → knew last state (completed)
+4. Listed directory contents → found all phase dirs (tts-6d3e4c, compositing-6d3e4c, etc.)
+5. Read `.hermes-task.json` → outputs mapping confirmed all phases done
+6. Loaded `browser-screen-record-task` skill → got canonical phase decomposition
+7. Compared first draft against skill's template:
+   - Missing Phase 2 (timeline-composer)
+   - Wrong phase order (TTS→record→cover→subtitle instead of parallel)
+   - Extra phases (subtitle-compositing, timeline-chart-preview are subsumed by composite)
+8. Fixed TASK.md to match skill's phase structure, all items marked [x]
+
+## Subsequent migration to symlink + output/ model
+
+After recovery, the task was migrated to the new structure:
+
+```
+tasks/<ts>.<name>-5d5a1a/
+├── TASK.md              →  ~/.hermes/personal/tasks/5d5a1a/task.md
+├── TASK_MEMORY.md       →  ~/.hermes/personal/tasks/5d5a1a/memory.md
+├── .hermes-task.json    →  ~/.hermes/personal/tasks/5d5a1a/meta.json
+├── input/               ← REQUIREMENTS.md + images/
+└── output/              ← all generated files
+```
+
+Migration commands:
+```bash
+# Create per-hash personal dir + symlinks
+python3 manage_task.py init 5d5a1a
+
+# Move user source files to input/
+mkdir -p input && mv REQUIREMENTS.md input/ && mv images/ input/
+
+# Move generated files to output/
+mkdir -p output && mv RECORDING.md COMPOSITING.md IMAGE_SLIDESHOW.md output/
+mv tts-*/ image-slideshow-*/ subtitle-gen-*/ browser-video-recording-*/ output/
+
+# Verify clean worked
+python3 pipeline.py --clean  # only removes output/, leaves input/ + symlinks
+
+# Re-export (now clean, no output/ in archive)
+python3 manage_task.py export 5d5a1a
+# → tar.gz contains: input/ + personal-tasks/5d5a1a/ only
+```
+
+## Lessons
+
+- When you discover TASK.md is missing: regenerate IMMEDIATELY, don't defer
+- Always verify recovered TASK.md against the governing skill's phase template
+- Symlink for TASK.md + .hermes-task.json prevents permanent loss from cleanup
+- Pipeline cleanup MUST use output/ boundary, never exclusion-based deletion
+- For tasks with a hash, `manage_task.py relink <hash>` is the fastest recovery path
+- `manage_task.py init <hash>` creates all three symlinks in one command

task-framework/skills/task-lifecycle-portability/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: task-lifecycle-portability
+description: Task migration, export/import, and symlink-protection model. Covers tar.gz
+  snapshots, double-git repos for metadata + execution history, and manage.py lifecycle
+  commands (export/import/rebuild/relink).
+version: 1.0.0
+category: software-development
+platforms:
+- linux
+- macos
+author: Hauzer S. Lee
+license: MIT
+metadata:
+  hermes:
+    tags:
+    - migration
+    - software-development
+---
+
+
+# Task Lifecycle & Portability
+
+Manages task portability between machines and protects task metadata from destructive cleanup.
+
+## Symlink Protection Model
+
+Three core files in each task directory are symlinks to `~/.hermes/personal/tasks/<hash>/`:
+
+| Symlink (in task dir) | Target | Content |
+|----------------------|--------|---------|
+| `TASK.md` | `task.md` | Checklist, status, goal |
+| `TASK_MEMORY.md` | `memory.md` | Decision log, per-session notes |
+| `.hermes-task.json` | `meta.json` | Hash, outputs, dependencies |
+
+Personal storage layout:
+
+```
+~/.hermes/personal/tasks/<hash>/
+├── .git/                    ← tracks task.md, memory.md, meta.json history
+├── task.md                  ← TASK.md actual content
+├── memory.md                ← TASK_MEMORY.md actual content
+└── meta.json                ← .hermes-task.json actual content
+```
+
+**Protection guarantees:**
+- `rm -rf` entire task dir → symlinks break, actual data in `~/.hermes/personal/tasks/<hash>/` remains
+- Pipeline exclusion-based cleanup can't reach symlinked files
+- `manage.py relink <hash>` restores broken symlinks in seconds
+- Each `<hash>/` has independent git repo for metadata change history
+
+## Cleanup Discipline
+
+**Only `output/` is safe to delete:**
+- `task_reset --hard` = `rm -rf output/` + reset checkbox
+- Never use exclusion-based deletion (`find . -not -name 'X' -delete` or positive-listing `rm -rf tts-*/ RECORDING.md ...`) — these always miss something or catch too much
+- All generated files (RECORDING.md, COMPOSITING.md, IMAGE_SLIDESHOW.md, SUBTITLE_SPEC.md, phase directories, logs) live in `output/`
+
+## Directory Boundary
+
+```
+tasks/<ts>.<name>-<hash6>/
+├── TASK.md              (symlink)
+├── TASK_MEMORY.md       (symlink)
+├── .hermes-task.json    (symlink)
+├── input/               ← SOURCE: user-provided, NEVER delete
+└── output/              ← GENERATED: pipeline owns this, safe to rm -rf
+```
+
+## Export / Import / Rebuild
+
+`manage.py <hash>` commands:
+
+| Command | What it does |
+|---------|-------------|
+| `export <hash>` | Follow symlinks, resolve to real content, produce `tasks/<ts>.<name>-<hash>.tar.gz` (excludes `output/`, includes `input/` + symlink targets + both `.git/` dirs) |
+| `import <tar.gz>` | Extract to `tasks/` directory, create `~/.hermes/personal/tasks/<hash>/` if needed, restore all symlinks |
+| `rebuild <hash>` | Find latest `<hash>.tar.gz` in `tasks/`, extract, restore symlinks. Generates semantic directory name from TASK.md title |
+| `relink <hash>` | Recreate broken symlinks for an existing task directory (no tarball needed) |
+
+**Actual script path:**
+`~/.hermes/skills/software-development/task-framework/scripts/manage_task.py`
+
+Usage: `python3 <path> <command> <arg>`
+
+**Export behavior:**
+- `tar --dereference` — follows symlinks, archive contains actual content, not symlink paths
+- Output dir is excluded (it's regenerable via pipeline)
+- Both git repos (`tasks/<dir>/.git/` and `~/.hermes/personal/tasks/<hash>/.git/`) are preserved in the tarball
+- Import restores both git histories independently
+
+**Cross-machine strategy:**
+- No automatic merge — each machine's copy is an independent task
+- To combine work from two machines: create a new task referencing both via `ref:<hash>/...`
+- `tar.gz` in git repo acts as backup even if personal `~/.hermes/personal/tasks/` is not pushed
+
+## Old Tasks (Migration)
+
+- Tasks already in `input/` + `output/` model: add symlinks via `manage.py init`
+- Legacy flat tasks (REQUIREMENTS.md + images/ at root, no input/output): migrate if feasible; abandon if too old
+- When you discover TASK.md is missing: **regenerate immediately from TASK_MEMORY.md + directory artifacts**, do not skip or defer
+
+## TASK.md Recovery (Edge Cases)
+
+See `references/task-recovery-procedure.md` for the full step-by-step TASK.md recovery process when the file is missing or corrupted. Key principles:
+
+1. **Check the symlink target first** — if the hash-based personal backup exists, recovery is instant via `manage_task.py relink <hash>`
+2. **Identify task type** — scan for signature files (REQUIREMENTS.md + RECORDING.md etc.) and load the task-type's governing skill for its defined phase structure
+3. **Map evidence to phases** — cross-reference output directories, `.hermes-task.json` outputs, and TASK_MEMORY.md against the skill's phase templates
+4. **Write TASK.md** following the skill's template — don't invent phases, don't reorder
+
+🔴 Critical: Do NOT guess phase structure from memory. Load the domain skill that governs this task type and use its defined phases. Verify each phase's output file exists before marking complete.
+
+**Real-world example:** `references/task-recovery-5d5a1a-example.md` — step-by-step walkthrough of recovering 5d5a1a's TASK.md after it was lost to exclusion-based cleanup.
+
+## Pipeline Output Model (Design)
+
+See `references/output-model-design.md` for the full 2026-06-11 design rationale. The core decisions:
+
+- **Output isolation**: All generated artifacts in `output/`, user materials in `input/`
+- **Cleanup strategy**: `rm -rf output/` — never exclusion-based deletion
+- **Symlink protection**: Three metadata files symlinked to personal storage `~/.hermes/personal/tasks/<hash>/`
+- **Manage tool**: `manage_task.py` with `init/export/import/rebuild/relink/reindex` commands
+
+**Implementation:** `references/pipeline-output-transition.md` — detailed diff of what changed in pipeline.py to adopt the output/ model.
+
+## Pitfalls
+| `ref:` resolution breaks when hash-only (no directory match) | `.hermes-task.json` outputs should use `ref:hash/output_name` format. Directory must contain the hash in its name for `ref:` glob resolution. |
+| Pipeline writes spec files to task root instead of output/ | All generated specs (RECORDING.md, COMPOSITING.md, IMAGE_SLIDESHOW.md, SUBTITLE_SPEC.md) belong in `output/`. Update pipeline scripts if they write to root. |

task-framework/skills/task-lifecycle-portability/references/design-session-20260611.md

@@ -0,0 +1,32 @@
+# Session Design Notes: Task Portability
+
+From a session with Hauzer on 2026-06-11 discussing TASK.md loss and recovery architecture.
+
+## Problem
+
+Pipeline exclusion-based deletion (`rm -rf tts-*/ RECORDING.md ...` or `find . -not -name 'REQUIREMENTS.md' -delete`) destroyed TASK.md because it was a regular file in the task root. User observed: "你那次是排除式删除，把除了 REQUIREMENTS.md 之外的很多有用的文件都删光了."
+
+## Solution Architecture (agreed design)
+
+Three-layer protection:
+
+1. **Directory isolation** — input/ (source) + output/ (generated) boundary. Pipeline only touches output/. Never exclusion-based deletion at task root.
+
+2. **Symlink protection** — TASK.md, TASK_MEMORY.md, .hermes-task.json all symlink to `~/.hermes/personal/tasks/<hash>/`. rm -rf task dir only breaks symlinks; actual content survives.
+
+3. **Tar.gz portability** — `manage.py export` creates self-contained snapshot with resolved content (no symlinks in archive), both git repos preserved. `import` restores symlinks on target machine.
+
+## Key Decisions
+
+- output/ excluded from tar.gz (regenerable)
+- tar.gz committed to git (storage cost accepted)
+- Cross-machine: no merge, independent tasks. Manual fusion via ref: links.
+- `~/.hermes/personal/tasks/<hash>/` git can bare-run (no upstream). Metadata tracking > remote collaboration.
+- Old tasks: migrate if feasible, abandon if not.
+
+## Manage.py Split
+
+| Responsibility | Skill | Commands |
+|---|---|---|
+| Note-taking (observer, file-agnostic) | task-memory | append, read |
+| Lifecycle (orchestrator, manages locations) | task-framework | init, relink, export, import, rebuild, reindex |

task-framework/skills/task-lifecycle-portability/references/output-model-design.md

@@ -0,0 +1,55 @@
+# Pipeline Output Model Design (resolved 2026-06-11)
+
+## Problem
+
+Pipeline cleanup using exclusion-based deletion (`find ... -not -name X -exec rm`) or positive-listing always either misses cleanup targets or accidentally deletes user files. Task-framework metadata files (TASK.md, TASK_MEMORY.md, .hermes-task.json) mixed with pipeline artifacts in the same directory — cleanup couldn't distinguish them.
+
+## Solution
+
+### Directory isolation
+
+All generated artifacts go into `output/` subdirectory; `input/` holds user source materials:
+
+```
+tasks/<ts>.<name>-<hash6>/
+├── TASK.md             → symlink to ~/.hermes/personal/tasks/<hash>/task.md
+├── TASK_MEMORY.md      → symlink
+├── .hermes-task.json   → symlink
+├── input/
+│   ├── REQUIREMENTS.md
+│   └── images/
+└── output/
+    ├── tts-<hash6>/
+    ├── RECORDING.md
+    ├── COMPOSITING.md
+    └── compositing-<hash6>/output.mp4
+```
+
+### Cleanup strategy
+
+```bash
+# pipeline.py --clean
+rm -rf output/
+
+# task_reset --hard
+rm -rf output/ + reset checkboxes
+```
+
+Both entry points clean `output/` uniformly, never conflicting.
+
+### Symlink protection
+
+Three core files all symlinked to `~/.hermes/personal/tasks/<hash>/`. A `rm -rf` of the entire task directory only removes symlinks — actual data is preserved.
+
+### Manage tool
+
+`manage_task.py` commands (in task-framework skill's `scripts/`):
+
+| Command | Action |
+|---------|--------|
+| `init <hash>` | Create per-hash directory + three symlinks |
+| `export <hash>` | Package tar.gz (dereference symlinks) |
+| `import <file>` | Restore from tar.gz |
+| `rebuild <hash>` | Find hash tar.gz and import |
+| `relink <hash>` | Rebuild symlinks |
+| `reindex` | Rebuild ~/.hermes/personal/tasks/index.md |

task-framework/skills/task-lifecycle-portability/references/pipeline-output-transition.md

@@ -0,0 +1,41 @@
+# Pipeline Output Model Transition (2026-06-11)
+
+## What Changed
+
+`video-production-pipeline/scripts/pipeline.py` was updated to write all generated files to `output/` instead of the task root.
+
+| Before | After |
+|--------|-------|
+| RECORDING.md at root | output/RECORDING.md |
+| COMPOSITING.md at root | output/COMPOSITING.md |
+| IMAGE_SLIDESHOW.md at root | output/IMAGE_SLIDESHOW.md |
+| SUBTITLE_SPEC.md at root | output/SUBTITLE_SPEC.md |
+| tts-<hash6>/ at root | output/tts-<hash6>/ |
+| image-slideshow-* at root | output/image-slideshow-*/ |
+| subtitle-gen-* at root | output/subtitle-gen-*/ |
+| browser-video-recording-* at root | output/browser-video-recording-*/ |
+| compositing-* at root | output/compositing-*/ |
+| REQUIREMENTS.md at root | input/REQUIREMENTS.md (fallback to root) |
+| `--clean` positive-list | `rm -rf output/` |
+
+## Why
+
+Exclusion-based deletion (`find . -not -name 'REQUIREMENTS.md' -delete` or positive-listing `rm -rf tts-*/ RECORDING.md ...`) destroyed TASK.md because it was a regular file in the task root. The structural fix: put all generated files in a single `output/` directory, then cleaning is simply `rm -rf output/`.
+
+## Migration
+
+Existing pipeline tasks were migrated manually:
+1. Created `input/` + `output/` dirs
+2. Moved REQUIREMENTS.md + images/ into `input/`
+3. Moved all generated specs and phase dirs into `output/`
+4. TASK.md, TASK_MEMORY.md, .hermes-task.json converted to symlinks
+
+## TTS cache location
+
+TTS cache scanning now looks in `output/` directory for existing tts-* dirs:
+- Old: `os.listdir(TASK_DIR)` → look for tts-* at root
+- New: `os.listdir(os.path.join(TASK_DIR, OUTPUT_DIR))` → look for tts-* under output/
+
+## script path
+
+`~/.hermes/skills/media/video-production-pipeline/scripts/pipeline.py`

task-framework/skills/task-lifecycle-portability/references/task-recovery-5d5a1a-example.md

@@ -0,0 +1,27 @@
+# TASK.md Recovery: 5d5a1a (2026-06-11)
+
+## Scenario
+
+Agent asked to find TASK.md for task `5d5a1a`. It didn't exist — deleted weeks earlier by exclusion-based cleanup. Only TASK_MEMORY.md and the phase directories remained.
+
+## Process
+
+1. **Identify task type** — scanned task directory. Found REQUIREMENTS.md + RECORDING.md + COMPOSITING.md → video production pipeline task.
+2. **Load governing skill** — `skill_view('browser-screen-record-task')` for the phase template.
+3. **Map evidence to phases** — cross-referenced phase directories (tts-6d3e4c/, browser-video-recording-6d3e4c/, compositing-6d3e4c/) against the skill's phase table.
+4. **Read TASK_MEMORY.md** — confirmed final output: 174.1s / 5.8MB, all phases complete.
+5. **Write TASK.md** following skill's template — used the correct phase decomposition (1a/b/c parallel → 2 timeline-composer → 3 recording → 4 composite), matching `browser-screen-record-task`'s defined phases.
+6. **Verify** — checked output files exist, status = completed.
+
+## Key Lesson
+
+Phase structure must come from the domain skill, not guessed from memory or prior conversation. When I initially wrote the TASK.md, I used my own phase order (missing timeline-composer, wrong parallel grouping). The user corrected: "你可以参考 browser-screen-record-task 这个 skill，看看你的 phases 分解的对不对".
+
+## Recovery from symlink protection (future)
+
+If TASK.md was a symlink and the personal backup exists:
+```bash
+# Instant recovery:
+manage_task.py relink 5d5a1a
+```
+No content reconstruction needed — the symlink target `~/.hermes/personal/tasks/5d5a1a/task.md` still has the content.