docs(memory): consolidate stranded agent-memory lessons from merged worktrees

[drmoisan]

Suggested title

docs(memory): consolidate stranded agent-memory lessons from merged worktrees

Summary

• Preserves 65 agent-memory lesson files and 19 extended lesson files that were left uncommitted in stale worktrees whose feature branches have already merged to main.
• Restores two promotion provenance records under docs/features/potential/promoted/ that main lacked.
• Adds the matching MEMORY.md index lines for every new lesson file, plus two index entries for orchestrator lessons that were already on main but unindexed.
• Replaces account and host tokens in the carried text with placeholders per the shared no-absolute-host-paths rule.
• Documentation and agent-memory only. No production code, test code, build configuration, or CI workflow is touched.

Why

The cleanup-merged-worktrees skill found 57 registered worktrees and 69 local branches after the recent parallel run and epic work. Forty-five branches were fully merged, but their worktrees still held uncommitted lesson files written by planner, executor, reviewer, and orchestrator agents. Deleting those worktrees without this consolidation would discard the content permanently.

Each stranded file was triaged against main by topic, not by filename. Only content judged genuinely new, or a correction to what main currently records, is carried here. Superseded drafts, duplicates of existing lessons, and lessons contradicted by later fixes on main were left behind for deletion with their worktrees.

What Changed

Agent-memory lessons (new files, 65)

• atomic-executor (20): toolchain and gate mechanics observed during execution, for example the vstest duplicate .coverage attachment, the MSTest deploy-directory token leak on failing runs, the global.json cwd-walk interaction with Bash discipline, and CSharpier's blank-line-before-comment rule.
• atomic-planner (9): plan-authoring rules such as splitting measured versus confirming runs, verifying citations in the assigned worktree, and the line-anchored gotchas of the planner-output hook.
• feature-review (11): review residual ledgers for recently merged issues and reviewer traps around Cobertura, Pester coverage nodes, and YAML comment-only diffs.
• orchestrator (14): hook and topology facts for preparation mode, prep worktrees, the Agent-tool-less session case, and coverage-gate visibility of [ExcludeFromCodeCoverage].
• parallel-orchestrator (5), parallel-planner (2), prd-feature (1), task-researcher (1).

Agent-memory lessons (extended, 19 modified files plus 8 MEMORY.md indexes)

• Existing lesson files gain paragraphs recorded during the bugs-2026-09-02 parallel run and in individual item worktrees. Most are additive; three parallel-planner files are rewrites that supersede stale measurements.
• The preflight inertness-test file is a three-way merge: main's newer "Better remedy" section is kept and the worktree's per-scope tiers and corollary are inserted ahead of it.

Promotion records (2)

• docs/features/potential/promoted/2026-09-02-quickfiler-date-time-format-missing-invariant-culture.md
• docs/features/potential/promoted/2026-09-03-terminal-notification-hook-test-lacks-sync-barrier.md

Architecture / How It Fits Together

Agent memory is tracked repository content under .claude/agent-memory/<agent>/, one lesson per file, indexed by that agent's MEMORY.md. Agents load the index at session start and open individual lesson files on demand. This PR adds files and index lines only; it does not change any hook, skill, agent definition, or script.

Verification

Completed

• Every carried file was compared against main by content hash and by git log --find-object; none of the carried content exists in git history, so nothing here duplicates a committed file.
• Every MEMORY.md diff was checked to be additions only (no removed index lines).
• A token scan for the developer account name, the machine name, and absolute user-profile paths reports no matches in the changed files after sanitization.
• The pr-author preflight (Test-OrchestratorStatePrCreationReadiness) and the orchestrator-state validator both passed.

Recommended

git diff --stat main...documentationandmemories
git grep -i -E "danmoisan|megalodon" documentationandmemories -- .claude/agent-memory docs

CI status for the head commit is not available in the collected context. Not verified in this PR.

Backward Compatibility / Migration Notes

• No breaking changes. No files are removed or renamed.
• Three lesson files carry a fact that is true only on the unmerged TaskMaster-wt-2026-09-02T08-47 branch: the model-routing-hook-reads-canonical-path-only.md "trap 2" paragraph describes a hook change that has not landed on main or upstream. Readers should treat that paragraph as describing a pending fix.

Risks and Mitigations

• Risk: a carried lesson is stale relative to a later fix on main. Mitigation: each file was checked against main's current script, hook, or config where it documents a defect; files whose defect is already fixed were excluded. Rollback is a revert of the single commit.
• Risk: two orchestrator lessons prescribe different remedies for the same prd-feature hook limitation (prd-feature-hook-blocks-reused-prep-worktree-topology.md versus preparation-child-cwd-is-session-root-not-item-worktree.md). Mitigation: both are carried so neither observation is lost; reconciling them is listed as a follow-up.
• Risk: the collected context classifies the branch as two changed docs files because it does not enumerate .claude/**. Mitigation: the appendix's name-status list is authoritative and shows all 92 files.

Review Guide

1. Start with the eight MEMORY.md diffs; they enumerate every new lesson with a one-line description.
2. Review the feature-review/project_*-review-residuals.md files next; several name residual defects that have no follow-up issue yet.
3. The parallel-planner rewrites and the preflight inertness-test merge are the only non-additive diffs.
4. The 65 added lesson files are independent of one another and can be reviewed in any order.

Follow-ups

• Reconcile the two orchestrator lessons that prescribe opposite remedies for the prd-feature hook limitation.
• Promote the unresolved residuals recorded in the review-residual ledgers to tracked issues.
• After this PR merges, the cleanup apply pass deletes the now-consolidated worktrees and the documentationandmemories branch.

GitHub Auto-close

• None (GitHub validation unavailable in the collected context; no verified autoclose list).

🤖 Generated with Claude Code