[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69BTHHMPCWRRG66A846XZ06":3,"skill-same:01M69BTHHMPCWRRG66A846XZ06":128},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":35,"linkOnly":36,"markdownContent":37,"markdownBody":38,"frontMatter":39,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":6,"ownerHtmlUrl":53,"ownerBlogUrl":54,"ownerDescription":55,"updatedAt":56,"install":57,"resources":70},"01M69BTHHMPCWRRG66A846XZ06","shadow-frog-dream",null,"Run autonomous experimentation while the user is AFK. Uses 6 investigation categories (investigation, bug hunting, feature design, refactoring, optimization, security audit) to systematically discover non-obvious behaviors. Every task is an experiment — implement in worktrees, commit to persistent dream branches, and push to the configured remote. Dreams compound across sessions: future experiments branch from prior dream branches, building a tree of progressively deeper work. Invoke when the user is AFK or asks for a dream run. Use mode=coherent to ground each child in its parent while encouraging diverse siblings, challenges, and alternatives.","microsoft\u002FShadowFrog","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69BTFDNCFRDGPJVWET4C0RN",33,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000015","视觉设计","SCENARIO","使用场景",[24,25,26,27,28,29,30,31,32,33,34],"shadow frog dream","design","security","implement","experiments","sessions","commit","validate","setup","cleanup","run","2026-11-10 10:12:30",false,"---\nname: shadow-frog-dream\ndescription: >-\n  Run autonomous experimentation while the user is AFK. Uses 6 investigation\n  categories (investigation, bug hunting, feature design, refactoring,\n  optimization, security audit) to systematically discover non-obvious\n  behaviors. Every task is an experiment — implement in worktrees, commit\n  to persistent dream branches, and push to the configured remote. Dreams compound\n  across sessions: future experiments branch from prior dream branches,\n  building a tree of progressively deeper work. Invoke when the user is\n  AFK or asks for a dream run. Use mode=coherent to ground each child in\n  its parent while encouraging diverse siblings, challenges, and alternatives.\nscripts:\n  - dream-tools.py\n  - dream-coverage.py\n  - dream-validate.py\n  - dream-reconcile.py\n  - dream-setup.py\n  - dream-cleanup.sh\n  - dream-gc.sh\n---\n\n# ShadowFrog Dream\n\nAutonomous experimentation while the user is away. Every task is an\n**experiment** — implement real code in a worktree, run it, persist as a\n**named git branch** pushed to a remote the user can write to. Dream's unique value is\nimplementation experience that **compounds across sessions**.\n\n## Modes: Broad or Coherent\n\nAccept `mode=broad` (default) or `mode=coherent`, for example\n`\u002Fshadow-frog-dream mode=coherent`. Resolve the requested mode before planning.\nCarry it into every task\u002Fsubagent prompt, manifest, report, and validation\ninvocation. Use `\u002Fshadow-frog-nap` instead when the desired deliverable is a\nlightweight feature-task brief rather than an executed experiment.\n\n**Broad mode** keeps the category, coverage, and breadth rules below.\n\n**Coherent mode regularizes parent-child edges, not siblings or a whole tree.**\nEach child has its own `goal` and identifies a parent capability, finding,\nlimitation, or design decision motivating its work. It can extend, integrate,\nchallenge, replace, simplify, or offer an alternative. The shared\n`parent_connection` format is defined in `\u002Fshadow-frog`.\n\n- Ten children of one parent may pursue ten different worthwhile directions.\n  Sibling summaries help avoid duplicates; they do not impose a common goal,\n  file-disjointness requirement, or fixed diversity quota.\n- Technical independence is not an automatic rejection. A justified alternative\n  can be coherent even without calling the parent's modules. Shared keywords,\n  a parent ID, or merely touching the same file are not enough.\n- A challenge needs a reason or evidence; do not manufacture flaws to lengthen\n  a chain. Preserve unchanged user requirements and name superseded decisions.\n- There is no fixed tree-wide feature objective. Direction can evolve through\n  substantive local transitions. Stop a path when no useful continuation exists.\n- Descendants wait for their actual parent implementation. Siblings may run in\n  parallel in separate worktrees, including on the same files. Refresh the\n  selected parent branch\u002Ftip after each accepted step rather than relying on\n  the session-start branch snapshot for newly created parents.\n\n**Precedence:** in coherent mode, skip category minimums, uncovered-file quotas,\nsaturation-driven parent rejection, unique-file\u002Fdirectory checks, mid-session\nbreadth replanning, disjoint-file assignments, and the \"breadth over depth\"\npreference below. Follow the user's total work budget; absent one, use 12\nexperiments as a ceiling, not a quota. All execution, artifact, reconciliation,\nand worktree safety requirements still apply.\n\nBefore launching each child, record its parent branch and resolved commit,\nown goal, and intended connection. Give it the parent's report, manifest,\nrelevant source\u002Fevidence, and short sibling summaries. Do not claim sibling\nfeatures are inherited code. Seeds from the base branch have no parent\nconnection; importing a prior dream uses that dream's actual branch.\n\n**Completion review:** explain what the parent made possible or revealed to be\ninadequate, the child's concrete delta, and why the result is useful. For a\nreplacement, compare the old\u002Fnew behavior against the relevant constraints.\nStructural validation cannot judge semantic coherence.\n\nCoherent branches and their canonical index ancestors are retained by the\npinned reconciler for continued exploration and reproducible task baselines.\nEvery mode uses that same guarded pruning path. Explicit later curation may\nremove branches only after checking references and preserving required commits.\nWorktrees can still be cleaned up normally after successful pushes.\n\n## Critical Invariants\n\nThese rules are stated ONCE here and enforced by helper scripts. Violating\nany of them is a completion criteria failure.\n\n### Prerequisite: `.shadow\u002F` must be git-tracked\n\nDream moves `.shadow\u002F` content **through git** — artifacts are committed onto\nthe dream branch, pushed to the remote, then read back by the reconciler via\n`git show origin\u002F\u003Cbranch> .shadow\u002F...`. If `.shadow\u002F` is gitignored (the\n\"local only\" option in `shadow-frog-init`), `git add -A` silently skips those\nfiles, nothing reaches the remote, and the reconciler finds no manifest —\n**every discovery is lost without warning**. `dream-setup.py` runs\n`git check-ignore` on a new `.shadow\u002F_dreams\u002F` child path up front and refuses\nto start if it's ignored.\nUse `shadow-frog-update` instead for local-only shadows.\n\n### Path Isolation\n\n```\nWORKTREE_BASE = \u003Csystem-temp>\u002Fshadowfrog-dreams\u002F\u003CDREAM_NS>\u002F\nWORKTREE_DIR  = $WORKTREE_BASE\u002Fdream-\u003CSLUG>\n```\n\n- Worktrees are ALWAYS in the system temp directory under\n  `shadowfrog-dreams\u002F\u003CDREAM_NS>\u002F`, NEVER in the project directory. This\n  prevents conflicts between parallel agents and keeps the main repo clean.\n- `DREAM_NS` (namespace) isolates branches per task\u002Finstance. Resolved\n  from: `DREAM_NAMESPACE` env → `TASK_INFO.json` → `.env` → repo basename.\n- Override only with `DREAM_WORKTREE_BASE` env var if the system temp volume is\n  too small. Relative overrides are resolved to an absolute path before setup\n  emits the lifecycle context.\n- `dream-setup.py` computes and enforces all paths. Use it.\n\n### Branch Naming\n\n```\nBRANCH_NAME = dream\u002F\u003CDREAM_NS>\u002F\u003CDREAM_ID>\nDREAM_ID    = YYYYMMDD-HHMMSSZ-\u003CSLUG>\n```\n\n### Artifact Format\n\n```\n.shadow\u002F_dreams\u002F\u003CDREAM_ID>\u002Freport.md\n.shadow\u002F_dreams\u002F\u003CDREAM_ID>\u002Fmanifest.json\n.shadow\u002F_dreams\u002F\u003CDREAM_ID>\u002Fpatch.diff\n```\n\nNEVER flat files (`_dreams\u002F\u003CDREAM_ID>.md`). Flat files break the pipeline.\n\n### RUN_PREFIX\n\nRepository code and tests MUST use the `RUN_PREFIX` resolved during preflight.\nWhen `RUN_PREFIX=\"uv run\"`, use it for the repository's Python\u002Fpytest commands.\nShadowFrog's standard-library helpers instead use the interpreter and absolute\ncommand arguments captured by `dream-tools.py`; their tooling version must not\ncome from the historical experiment checkout.\n\n### Reconciliation is Mandatory\n\nEvery dream branch must reconcile to main before the session ends. The\nmost common failure mode is agents pushing dream branches but never\nreconciling — losing all discoveries.\n\n**Two modes:**\n- **Parallel mode (default):** Launch a batch of 3-4 sub-agents → wait\n  for all to push → run the pinned `commands.reconcile` ONCE at the end\n  of the batch. The reconciler auto-discovers every un-reconciled dream\n  branch in the namespace — you do NOT pass branch names. One call merges\n  every pushed branch.\n- **Sequential mode (fallback when sub-agents unavailable):**\n  Complete dream → push → reconcile → verify → next dream. Adds ~30s\n  per dream but guarantees zero data loss if the session crashes\n  mid-batch.\n\nNever queue multiple un-reconciled batches; reconcile at the end of\neach batch or each individual dream.\n\n### Script Failure Recovery\n\nThe pinned helpers are self-documenting. Diagnose errors by reading their\ncurrent sources, fix the reported prerequisite or artifact, and retry the same\nchecked command. Never substitute worktree-local helpers, downgrade the mode,\nskip validation, or imitate branch deletion manually.\n\nIf the tooling snapshot is missing or changed, stop. Restore or pin a fresh\ncomplete bundle from the current installation in the controller checkout, not\nfrom a historical dream. Do not edit a snapshot to make its hash checks pass.\n\n```\nPushable remote\n  main --- .shadow\u002F (accumulated ALL discoveries)\n  |\n  +-- dream\u002F\u003Cns>\u002F\u003Cid-1>  (cycle 1, agent A, from main)\n  +-- dream\u002F\u003Cns>\u002F\u003Cid-2>  (cycle 1, agent B, from main)\n  +-- dream\u002F\u003Cns>\u002F\u003Cid-3>  (cycle 2, from dream\u002F\u003Cns>\u002F\u003Cid-1>, compounding)\n```\n\n- Branches are live — `git checkout dream\u002F\u003Cid>` runs the code\n- Shadow follows lineage — ancestor chain, not sibling branches\n- Main is the accumulator — reconciliation merges ALL discoveries\n\n### Prerequisites\n\n1. Repo cloned locally with a pushable remote where `dream\u002F...` branches are allowed\n2. ShadowFrog skills installed (`install.sh --project \u002Fpath\u002Fto\u002Frepo`)\n3. `.shadow\u002F` initialized (`\u002Fshadow-frog-init`) and tracked by git\n\nUse the user's existing repo directly when it has a remote that accepts\n`dream\u002F...` branches. If no writable remote is configured, do not start a\ndream run; the user must configure one first.\n\n## Helper Scripts\n\nThis skill bundles 7 helper scripts. **Pin current tooling before creating or\nentering an experiment worktree, or switching the controller's code branch.**\nHistorical branches can contain older helpers that silently ignore new flags.\n\nLocate `dream-tools.py` beside this currently loaded skill in the controller's\n`.github\u002Fskills\u002Fshadow-frog-dream\u002F` or `.claude\u002Fskills\u002Fshadow-frog-dream\u002F`.\nChoose a new directory in the host's run\u002Fsession workspace, **outside both the\ntarget repository and the skill-source repository**:\n\n```text\npython CURRENT_SKILL\u002Fdream-tools.py pin --repo-root REPO_ROOT --output EXTERNAL_RUN_TOOLS --mode coherent\n```\n\nUse `--mode broad` for a broad run. The command copies the current Dream and\ncore helpers\u002Finstructions, atomically writes `tooling.json` after copying, and\nprints a JSON control packet. Save the packet in the external run workspace\nand pass it unchanged to every child. This is host-local tooling, not a shadow\ndiscovery or task artifact; never commit it into the target repository.\n\nThe packet contains:\n- `commands.validate`, `commands.reconcile`, `commands.coverage`: absolute\n  argument arrays, including the captured interpreter, snapshot runner, and\n  manifest digest. Reconcile\u002Fcoverage already include `REPO_ROOT`.\n- `helper_paths`: absolute paths to the bundled lifecycle scripts\u002Fmodules.\n- `instructions`: current core\u002FDream skill copies children must use for the\n  workflow, rather than the old copies in their code worktrees.\n- `mode`, `repo_root`, and the absolute pinned `skill_dir` (`SKILL_DIR` below).\n\nExecute command arrays as arguments, not shell code. Append only the operation's\narguments: `[DREAM_ID, WORKTREE_DIR]` for validation,\n`[\"--namespace\", DREAM_NS, \"--worktree-base\", WORKTREE_ROOT]` for reconciliation,\nand optionally `[\"--cleanup-branches\"]` after committing and\npushing reconciliation. The dispatcher supplies the pinned validation mode and\nrejects mode overrides. It checks the manifest digest and all captured file\nhashes before executing the helper, preserving its output and exit status.\n\nFor example, the equivalent native command shape for validation is:\n\n```text\npython PINNED_SKILL\u002Fdream-tools.py run --digest PIN_DIGEST validate DREAM_ID WORKTREE_DIR\n```\n\n`PINNED_SKILL` and `PIN_DIGEST` come from the packet; do not fabricate them.\nKeep the snapshot while children or resumed work reference it. The run workspace\nowns its eventual cleanup; this helper never recursively deletes directories.\nRe-pin on a different host rather than reusing host-specific interpreter paths.\n\n| Script | Purpose | When to use |\n|--------|---------|-------------|\n| `dream-tools.py` | Pins current tooling and dispatches checked Python helpers | **Before worktrees** and for every validation\u002Freconciliation\u002Fcoverage call |\n| `dream-setup.py` | Creates worktree + branch with namespace isolation | **Phase 3** — start of every experiment |\n| `dream-validate.py` | Validates artifacts before push (hard gate) | **Phase 5** — before `git push` |\n| `dream-reconcile.py` | Merges dream branches into main's `.shadow\u002F` | **Phase 6** — after all experiments done |\n| `dream-coverage.py` | Computes exploration coverage map | **Phase 2** — task planning for diversity |\n| `dream-cleanup.sh` | Safely removes ONE dream worktree (with safety gate) | **After push** — replaces the old inline cleanup snippet |\n| `dream-gc.sh` | Sweeps orphan dream worktrees from `$DREAM_WORKTREE_BASE` | **Auto** — triggered by `dream-setup.py` (per-namespace throttle, default 1× \u002F hour) in orphan-only mode; also `--task-complete --namespace \"$DREAM_NS\" --min-age-min 0` for end-of-session sweep of registered-but-stale dirs. On Windows, automatic sweeping remains disabled until `dream-gc.py` replaces the POSIX-only helper. |\n\nThe shared `shadow-frog\u002F_coherence.py`, `_dream_namespace.py`, and\n`_worktree_paths.py` are captured with the Dream tools.\nNever rediscover these Python helpers relative to `WORKTREE_DIR`. All scripts\nsupport `--help`. Setup returns JSON only. Consume it through the host's native\nJSON tools, not shell exports. The remaining cleanup\u002FGC shell scripts keep their\nsafety gates; use their Python ports when available.\n\nIn shell recipes, `PYTHON_BIN` is the captured interpreter (the first element\nof `commands.validate`) and `SKILL_DIR` is the pinned `skill_dir`. Pass these\nvalues explicitly; shell variables do not persist across tool calls.\n\n## Phase 1: Preflight and Assess\n\n### Preflight Validation\n\n```bash\nREPO_ROOT=$(git rev-parse --show-toplevel)\ncd \"$REPO_ROOT\"\n\n# 0. Resolve DREAM_NAMESPACE with the same parser setup\u002Freconciliation use.\nDREAM_NAMESPACE=\"$(\"$PYTHON_BIN\" -c '\nimport sys\nsys.path.insert(0, sys.argv[1])\nfrom _dream_namespace import resolve_dream_namespace\nprint(resolve_dream_namespace(sys.argv[2]))\n' \"$SKILL_DIR\" \"$REPO_ROOT\")\" || exit 1\nexport DREAM_NAMESPACE\necho \"Dream namespace: $DREAM_NAMESPACE\"\n\n# 1. Detect default branch\nDEFAULT_BRANCH=$(git symbolic-ref refs\u002Fremotes\u002Forigin\u002FHEAD 2>\u002Fdev\u002Fnull | sed 's|refs\u002Fremotes\u002Forigin\u002F||')\nif [ -z \"$DEFAULT_BRANCH\" ]; then\n    if git show-ref --verify refs\u002Fremotes\u002Forigin\u002Fmain >\u002Fdev\u002Fnull 2>&1; then\n        DEFAULT_BRANCH=\"main\"\n    elif git show-ref --verify refs\u002Fremotes\u002Forigin\u002Fmaster >\u002Fdev\u002Fnull 2>&1; then\n        DEFAULT_BRANCH=\"master\"\n    else\n        echo \"ERROR: Cannot detect default branch. Fix: git remote set-head origin \u003Cbranch>\"\n    fi\nfi\necho \"Default branch: $DEFAULT_BRANCH\"\n\n# 2-5. Validate environment\necho \"Current branch: $(git branch --show-current)\"\necho \"Remote: $(git remote get-url origin)\"\ngit ls-remote origin HEAD >\u002Fdev\u002Fnull 2>&1 || echo \"ERROR: Cannot reach remote.\"\n[ -d .shadow ] || echo \"ERROR: .shadow\u002F not found. Run \u002Fshadow-frog-init first.\"\nmkdir -p .shadow\u002F_dreams\ngit diff --quiet && git diff --cached --quiet || echo \"ERROR: Uncommitted changes.\"\n\n# 6. Fetch all remote branches (ONE fetch for all agents)\ngit fetch origin --prune\n\n# 7. List dream branches (namespace-filtered)\nDREAM_NS=\"${DREAM_NAMESPACE:-}\"\nBRANCH_PATTERN=\"${DREAM_NS:+origin\u002Fdream\u002F${DREAM_NS}\u002F}\"\nBRANCH_PATTERN=\"${BRANCH_PATTERN:-origin\u002Fdream\u002F}\"\necho \"Available dream branches:\"\ngit branch -r | grep \"$BRANCH_PATTERN\" | sed 's|origin\u002F||' || echo \"  (none)\"\n\n# 8. Detect RUN_PREFIX from lockfiles\nif [ -f uv.lock ]; then\n    uv sync --all-groups 2>&1 | tail -3\n    RUN_PREFIX=\"uv run\"\nelif [ -f package-lock.json ]; then\n    npm install --quiet 2>&1 | tail -3\n    RUN_PREFIX=\"npx\"\nelif [ -f yarn.lock ]; then\n    yarn install --silent 2>&1 | tail -3\n    RUN_PREFIX=\"npx\"\nelse\n    RUN_PREFIX=\"\"\nfi\necho \"RUN_PREFIX='$RUN_PREFIX'\"\n\n# 9. List compoundable experiments\necho \"\"\necho \"=== COMPOUNDABLE EXPERIMENTS ===\"\nif [ -f .shadow\u002F_dreams\u002F_index.md ]; then\n    awk -F'|' 'NR>2 && \u002Fuseful\u002F {\n        gsub(\u002F \u002F,\"\",$2); gsub(\u002F \u002F,\"\",$4); gsub(\u002F \u002F,\"\",$6);\n        gsub(\u002F^ +| +$\u002F,\"\",$5);\n        if ($2 != \"\" && $6 != \"\") print $6 \" | \" $3 \" | \" $5\n    }' .shadow\u002F_dreams\u002F_index.md\n    COMPOUNDABLE=$(awk -F'|' 'NR>2 && \u002Fuseful\u002F {gsub(\u002F \u002F,\"\",$2); if ($2 != \"\") c++} END {print c+0}' .shadow\u002F_dreams\u002F_index.md)\n    echo \"Total compoundable: $COMPOUNDABLE\"\nelse\n    echo \"(none — first dream session)\"\nfi\n```\n\n**If any check prints ERROR, STOP.** Do not use `exit 1` — check output\nand stop at the agent level.\n\n(`RUN_PREFIX` MUST be threaded into every subagent prompt for repository\ncode\u002Ftests. Helper commands use the pinned packet's interpreter instead.)\n\n### Snapshot Branch State\n\nAfter the single `git fetch`, capture dream branches and pass to all\nsub-agents — they do NOT fetch independently.\n\n```bash\nDREAM_NS=\"${DREAM_NAMESPACE:-}\"\nBRANCH_FILTER=\"${DREAM_NS:+origin\u002Fdream\u002F${DREAM_NS}\u002F}\"\nBRANCH_FILTER=\"${BRANCH_FILTER:-origin\u002Fdream\u002F}\"\ngit branch -r --format='%(refname:short) %(objectname:short)' \\\n  | grep -F \"$BRANCH_FILTER\" \\\n  | sed 's|origin\u002F||' > .shadow\u002F_dreams\u002F.branch-map.txt\ncat .shadow\u002F_dreams\u002F.branch-map.txt\n\n# Initialize session tracking (orchestrator-only; agents do NOT write here)\n: > .shadow\u002F_dreams\u002F.session-branches.txt\n```\n\n### Assess Codebase\n\nRead `_meta\u002Fstate.json`, `_index.md`, existing discoveries, and **past\ndream reports** in `_dreams\u002F`.\n\n### Build Exploration Coverage Map\n\nRun the packet's `commands.coverage`. It already contains the pinned\ninterpreter\u002Ftool version and the original repository path.\n\n**Coverage definition:** A file is \"covered\" only when its shadow has\n≥1 behavioral discovery (line starting with `- `). Placeholder-only = NOT covered.\n\n**Scoped exploration (`--scope`)** — pass `--scope \u003Cpath-prefix>` (repeatable)\nto restrict the coverage map to a specific subtree. Use this when the\nbroader repo is well-explored but a particular area (e.g., a known\nfrontier of bugs, a newly-added module, a subsystem the user just\nflagged) deserves a focused dream session. All counts (totals, %,\nsaturated, fan-in, per-dir) are computed over the scoped subset only.\n\nFor one subtree, append `[\"--scope\", \"src\u002Fauth\u002F\"]` to `commands.coverage`.\nFor several, append repeated `--scope` argument pairs.\n\nIn broad mode, when using `--scope`, the per-category task quotas (Phase 2) still apply\nbut are interpreted against the scoped subset. Don't use scoped\nexploration as the default — pick it only when there's a concrete reason\nto concentrate effort.\n\n### Review Past Dreams (Required)\n\nIn coherent mode, use the index to select parents, then read the selected\nparent reports\u002Fmanifests and relevant ancestor evidence. Do not reread every\nreport or reject a useful parent merely because its files are well covered.\n\nWhen compoundable experiments exist (preflight step 9):\n- Broad mode: read the candidate reports. Coherent mode: read the selected\n  parent's report\u002Fmanifest and the relevant ancestor evidence.\n- Choose which to continue (extending, fixing, integrating)\n- Note `dead_end` experiments to avoid repeating\n- Trace lineage via the `parent` column in `_dreams\u002F_index.md`\n\n**Compounding quality gate** — before choosing to compound from a parent:\n\n1. Read the parent's `report.md` AND `manifest.json`\n2. Verify the parent has a non-empty `patch.diff` (prose-only parents\n   are low-value — prefer parents with working code)\n3. Broad mode: identify a specific file\u002Ffunction to modify or extend.\n   Coherent mode: identify the parent capability, finding, or decision that\n   motivates the child; a technically independent alternative is allowed.\n4. Broad mode: check saturation (8+ discoveries) and prefer a fresh target\n   unless there is a concrete new angle. Coherent mode has no saturation gate;\n   assess whether the proposed continuation adds useful evidence or capability.\n5. Log your compounding intent: \"I will extend parent's retry logic in\n   `src\u002Fhttp.py` to handle connection timeouts\" — vague \"continue\n   exploring\" is NOT compounding\n\n**First dream session:** if preflight step 9 shows `(none)`, all tasks\nbranch from main.\n\n## Phase 2: Plan\n\nIn broad mode, generate a concrete plan. **Target 12 tasks (2 per category).** On small\ncodebases (\u003C30 source files), minimum 6 tasks across 4+ categories.\n\n### The 6 Investigation Categories\n\n| Category | Priority signals | Experiment |\n|----------|------------------|------------|\n| **Investigation** | Files with 0-2 discoveries, untraced import chains, `uncertain` entries | Test behavior hypotheses with assertions |\n| **Bug hunting** | Error handling, concurrency, unvalidated inputs | Fuzz inputs, trigger error paths, reproduce races |\n| **Feature design** | TODOs, FIXMEs, user-facing gaps, integration opportunities | Implement the feature, run it, evaluate integration |\n| **Refactoring** | God classes, duplication, high coupling | Refactor, run existing tests, measure complexity |\n| **Optimization** | Hot paths, nested loops, repeated I\u002FO, missing caches | Profile, optimize, measure before\u002Fafter |\n| **Security audit** | Auth, data handling, deserialization, user inputs | Test adversarial inputs and injection vectors locally |\n\n**Exception — user-directed focus**: If the user specifies a focus area\n(e.g., \"dream focus on security\"), allocate ALL tasks to that category.\n\n### Task Plan Format\n\nEach task specifies **base branch**, **primary target file(s)**, and **why**:\n\n```\nTasks (by category):\n  Investigation:\n    1. [title] — write tracing tests for [target]\n       Base: main\n       Target: src\u002Fauth\u002Fvalidator.py (UNCOVERED, 12 refs)\n       Why: High fan-in utility with no shadow coverage\n  Bug hunting:\n    1. [title] — fuzz [target]\n       Base: dream\u002F\u003Cns>\u002F\u003Cprior-id> (compounds prior)\n       Target: src\u002Fparsers\u002Fcsv.py (extending parent's failing tests)\n       Why: Parent found 2 crashes, need to verify fixes\n  ...\n```\n\n### Diversity Rules\n\nIn broad mode, prefer breadth over depth: more files with 2-3 discoveries over\none file with 20. Prevent fixation with these rules:\n\n1. **Max 2 tasks per source file** (unless prior dream left concrete follow-up)\n2. **≥30% of tasks on uncovered files** (from coverage map)\n3. **≥2 tasks on \"deep\" files** (utilities, internals, converters)\n4. **Vary directories** — no 3+ consecutive tasks in same dir\n\n**Self-check before finalizing:** unique target files ≥ 60% of task count,\nuncovered file tasks ≥ 30%, no file in > 2 tasks. Swap if failing.\n\n**Escape hatches** (document justification): prior dream's failing test,\nconcrete untested hypothesis, file is 500+ lines with unexplored sections,\ncodebase has \u003C20 source files.\n\n### Task Design\n\nEach task needs: **category**, **hypothesis**, **what to implement**,\n**base branch**, **primary target** (with coverage status), **why this\ntarget**, **scope** (hours, not days), and **success criteria**.\n\nAlso include the selected **mode**. Coherent tasks additionally carry their\nown **goal** and **parent_connection**, not a shared sibling\u002Ftree objective.\nCategory still describes the experiment, but coherent mode has no category quota.\n\nFor example, \"Fuzz the CSV parser with malformed inputs to reproduce crashes\nor silent corruption\" is a concrete experiment; \"Review error handling\" is not.\n\n### Feature Design: Motivation Required\n\nFeature experiments must address a real gap identified in existing code.\nAnswer: \"Why would maintainers want this?\" with a specific code reference.\nThe feature must connect to the existing codebase (imports, modifies,\nreplaces duplication). Standalone modules with only stdlib don't qualify.\n\n### Vary Your Approach\n\nEach experiment should have unique structure driven by its hypothesis. If\nyou find yourself copying the same module layout (one source file + one\ntest file, identical importlib hack) across experiments, you're optimizing\nfor throughput over insight. Vary your approach: some experiments modify\nexisting files, some add tests for existing code, some create minimal\nscripts, some refactor existing modules.\n\n### File Selection Guidance\n\nAgents gravitate toward entry points. Evaluation shows this causes missed bugs.\n\n**High-value targets typically missed:**\n- High fan-in files (imported by many, rarely explored directly)\n- Internal\u002Fprivate modules (`_internal\u002F`, `_utils\u002F`, `_compat\u002F`)\n- Conversion\u002Fserialization code (parse, encode, format, marshal)\n- Error handling paths (exception hierarchies, fallback logic)\n\n**Avoid:** Starting from `__init__.py`, skipping \"boring\" files, same\ndirectory 3+ times, ignoring files with few public symbols.\n\n## Phase 3: Execute Tasks\n\nWork through the plan. **Launch 3-4 experiments in parallel** via\nsub-agents. Each handles the full lifecycle: create worktree → implement\n→ test → write shadow + manifest + report → commit → push → clean up.\nIf sub-agents are unavailable, fall back to sequential execution.\n\nIn coherent mode, a parallel batch can contain diverse siblings of an already\navailable parent. Never launch a descendant before its parent exists. Include\nthe mode, goal, connection, and expected parent commit in each child prompt.\n\n**Each experiment runs in a separate git worktree.** The worktree IS the\ndream branch (created with `-b`). After pushing, the worktree is removed\nbut the branch persists on the remote.\n\n### Reading Before Implementing\n\nBefore implementing, read the target source and its shadow, plus shadows of\nreferenced\u002Freferencing files. Identify current behavior, edge cases, and\nimplicit contracts. Reading is preparation; the deliverable is code written\nand run, with results recorded.\n\n### Experiment Setup\n\nUse `dream-setup.py` to create worktrees (handles all path computation,\nnamespace resolution, worktree creation, and validation):\n\nUse the absolute setup helper from `helper_paths[\"dream-setup.py\"]` with the\ncaptured Python interpreter. The equivalent command shape is:\n\n```text\npython PINNED_SKILL\u002Fdream-setup.py --slug t01-csv-fuzzer --repo-root REPO_ROOT\npython PINNED_SKILL\u002Fdream-setup.py --slug t03-extend --repo-root REPO_ROOT --base-branch dream\u002F\u003Cns>\u002F\u003Cprior-id>\n```\n\nCheck the exit code before consuming JSON. Keep the returned `repo_root`,\n`default_branch`, `dream_ns`, `dream_id`, `branch_name`, `parent_branch`,\n`worktree_dir`, `worktree_root`, `worktree_base`, `base_commit`, `run_prefix`,\nand `slug` in the agent's task state. Uppercase names in later recipes refer\nto these values. Forward the canonical `worktree_root` to reconciliation\nas `--worktree-base` and to shell cleanup\u002FGC as `DREAM_WORKTREE_BASE`.\n\n**If `dream-setup.py` fails or is not found:** Apply the Script Failure\nRecovery rule (diagnose the pinned script and retry safely). Common causes:\nmissing git remote, branch already exists, or temp-directory permissions.\n\nDo not infer the current tool location from the experimental worktree. The\npacket and its outside-repository snapshot remain authoritative, even if the\ncontroller checkout later changes branches.\n\n**If worktree creation fails:** mark task `blocked`, replace with another.\n\n### What Meaningful Compounding Looks Like\n\nIn broad mode, compounding means **actively engaging with the parent's code**, not just\nsitting on its branch. Valid compounding approaches:\n- **Extend**: import or call the parent's modules and build on them\n- **Modify**: edit the parent's code to fix limitations noted in its report\n- **Refactor**: restructure the parent's implementation for better design\n- **Integrate**: wire the parent's standalone module into the real codebase\n- **Test deeper**: add edge-case tests for the parent's implementation\n\nDon't assume the parent dream's code is complete or frozen — iterative\nimprovement is the whole point. If you can't find anything meaningful to\nbuild on, start fresh from main instead.\n\nIn broad mode, compounding that only adds a new standalone module beside the parent's\ncode (with no imports, edits, or integration) is NOT compounding — it's\na fresh experiment on the wrong branch.\n\nIn coherent mode, apply the parent-connection review instead: a standalone\nalternative is allowed if it substantively responds to the parent's findings\nor design, rather than being unrelated work parked on the same branch.\n\n### Run\n\nImplement the experiment, run tests\u002Fbuilds, and debug as needed. Record what\nworked, failed, or surprised you as you go.\n\n### Write Shadow Discoveries\n\n**On the dream branch** (in the worktree), NOT on main.\n\n**Every experiment MUST write ≥1 discovery to a per-file `.shadow\u002F*.md`.**\nAuthoring order: write the human-readable shadow first, then mirror every\ndiscovery into `manifest.json`. For reconciliation the **manifest is the\nsource of truth** — the reconciler merges manifest entries into main, so a\ndiscovery that is missing from the manifest never reaches main. The per-file\nshadow is the human-readable copy (and a required validate gate), not the\npropagation path.\n\nFollow the dedup and writing rules in `\u002Fshadow-frog`. Dream discoveries\nare typically `source: exploration`. Mark `verified` when confirmed by\nrunning code; `uncertain` if not fully testable.\n\nNew discoveries start with visible `citation_score: 0`. Keep that field in\nthe corresponding manifest entry as well. Existing knowledge that informed\nthe task can be cited once through the core increment helper or reported to\nthe coordinator for serialized updates. Do not count merely enumerated entries.\nScores are approximate within the relevant checkout; reconciliation preserves\nthe larger score when the same claim is supplied again, rather than summing\ninherited counts. Counter-only branch edits are not imported unless represented\nin a matching manifest discovery; they do not justify unsupported `op` values.\n\n#### How to Append\n\nFind the `##`\u002F`###` heading for the symbol, then:\n- Placeholder `_No discoveries yet._` → replace with discovery\n- Existing discoveries → append after last bullet\n- No heading → create before `## Cross-References`\n\n#### Label Triage (REQUIRED)\n\nAfter writing each discovery, evaluate whether it deserves any of the\nfive actionable labels from `\u002Fshadow-frog` (`bug`, `security`,\n`performance`, `feature-gap`, `tech-debt`), using that skill's definitions.\n\nRules:\n- Apply labels to BOTH the in-file discovery markdown AND the\n  `manifest.json` discovery entry (`\"labels\": [\"bug\"]`). The reconciler\n  uses the manifest as source of truth; the in-file copy is for humans\n  reading the shadow directly.\n- Multiple labels are fine when accurate: `labels: [bug, security]`.\n- Omit labels for pure behavioral observations (\"retries N times before\n  giving up\", \"default timeout is 30s\") — these are knowledge, not\n  action items.\n- Do not apply labels speculatively. The label says \"an engineer should\n  act on this.\" If you wouldn't act on it, don't label it.\n\nExample:\n\n```\n- \u002Fapi\u002Fupload accepts paths from request body without normalization,\n  allowing `..\u002F` traversal into \u002Fetc\u002F.\n  _(verified, source: exploration, labels: [bug, security], citation_score: 0)_\n  Dream report: `_dreams\u002F20260518-161200Z-upload-traversal\u002F`\n```\n\n`dream-validate.py` emits non-blocking warnings when discovery text\ncontains label-signal keywords but no label is set. Treat those\nwarnings as a prompt to re-check the triage, not as a directive.\n\n#### Anchor Rules\n\n- About existing code → anchor to that symbol\n- Spans 3+ files → `_cross\u002F\u003Cslug>.md`\n- Project-wide convention → `_prefs.md`\n- **Only create shadows for base-codebase files** — experiment-only files\n  don't get shadows (the branch IS the artifact). Anchor findings to the\n  existing code they relate to.\n\n#### Cross-Cutting Discoveries\n\nWhen you see the same behavior in 3+ files, create a `_cross\u002F\u003Cslug>.md`\nrather than repeating the discovery in each per-file shadow. Add\nback-pointers in each file's `## Cross-References` section.\n\n#### Discovery Quality\n\nDiscoveries must be **self-contained process knowledge** — understandable\nfrom the base codebase without checking out the dream branch. Capture what\nwas learned, how to apply it, and what to avoid, not a description of the\nexperiment-only artifact.\n\n- **Good:** \"agent.py's retry loop catches all exceptions including OOM,\n  masking fatal errors that should crash immediately.\"\n- **Bad:** \"The implemented PluginFramework has PluginRegistry, PluginManager,\n  and 7 lifecycle hooks.\" This describes a branch-only artifact.\n\nPer-file discoveries should reference the dream report:\n\n```\n- Retrying with exponential backoff recovers from 99% of transient errors,\n  but must exclude 4xx or it retries bad requests for 30s.\n  _(verified, source: exploration, citation_score: 0)_\n  Dream report: `_dreams\u002F20250612-143012Z-retry-logic\u002F`\n```\n\n### Write Discovery Manifest\n\nAfter shadow writes, create `.shadow\u002F_dreams\u002F$DREAM_ID\u002Fmanifest.json`:\n\n```json\n{\n  \"dream_id\": \"\u003CDREAM_ID>\",\n  \"branch\": \"\u003CBRANCH_NAME>\",\n  \"parent_branch\": \"main\",\n  \"mode\": \"broad\",\n  \"category\": \"bug hunting\",\n  \"verdict\": \"useful\",\n  \"title\": \"CSV Parser Edge Cases\",\n  \"discoveries\": [\n    {\n      \"op\": \"add\",\n      \"anchor\": \"src\u002Fparsers\u002Fcsv.py::parse_row\",\n      \"text\": \"Unescaped quotes in fields cause silent truncation.\",\n      \"status\": \"verified\",\n      \"source\": \"exploration\",\n      \"labels\": [\"bug\"],\n      \"citation_score\": 0,\n      \"also_involves\": [\"src\u002Fparsers\u002Futils.py::unescape\"],\n      \"dream_report\": \"_dreams\u002F\u003CDREAM_ID>\u002F\"\n    }\n  ],\n  \"cross_cutting\": []\n}\n```\n\n**Anchor format:** `file::symbol` with bare names (no backticks). The\nreconciler handles normalization.\n\nFor coherent experiments, set `\"mode\": \"coherent\"`, add a nonempty `\"goal\"`\nfor this experiment, and include `\"parent_connection\"` in the shared\n`\u002Fshadow-frog` format when `parent_branch` is a prior `dream\u002F...` branch.\nSeeds use null or omit the connection. `parent_branch` is the authoritative\nparent reference; siblings need not share goals or modify different files.\nThese fields survive reconciliation in the archived manifest.\n\nManifest `op` values: only `add` is supported by the reconciler today.\n`update` and `refute` are reserved keywords — `dream-validate.py` will\nreject any discovery whose `op` is not `add`. To revise or contradict an\nexisting discovery, run a meditate session against main's `.shadow\u002F`\ninstead of trying to do it from a dream branch.\n\n`citation_score` on per-file or cross-cutting manifest entries is a nonnegative\ninteger, defaulting to 0. It is a reuse hint, never a verification or trust signal.\n\n**Hard gate — discoveries must be mirrored into per-file shadows.** The\nreconciler merges `manifest.json` entries into main directly (so discoveries\nare not lost at merge time), but the branch's per-file shadows must ALSO be\nupdated so human PR reviewers can read the discoveries in context. If\n`manifest.json` declares discoveries but no `.shadow\u002F*.md` files outside\n`_dreams\u002F` are modified in the branch diff vs `base_commit`,\n`dream-validate.py` rejects the dream. Always write each discovery into BOTH\nthe corresponding per-file shadow (or `.shadow\u002F_cross\u002F`) AND the manifest\nbefore staging.\n\n### Save Dream Report\n\nSave as `.shadow\u002F_dreams\u002F$DREAM_ID\u002Freport.md`:\n\n```markdown\n---\ndream_id: \"\u003CDREAM_ID>\"\ncategory: bug hunting\nverdict: useful\nbase_commit: \"\u003CBASE_COMMIT>\"\nbranch: \"\u003CBRANCH_NAME>\"\nparent_branch: \"main\"\nmode: broad\nremote: \"origin\"\nrelated_symbols:\n  - \"src\u002Fparsers\u002Fcsv.py::parse_row\"\nbuilds_on: []\n---\n\n# CSV Parser Edge Cases\n\n## Motivation\n\u003Ccite specific existing files\u002Fsymbols where gap was identified>\n\n## Compounding Delta\n\u003CONLY for a prior-dream parent — what parent code or design was engaged and changed>\n\n## Parent Connection\n\u003Ccoherent mode: own goal, relation, parent basis, delta, preserved constraints,\nand superseded decisions; explain alternatives even when technically independent>\n\n## Hypothesis\n\u003Cwhat we expected to learn>\n\n## Implementation\n\u003Ckey decisions, approach>\n\n## Commands Run\n\u003Cexact commands with exit codes>\n\n## Evaluation\n\u003Cresults, what worked\u002Fdidn't>\n\n## Takeaways\n\u003Clessons, gotchas>\n\n## Verdict Details\n\u003Cwhy useful\u002Fdead_end>\n```\n\n| Field | Required | Values |\n|-------|----------|--------|\n| `dream_id` | yes | `YYYYMMDD-HHMMSSZ-slug` |\n| `category` | yes | one of the 6 categories |\n| `verdict` | yes | `useful` or `dead_end` |\n| `base_commit` | yes | SHA branched from |\n| `branch` | yes | full branch name |\n| `parent_branch` | yes | `main` or prior branch path |\n| `mode` | coherent runs | `broad` (default) or `coherent`; must match manifest and validator |\n| `related_symbols` | yes | `file::symbol` refs |\n\n**`tip_commit` is NOT in the report.** Including the final commit SHA\ncreates a chicken-and-egg problem (SHA changes when report is committed).\nThe reconciler derives it via `git rev-parse origin\u002F$BRANCH` and records\nit in `_dreams\u002F_index.md`.\n\n**Verdict** is the agent's assessment (set once, immutable):\n- `useful` — produced actionable findings, working code, or valuable lessons\n- `dead_end` — approach doesn't work; documented why so future dreams skip\n\n### Validate, Commit, Push\n\nValidation must use `commands.validate` from the pinned packet. Its mode was\nfixed before the worktree was created; no mode override or local-helper fallback\nis allowed. Carry this exact command prefix into each subagent prompt.\n\n```bash\ncd \"$WORKTREE_DIR\"\n\n# 1. Generate diff (exclude .shadow\u002F and common build artifacts)\ngit add -A -- ':!.dream_parent' ':!__pycache__\u002F' ':!.pytest_cache\u002F'\ngit commit -m \"dream: $SLUG\"\nmkdir -p .shadow\u002F_dreams\u002F\"$DREAM_ID\"\ngit diff \"$BASE_COMMIT\" HEAD -- \\\n    ':!.shadow\u002F' ':!__pycache__\u002F' ':!*.pyc' ':!.pytest_cache\u002F' \\\n    ':!node_modules\u002F' ':!*.lock' ':!dist\u002F' ':!build\u002F' \\\n    > .shadow\u002F_dreams\u002F\"$DREAM_ID\"\u002Fpatch.diff\n[ ! -s .shadow\u002F_dreams\u002F\"$DREAM_ID\"\u002Fpatch.diff ] && echo \"WARNING: Empty diff\"\n\n```\n\n**2. Validate (hard gate):** execute `commands.validate + [DREAM_ID,\nWORKTREE_DIR]`. The copied runner verifies the tooling and passes the pinned\n`--mode` to the copied validator. Stop on any nonzero exit; fix the artifact or\ntooling issue and retry. File-existence checks are not a substitute for validation.\n\n**3. Only after validation succeeds, commit and push:**\n\n```bash\ngit add -A -- ':!.dream_parent'\ngit commit -m \"dream: $SLUG — final with report and manifest\"\nif git push origin \"$BRANCH_NAME\"; then\n    echo \"Pushed: $BRANCH_NAME\"\nelse\n    echo \"ERROR: Push failed. Keep worktree for recovery.\"\n    exit 1\nfi\n```\n\n**Do NOT write to `.session-branches.txt`** — that is managed by the\norchestrator after all agents complete. Agents only push their branch;\nthe orchestrator discovers pushed branches from the remote.\n\n### Worktree Cleanup\n\n```bash\nDREAM_WORKTREE_BASE=\"$WORKTREE_ROOT\" \\\n    bash \"$SKILL_DIR\u002Fdream-cleanup.sh\" \"$WORKTREE_DIR\" --repo-root \"$REPO_ROOT\"\n```\n\n`dream-cleanup.sh` does the equivalent of `git worktree remove --force`\nfollowed by `git worktree prune`, with a safety-gated `rm -rf` fallback if\nworktree removal silently fails. The fallback only accepts paths matching\n`\u003Cworktree_root>\u002F\u003Cns>\u002Fdream-\u003Cslug>`\nexactly; any other path is refused.\n\nRemove as you go. If push failed, keep the worktree.\n\n### Mid-Session Diversity Check\n\nThis breadth check applies to broad mode. In coherent mode, review edge quality\nand sibling duplication instead; do not swap out a relevant continuation just\nto increase unique-file counts.\n\nAfter completing roughly half of your planned tasks, pause and review:\n\n1. **Count unique primary target files** explored so far. If fewer than\n   50% of completed tasks targeted distinct files, remaining tasks MUST\n   target new files.\n2. **Check for re-exploration** — are any completed tasks exploring files\n   already well-covered before this session? Swap remaining tasks for\n   uncovered ones.\n3. **Review coverage map delta** — if fewer than 2 previously uncovered\n   files explored, prioritize uncovered files for remaining tasks.\n4. **Adjust the plan** — swap, add, or reorder remaining tasks. The plan\n   is a starting point, not a contract.\n\nThis prevents the fixation failure mode where the first half discovers a\nrich area and the second half keeps digging there instead of spreading.\n\n## Phase 4: AFK-Safe Patterns\n\n1. Worktrees are outside the repo — writes don't trigger approval\n2. Temp scripts go in `\u002Ftmp\u002Fshadow-dream-\u003Cslug>.*`\n3. Never modify main directly — only during reconciliation\n4. Clean up worktrees after push\n5. Shadow writes on dream branches are safe\n\n## Phase 5: Parallel Agent Rules\n\n1. Broad mode targets different files. Coherent siblings may target the same files in their separate worktrees.\n2. Each agent gets its own branch (inherently isolated)\n3. Each agent writes its own manifest in its `$DREAM_ID\u002F` directory\n4. Do NOT write to main or shared files (`_index.md`, `state.json`)\n5. Do NOT update shared indexes or `state.json` — reconciled post-dream by orchestrator\n6. Broad mode: fetch once and use the initial snapshot. Coherent mode: after a\n   parent is pushed, the orchestrator refreshes that parent's ref\u002Fcommit and\n   branch map before launching its children. Siblings share the refreshed\n   snapshot; subagents never fetch independently.\n7. Manifest anchors use bare symbol names (reconciler normalizes)\n8. Thread `RUN_PREFIX` into every subagent prompt\n9. Include `WORKTREE_ROOT`, `WORKTREE_BASE`, and `DREAM_NS` in every subagent prompt\n10. Dream artifacts MUST use subdirectory format — flat files are a\n    completion criteria violation (see Critical Invariants → Artifact Format)\n11. Thread the selected mode and pinned tool packet into every prompt. For\n    coherent children, include their own goal, parent packet, connection, and\n    expected parent commit. Use the supplied validation command; never resolve\n    a helper from the child's installed skill directories.\n\n## Phase 6: Reconcile to Main\n\n**⚠️ CRITICAL: Reconciliation is MANDATORY at the end of every dream batch.**\nSee Critical Invariants → Reconciliation is Mandatory (above) for the\nparallel-vs-sequential mode definitions and the auto-discover rule. Do\nNOT defer reconciliation across batches.\n\nThe `_index.md` entry is your sequential-mode checkpoint — any dream\nlisted there is safe if the session crashes.\n\nUse the reconciliation script:\n\n```bash\ncd \"$REPO_ROOT\"\ngit checkout \"$DEFAULT_BRANCH\"\ngit fetch origin --prune\n\n```\n\nThen execute `commands.reconcile + [\"--namespace\", DREAM_NS, \"--worktree-base\",\nWORKTREE_ROOT]`. It already names the original repository and the pinned helper,\nso checking out the default branch cannot downgrade the tooling.\n\nOn an error, diagnose the pinned source and repair the reported artifacts or\npreconditions before retrying. Do not fall back to a worktree-local reconciler\nor manually imitate its branch-deletion steps.\n\n### What the Reconciler Does\n\nManifest destinations are preflighted before any writes, including in dry runs.\nAbsolute\u002Ftraversal paths and symlinks escaping `.shadow\u002F` fail with a nonzero\nexit. Repair the indicated manifest field or filesystem alias before retrying;\ndo not bypass containment checks.\n\n1. **Discovers** new branches (namespace-filtered, not in `_index.md`)\n2. **Reads\u002Fvalidates** manifests from remote branches\n3. **Merges** discoveries into main's per-file shadows (semantic dedup; on an exact-text duplicate it upgrades the existing entry's metadata — unions labels, raises source trust, promotes `uncertain`→`verified` — but never alters a `refuted` status)\n4. **Mirrors** reports, manifests, patches to main's `_dreams\u002F`\n5. **Updates** `_dreams\u002F_index.md` with new entries\n6. **Updates** `_meta\u002Fstate.json`\n7. **Rebuilds** top-level `.shadow\u002F_index.md` (per-file discovery counts)\n8. **Verifies** all artifacts present (hard gate)\n9. **(Optional)** Deletes reconciled broad branches — only with `--cleanup-branches`, and only after the reconciliation has been committed and pushed (refuses on a dirty `.shadow\u002F` or when HEAD is not yet on `origin\u002F\u003Cdefault-branch>`). Coherent branches and their ancestors are retained; unreadable indexed manifests prevent cleanup rather than risking task baselines.\n\n### After Reconciliation: Commit, Push, and Cleanup\n\n```bash\ncd \"$REPO_ROOT\"\ngit add .shadow\u002F\ngit commit -m \"dream: reconcile $(date -u +%Y%m%d-%H%M%SZ) — N experiments\"\ngit pull --rebase origin \"$DEFAULT_BRANCH\" || {\n    echo \"ERROR: Rebase failed. Abort and retry manually.\"\n    git rebase --abort 2>\u002Fdev\u002Fnull\n    exit 1\n}\nif git push origin \"$DEFAULT_BRANCH\"; then\n    echo \"✓ Pushed reconciliation\"\nelse\n    echo \"ERROR: Push failed. Retry: git pull --rebase && git push\"\n    echo \"⚠️ Do NOT clean up branches until push succeeds.\"\n    exit 1\nfi\n```\n\n### Post-Reconciliation Branch Cleanup\n\nThere is **one automatic pruning path in either mode**. After reconciliation\nis committed and pushed, execute:\n\n```text\ncommands.reconcile + [\"--namespace\", DREAM_NS, \"--worktree-base\", WORKTREE_ROOT, \"--cleanup-branches\"]\n```\n\nThis is argument-array notation, not shell code. The command verifies persisted\nartifacts, remote state, descendants, and coherent retention. A broad run can\nreconcile pending coherent branches from an earlier session; the current run's\nmode is never permission to delete those branches.\n\nCleanup also retains branches whose local or remote-tracking tips are not covered\nby the indexed `tip_commit`, and never force-removes a registered worktree.\nPreserve follow-up work and commit\u002Fpush its updated reconciliation before retrying;\nrepair missing or invalid tips only after verifying the archived experiment.\n\nNever use an inline deletion loop or manually duplicate these checks. A retained\nbranch is not failed cleanup: coherent branches and their canonical index\nancestors remain available until explicit curation. `SHADOWFROG_KEEP_BRANCHES`\nstill disables automatic pruning. Worktree cleanup is independent.\n\nUnreadable lineage metadata exits nonzero before any branch deletion. Restore\nthe indicated manifest or repair the stale `_dreams\u002F_index.md` row after checking\nits descendants, then retry. Do not delete valid archives to bypass the refusal.\n\n**Worktree cleanup** happens separately (Phase 7 — see \"Worktree Pruning\"\nbelow). Worktrees can be removed immediately after branch push regardless\nof reconciliation status. Reconciled branches also have their worktree\nGC'd automatically by `dream-reconcile.py --cleanup-branches`.\n\n### Recovery\n\nIf reconciliation is interrupted: branches are already pushed (no data\nloss). Re-run reconciliation — it's idempotent. The reconciler uses\n`_dreams\u002F_index.md` as its journal: any branch already listed there is\nskipped, any branch not listed is reprocessed. The reconciler's own\nstep 8 verifies all artifacts on main; if verification fails the script\nexits non-zero — fix the cause and re-run.\n\n## Phase 7: Summary, Review, and Pruning\n\n### End-of-Session Cleanup\n\nBefore the summary, sweep leftover worktrees from the mid-batch leak\n(dreams that pushed but weren't `dream-cleanup.sh`'d before the loop\nexited). Only run this once the agent has asserted no more dreams are\nstarting **in this namespace**:\n\n```bash\nDREAM_WORKTREE_BASE=\"$WORKTREE_ROOT\" bash \"$SKILL_DIR\u002Fdream-gc.sh\" \\\n    --task-complete --namespace \"$DREAM_NS\" \\\n    --repo-root \"$REPO_ROOT\" --min-age-min 0\n```\n\nSee \"Worktree Pruning\" below for `--namespace` rationale, `--min-age-min`\nsemantics, and the other three cleanup paths.\n\n### Summary\n\n```\nDream session complete.\n  Results (by category):\n    Investigation: N tasks, M discoveries\n    Bug hunting: ...\n  Branches pushed: K\n  Branch tree:\n    main\n    +-- dream\u002F\u003Cid-1> (useful)\n    +-- dream\u002F\u003Cid-2> (dead_end)\n  Top findings:\n    - \u003Cdiscovery> -- \u003Ccategory>\n```\n\n### Experiment Review\n\nWalk through each experiment with the user. Actions:\n- **Keep** (default) — branch and report stay\n- **Delete** — remove from `_dreams\u002F`, delete remote branch\n- **Checkout** — inspect the code live\n\nWait for user confirmation before deleting any remote branch.\n\n### Branch Pruning\n\nOnly the guarded Phase 6 cleanup command performs automatic branch pruning.\nIf push failed or lineage verification was refused, fix that condition before\nretrying it. If a branch was retained for coherence or `SHADOWFROG_KEEP_BRANCHES`,\nleave it retained; do not route it to a separate deletion recipe.\n\nExplicit curation is a distinct, user-approved decision. First identify all\ndependent dreams and exported task baselines, preserve any required commits\nunder durable refs, and update consumers before retiring a branch or archive.\nRemoving an archive requires repairing its index entry and descendant references\nas well. There is no automatic expiry for coherent task baselines.\n\n### Worktree Pruning\n\nDream worktrees live OUTSIDE the repo at\n`${DREAM_WORKTREE_BASE:-\u003Csystem-temp>\u002Fshadowfrog-dreams}\u002F\u003Cns>\u002Fdream-\u003Cslug>\u002F`. There\nare four places they get cleaned up:\n\n1. **`dream-cleanup.sh`** — called by the agent after each `git push` (see\n   \"Worktree Cleanup\" earlier in this skill). Removes ONE worktree.\n2. **`dream-reconcile.py --cleanup-branches`** — after deleting a merged\n   branch, also `rm -rf`s its worktree directory. No extra command needed.\n3. **`dream-gc.sh` (auto-triggered)** — `dream-setup.py` invokes this\n   sweeper at the start of each new dream, throttled by a per-namespace\n   `.last-gc` tombstone to run at most once per `DREAM_GC_INTERVAL_MIN`\n   minutes (default 60). Catches orphaned worktrees.\n\n   Env knobs (all optional, sensible defaults):\n     - `DREAM_GC_AUTO=0` — disable the auto-trigger entirely\n     - `DREAM_GC_INTERVAL_MIN` — how often the trigger fires (default 60)\n     - `DREAM_GC_AGE_MIN` — min worktree age to sweep (default 60)\n\n4. **`dream-gc.sh --task-complete --namespace \"$DREAM_NS\"`** —\n   end-of-session sweep, run by the agent when it stops dreaming (dream\n   count reached, or genuinely blocked). Unlike the auto-trigger, this\n   mode ALSO removes `stale-registered` worktrees (valid `.git` pointer\n   but no `dream-cleanup.sh` ever ran on them — the mid-batch\n   `task_complete` leak). The agent's assertion \"I'm done dreaming\n   **in this namespace**\" is what makes this safe.\n\n   **Required:** `--namespace` (or `DREAM_NAMESPACE` env). The script\n   refuses with exit 2 if neither is given — that prevents a multi-repo\n   fleet sharing one `$DREAM_WORKTREE_BASE` from one agent's\n   `task_complete` destroying another agent's live worktrees.\n\n   `--min-age-min` is an **mtime gate, not a liveness check**. Pass `0`\n   at end-of-session to catch the freshly-pushed final batch; pass a\n   higher value (e.g. `10`) if you can't fully assert that no other\n   dream in the same namespace is in flight. Locked worktrees\n   (`git worktree lock`) are always respected — the sweeper WARNs and\n   leaves them in place.\n\n   ```bash\n   # At the end of the dream loop, before the final summary:\n   DREAM_WORKTREE_BASE=\"$WORKTREE_ROOT\" bash \"$SKILL_DIR\u002Fdream-gc.sh\" \\\n       --task-complete \\\n       --namespace \"$DREAM_NS\" \\\n       --repo-root \"$REPO_ROOT\" \\\n       --min-age-min 0\n   ```\n\nAll four paths share a single safety gate (`_worktree_safety.py`) that\nrefuses ANY path which is not strictly under `$DREAM_WORKTREE_BASE` and\ndoesn't match the exact `\u003Cbase>\u002F\u003Cns>\u002Fdream-\u003Cslug>` shape. The gate is\nunconditional — even an attacker-controlled `$DREAM_WORKTREE_BASE` cannot\ncause `rm -rf \u002F`.\n\n### Applying Dream Code\n\n```bash\n# Option 1: Merge the dream branch\ngit checkout \"$DEFAULT_BRANCH\"\ngit merge dream\u002F\u003Cid> --no-ff -m \"Adopt dream: \u003Ctitle>\"\n\n# Option 2: Cherry-pick specific commits\ngit cherry-pick \u003Ctip_commit>\n\n# Option 3: Apply the patch (if branch was pruned but commit exists)\ngit show \u003Ctip_commit> | git apply\n```\n\n## Experiment Completion Criteria\n\nA task is complete ONLY when ALL of these hold:\n\n1. Code was written or modified (non-empty `patch.diff`)\n2. At least one command was executed with exit code recorded in `Commands Run`\n3. At least one finding tied to running code (not just reading)\n4. At least one per-file `.shadow\u002F*.md` edit made\n5. Discoveries are behavioral insights, not feature descriptions\n6. `report.md` saved with all required fields\n7. Dream branch pushed to remote\n8. Reconciliation completed and verified (`report.md`, `manifest.json`,\n   `patch.diff` exist on main, `_index.md` has entry)\n\nAdditional gates:\n- **Feature design:** `## Motivation` cites specific existing code\n- **Broad compounding:** `## Compounding Delta` explains what parent code was modified\n- **Coherent mode:** mode is threaded through validation and artifacts; each\n  child has a substantive parent connection and its own goal. Siblings remain\n  free to differ. A validated schema is not a substitute for this review.\n\nA task that fails these criteria is **not completed**. If setup fails or\nthe experiment produces nothing, mark it `blocked` in the summary and\nreplace it with another experiment. Blocked tasks do not count toward the\ncategory minimum.\n\n> **After reconciliation:** run `\u002Fshadow-frog-meditate` to consolidate\n> discoveries and repair the index.\n\n### Exporting Coherent Work as SWE Tasks\n\nSelect a root-to-leaf trajectory, not a concatenation of independent siblings.\nCombining siblings requires an explicit integration experiment. Each task's\ncode baseline must be an actual retained commit, separate from conceptual\nprovenance. For sequential tasks, state which earlier requirements change.\nFor one combined task, use the final active behavioral contract: replacing\ndesign A with B does not require implementing both. Do not rewrite historical\nreports or use unsupported manifest `refute` operations to supersede a design.\n\n## Curating Dream Experiments for Upstream PRs\n\nOnce dream branches accumulate, you (or the user) may want to surface a\nfew worth submitting to the upstream project. The default AI failure mode\nis sycophancy — approving too many experiments because they look like\nwork. Resist that. Apply these heuristics:\n\n1. **The maintainer test.** For each experiment, ask: *If I submitted this\n   as a PR to an open-source repo I don't maintain, would the maintainer\n   merge it — or politely close it?* This is the only question that matters.\n2. **Devil's advocate framing.** Your job is to find reasons NOT to PR\n   each experiment. Recommend only when you cannot find a compelling\n   reason to reject.\n3. **70% rejection quota.** If you approve more than 30% of experiments\n   reviewed, your standards are too low. Re-evaluate.\n4. **The \"so what?\" test.** Would a human engineer read the report and\n   say \"so what?\" If yes, reject.\n5. **The 30-minute test.** Could a competent developer have produced\n   this in 30 minutes with a linter, TODO grep, or quick docs read? If\n   yes, it's maintenance work, not a contribution. Reject.\n6. **The novelty test.** Does the experiment reveal a non-obvious\n   behavior, hidden assumption, or unexpected interaction? If not, reject.\n7. **No credit for effort.** A 10-experiment chain that produces a minor\n   tweak is still a minor tweak. Judge the result, not the journey.\n\nWhen you do submit a PR, write the body for someone who has never seen\nthe dream branch. Include: one-paragraph \"what it does\" derived from the dream\nreport, the experiment's evidence (test output, before\u002Fafter metric),\nand an honest \"what we did not verify\" note.\n","# ShadowFrog Dream\n\nAutonomous experimentation while the user is away. Every task is an\n**experiment** — implement real code in a worktree, run it, persist as a\n**named git branch** pushed to a remote the user can write to. Dream's unique value is\nimplementation experience that **compounds across sessions**.\n\n## Modes: Broad or Coherent\n\nAccept `mode=broad` (default) or `mode=coherent`, for example\n`\u002Fshadow-frog-dream mode=coherent`. Resolve the requested mode before planning.\nCarry it into every task\u002Fsubagent prompt, manifest, report, and validation\ninvocation. Use `\u002Fshadow-frog-nap` instead when the desired deliverable is a\nlightweight feature-task brief rather than an executed experiment.\n\n**Broad mode** keeps the category, coverage, and breadth rules below.\n\n**Coherent mode regularizes parent-child edges, not siblings or a whole tree.**\nEach child has its own `goal` and identifies a parent capability, finding,\nlimitation, or design decision motivating its work. It can extend, integrate,\nchallenge, replace, simplify, or offer an alternative. The shared\n`parent_connection` format is defined in `\u002Fshadow-frog`.\n\n- Ten children of one parent may pursue ten different worthwhile directions.\n  Sibling summaries help avoid duplicates; they do not impose a common goal,\n  file-disjointness requirement, or fixed diversity quota.\n- Technical independence is not an automatic rejection. A justified alternative\n  can be coherent even without calling the parent's modules. Shared keywords,\n  a parent ID, or merely touching the same file are not enough.\n- A challenge needs a reason or evidence; do not manufacture flaws to lengthen\n  a chain. Preserve unchanged user requirements and name superseded decisions.\n- There is no fixed tree-wide feature objective. Direction can evolve through\n  substantive local transitions. Stop a path when no useful continuation exists.\n- Descendants wait for their actual parent implementation. Siblings may run in\n  parallel in separate worktrees, including on the same files. Refresh the\n  selected parent branch\u002Ftip after each accepted step rather than relying on\n  the session-start branch snapshot for newly created parents.\n\n**Precedence:** in coherent mode, skip category minimums, uncovered-file quotas,\nsaturation-driven parent rejection, unique-file\u002Fdirectory checks, mid-session\nbreadth replanning, disjoint-file assignments, and the \"breadth over depth\"\npreference below. Follow the user's total work budget; absent one, use 12\nexperiments as a ceiling, not a quota. All execution, artifact, reconciliation,\nand worktree safety requirements still apply.\n\nBefore launching each child, record its parent branch and resolved commit,\nown goal, and intended connection. Give it the parent's report, manifest,\nrelevant source\u002Fevidence, and short sibling summaries. Do not claim sibling\nfeatures are inherited code. Seeds from the base branch have no parent\nconnection; importing a prior dream uses that dream's actual branch.\n\n**Completion review:** explain what the parent made possible or revealed to be\ninadequate, the child's concrete delta, and why the result is useful. For a\nreplacement, compare the old\u002Fnew behavior against the relevant constraints.\nStructural validation cannot judge semantic coherence.\n\nCoherent branches and their canonical index ancestors are retained by the\npinned reconciler for continued exploration and reproducible task baselines.\nEvery mode uses that same guarded pruning path. Explicit later curation may\nremove branches only after checking references and preserving required commits.\nWorktrees can still be cleaned up normally after successful pushes.\n\n## Critical Invariants\n\nThese rules are stated ONCE here and enforced by helper scripts. Violating\nany of them is a completion criteria failure.\n\n### Prerequisite: `.shadow\u002F` must be git-tracked\n\nDream moves `.shadow\u002F` content **through git** — artifacts are committed onto\nthe dream branch, pushed to the remote, then read back by the reconciler via\n`git show origin\u002F\u003Cbranch> .shadow\u002F...`. If `.shadow\u002F` is gitignored (the\n\"local only\" option in `shadow-frog-init`), `git add -A` silently skips those\nfiles, nothing reaches the remote, and the reconciler finds no manifest —\n**every discovery is lost without warning**. `dream-setup.py` runs\n`git check-ignore` on a new `.shadow\u002F_dreams\u002F` child path up front and refuses\nto start if it's ignored.\nUse `shadow-frog-update` instead for local-only shadows.\n\n### Path Isolation\n\n```\nWORKTREE_BASE = \u003Csystem-temp>\u002Fshadowfrog-dreams\u002F\u003CDREAM_NS>\u002F\nWORKTREE_DIR  = $WORKTREE_BASE\u002Fdream-\u003CSLUG>\n```\n\n- Worktrees are ALWAYS in the system temp directory under\n  `shadowfrog-dreams\u002F\u003CDREAM_NS>\u002F`, NEVER in the project directory. This\n  prevents conflicts between parallel agents and keeps the main repo clean.\n- `DREAM_NS` (namespace) isolates branches per task\u002Finstance. Resolved\n  from: `DREAM_NAMESPACE` env → `TASK_INFO.json` → `.env` → repo basename.\n- Override only with `DREAM_WORKTREE_BASE` env var if the system temp volume is\n  too small. Relative overrides are resolved to an absolute path before setup\n  emits the lifecycle context.\n- `dream-setup.py` computes and enforces all paths. Use it.\n\n### Branch Naming\n\n```\nBRANCH_NAME = dream\u002F\u003CDREAM_NS>\u002F\u003CDREAM_ID>\nDREAM_ID    = YYYYMMDD-HHMMSSZ-\u003CSLUG>\n```\n\n### Artifact Format\n\n```\n.shadow\u002F_dreams\u002F\u003CDREAM_ID>\u002Freport.md\n.shadow\u002F_dreams\u002F\u003CDREAM_ID>\u002Fmanifest.json\n.shadow\u002F_dreams\u002F\u003CDREAM_ID>\u002Fpatch.diff\n```\n\nNEVER flat files (`_dreams\u002F\u003CDREAM_ID>.md`). Flat files break the pipeline.\n\n### RUN_PREFIX\n\nRepository code and tests MUST use the `RUN_PREFIX` resolved during preflight.\nWhen `RUN_PREFIX=\"uv run\"`, use it for the repository's Python\u002Fpytest commands.\nShadowFrog's standard-library helpers instead use the interpreter and absolute\ncommand arguments captured by `dream-tools.py`; their tooling version must not\ncome from the historical experiment checkout.\n\n### Reconciliation is Mandatory\n\nEvery dream branch must reconcile to main before the session ends. The\nmost common failure mode is agents pushing dream branches but never\nreconciling — losing all discoveries.\n\n**Two modes:**\n- **Parallel mode (default):** Launch a batch of 3-4 sub-agents → wait\n  for all to push → run the pinned `commands.reconcile` ONCE at the end\n  of the batch. The reconciler auto-discovers every un-reconciled dream\n  branch in the namespace — you do NOT pass branch names. One call merges\n  every pushed branch.\n- **Sequential mode (fallback when sub-agents unavailable):**\n  Complete dream → push → reconcile → verify → next dream. Adds ~30s\n  per dream but guarantees zero data loss if the session crashes\n  mid-batch.\n\nNever queue multiple un-reconciled batches; reconcile at the end of\neach batch or each individual dream.\n\n### Script Failure Recovery\n\nThe pinned helpers are self-documenting. Diagnose errors by reading their\ncurrent sources, fix the reported prerequisite or artifact, and retry the same\nchecked command. Never substitute worktree-local helpers, downgrade the mode,\nskip validation, or imitate branch deletion manually.\n\nIf the tooling snapshot is missing or changed, stop. Restore or pin a fresh\ncomplete bundle from the current installation in the controller checkout, not\nfrom a historical dream. Do not edit a snapshot to make its hash checks pass.\n\n```\nPushable remote\n  main --- .shadow\u002F (accumulated ALL discoveries)\n  |\n  +-- dream\u002F\u003Cns>\u002F\u003Cid-1>  (cycle 1, agent A, from main)\n  +-- dream\u002F\u003Cns>\u002F\u003Cid-2>  (cycle 1, agent B, from main)\n  +-- dream\u002F\u003Cns>\u002F\u003Cid-3>  (cycle 2, from dream\u002F\u003Cns>\u002F\u003Cid-1>, compounding)\n```\n\n- Branches are live — `git checkout dream\u002F\u003Cid>` runs the code\n- Shadow follows lineage — ancestor chain, not sibling branches\n- Main is the accumulator — reconciliation merges ALL discoveries\n\n### Prerequisites\n\n1. Repo cloned locally with a pushable remote where `dream\u002F...` branches are allowed\n2. ShadowFrog skills installed (`install.sh --project \u002Fpath\u002Fto\u002Frepo`)\n3. `.shadow\u002F` initialized (`\u002Fshadow-frog-init`) and tracked by git\n\nUse the user's existing repo directly when it has a remote that accepts\n`dream\u002F...` branches. If no writable remote is configured, do not start a\ndream run; the user must configure one first.\n\n## Helper Scripts\n\nThis skill bundles 7 helper scripts. **Pin current tooling before creating or\nentering an experiment worktree, or switching the controller's code branch.**\nHistorical branches can contain older helpers that silently ignore new flags.\n\nLocate `dream-tools.py` beside this currently loaded skill in the controller's\n`.github\u002Fskills\u002Fshadow-frog-dream\u002F` or `.claude\u002Fskills\u002Fshadow-frog-dream\u002F`.\nChoose a new directory in the host's run\u002Fsession workspace, **outside both the\ntarget repository and the skill-source repository**:\n\n```text\npython CURRENT_SKILL\u002Fdream-tools.py pin --repo-root REPO_ROOT --output EXTERNAL_RUN_TOOLS --mode coherent\n```\n\nUse `--mode broad` for a broad run. The command copies the current Dream and\ncore helpers\u002Finstructions, atomically writes `tooling.json` after copying, and\nprints a JSON control packet. Save the packet in the external run workspace\nand pass it unchanged to every child. This is host-local tooling, not a shadow\ndiscovery or task artifact; never commit it into the target repository.\n\nThe packet contains:\n- `commands.validate`, `commands.reconcile`, `commands.coverage`: absolute\n  argument arrays, including the captured interpreter, snapshot runner, and\n  manifest digest. Reconcile\u002Fcoverage already include `REPO_ROOT`.\n- `helper_paths`: absolute paths to the bundled lifecycle scripts\u002Fmodules.\n- `instructions`: current core\u002FDream skill copies children must use for the\n  workflow, rather than the old copies in their code worktrees.\n- `mode`, `repo_root`, and the absolute pinned `skill_dir` (`SKILL_DIR` below).\n\nExecute command arrays as arguments, not shell code. Append only the operation's\narguments: `[DREAM_ID, WORKTREE_DIR]` for validation,\n`[\"--namespace\", DREAM_NS, \"--worktree-base\", WORKTREE_ROOT]` for reconciliation,\nand optionally `[\"--cleanup-branches\"]` after committing and\npushing reconciliation. The dispatcher supplies the pinned validation mode and\nrejects mode overrides. It checks the manifest digest and all captured file\nhashes before executing the helper, preserving its output and exit status.\n\nFor example, the equivalent native command shape for validation is:\n\n```text\npython PINNED_SKILL\u002Fdream-tools.py run --digest PIN_DIGEST validate DREAM_ID WORKTREE_DIR\n```\n\n`PINNED_SKILL` and `PIN_DIGEST` come from the packet; do not fabricate them.\nKeep the snapshot while children or resumed work reference it. The run workspace\nowns its eventual cleanup; this helper never recursively deletes directories.\nRe-pin on a different host rather than reusing host-specific interpreter paths.\n\n| Script | Purpose | When to use |\n|--------|---------|-------------|\n| `dream-tools.py` | Pins current tooling and dispatches checked Python helpers | **Before worktrees** and for every validation\u002Freconciliation\u002Fcoverage call |\n| `dream-setup.py` | Creates worktree + branch with namespace isolation | **Phase 3** — start of every experiment |\n| `dream-validate.py` | Validates artifacts before push (hard gate) | **Phase 5** — before `git push` |\n| `dream-reconcile.py` | Merges dream branches into main's `.shadow\u002F` | **Phase 6** — after all experiments done |\n| `dream-coverage.py` | Computes exploration coverage map | **Phase 2** — task planning for diversity |\n| `dream-cleanup.sh` | Safely removes ONE dream worktree (with safety gate) | **After push** — replaces the old inline cleanup snippet |\n| `dream-gc.sh` | Sweeps orphan dream worktrees from `$DREAM_WORKTREE_BASE` | **Auto** — triggered by `dream-setup.py` (per-namespace throttle, default 1× \u002F hour) in orphan-only mode; also `--task-complete --namespace \"$DREAM_NS\" --min-age-min 0` for end-of-session sweep of registered-but-stale dirs. On Windows, automatic sweeping remains disabled until `dream-gc.py` replaces the POSIX-only helper. |\n\nThe shared `shadow-frog\u002F_coherence.py`, `_dream_namespace.py`, and\n`_worktree_paths.py` are captured with the Dream tools.\nNever rediscover these Python helpers relative to `WORKTREE_DIR`. All scripts\nsupport `--help`. Setup returns JSON only. Consume it through the host's native\nJSON tools, not shell exports. The remaining cleanup\u002FGC shell scripts keep their\nsafety gates; use their Python ports when available.\n\nIn shell recipes, `PYTHON_BIN` is the captured interpreter (the first element\nof `commands.validate`) and `SKILL_DIR` is the pinned `skill_dir`. Pass these\nvalues explicitly; shell variables do not persist across tool calls.\n\n## Phase 1: Preflight and Assess\n\n### Preflight Validation\n\n```bash\nREPO_ROOT=$(git rev-parse --show-toplevel)\ncd \"$REPO_ROOT\"\n\n# 0. Resolve DREAM_NAMESPACE with the same parser setup\u002Freconciliation use.\nDREAM_NAMESPACE=\"$(\"$PYTHON_BIN\" -c '\nimport sys\nsys.path.insert(0, sys.argv[1])\nfrom _dream_namespace import resolve_dream_namespace\nprint(resolve_dream_namespace(sys.argv[2]))\n' \"$SKILL_DIR\" \"$REPO_ROOT\")\" || exit 1\nexport DREAM_NAMESPACE\necho \"Dream namespace: $DREAM_NAMESPACE\"\n\n# 1. Detect default branch\nDEFAULT_BRANCH=$(git symbolic-ref refs\u002Fremotes\u002Forigin\u002FHEAD 2>\u002Fdev\u002Fnull | sed 's|refs\u002Fremotes\u002Forigin\u002F||')\nif [ -z \"$DEFAULT_BRANCH\" ]; then\n    if git show-ref --verify refs\u002Fremotes\u002Forigin\u002Fmain >\u002Fdev\u002Fnull 2>&1; then\n        DEFAULT_BRANCH=\"main\"\n    elif git show-ref --verify refs\u002Fremotes\u002Forigin\u002Fmaster >\u002Fdev\u002Fnull 2>&1; then\n        DEFAULT_BRANCH=\"master\"\n    else\n        echo \"ERROR: Cannot detect default branch. Fix: git remote set-head origin \u003Cbranch>\"\n    fi\nfi\necho \"Default branch: $DEFAULT_BRANCH\"\n\n# 2-5. Validate environment\necho \"Current branch: $(git branch --show-current)\"\necho \"Remote: $(git remote get-url origin)\"\ngit ls-remote origin HEAD >\u002Fdev\u002Fnull 2>&1 || echo \"ERROR: Cannot reach remote.\"\n[ -d .shadow ] || echo \"ERROR: .shadow\u002F not found. Run \u002Fshadow-frog-init first.\"\nmkdir -p .shadow\u002F_dreams\ngit diff --quiet && git diff --cached --quiet || echo \"ERROR: Uncommitted changes.\"\n\n# 6. Fetch all remote branches (ONE fetch for all agents)\ngit fetch origin --prune\n\n# 7. List dream branches (namespace-filtered)\nDREAM_NS=\"${DREAM_NAMESPACE:-}\"\nBRANCH_PATTERN=\"${DREAM_NS:+origin\u002Fdream\u002F${DREAM_NS}\u002F}\"\nBRANCH_PATTERN=\"${BRANCH_PATTERN:-origin\u002Fdream\u002F}\"\necho \"Available dream branches:\"\ngit branch -r | grep \"$BRANCH_PATTERN\" | sed 's|origin\u002F||' || echo \"  (none)\"\n\n# 8. Detect RUN_PREFIX from lockfiles\nif [ -f uv.lock ]; then\n    uv sync --all-groups 2>&1 | tail -3\n    RUN_PREFIX=\"uv run\"\nelif [ -f package-lock.json ]; then\n    npm install --quiet 2>&1 | tail -3\n    RUN_PREFIX=\"npx\"\nelif [ -f yarn.lock ]; then\n    yarn install --silent 2>&1 | tail -3\n    RUN_PREFIX=\"npx\"\nelse\n    RUN_PREFIX=\"\"\nfi\necho \"RUN_PREFIX='$RUN_PREFIX'\"\n\n# 9. List compoundable experiments\necho \"\"\necho \"=== COMPOUNDABLE EXPERIMENTS ===\"\nif [ -f .shadow\u002F_dreams\u002F_index.md ]; then\n    awk -F'|' 'NR>2 && \u002Fuseful\u002F {\n        gsub(\u002F \u002F,\"\",$2); gsub(\u002F \u002F,\"\",$4); gsub(\u002F \u002F,\"\",$6);\n        gsub(\u002F^ +| +$\u002F,\"\",$5);\n        if ($2 != \"\" && $6 != \"\") print $6 \" | \" $3 \" | \" $5\n    }' .shadow\u002F_dreams\u002F_index.md\n    COMPOUNDABLE=$(awk -F'|' 'NR>2 && \u002Fuseful\u002F {gsub(\u002F \u002F,\"\",$2); if ($2 != \"\") c++} END {print c+0}' .shadow\u002F_dreams\u002F_index.md)\n    echo \"Total compoundable: $COMPOUNDABLE\"\nelse\n    echo \"(none — first dream session)\"\nfi\n```\n\n**If any check prints ERROR, STOP.** Do not use `exit 1` — check output\nand stop at the agent level.\n\n(`RUN_PREFIX` MUST be threaded into every subagent prompt for repository\ncode\u002Ftests. Helper commands use the pinned packet's interpreter instead.)\n\n### Snapshot Branch State\n\nAfter the single `git fetch`, capture dream branches and pass to all\nsub-agents — they do NOT fetch independently.\n\n```bash\nDREAM_NS=\"${DREAM_NAMESPACE:-}\"\nBRANCH_FILTER=\"${DREAM_NS:+origin\u002Fdream\u002F${DREAM_NS}\u002F}\"\nBRANCH_FILTER=\"${BRANCH_FILTER:-origin\u002Fdream\u002F}\"\ngit branch -r --format='%(refname:short) %(objectname:short)' \\\n  | grep -F \"$BRANCH_FILTER\" \\\n  | sed 's|origin\u002F||' > .shadow\u002F_dreams\u002F.branch-map.txt\ncat .shadow\u002F_dreams\u002F.branch-map.txt\n\n# Initialize session tracking (orchestrator-only; agents do NOT write here)\n: > .shadow\u002F_dreams\u002F.session-branches.txt\n```\n\n### Assess Codebase\n\nRead `_meta\u002Fstate.json`, `_index.md`, existing discoveries, and **past\ndream reports** in `_dreams\u002F`.\n\n### Build Exploration Coverage Map\n\nRun the packet's `commands.coverage`. It already contains the pinned\ninterpreter\u002Ftool version and the original repository path.\n\n**Coverage definition:** A file is \"covered\" only when its shadow has\n≥1 behavioral discovery (line starting with `- `). Placeholder-only = NOT covered.\n\n**Scoped exploration (`--scope`)** — pass `--scope \u003Cpath-prefix>` (repeatable)\nto restrict the coverage map to a specific subtree. Use this when the\nbroader repo is well-explored but a particular area (e.g., a known\nfrontier of bugs, a newly-added module, a subsystem the user just\nflagged) deserves a focused dream session. All counts (totals, %,\nsaturated, fan-in, per-dir) are computed over the scoped subset only.\n\nFor one subtree, append `[\"--scope\", \"src\u002Fauth\u002F\"]` to `commands.coverage`.\nFor several, append repeated `--scope` argument pairs.\n\nIn broad mode, when using `--scope`, the per-category task quotas (Phase 2) still apply\nbut are interpreted against the scoped subset. Don't use scoped\nexploration as the default — pick it only when there's a concrete reason\nto concentrate effort.\n\n### Review Past Dreams (Required)\n\nIn coherent mode, use the index to select parents, then read the selected\nparent reports\u002Fmanifests and relevant ancestor evidence. Do not reread every\nreport or reject a useful parent merely because its files are well covered.\n\nWhen compoundable experiments exist (preflight step 9):\n- Broad mode: read the candidate reports. Coherent mode: read the selected\n  parent's report\u002Fmanifest and the relevant ancestor evidence.\n- Choose which to continue (extending, fixing, integrating)\n- Note `dead_end` experiments to avoid repeating\n- Trace lineage via the `parent` column in `_dreams\u002F_index.md`\n\n**Compounding quality gate** — before choosing to compound from a parent:\n\n1. Read the parent's `report.md` AND `manifest.json`\n2. Verify the parent has a non-empty `patch.diff` (prose-only parents\n   are low-value — prefer parents with working code)\n3. Broad mode: identify a specific file\u002Ffunction to modify or extend.\n   Coherent mode: identify the parent capability, finding, or decision that\n   motivates the child; a technically independent alternative is allowed.\n4. Broad mode: check saturation (8+ discoveries) and prefer a fresh target\n   unless there is a concrete new angle. Coherent mode has no saturation gate;\n   assess whether the proposed continuation adds useful evidence or capability.\n5. Log your compounding intent: \"I will extend parent's retry logic in\n   `src\u002Fhttp.py` to handle connection timeouts\" — vague \"continue\n   exploring\" is NOT compounding\n\n**First dream session:** if preflight step 9 shows `(none)`, all tasks\nbranch from main.\n\n## Phase 2: Plan\n\nIn broad mode, generate a concrete plan. **Target 12 tasks (2 per category).** On small\ncodebases (\u003C30 source files), minimum 6 tasks across 4+ categories.\n\n### The 6 Investigation Categories\n\n| Category | Priority signals | Experiment |\n|----------|------------------|------------|\n| **Investigation** | Files with 0-2 discoveries, untraced import chains, `uncertain` entries | Test behavior hypotheses with assertions |\n| **Bug hunting** | Error handling, concurrency, unvalidated inputs | Fuzz inputs, trigger error paths, reproduce races |\n| **Feature design** | TODOs, FIXMEs, user-facing gaps, integration opportunities | Implement the feature, run it, evaluate integration |\n| **Refactoring** | God classes, duplication, high coupling | Refactor, run existing tests, measure complexity |\n| **Optimization** | Hot paths, nested loops, repeated I\u002FO, missing caches | Profile, optimize, measure before\u002Fafter |\n| **Security audit** | Auth, data handling, deserialization, user inputs | Test adversarial inputs and injection vectors locally |\n\n**Exception — user-directed focus**: If the user specifies a focus area\n(e.g., \"dream focus on security\"), allocate ALL tasks to that category.\n\n### Task Plan Format\n\nEach task specifies **base branch**, **primary target file(s)**, and **why**:\n\n```\nTasks (by category):\n  Investigation:\n    1. [title] — write tracing tests for [target]\n       Base: main\n       Target: src\u002Fauth\u002Fvalidator.py (UNCOVERED, 12 refs)\n       Why: High fan-in utility with no shadow coverage\n  Bug hunting:\n    1. [title] — fuzz [target]\n       Base: dream\u002F\u003Cns>\u002F\u003Cprior-id> (compounds prior)\n       Target: src\u002Fparsers\u002Fcsv.py (extending parent's failing tests)\n       Why: Parent found 2 crashes, need to verify fixes\n  ...\n```\n\n### Diversity Rules\n\nIn broad mode, prefer breadth over depth: more files with 2-3 discoveries over\none file with 20. Prevent fixation with these rules:\n\n1. **Max 2 tasks per source file** (unless prior dream left concrete follow-up)\n2. **≥30% of tasks on uncovered files** (from coverage map)\n3. **≥2 tasks on \"deep\" files** (utilities, internals, converters)\n4. **Vary directories** — no 3+ consecutive tasks in same dir\n\n**Self-check before finalizing:** unique target files ≥ 60% of task count,\nuncovered file tasks ≥ 30%, no file in > 2 tasks. Swap if failing.\n\n**Escape hatches** (document justification): prior dream's failing test,\nconcrete untested hypothesis, file is 500+ lines with unexplored sections,\ncodebase has \u003C20 source files.\n\n### Task Design\n\nEach task needs: **category**, **hypothesis**, **what to implement**,\n**base branch**, **primary target** (with coverage status), **why this\ntarget**, **scope** (hours, not days), and **success criteria**.\n\nAlso include the selected **mode**. Coherent tasks additionally carry their\nown **goal** and **parent_connection**, not a shared sibling\u002Ftree objective.\nCategory still describes the experiment, but coherent mode has no category quota.\n\nFor example, \"Fuzz the CSV parser with malformed inputs to reproduce crashes\nor silent corruption\" is a concrete experiment; \"Review error handling\" is not.\n\n### Feature Design: Motivation Required\n\nFeature experiments must address a real gap identified in existing code.\nAnswer: \"Why would maintainers want this?\" with a specific code reference.\nThe feature must connect to the existing codebase (imports, modifies,\nreplaces duplication). Standalone modules with only stdlib don't qualify.\n\n### Vary Your Approach\n\nEach experiment should have unique structure driven by its hypothesis. If\nyou find yourself copying the same module layout (one source file + one\ntest file, identical importlib hack) across experiments, you're optimizing\nfor throughput over insight. Vary your approach: some experiments modify\nexisting files, some add tests for existing code, some create minimal\nscripts, some refactor existing modules.\n\n### File Selection Guidance\n\nAgents gravitate toward entry points. Evaluation shows this causes missed bugs.\n\n**High-value targets typically missed:**\n- High fan-in files (imported by many, rarely explored directly)\n- Internal\u002Fprivate modules (`_internal\u002F`, `_utils\u002F`, `_compat\u002F`)\n- Conversion\u002Fserialization code (parse, encode, format, marshal)\n- Error handling paths (exception hierarchies, fallback logic)\n\n**Avoid:** Starting from `__init__.py`, skipping \"boring\" files, same\ndirectory 3+ times, ignoring files with few public symbols.\n\n## Phase 3: Execute Tasks\n\nWork through the plan. **Launch 3-4 experiments in parallel** via\nsub-agents. Each handles the full lifecycle: create worktree → implement\n→ test → write shadow + manifest + report → commit → push → clean up.\nIf sub-agents are unavailable, fall back to sequential execution.\n\nIn coherent mode, a parallel batch can contain diverse siblings of an already\navailable parent. Never launch a descendant before its parent exists. Include\nthe mode, goal, connection, and expected parent commit in each child prompt.\n\n**Each experiment runs in a separate git worktree.** The worktree IS the\ndream branch (created with `-b`). After pushing, the worktree is removed\nbut the branch persists on the remote.\n\n### Reading Before Implementing\n\nBefore implementing, read the target source and its shadow, plus shadows of\nreferenced\u002Freferencing files. Identify current behavior, edge cases, and\nimplicit contracts. Reading is preparation; the deliverable is code written\nand run, with results recorded.\n\n### Experiment Setup\n\nUse `dream-setup.py` to create worktrees (handles all path computation,\nnamespace resolution, worktree creation, and validation):\n\nUse the absolute setup helper from `helper_paths[\"dream-setup.py\"]` with the\ncaptured Python interpreter. The equivalent command shape is:\n\n```text\npython PINNED_SKILL\u002Fdream-setup.py --slug t01-csv-fuzzer --repo-root REPO_ROOT\npython PINNED_SKILL\u002Fdream-setup.py --slug t03-extend --repo-root REPO_ROOT --base-branch dream\u002F\u003Cns>\u002F\u003Cprior-id>\n```\n\nCheck the exit code before consuming JSON. Keep the returned `repo_root`,\n`default_branch`, `dream_ns`, `dream_id`, `branch_name`, `parent_branch`,\n`worktree_dir`, `worktree_root`, `worktree_base`, `base_commit`, `run_prefix`,\nand `slug` in the agent's task state. Uppercase names in later recipes refer\nto these values. Forward the canonical `worktree_root` to reconciliation\nas `--worktree-base` and to shell cleanup\u002FGC as `DREAM_WORKTREE_BASE`.\n\n**If `dream-setup.py` fails or is not found:** Apply the Script Failure\nRecovery rule (diagnose the pinned script and retry safely). Common causes:\nmissing git remote, branch already exists, or temp-directory permissions.\n\nDo not infer the current tool location from the experimental worktree. The\npacket and its outside-repository snapshot remain authoritative, even if the\ncontroller checkout later changes branches.\n\n**If worktree creation fails:** mark task `blocked`, replace with another.\n\n### What Meaningful Compounding Looks Like\n\nIn broad mode, compounding means **actively engaging with the parent's code**, not just\nsitting on its branch. Valid compounding approaches:\n- **Extend**: import or call the parent's modules and build on them\n- **Modify**: edit the parent's code to fix limitations noted in its report\n- **Refactor**: restructure the parent's implementation for better design\n- **Integrate**: wire the parent's standalone module into the real codebase\n- **Test deeper**: add edge-case tests for the parent's implementation\n\nDon't assume the parent dream's code is complete or frozen — iterative\nimprovement is the whole point. If you can't find anything meaningful to\nbuild on, start fresh from main instead.\n\nIn broad mode, compounding that only adds a new standalone module beside the parent's\ncode (with no imports, edits, or integration) is NOT compounding — it's\na fresh experiment on the wrong branch.\n\nIn coherent mode, apply the parent-connection review instead: a standalone\nalternative is allowed if it substantively responds to the parent's findings\nor design, rather than being unrelated work parked on the same branch.\n\n### Run\n\nImplement the experiment, run tests\u002Fbuilds, and debug as needed. Record what\nworked, failed, or surprised you as you go.\n\n### Write Shadow Discoveries\n\n**On the dream branch** (in the worktree), NOT on main.\n\n**Every experiment MUST write ≥1 discovery to a per-file `.shadow\u002F*.md`.**\nAuthoring order: write the human-readable shadow first, then mirror every\ndiscovery into `manifest.json`. For reconciliation the **manifest is the\nsource of truth** — the reconciler merges manifest entries into main, so a\ndiscovery that is missing from the manifest never reaches main. The per-file\nshadow is the human-readable copy (and a required validate gate), not the\npropagation path.\n\nFollow the dedup and writing rules in `\u002Fshadow-frog`. Dream discoveries\nare typically `source: exploration`. Mark `verified` when confirmed by\nrunning code; `uncertain` if not fully testable.\n\nNew discoveries start with visible `citation_score: 0`. Keep that field in\nthe corresponding manifest entry as well. Existing knowledge that informed\nthe task can be cited once through the core increment helper or reported to\nthe coordinator for serialized updates. Do not count merely enumerated entries.\nScores are approximate within the relevant checkout; reconciliation preserves\nthe larger score when the same claim is supplied again, rather than summing\ninherited counts. Counter-only branch edits are not imported unless represented\nin a matching manifest discovery; they do not justify unsupported `op` values.\n\n#### How to Append\n\nFind the `##`\u002F`###` heading for the symbol, then:\n- Placeholder `_No discoveries yet._` → replace with discovery\n- Existing discoveries → append after last bullet\n- No heading → create before `## Cross-References`\n\n#### Label Triage (REQUIRED)\n\nAfter writing each discovery, evaluate whether it deserves any of the\nfive actionable labels from `\u002Fshadow-frog` (`bug`, `security`,\n`performance`, `feature-gap`, `tech-debt`), using that skill's definitions.\n\nRules:\n- Apply labels to BOTH the in-file discovery markdown AND the\n  `manifest.json` discovery entry (`\"labels\": [\"bug\"]`). The reconciler\n  uses the manifest as source of truth; the in-file copy is for humans\n  reading the shadow directly.\n- Multiple labels are fine when accurate: `labels: [bug, security]`.\n- Omit labels for pure behavioral observations (\"retries N times before\n  giving up\", \"default timeout is 30s\") — these are knowledge, not\n  action items.\n- Do not apply labels speculatively. The label says \"an engineer should\n  act on this.\" If you wouldn't act on it, don't label it.\n\nExample:\n\n```\n- \u002Fapi\u002Fupload accepts paths from request body without normalization,\n  allowing `..\u002F` traversal into \u002Fetc\u002F.\n  _(verified, source: exploration, labels: [bug, security], citation_score: 0)_\n  Dream report: `_dreams\u002F20260518-161200Z-upload-traversal\u002F`\n```\n\n`dream-validate.py` emits non-blocking warnings when discovery text\ncontains label-signal keywords but no label is set. Treat those\nwarnings as a prompt to re-check the triage, not as a directive.\n\n#### Anchor Rules\n\n- About existing code → anchor to that symbol\n- Spans 3+ files → `_cross\u002F\u003Cslug>.md`\n- Project-wide convention → `_prefs.md`\n- **Only create shadows for base-codebase files** — experiment-only files\n  don't get shadows (the branch IS the artifact). Anchor findings to the\n  existing code they relate to.\n\n#### Cross-Cutting Discoveries\n\nWhen you see the same behavior in 3+ files, create a `_cross\u002F\u003Cslug>.md`\nrather than repeating the discovery in each per-file shadow. Add\nback-pointers in each file's `## Cross-References` section.\n\n#### Discovery Quality\n\nDiscoveries must be **self-contained process knowledge** — understandable\nfrom the base codebase without checking out the dream branch. Capture what\nwas learned, how to apply it, and what to avoid, not a description of the\nexperiment-only artifact.\n\n- **Good:** \"agent.py's retry loop catches all exceptions including OOM,\n  masking fatal errors that should crash immediately.\"\n- **Bad:** \"The implemented PluginFramework has PluginRegistry, PluginManager,\n  and 7 lifecycle hooks.\" This describes a branch-only artifact.\n\nPer-file discoveries should reference the dream report:\n\n```\n- Retrying with exponential backoff recovers from 99% of transient errors,\n  but must exclude 4xx or it retries bad requests for 30s.\n  _(verified, source: exploration, citation_score: 0)_\n  Dream report: `_dreams\u002F20250612-143012Z-retry-logic\u002F`\n```\n\n### Write Discovery Manifest\n\nAfter shadow writes, create `.shadow\u002F_dreams\u002F$DREAM_ID\u002Fmanifest.json`:\n\n```json\n{\n  \"dream_id\": \"\u003CDREAM_ID>\",\n  \"branch\": \"\u003CBRANCH_NAME>\",\n  \"parent_branch\": \"main\",\n  \"mode\": \"broad\",\n  \"category\": \"bug hunting\",\n  \"verdict\": \"useful\",\n  \"title\": \"CSV Parser Edge Cases\",\n  \"discoveries\": [\n    {\n      \"op\": \"add\",\n      \"anchor\": \"src\u002Fparsers\u002Fcsv.py::parse_row\",\n      \"text\": \"Unescaped quotes in fields cause silent truncation.\",\n      \"status\": \"verified\",\n      \"source\": \"exploration\",\n      \"labels\": [\"bug\"],\n      \"citation_score\": 0,\n      \"also_involves\": [\"src\u002Fparsers\u002Futils.py::unescape\"],\n      \"dream_report\": \"_dreams\u002F\u003CDREAM_ID>\u002F\"\n    }\n  ],\n  \"cross_cutting\": []\n}\n```\n\n**Anchor format:** `file::symbol` with bare names (no backticks). The\nreconciler handles normalization.\n\nFor coherent experiments, set `\"mode\": \"coherent\"`, add a nonempty `\"goal\"`\nfor this experiment, and include `\"parent_connection\"` in the shared\n`\u002Fshadow-frog` format when `parent_branch` is a prior `dream\u002F...` branch.\nSeeds use null or omit the connection. `parent_branch` is the authoritative\nparent reference; siblings need not share goals or modify different files.\nThese fields survive reconciliation in the archived manifest.\n\nManifest `op` values: only `add` is supported by the reconciler today.\n`update` and `refute` are reserved keywords — `dream-validate.py` will\nreject any discovery whose `op` is not `add`. To revise or contradict an\nexisting discovery, run a meditate session against main's `.shadow\u002F`\ninstead of trying to do it from a dream branch.\n\n`citation_score` on per-file or cross-cutting manifest entries is a nonnegative\ninteger, defaulting to 0. It is a reuse hint, never a verification or trust signal.\n\n**Hard gate — discoveries must be mirrored into per-file shadows.** The\nreconciler merges `manifest.json` entries into main directly (so discoveries\nare not lost at merge time), but the branch's per-file shadows must ALSO be\nupdated so human PR reviewers can read the discoveries in context. If\n`manifest.json` declares discoveries but no `.shadow\u002F*.md` files outside\n`_dreams\u002F` are modified in the branch diff vs `base_commit`,\n`dream-validate.py` rejects the dream. Always write each discovery into BOTH\nthe corresponding per-file shadow (or `.shadow\u002F_cross\u002F`) AND the manifest\nbefore staging.\n\n### Save Dream Report\n\nSave as `.shadow\u002F_dreams\u002F$DREAM_ID\u002Freport.md`:\n\n```markdown\n---\ndream_id: \"\u003CDREAM_ID>\"\ncategory: bug hunting\nverdict: useful\nbase_commit: \"\u003CBASE_COMMIT>\"\nbranch: \"\u003CBRANCH_NAME>\"\nparent_branch: \"main\"\nmode: broad\nremote: \"origin\"\nrelated_symbols:\n  - \"src\u002Fparsers\u002Fcsv.py::parse_row\"\nbuilds_on: []\n---\n\n# CSV Parser Edge Cases\n\n## Motivation\n\u003Ccite specific existing files\u002Fsymbols where gap was identified>\n\n## Compounding Delta\n\u003CONLY for a prior-dream parent — what parent code or design was engaged and changed>\n\n## Parent Connection\n\u003Ccoherent mode: own goal, relation, parent basis, delta, preserved constraints,\nand superseded decisions; explain alternatives even when technically independent>\n\n## Hypothesis\n\u003Cwhat we expected to learn>\n\n## Implementation\n\u003Ckey decisions, approach>\n\n## Commands Run\n\u003Cexact commands with exit codes>\n\n## Evaluation\n\u003Cresults, what worked\u002Fdidn't>\n\n## Takeaways\n\u003Clessons, gotchas>\n\n## Verdict Details\n\u003Cwhy useful\u002Fdead_end>\n```\n\n| Field | Required | Values |\n|-------|----------|--------|\n| `dream_id` | yes | `YYYYMMDD-HHMMSSZ-slug` |\n| `category` | yes | one of the 6 categories |\n| `verdict` | yes | `useful` or `dead_end` |\n| `base_commit` | yes | SHA branched from |\n| `branch` | yes | full branch name |\n| `parent_branch` | yes | `main` or prior branch path |\n| `mode` | coherent runs | `broad` (default) or `coherent`; must match manifest and validator |\n| `related_symbols` | yes | `file::symbol` refs |\n\n**`tip_commit` is NOT in the report.** Including the final commit SHA\ncreates a chicken-and-egg problem (SHA changes when report is committed).\nThe reconciler derives it via `git rev-parse origin\u002F$BRANCH` and records\nit in `_dreams\u002F_index.md`.\n\n**Verdict** is the agent's assessment (set once, immutable):\n- `useful` — produced actionable findings, working code, or valuable lessons\n- `dead_end` — approach doesn't work; documented why so future dreams skip\n\n### Validate, Commit, Push\n\nValidation must use `commands.validate` from the pinned packet. Its mode was\nfixed before the worktree was created; no mode override or local-helper fallback\nis allowed. Carry this exact command prefix into each subagent prompt.\n\n```bash\ncd \"$WORKTREE_DIR\"\n\n# 1. Generate diff (exclude .shadow\u002F and common build artifacts)\ngit add -A -- ':!.dream_parent' ':!__pycache__\u002F' ':!.pytest_cache\u002F'\ngit commit -m \"dream: $SLUG\"\nmkdir -p .shadow\u002F_dreams\u002F\"$DREAM_ID\"\ngit diff \"$BASE_COMMIT\" HEAD -- \\\n    ':!.shadow\u002F' ':!__pycache__\u002F' ':!*.pyc' ':!.pytest_cache\u002F' \\\n    ':!node_modules\u002F' ':!*.lock' ':!dist\u002F' ':!build\u002F' \\\n    > .shadow\u002F_dreams\u002F\"$DREAM_ID\"\u002Fpatch.diff\n[ ! -s .shadow\u002F_dreams\u002F\"$DREAM_ID\"\u002Fpatch.diff ] && echo \"WARNING: Empty diff\"\n\n```\n\n**2. Validate (hard gate):** execute `commands.validate + [DREAM_ID,\nWORKTREE_DIR]`. The copied runner verifies the tooling and passes the pinned\n`--mode` to the copied validator. Stop on any nonzero exit; fix the artifact or\ntooling issue and retry. File-existence checks are not a substitute for validation.\n\n**3. Only after validation succeeds, commit and push:**\n\n```bash\ngit add -A -- ':!.dream_parent'\ngit commit -m \"dream: $SLUG — final with report and manifest\"\nif git push origin \"$BRANCH_NAME\"; then\n    echo \"Pushed: $BRANCH_NAME\"\nelse\n    echo \"ERROR: Push failed. Keep worktree for recovery.\"\n    exit 1\nfi\n```\n\n**Do NOT write to `.session-branches.txt`** — that is managed by the\norchestrator after all agents complete. Agents only push their branch;\nthe orchestrator discovers pushed branches from the remote.\n\n### Worktree Cleanup\n\n```bash\nDREAM_WORKTREE_BASE=\"$WORKTREE_ROOT\" \\\n    bash \"$SKILL_DIR\u002Fdream-cleanup.sh\" \"$WORKTREE_DIR\" --repo-root \"$REPO_ROOT\"\n```\n\n`dream-cleanup.sh` does the equivalent of `git worktree remove --force`\nfollowed by `git worktree prune`, with a safety-gated `rm -rf` fallback if\nworktree removal silently fails. The fallback only accepts paths matching\n`\u003Cworktree_root>\u002F\u003Cns>\u002Fdream-\u003Cslug>`\nexactly; any other path is refused.\n\nRemove as you go. If push failed, keep the worktree.\n\n### Mid-Session Diversity Check\n\nThis breadth check applies to broad mode. In coherent mode, review edge quality\nand sibling duplication instead; do not swap out a relevant continuation just\nto increase unique-file counts.\n\nAfter completing roughly half of your planned tasks, pause and review:\n\n1. **Count unique primary target files** explored so far. If fewer than\n   50% of completed tasks targeted distinct files, remaining tasks MUST\n   target new files.\n2. **Check for re-exploration** — are any completed tasks exploring files\n   already well-covered before this session? Swap remaining tasks for\n   uncovered ones.\n3. **Review coverage map delta** — if fewer than 2 previously uncovered\n   files explored, prioritize uncovered files for remaining tasks.\n4. **Adjust the plan** — swap, add, or reorder remaining tasks. The plan\n   is a starting point, not a contract.\n\nThis prevents the fixation failure mode where the first half discovers a\nrich area and the second half keeps digging there instead of spreading.\n\n## Phase 4: AFK-Safe Patterns\n\n1. Worktrees are outside the repo — writes don't trigger approval\n2. Temp scripts go in `\u002Ftmp\u002Fshadow-dream-\u003Cslug>.*`\n3. Never modify main directly — only during reconciliation\n4. Clean up worktrees after push\n5. Shadow writes on dream branches are safe\n\n## Phase 5: Parallel Agent Rules\n\n1. Broad mode targets different files. Coherent siblings may target the same files in their separate worktrees.\n2. Each agent gets its own branch (inherently isolated)\n3. Each agent writes its own manifest in its `$DREAM_ID\u002F` directory\n4. Do NOT write to main or shared files (`_index.md`, `state.json`)\n5. Do NOT update shared indexes or `state.json` — reconciled post-dream by orchestrator\n6. Broad mode: fetch once and use the initial snapshot. Coherent mode: after a\n   parent is pushed, the orchestrator refreshes that parent's ref\u002Fcommit and\n   branch map before launching its children. Siblings share the refreshed\n   snapshot; subagents never fetch independently.\n7. Manifest anchors use bare symbol names (reconciler normalizes)\n8. Thread `RUN_PREFIX` into every subagent prompt\n9. Include `WORKTREE_ROOT`, `WORKTREE_BASE`, and `DREAM_NS` in every subagent prompt\n10. Dream artifacts MUST use subdirectory format — flat files are a\n    completion criteria violation (see Critical Invariants → Artifact Format)\n11. Thread the selected mode and pinned tool packet into every prompt. For\n    coherent children, include their own goal, parent packet, connection, and\n    expected parent commit. Use the supplied validation command; never resolve\n    a helper from the child's installed skill directories.\n\n## Phase 6: Reconcile to Main\n\n**⚠️ CRITICAL: Reconciliation is MANDATORY at the end of every dream batch.**\nSee Critical Invariants → Reconciliation is Mandatory (above) for the\nparallel-vs-sequential mode definitions and the auto-discover rule. Do\nNOT defer reconciliation across batches.\n\nThe `_index.md` entry is your sequential-mode checkpoint — any dream\nlisted there is safe if the session crashes.\n\nUse the reconciliation script:\n\n```bash\ncd \"$REPO_ROOT\"\ngit checkout \"$DEFAULT_BRANCH\"\ngit fetch origin --prune\n\n```\n\nThen execute `commands.reconcile + [\"--namespace\", DREAM_NS, \"--worktree-base\",\nWORKTREE_ROOT]`. It already names the original repository and the pinned helper,\nso checking out the default branch cannot downgrade the tooling.\n\nOn an error, diagnose the pinned source and repair the reported artifacts or\npreconditions before retrying. Do not fall back to a worktree-local reconciler\nor manually imitate its branch-deletion steps.\n\n### What the Reconciler Does\n\nManifest destinations are preflighted before any writes, including in dry runs.\nAbsolute\u002Ftraversal paths and symlinks escaping `.shadow\u002F` fail with a nonzero\nexit. Repair the indicated manifest field or filesystem alias before retrying;\ndo not bypass containment checks.\n\n1. **Discovers** new branches (namespace-filtered, not in `_index.md`)\n2. **Reads\u002Fvalidates** manifests from remote branches\n3. **Merges** discoveries into main's per-file shadows (semantic dedup; on an exact-text duplicate it upgrades the existing entry's metadata — unions labels, raises source trust, promotes `uncertain`→`verified` — but never alters a `refuted` status)\n4. **Mirrors** reports, manifests, patches to main's `_dreams\u002F`\n5. **Updates** `_dreams\u002F_index.md` with new entries\n6. **Updates** `_meta\u002Fstate.json`\n7. **Rebuilds** top-level `.shadow\u002F_index.md` (per-file discovery counts)\n8. **Verifies** all artifacts present (hard gate)\n9. **(Optional)** Deletes reconciled broad branches — only with `--cleanup-branches`, and only after the reconciliation has been committed and pushed (refuses on a dirty `.shadow\u002F` or when HEAD is not yet on `origin\u002F\u003Cdefault-branch>`). Coherent branches and their ancestors are retained; unreadable indexed manifests prevent cleanup rather than risking task baselines.\n\n### After Reconciliation: Commit, Push, and Cleanup\n\n```bash\ncd \"$REPO_ROOT\"\ngit add .shadow\u002F\ngit commit -m \"dream: reconcile $(date -u +%Y%m%d-%H%M%SZ) — N experiments\"\ngit pull --rebase origin \"$DEFAULT_BRANCH\" || {\n    echo \"ERROR: Rebase failed. Abort and retry manually.\"\n    git rebase --abort 2>\u002Fdev\u002Fnull\n    exit 1\n}\nif git push origin \"$DEFAULT_BRANCH\"; then\n    echo \"✓ Pushed reconciliation\"\nelse\n    echo \"ERROR: Push failed. Retry: git pull --rebase && git push\"\n    echo \"⚠️ Do NOT clean up branches until push succeeds.\"\n    exit 1\nfi\n```\n\n### Post-Reconciliation Branch Cleanup\n\nThere is **one automatic pruning path in either mode**. After reconciliation\nis committed and pushed, execute:\n\n```text\ncommands.reconcile + [\"--namespace\", DREAM_NS, \"--worktree-base\", WORKTREE_ROOT, \"--cleanup-branches\"]\n```\n\nThis is argument-array notation, not shell code. The command verifies persisted\nartifacts, remote state, descendants, and coherent retention. A broad run can\nreconcile pending coherent branches from an earlier session; the current run's\nmode is never permission to delete those branches.\n\nCleanup also retains branches whose local or remote-tracking tips are not covered\nby the indexed `tip_commit`, and never force-removes a registered worktree.\nPreserve follow-up work and commit\u002Fpush its updated reconciliation before retrying;\nrepair missing or invalid tips only after verifying the archived experiment.\n\nNever use an inline deletion loop or manually duplicate these checks. A retained\nbranch is not failed cleanup: coherent branches and their canonical index\nancestors remain available until explicit curation. `SHADOWFROG_KEEP_BRANCHES`\nstill disables automatic pruning. Worktree cleanup is independent.\n\nUnreadable lineage metadata exits nonzero before any branch deletion. Restore\nthe indicated manifest or repair the stale `_dreams\u002F_index.md` row after checking\nits descendants, then retry. Do not delete valid archives to bypass the refusal.\n\n**Worktree cleanup** happens separately (Phase 7 — see \"Worktree Pruning\"\nbelow). Worktrees can be removed immediately after branch push regardless\nof reconciliation status. Reconciled branches also have their worktree\nGC'd automatically by `dream-reconcile.py --cleanup-branches`.\n\n### Recovery\n\nIf reconciliation is interrupted: branches are already pushed (no data\nloss). Re-run reconciliation — it's idempotent. The reconciler uses\n`_dreams\u002F_index.md` as its journal: any branch already listed there is\nskipped, any branch not listed is reprocessed. The reconciler's own\nstep 8 verifies all artifacts on main; if verification fails the script\nexits non-zero — fix the cause and re-run.\n\n## Phase 7: Summary, Review, and Pruning\n\n### End-of-Session Cleanup\n\nBefore the summary, sweep leftover worktrees from the mid-batch leak\n(dreams that pushed but weren't `dream-cleanup.sh`'d before the loop\nexited). Only run this once the agent has asserted no more dreams are\nstarting **in this namespace**:\n\n```bash\nDREAM_WORKTREE_BASE=\"$WORKTREE_ROOT\" bash \"$SKILL_DIR\u002Fdream-gc.sh\" \\\n    --task-complete --namespace \"$DREAM_NS\" \\\n    --repo-root \"$REPO_ROOT\" --min-age-min 0\n```\n\nSee \"Worktree Pruning\" below for `--namespace` rationale, `--min-age-min`\nsemantics, and the other three cleanup paths.\n\n### Summary\n\n```\nDream session complete.\n  Results (by category):\n    Investigation: N tasks, M discoveries\n    Bug hunting: ...\n  Branches pushed: K\n  Branch tree:\n    main\n    +-- dream\u002F\u003Cid-1> (useful)\n    +-- dream\u002F\u003Cid-2> (dead_end)\n  Top findings:\n    - \u003Cdiscovery> -- \u003Ccategory>\n```\n\n### Experiment Review\n\nWalk through each experiment with the user. Actions:\n- **Keep** (default) — branch and report stay\n- **Delete** — remove from `_dreams\u002F`, delete remote branch\n- **Checkout** — inspect the code live\n\nWait for user confirmation before deleting any remote branch.\n\n### Branch Pruning\n\nOnly the guarded Phase 6 cleanup command performs automatic branch pruning.\nIf push failed or lineage verification was refused, fix that condition before\nretrying it. If a branch was retained for coherence or `SHADOWFROG_KEEP_BRANCHES`,\nleave it retained; do not route it to a separate deletion recipe.\n\nExplicit curation is a distinct, user-approved decision. First identify all\ndependent dreams and exported task baselines, preserve any required commits\nunder durable refs, and update consumers before retiring a branch or archive.\nRemoving an archive requires repairing its index entry and descendant references\nas well. There is no automatic expiry for coherent task baselines.\n\n### Worktree Pruning\n\nDream worktrees live OUTSIDE the repo at\n`${DREAM_WORKTREE_BASE:-\u003Csystem-temp>\u002Fshadowfrog-dreams}\u002F\u003Cns>\u002Fdream-\u003Cslug>\u002F`. There\nare four places they get cleaned up:\n\n1. **`dream-cleanup.sh`** — called by the agent after each `git push` (see\n   \"Worktree Cleanup\" earlier in this skill). Removes ONE worktree.\n2. **`dream-reconcile.py --cleanup-branches`** — after deleting a merged\n   branch, also `rm -rf`s its worktree directory. No extra command needed.\n3. **`dream-gc.sh` (auto-triggered)** — `dream-setup.py` invokes this\n   sweeper at the start of each new dream, throttled by a per-namespace\n   `.last-gc` tombstone to run at most once per `DREAM_GC_INTERVAL_MIN`\n   minutes (default 60). Catches orphaned worktrees.\n\n   Env knobs (all optional, sensible defaults):\n     - `DREAM_GC_AUTO=0` — disable the auto-trigger entirely\n     - `DREAM_GC_INTERVAL_MIN` — how often the trigger fires (default 60)\n     - `DREAM_GC_AGE_MIN` — min worktree age to sweep (default 60)\n\n4. **`dream-gc.sh --task-complete --namespace \"$DREAM_NS\"`** —\n   end-of-session sweep, run by the agent when it stops dreaming (dream\n   count reached, or genuinely blocked). Unlike the auto-trigger, this\n   mode ALSO removes `stale-registered` worktrees (valid `.git` pointer\n   but no `dream-cleanup.sh` ever ran on them — the mid-batch\n   `task_complete` leak). The agent's assertion \"I'm done dreaming\n   **in this namespace**\" is what makes this safe.\n\n   **Required:** `--namespace` (or `DREAM_NAMESPACE` env). The script\n   refuses with exit 2 if neither is given — that prevents a multi-repo\n   fleet sharing one `$DREAM_WORKTREE_BASE` from one agent's\n   `task_complete` destroying another agent's live worktrees.\n\n   `--min-age-min` is an **mtime gate, not a liveness check**. Pass `0`\n   at end-of-session to catch the freshly-pushed final batch; pass a\n   higher value (e.g. `10`) if you can't fully assert that no other\n   dream in the same namespace is in flight. Locked worktrees\n   (`git worktree lock`) are always respected — the sweeper WARNs and\n   leaves them in place.\n\n   ```bash\n   # At the end of the dream loop, before the final summary:\n   DREAM_WORKTREE_BASE=\"$WORKTREE_ROOT\" bash \"$SKILL_DIR\u002Fdream-gc.sh\" \\\n       --task-complete \\\n       --namespace \"$DREAM_NS\" \\\n       --repo-root \"$REPO_ROOT\" \\\n       --min-age-min 0\n   ```\n\nAll four paths share a single safety gate (`_worktree_safety.py`) that\nrefuses ANY path which is not strictly under `$DREAM_WORKTREE_BASE` and\ndoesn't match the exact `\u003Cbase>\u002F\u003Cns>\u002Fdream-\u003Cslug>` shape. The gate is\nunconditional — even an attacker-controlled `$DREAM_WORKTREE_BASE` cannot\ncause `rm -rf \u002F`.\n\n### Applying Dream Code\n\n```bash\n# Option 1: Merge the dream branch\ngit checkout \"$DEFAULT_BRANCH\"\ngit merge dream\u002F\u003Cid> --no-ff -m \"Adopt dream: \u003Ctitle>\"\n\n# Option 2: Cherry-pick specific commits\ngit cherry-pick \u003Ctip_commit>\n\n# Option 3: Apply the patch (if branch was pruned but commit exists)\ngit show \u003Ctip_commit> | git apply\n```\n\n## Experiment Completion Criteria\n\nA task is complete ONLY when ALL of these hold:\n\n1. Code was written or modified (non-empty `patch.diff`)\n2. At least one command was executed with exit code recorded in `Commands Run`\n3. At least one finding tied to running code (not just reading)\n4. At least one per-file `.shadow\u002F*.md` edit made\n5. Discoveries are behavioral insights, not feature descriptions\n6. `report.md` saved with all required fields\n7. Dream branch pushed to remote\n8. Reconciliation completed and verified (`report.md`, `manifest.json`,\n   `patch.diff` exist on main, `_index.md` has entry)\n\nAdditional gates:\n- **Feature design:** `## Motivation` cites specific existing code\n- **Broad compounding:** `## Compounding Delta` explains what parent code was modified\n- **Coherent mode:** mode is threaded through validation and artifacts; each\n  child has a substantive parent connection and its own goal. Siblings remain\n  free to differ. A validated schema is not a substitute for this review.\n\nA task that fails these criteria is **not completed**. If setup fails or\nthe experiment produces nothing, mark it `blocked` in the summary and\nreplace it with another experiment. Blocked tasks do not count toward the\ncategory minimum.\n\n> **After reconciliation:** run `\u002Fshadow-frog-meditate` to consolidate\n> discoveries and repair the index.\n\n### Exporting Coherent Work as SWE Tasks\n\nSelect a root-to-leaf trajectory, not a concatenation of independent siblings.\nCombining siblings requires an explicit integration experiment. Each task's\ncode baseline must be an actual retained commit, separate from conceptual\nprovenance. For sequential tasks, state which earlier requirements change.\nFor one combined task, use the final active behavioral contract: replacing\ndesign A with B does not require implementing both. Do not rewrite historical\nreports or use unsupported manifest `refute` operations to supersede a design.\n\n## Curating Dream Experiments for Upstream PRs\n\nOnce dream branches accumulate, you (or the user) may want to surface a\nfew worth submitting to the upstream project. The default AI failure mode\nis sycophancy — approving too many experiments because they look like\nwork. Resist that. Apply these heuristics:\n\n1. **The maintainer test.** For each experiment, ask: *If I submitted this\n   as a PR to an open-source repo I don't maintain, would the maintainer\n   merge it — or politely close it?* This is the only question that matters.\n2. **Devil's advocate framing.** Your job is to find reasons NOT to PR\n   each experiment. Recommend only when you cannot find a compelling\n   reason to reject.\n3. **70% rejection quota.** If you approve more than 30% of experiments\n   reviewed, your standards are too low. Re-evaluate.\n4. **The \"so what?\" test.** Would a human engineer read the report and\n   say \"so what?\" If yes, reject.\n5. **The 30-minute test.** Could a competent developer have produced\n   this in 30 minutes with a linter, TODO grep, or quick docs read? If\n   yes, it's maintenance work, not a contribution. Reject.\n6. **The novelty test.** Does the experiment reveal a non-obvious\n   behavior, hidden assumption, or unexpected interaction? If not, reject.\n7. **No credit for effort.** A 10-experiment chain that produces a minor\n   tweak is still a minor tweak. Judge the result, not the journey.\n\nWhen you do submit a PR, write the body for someone who has never seen\nthe dream branch. Include: one-paragraph \"what it does\" derived from the dream\nreport, the experiment's evidence (test output, before\u002Fafter metric),\nand an honest \"what we did not verify\" note.\n",{"name":5,"scripts":40,"description":7},[41,42,43,44,45,46,47],"dream-tools.py","dream-coverage.py","dream-validate.py","dream-reconcile.py","dream-setup.py","dream-cleanup.sh","dream-gc.sh","main","42c6c9f7251ec110ba426e14f09cab159a6714d3","skills\u002Fshadow-frog-dream",9,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-05 10:56:08",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add microsoft\u002FShadowFrog --skill shadow-frog-dream",{"tool":63,"command":64},"bunx","bunx skills add microsoft\u002FShadowFrog --skill shadow-frog-dream",{"tool":66,"command":67},"pnpm","pnpm dlx skills add microsoft\u002FShadowFrog --skill shadow-frog-dream","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002FSKILL.md",true,[71,77,81,85,88,91,94,97,100,103,106,112,116,120,124],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"_dream_namespace.py","SCRIPT","脚本",2340,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002F_dream_namespace.py",{"path":78,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":79,"sourceHtmlUrl":80},"_worktree_paths.py",585,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002F_worktree_paths.py",{"path":82,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":83,"sourceHtmlUrl":84},"_worktree_safety.py",10740,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002F_worktree_safety.py",{"path":46,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":86,"sourceHtmlUrl":87},6515,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-cleanup.sh",{"path":42,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":89,"sourceHtmlUrl":90},9272,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-coverage.py",{"path":47,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":92,"sourceHtmlUrl":93},13804,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-gc.sh",{"path":44,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":95,"sourceHtmlUrl":96},90145,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-reconcile.py",{"path":45,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":98,"sourceHtmlUrl":99},14728,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-setup.py",{"path":41,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":101,"sourceHtmlUrl":102},9996,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-tools.py",{"path":43,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":104,"sourceHtmlUrl":105},18026,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-dream\u002Fdream-validate.py",{"path":107,"resourceType":108,"resourceTypeDesc":109,"sizeBytes":110,"sourceHtmlUrl":111},"references\u002F_images.md","REFERENCE","参考文档",307,"https:\u002F\u002Fgithub.com\u002Fdavila7\u002Fclaude-code-templates\u002Fblob\u002Fmain\u002Fcli-tool\u002Fcomponents\u002Fskills\u002Fai-research\u002Ffine-tuning-llama-factory\u002Freferences\u002F_images.md",{"path":113,"resourceType":108,"resourceTypeDesc":109,"sizeBytes":114,"sourceHtmlUrl":115},"references\u002Fadvanced.md",47823,"https:\u002F\u002Fgithub.com\u002Fdavila7\u002Fclaude-code-templates\u002Fblob\u002Fmain\u002Fcli-tool\u002Fcomponents\u002Fskills\u002Fai-research\u002Ffine-tuning-llama-factory\u002Freferences\u002Fadvanced.md",{"path":117,"resourceType":108,"resourceTypeDesc":109,"sizeBytes":118,"sourceHtmlUrl":119},"references\u002Fgetting_started.md",16188,"https:\u002F\u002Fgithub.com\u002Fdavila7\u002Fclaude-code-templates\u002Fblob\u002Fmain\u002Fcli-tool\u002Fcomponents\u002Fskills\u002Fai-research\u002Ffine-tuning-llama-factory\u002Freferences\u002Fgetting_started.md",{"path":121,"resourceType":108,"resourceTypeDesc":109,"sizeBytes":122,"sourceHtmlUrl":123},"references\u002Findex.md",262,"https:\u002F\u002Fgithub.com\u002Fdavila7\u002Fclaude-code-templates\u002Fblob\u002Fmain\u002Fcli-tool\u002Fcomponents\u002Fskills\u002Fai-research\u002Ffine-tuning-llama-factory\u002Freferences\u002Findex.md",{"path":125,"resourceType":108,"resourceTypeDesc":109,"sizeBytes":126,"sourceHtmlUrl":127},"references\u002Fother.md",1166,"https:\u002F\u002Fgithub.com\u002Fdavila7\u002Fclaude-code-templates\u002Fblob\u002Fmain\u002Fcli-tool\u002Fcomponents\u002Fskills\u002Fai-research\u002Ffine-tuning-llama-factory\u002Freferences\u002Fother.md",[129,155,165,185,196,204],{"skillNo":130,"name":131,"nameZh":6,"description":132,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":133,"categories":134,"keywords":135,"publishedAt":35},"01M69BTYQ2DPDT4ZDMD52GJVEJ","shadow-frog","Use a shadow knowledge base to understand any codebase. The .shadow\u002F directory mirrors the source tree with markdown files containing behavioral insights — known bugs, edge cases, implicit contracts, and user preferences. Always check the shadow before editing, debugging, or investigating code. When the user shares important context, write it to the shadow immediately. Invoke shadow-frog-init to create it, shadow-frog-update to refresh it, shadow-frog-dream for autonomous experiments, shadow-frog-nap for lightweight feature-task ideation, shadow-frog-meditate for shadow hygiene, or shadow-frog-viewer for user-facing browsing and visualization.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog\u002FSKILL.md",[],[136,137,138,139,140,141,142,28,143,144,145,146,147,148,149,150,151,152,153,154],"shadow frog","Shadow","insights","directory","meditate","knowledge base","autonomous","files","init","nap","debugging","create","update","visualization","code","markdown","dream","knowledge","write",{"skillNo":156,"name":157,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":161,"publishedAt":35},"01M69BTX451Y89BYJ36DEYJQPA","shadow-frog-viewer","Help users browse and visualize the shadow knowledge base: overview, search for files or symbols or text, view preferences, or see recent discoveries. Invoke when the user wants to see what's in the shadow, get an overview, or find specific knowledge.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-viewer\u002FSKILL.md",[],[162,163,164],"shadow frog viewer","help","visualize",{"skillNo":166,"name":167,"nameZh":6,"description":168,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":169,"categories":170,"keywords":171,"publishedAt":35},"01M69BTVF2EGFP9RDPPKWMS3V6","shadow-frog-update","Update the shadow knowledge base after code changes and from conversational insights. Detects what changed via git diff, refreshes per-file shadows, captures knowledge shared by the user during the session, and updates cross-cutting discoveries. Invoke manually with \u002Fshadow-frog-update; the preToolUse hook will remind the agent when the shadow is behind HEAD.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-update\u002FSKILL.md",[],[137,136,172,148,173,174,138,175,176,177,178,141,150,179,180,153,181,182,183,184],"shadow frog update","updates","changes","with","via","head","shared","git","file","remind","session","diff","base",{"skillNo":186,"name":187,"nameZh":6,"description":188,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":189,"categories":190,"keywords":191,"publishedAt":35},"01M69BTS58A2NGMMP9V5SH1FVE","shadow-frog-nap","Generate grounded software feature-task briefs with a small, bounded ideation budget instead of implementing every idea. Read focused source and optional shadow\u002Fdream evidence, grow or resume a persistent proposal tree, and obtain independent shortlist judgments. Run only decision-changing probes of existing behavior. Use mode=coherent to connect each child to its parent's findings or design while encouraging diverse siblings. Use for lightweight ideation, nap runs, or preparing SWE implementation tasks; use shadow-frog-dream for full implementation-backed experiments.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-nap\u002FSKILL.md",[],[192,145,25,28,193,194,195,34],"shadow frog nap","tasks","connect","generate",{"skillNo":197,"name":198,"nameZh":6,"description":199,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":200,"categories":201,"keywords":202,"publishedAt":35},"01M69BTQ4VYJ5TEYGJ0JT6AYYS","shadow-frog-meditate","Clean and consolidate the shadow knowledge base. Scans all shadow files for duplicate discoveries (same claim, different wording), near-duplicates (one extends another), and conflicting entries (contradicting claims). Merges duplicates, resolves conflicts by investigating the code, and asks the user only when resolution is unclear. Invoke periodically to keep the shadow focused and free of noise.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-meditate\u002FSKILL.md",[],[203,150],"shadow frog meditate",{"skillNo":205,"name":206,"nameZh":6,"description":207,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":208,"categories":209,"keywords":210,"publishedAt":35},"01M69BTN77C5G6REERWK8G4FB6","shadow-frog-init","Initialize a shadow knowledge base for any codebase. Creates a .shadow\u002F directory that mirrors the source tree with markdown files for AI-discovered insights. Run this once per repo before using other shadow-frog skills. Refuses to overwrite an existing .shadow\u002F unless --reset is passed.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FShadowFrog\u002Fblob\u002Fmain\u002Fskills\u002Fshadow-frog-init\u002FSKILL.md",[],[144,136,137,211,139,34,151,153,212,213,143,184,141,214,175,138,215,216,217,218],"shadow frog init","repo","initialize","reset","tree","for","codebase","Existing"]