{"id":"f68ea1f3-544e-49a9-9ad3-bb172b72a019","entityType":"agent","slug":"clawhub-drumrobot-fix-plan","name":"fix-plan","canonicalUrl":"https://www.xpersona.co/agent/clawhub-drumrobot-fix-plan","canonicalPath":"/agent/clawhub-drumrobot-fix-plan","generatedAt":"2026-10-10T06:43:11.592Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:19:19.018Z","emptyReason":null},"description":"fix_plan.md / checklist.md schema and lifecycle management. Topics — format ([ ]/[x]/[BLOCKED] markers, Progress/Completed sections), priority (P0-P3 BLOCKED suffix + external/selfable classification), add (Action/Why/How authoring), update (flip marker / note / `[KEY:VALUE]` attr), upsert (dup-check → update in place or fall back to add), draft (deferred plan stub → promote via code-workflow), move ([x] → Completed summary, subtree partial completion), sync (gh pr/issue state polling → auto-check), issue-drafts (write → publish → archive → delete), model-triage (fit + dedicated section), completion-criteria (DoD + marker rules). Default (no args): move (or archive-receiver) → format → sync → priority → flowchart-sync (incl. pinned-mission liveness check), scoped by role-profile (--role=pm|deep|impl). Use when: \"fix_plan\", \"checklist\", \"BLOCKED priority\", \"triage blocked\", \"fix-plan sync\", \"issue draft cleanup\", \"fix-plan draft\", \"fix-plan default\", \"fix-plan archive\", \"model triage\", \"completion criteria\", \"role profile\", \"--role\", \"orca session launch\", \"fix-plan upsert\", \"dup check tracker\", \"pinned mission liveness\", \"pinned-backing\", \"set-attr\".","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17ay1v6v88r2m102pvvc44gz183qcrm:fix-plan","sourceUrl":"https://clawhub.ai/drumrobot/fix-plan","homepage":"https://clawhub.ai/drumrobot/skills/fix-plan","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/drumrobot/fix-plan","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/drumrobot/skills/fix-plan","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":67,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"fix-plan technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:19:19.018Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:19:19.018Z","emptyReason":null},"stars":null,"forks":null,"downloads":2329,"packageName":null,"latestVersion":"0.17.1","tractionLabel":"2.3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:19:19.018Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T16:19:19.018Z","lastCrawledAt":"2026-10-09T16:19:19.018Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T16:19:19.018Z","lastVerifiedAt":null,"highlights":[{"version":"0.17.1","createdAt":"2026-10-06T07:55:55.701Z","changelog":"Version 0.17.1 - Expanded `update` topic: can now set a trailing `[KEY:VALUE]` attribute (e.g., `ICE`, `ch`, `RAID`) on checklist items, not just flip marker or append progress note. - Documented new \"set-attr\" usage in commands and description. - Improved docs for attribute mutation and registered vocabulary. - Removed obsolete `skill-card.md` file. - Minor clarifications and doc updates for usage and invocation triggers.","fileCount":56,"zipByteSize":214730},{"version":"0.17.0","createdAt":"2026-09-30T14:21:15.764Z","changelog":"**New automation and validation features; expanded script utilities and verification coverage.** - Added new scripts for task locking, artifact scanning, and P2/P3 pruning, with associated tests. - Enhanced verification to cross-check \"residual =\" notes against plan checklist progress. - Improved and clarified guide topics around flowchart syncing, move audits, and file reference validation. - Removed legacy skill card documentation for a leaner footprint. - Updated topic descriptions and dependency diagrams for clarity and accuracy.","fileCount":56,"zipByteSize":208874},{"version":"0.16.1","createdAt":"2026-09-27T15:52:08.073Z","changelog":"fix-plan 0.16.1 - Removed redundant file: skill-card.md. - Updated and clarified documentation for several modules, including claim.md and CHANGELOG.md. - Refined logic and tests in scripts/workspace_profile.py and tests/test_workspace_profile.py for improved role-profile handling. - Minor cleanup and reorganization for code and documentation consistency.","fileCount":49,"zipByteSize":185810},{"version":"0.16.0","createdAt":"2026-09-24T14:19:40.844Z","changelog":"**Adds pinned-mission liveness checks and supporting scripts.** - Introduced liveness checking for pinned missions, with `pinned_liveness_check.py` and tested via `test_pinned_liveness_check.py`. - Updated the default flow to include pinned-mission liveness checks in flowchart-sync (pm role). - Added `add_pipeline_log.py` and `append_pipeline_log.py` scripts for pipeline logging. - Removed obsolete `skill-card.md` file. - Updated documentation: Clarified flowchart topic and default invocation for new liveness check, and expanded usage keywords.","fileCount":49,"zipByteSize":184126},{"version":"0.15.0","createdAt":"2026-09-20T11:23:17.451Z","changelog":"**Summary: Maintenance, minor additions, and cleanup.** - Added new utility and test scripts: `scripts/sync_shared_artifacts.py`, `scripts/test_sync_shared_artifacts.py` - Removed obsolete file: `skill-card.md` - Updated documentation (`CHANGELOG.md`) - No functionality changes to main skill logic","fileCount":45,"zipByteSize":169627},{"version":"0.14.0","createdAt":"2026-09-18T15:53:28.734Z","changelog":"fix-plan 0.14.0 - Added archive_pipeline_log.py script for archiving pipeline logs. - Updated core scripts (add_item.py, update_item.py, workspace_profile.py) for improved plan and checklist lifecycle handling. - Revised markdown guides (add.md, draft.md, CHANGELOG.md, etc.) for clearer topic documentation. - Removed deprecated skill-card.md file.","fileCount":43,"zipByteSize":164852},{"version":"0.13.0","createdAt":"2026-09-14T14:15:34.478Z","changelog":"fix-plan 0.13.0 - Removed deprecated skill-card.md file. - Documentation refresh across guides (CHANGELOG.md, SKILL.md, flowchart.md, format.md, priority.md) for consistency and completeness. - No schema or workflow changes—core logic and workflows remain unchanged. - Maintenance release, focusing on cleanup and improved documentation.","fileCount":42,"zipByteSize":154191},{"version":"0.12.1","createdAt":"2026-09-10T05:56:08.547Z","changelog":"fix-plan 0.12.1 - Internal refactors in workspace profile and item update scripts. - Improved or updated testing for workspace profile logic. - Removed redundant or obsolete documentation file (skill-card.md). - Minor updates to changelog and documentation.","fileCount":42,"zipByteSize":151461}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17ay1v6v88r2m102pvvc44gz183qcrm:fix-plan","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17ay1v6v88r2m102pvvc44gz183qcrm:fix-plan` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/drumrobot/fix-plan before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T06:43:11.590Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-drumrobot-fix-plan/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T16:19:19.018Z","emptyReason":null},"readme":"Skill: fix-plan\n\nOwner: drumrobot\n\nSummary: fix_plan.md / checklist.md schema and lifecycle management. Topics — format ([ ]/[x]/[BLOCKED] markers, Progress/Completed sections), priority (P0-P3 BLOCKED suffix + external/selfable classification), add (Action/Why/How authoring), update (flip marker / note / `[KEY:VALUE]` attr), upsert (dup-check → update in place or fall back to add), draft (deferred plan stub → promote via code-workflow), move ([x] → Completed summary, subtree partial completion), sync (gh pr/issue state polling → auto-check), issue-drafts (write → publish → archive → delete), model-triage (fit + dedicated section), completion-criteria (DoD + marker rules). Default (no args): move (or archive-receiver) → format → sync → priority → flowchart-sync (incl. pinned-mission liveness check), scoped by role-profile (--role=pm|deep|impl). Use when: \"fix_plan\", \"checklist\", \"BLOCKED priority\", \"triage blocked\", \"fix-plan sync\", \"issue draft cleanup\", \"fix-plan draft\", \"fix-plan default\", \"fix-plan archive\", \"model triage\", \"completion criteria\", \"role profile\", \"--role\", \"orca session launch\", \"fix-plan upsert\", \"dup check tracker\", \"pinned mission liveness\", \"pinned-backing\", \"set-attr\".\n\nTags: latest:0.17.1\n\nVersion history:\n\nv0.17.1 | 2026-10-06T07:55:55.701Z | auto\n\nVersion 0.17.1\n\n- Expanded `update` topic: can now set a trailing `[KEY:VALUE]` attribute (e.g., `ICE`, `ch`, `RAID`) on checklist items, not just flip marker or append progress note.\n- Documented new \"set-attr\" usage in commands and description.\n- Improved docs for attribute mutation and registered vocabulary.\n- Removed obsolete `skill-card.md` file.\n- Minor clarifications and doc updates for usage and invocation triggers.\n\nv0.17.0 | 2026-09-30T14:21:15.764Z | auto\n\n**New automation and validation features; expanded script utilities and verification coverage.**\n\n- Added new scripts for task locking, artifact scanning, and P2/P3 pruning, with associated tests.\n- Enhanced verification to cross-check \"residual =\" notes against plan checklist progress.\n- Improved and clarified guide topics around flowchart syncing, move audits, and file reference validation.\n- Removed legacy skill card documentation for a leaner footprint.\n- Updated topic descriptions and dependency diagrams for clarity and accuracy.\n\nv0.16.1 | 2026-09-27T15:52:08.073Z | auto\n\nfix-plan 0.16.1\n\n- Removed redundant file: skill-card.md.\n- Updated and clarified documentation for several modules, including claim.md and CHANGELOG.md.\n- Refined logic and tests in scripts/workspace_profile.py and tests/test_workspace_profile.py for improved role-profile handling.\n- Minor cleanup and reorganization for code and documentation consistency.\n\nv0.16.0 | 2026-09-24T14:19:40.844Z | auto\n\n**Adds pinned-mission liveness checks and supporting scripts.**\n\n- Introduced liveness checking for pinned missions, with `pinned_liveness_check.py` and tested via `test_pinned_liveness_check.py`.\n- Updated the default flow to include pinned-mission liveness checks in flowchart-sync (pm role).\n- Added `add_pipeline_log.py` and `append_pipeline_log.py` scripts for pipeline logging.\n- Removed obsolete `skill-card.md` file.\n- Updated documentation: Clarified flowchart topic and default invocation for new liveness check, and expanded usage keywords.\n\nv0.15.0 | 2026-09-20T11:23:17.451Z | auto\n\n**Summary: Maintenance, minor additions, and cleanup.**\n\n- Added new utility and test scripts: `scripts/sync_shared_artifacts.py`, `scripts/test_sync_shared_artifacts.py`\n- Removed obsolete file: `skill-card.md`\n- Updated documentation (`CHANGELOG.md`)\n- No functionality changes to main skill logic\n\nv0.14.0 | 2026-09-18T15:53:28.734Z | auto\n\nfix-plan 0.14.0\n\n- Added archive_pipeline_log.py script for archiving pipeline logs.\n- Updated core scripts (add_item.py, update_item.py, workspace_profile.py) for improved plan and checklist lifecycle handling.\n- Revised markdown guides (add.md, draft.md, CHANGELOG.md, etc.) for clearer topic documentation.\n- Removed deprecated skill-card.md file.\n\nv0.13.0 | 2026-09-14T14:15:34.478Z | auto\n\nfix-plan 0.13.0\n\n- Removed deprecated skill-card.md file.\n- Documentation refresh across guides (CHANGELOG.md, SKILL.md, flowchart.md, format.md, priority.md) for consistency and completeness.\n- No schema or workflow changes—core logic and workflows remain unchanged.\n- Maintenance release, focusing on cleanup and improved documentation.\n\nv0.12.1 | 2026-09-10T05:56:08.547Z | auto\n\nfix-plan 0.12.1\n\n- Internal refactors in workspace profile and item update scripts.\n- Improved or updated testing for workspace profile logic.\n- Removed redundant or obsolete documentation file (skill-card.md).\n- Minor updates to changelog and documentation.\n\nv0.12.0 | 2026-09-06T10:31:28.181Z | auto\n\nVersion 0.12.0\n\n- Added new claim functionality with scripts/claim_item.py and corresponding test script scripts/test_claim_item.py.\n- Improved or updated integrity checking logic in scripts/hook_integrity_check.py.\n- Removed skill-card.md from the project.\n- Updated documentation in CHANGELOG.md.\n\nv0.11.1 | 2026-09-05T15:54:25.225Z | auto\n\n**Adds atomic in-place checklist updating (\"update\" topic) and supporting script.**\n\n- New \"update\" topic and [update.md] guide: mutate checklist items in-place (flip marker / append note) without direct manual edits.\n- Added `scripts/update_item.py` implementation for controlled modifications.\n- Updated dependencies and topic docs to cover \"update\".\n- Removed deprecated `skill-card.md`.\n- Minor doc and topic-listing fixes for clarity and completeness.\n\nv0.11.0 | 2026-09-01T22:37:55.879Z | auto\n\nfix-plan v0.11.0\n\n- Introduced new upsert topic and API, enabling duplicate-check before authoring (update-in-place or fallback to add).\n- Added upsert.md documentation; removed obsolete skill-card.md file.\n- Expanded usage guidance to include \"fix-plan upsert\", \"dup check tracker\", and \"orca session launch\".\n- Updated topic dependency tree and main description to reflect upsert flow and fallback to add.\n- Minor documentation and configuration improvements for clarity.\n\nv0.10.0 | 2026-08-30T11:13:30.354Z | auto\n\n## fix-plan v0.10.0\n\n- Added new scripts for merging duplicate sections and updating markers.\n- Migrated \"completed bloat\" check automation from shell script to JavaScript.\n- Removed legacy plane sync, bulk update, and test scripts to simplify codebase.\n- Updated documentation and topic guidance.\n- General refactor for improved modularity and maintainability.\n\nv0.9.1 | 2026-08-26T17:25:55.892Z | auto\n\n- Added integrity and bulk update scripts for improved sync and data validation (plane_sync, plane_bulk_update, hook_integrity_check).\n- Introduced new tests for priority mapping and schema validation.\n- Removed obsolete skill-card and plane_create_issue scripts.\n- Updated completion criteria and documentation for enhanced consistency and clarity across lifecycle management and automation.\n\nv0.9.0 | 2026-08-21T05:41:11.145Z | auto\n\nfix-plan 0.9.0\n\n- Added three new files, including integration scripts and tests.\n- Updated core logic and documentation across 8 files, improving schema and lifecycle handling.\n- Introduced a script to prevent direct checklist edits (block-direct-checklist-edit.js).\n- Added workspace profile support and coverage tests.\n- Removed deprecated skill-card.md.\n- Enhanced sync and issue management with Plane integration scripts.\n\nv0.8.0 | 2026-08-18T05:41:39.238Z | auto\n\nfix-plan 0.8.0\n\n- Updated documentation and SKILL.md for improved clarity and conciseness.\n- Added new script: scripts/plane_create_issue.py.\n- Removed deprecated file: skill-card.md.\n- Modified and improved syncing, draft, model-triage, and artifact post-ingest logic in various scripts and guides.\n- Streamlined description and invocation guidance for the default pipeline and supported roles.\n\nv0.7.0 | 2026-08-17T12:07:09.599Z | auto\n\nfix-plan v0.7.0\n\n- Added new \"claim\" topic for multi-session in-progress leases, preventing duplicate work via [CLAIMED::] tags.\n- Introduced \"verify\" topic for commit-hash and file-path staleness checks before trusting unresolved work items.\n- Expanded configuration options: claim-ttl (for claim expiry management).\n- Updated docs and SKILL.md for concise topic descriptions and new topics.\n- Removed obsolete \"skill-card.md\".\n- Various improvements across lifecycle, sync, and move logic, including enhanced audit and section sync procedures.\n\nv0.6.2 | 2026-08-13T07:00:16.461Z | auto\n\nfix-plan 0.6.2\n\n- Added tests for workspace profile detection (new test_workspace_profile.py).\n- Improved and updated scripts for cleanup and Plane sync workflows.\n- Updated model triage documentation.\n- Removed obsolete skill-card.md file.\n- General maintenance and minor corrections to documentation and code.\n\nv0.6.0 | 2026-08-09T14:11:19.139Z | auto\n\n**Expanded sync automation and maintenance in this release:**\n\n- Added new scripts for task detection, queue management, and staleness checking (`detect_bloated_tasks.py`, `fable_queue_replenish.py`, `stale_check.py`).\n- Introduced automated tests for sync logic with `test_plane_sync.py`.\n- Improved and expanded sync logic in `plane_sync.py`, including Plane REST API polling.\n- Updated lifecycle and file maintenance docs (`move.md`, `sync.md`, `workspace_profile.py`).\n- Retired the outdated `skill-card.md`.\n\nv0.5.1 | 2026-08-06T09:21:34.163Z | auto\n\nfix-plan v0.5.1\n\n- Removed skill-card.md for a slimmer codebase.\n- Updated existing documentation (notably CHANGELOG.md and move.md) for improved clarity and alignment.\n- No changes to core logic or schema; this is a maintenance/internal cleanup release.\n\nv0.5.0 | 2026-08-04T07:32:53.769Z | auto\n\nv0.5.0 adds sync-automation and improves sync processes\n\n- Added sync-automation topic and documentation, including a stop-hook script to nudge overdue syncs without making network calls in hooks.\n- Broadened usage descriptions to include \"sync automation\" and \"sync nudge.\"\n- Expanded sync documentation to clarify stop-hook and automation behavior.\n- Removed obsolete skill-card.md file.\n\nv0.4.0 | 2026-07-28T23:09:42.939Z | auto\n\n**Summary: Adds model-triage, completion-criteria, and flowchart topics, enhances sync features, introduces role-based execution.**\n\n- New topics: model-triage (model fit sections), completion-criteria (definition of done/DoD), and flowchart (Mermaid priority graph).\n- Sync now supports both GitHub and Plane API polling, with new secondary-sync receiver and scripts.\n- Role-based execution: default invocation can be scoped (--role=pm|deep|impl), with context detection fallback.\n- Enhanced default pipeline: now includes move/archive-receiver, format check, sync, priority triage, and flowchart drift-check.\n- Expanded configuration: adds role-profile and secondary-sync-receiver options.\n- Refactored/added scripts for artifact processing and workspace profiling.\n- Obsolete file skill-card.md removed.\n\nv0.3.3 | 2026-07-23T13:39:23.769Z | auto\n\n**fix-plan v0.3.3**\n\n- Removed the `skill-card.md` file from the repository.\n- Updated documentation (`CHANGELOG.md`, `move.md`).\n- No changes to skill interface or configuration.\n- Internal and doc-only maintenance release.\n\nv0.3.2 | 2026-07-16T12:29:51.776Z | auto\n\n- Added support for independent, receiver-free local archiving of the `## Completed` section by time period (`monthly` or `weekly`) to keep tracker files small.\n- New config option: `completed-archive-period` (default: `monthly`)—moves older Completed entries to `.bak` archive files automatically.\n- Documented option `--completed-archive-period=weekly|monthly` and clarified Completed-section size management.\n- Added `scripts/cleanup.py` to support automated archive/cleanup features.\n- Updated documentation in SKILL.md, format.md, move.md, and sync.md to reflect new local archive functionality and options.\n\nv0.3.1 | 2026-06-26T16:24:11.231Z | auto\n\nfix-plan 0.3.1\n\n- Dependency change: The `priority` topic now invokes `sync` as step 0 to ensure external state is up-to-date before triaging (prevents triage on stale data).\n- Documentation updates in SKILL.md and priority.md reflecting the above dependency and triage workflow.\n- Removed skill-card.md, consolidating documentation under SKILL.md.\n- No functional or configuration changes beyond updated dependency workflow and documentation clarifications.\n\nv0.3.0 | 2026-06-19T23:10:42.318Z | auto\n\n**Major update: Adds \"plan draft\" support and completes default invocation/archiving contract.**\n\n- Introduced new `draft` topic: record deferred plan stubs in `## Plan Drafts` and promote via code-workflow steps.\n- Default invocation `/fix-plan` (no args) now dispatches `## Completed` section to a caller-supplied archive receiver; falls back to in-tracker cleanup if none registered.\n- Expanded options: `archive-receiver` (for default archiving) and clarified `rag-receiver`/`task-tracker` config behavior.\n- Updated topic dependencies: now directly integrates with `code-workflow` on plan promotion.\n- Added and documented the draft.md file; removed legacy skill-card.md.\n- Improved usage documentation, clarifying vendor-agnostic dispatch/receiver contract and fallback behaviors.\n\nv0.2.0 | 2026-06-11T14:36:46.755Z | auto\n\n- Introduced reusable schema and lifecycle management for `fix_plan.md` and `checklist.md` files.\n- Added structured conventions for item state markers ([ ], [x], [BLOCKED]), progress/completed sections, and section consistency.\n- Implemented priority system with `[BLOCKED:P0-P3:reason]` markers and external/selfable classifications, aligned with GitHub labels.\n- Enabled authoring and movement of checklist items, including summary rules for completed items.\n- Integrated GitHub PR/Issue polling to auto-update item state based on merge/close status.\n- Established a lifecycle for issue drafts, including publishing, archiving, and deletion workflows.\n\nArchive index:\n\nArchive v0.17.1: 56 files, 214730 bytes\n\nFiles: add.md (13631b), CHANGELOG.md (28471b), claim.md (8104b), completion-criteria.md (7150b), draft.md (16459b), flowchart.md (17243b), format.md (13045b), issue-drafts.md (3429b), LICENSE (1063b), model-triage.md (10426b), move.md (19724b), priority.md (11457b), resources/block-direct-checklist-edit.js (3189b), resources/check-completed-bloat.js (3322b), resources/sync-checkpoint-nudge.sh (2870b), resources/warn-fixplan-item-schema.sh (6295b), scripts/add_item.py (21513b), scripts/add_pipeline_log.py (4571b), scripts/append_pipeline_log.py (3325b), scripts/archive_pipeline_log.py (15433b), scripts/artifact_post_ingest.py (7010b), scripts/artifact_pre_lookup.py (5214b), scripts/claim_item.py (18316b), scripts/cleanup.py (20343b), scripts/detect_bloated_tasks.py (5899b), scripts/fable_queue_replenish.py (4376b), scripts/hook_integrity_check.py (19035b), scripts/merge_duplicate_sections.py (3419b), scripts/pinned_liveness_check.py (7652b), scripts/prune_p2p3.py (8977b), scripts/scan_unmigrated_artifacts.py (7170b), scripts/stale_check.py (8907b), scripts/sync_shared_artifacts.py (7712b), scripts/task_lock.py (12549b), scripts/test_claim_item.py (17947b), scripts/test_cleanup.py (7024b), scripts/test_pinned_liveness_check.py (9248b), scripts/test_prune_p2p3.py (3362b), scripts/test_scan_unmigrated_artifacts.py (3144b), scripts/test_sync_shared_artifacts.py (4294b), scripts/test_task_lock.py (4625b), scripts/test_workspace_profile.py (7322b), scripts/update_item.py (59495b), scripts/update_marker.py (1831b), scripts/update_pinned_mission.py (3891b), scripts/workspace_profile.py (14915b), skill-card.md (1806b), SKILL.md (45268b), sync-automation.md (4930b), sync.md (10525b), tests/test_workspace_profile.py (11853b), tests/test-warn-fixplan-item-schema.sh (7749b), update.md (7378b), upsert.md (5971b), verify.md (11132b), _meta.json (128b)\n\nFile v0.17.1:SKILL.md\n\n---\nname: fix-plan\ndescription: |\n fix_plan.md / checklist.md schema and lifecycle management. Topics — format ([ ]/[x]/[BLOCKED] markers, Progress/Completed sections), priority (P0-P3 BLOCKED suffix + external/selfable classification), add (Action/Why/How authoring), update (flip marker / note / `[KEY:VALUE]` attr), upsert (dup-check → update in place or fall back to add), draft (deferred plan stub → promote via code-workflow), move ([x] → Completed summary, subtree partial completion), sync (gh pr/issue state polling → auto-check), issue-drafts (write → publish → archive → delete), model-triage (fit + dedicated section), completion-criteria (DoD + marker rules).\n Default (no args): move (or archive-receiver) → format → sync → priority → flowchart-sync (incl. pinned-mission liveness check), scoped by role-profile (--role=pm|deep|impl).\n Use when: \"fix_plan\", \"checklist\", \"BLOCKED priority\", \"triage blocked\", \"fix-plan sync\", \"issue draft cleanup\", \"fix-plan draft\", \"fix-plan default\", \"fix-plan archive\", \"model triage\", \"completion criteria\", \"role profile\", \"--role\", \"orca session launch\", \"fix-plan upsert\", \"dup check tracker\", \"pinned mission liveness\", \"pinned-backing\", \"set-attr\".\nmetadata:\n author: es6kr\n version: \"0.1.0\"\ndepends-on:\n - code-workflow\n - github-flow\nallowed-tools:\n - Read\n - Edit\n - Write\n - Grep\n - Bash(gh:*)\n - Bash(mv:*)\n - Bash(mkdir:*)\n---\n\n# Fix Plan\n\nSchema and lifecycle management for `fix_plan.md` (Ralph convention) and `checklist.md` (non-Ralph workspaces). Vendor-agnostic — extracted from Ralph integration to be reusable across environments.\n\n## Topics\n\n| Topic | Description | Guide |\n|-------|-------------|-------|\n| add | New item authoring schema (Action / Why / How), length budget, deliverable separation (research / plan / checklist split) | [add.md](./add.md) |\n| claim | Multi-session in-progress lease: `[CLAIMED::]` suffix tag on `[ ]` / `[BLOCKED:*:selfable]` items, claim→refresh→release lifecycle, stale-TTL takeover — prevents two sessions duplicating the same item | [claim.md](./claim.md) |\n| completion-criteria | Definition of done per item output type (`Why` = scope narrative vs `How to apply` = deliverable), marker transition rules, residual-scope split | [completion-criteria.md](./completion-criteria.md) |\n| draft | Record a deferred plan **stub** (purpose + defer reason + resume trigger + expected deliverable) in `## Plan Drafts` when full planning is postponed; promote to `code-workflow` research→plan when the trigger fires. Invoked `/fix-plan draft` | [draft.md](./draft.md) |\n| flowchart | Priority flowchart (Mermaid `graph TD` dependency graph) authoring, clean syntax rules (no inline `%%`), plan document node mapping (`llm-wiki/outputs/`, `.ralph/plan-drafts/`) without `file://` URLs, the `pm`-role default-pipeline sync procedure (drift check against priority-triage output), and the pinned-mission liveness check (`pinned_liveness_check.py` — cite backing items via ``, surface a resolved candidate via `AskUserQuestion`, never auto-write) | [flowchart.md](./flowchart.md) |\n| format | Schema: `[ ]` / `[x]` / `[BLOCKED]` markers, Progress/Completed sections, item state changes, section-consistency check | [format.md](./format.md) |\n| issue-drafts | Issue Drafts lifecycle: write → publish → archive (`.bak/`) → delete from fix_plan | [issue-drafts.md](./issue-drafts.md) |\n| model-triage | High-capability model triage: 5 fit categories + anti-fit table + cross-section discovery procedure + dedicated `## Target Tasks` section operation | [model-triage.md](./model-triage.md) |\n| move | `[x]` → Completed summary rules, subtree-move partial completion under unfinished parent, optional abstract RAG dispatch, and `detect_bloated_tasks.py` automated audit | [move.md](./move.md) |\n| priority | `[BLOCKED:P0-P3:reason]` GitHub-aligned priority suffix + `external` / `selfable` reason classification + triage workflow | [priority.md](./priority.md) |\n| sync | GitHub PR/Issue & Plane REST API state polling (`gh` CLI + `plane_sync.py`) → auto-check `[ ]` → `[x]` on MERGED PR or CLOSED issue; PR CLOSED-without-merge → `[BLOCKED:P2:external]` | [sync.md](./sync.md) |\n| sync-automation | Stop-hook checkpoint nudge — reminds to run `sync` when a tracker referencing PR/Issue numbers hasn't been synced in a while, without any network call inside the hook itself | [sync-automation.md](./sync-automation.md) |\n| update | Mutate an EXISTING item in place — flip its marker, append a one-line progress note, or set a trailing `[KEY:VALUE]` attribute (registered vocabulary: `ICE` / `ch` / `RAID`) — via `update_item.py`, without going around `block-direct-checklist-edit.js` | [update.md](./update.md) |\n| upsert | Dup-check the tracker before authoring — match on Action semantics across all sections, update in place (preserve `Why`, state priority reclassification) when found, fall back to `add`'s schema otherwise | [upsert.md](./upsert.md) |\n| verify | Cross-check commit-hash/file-path references cited in tracker items against local git/filesystem state before trusting a \"still unresolved\" claim (distinct from `sync`'s external GitHub polling); second dimension cross-checks inline \"residual =\" notes against the linked plan's Progress Checklist (stale-forward detection) | [verify.md](./verify.md) |\n\n## Topic Dependencies\n\n```text\nfix-plan (schema + lifecycle)\n ├─→ (default, no args) → move (archive-receiver) ──→ format ──→ sync ──→ priority ──→ flowchart-sync\n ├─→ format (entry — section structure + markers)\n ├─→ priority (new convention — BLOCKED P0-P3 + reason)\n │ └─→ depends on sync (Step 0: refresh external state before classifying)\n ├─→ add (authoring act-now items)\n ├─→ upsert (dup-check → update-in-place OR fall back to add's schema for a genuinely new item)\n │ └─→ add (fallback path)\n ├─→ claim (multi-session lease) — annotates format's markers; move drops the tag on completion; priority triage excludes fresh-claimed items\n ├─→ model-triage (cross-section discovery → dedicated section; items authored via add's schema)\n ├─→ draft (deferred plan stub → `## Plan Drafts`)\n │ └─→ code-workflow/steps dispatch on promote (research → plan)\n ├─→ move (completion → Completed)\n │ └─→ optional --rag=: dispatch for semantic indexing (caller-supplied)\n ├─→ sync (GitHub state polling) — depends on github-flow gh CLI conventions\n │ └─→ sync-automation (Stop-hook nudges this topic when overdue — no direct call dependency)\n ├─→ verify (local git/filesystem staleness check — complements sync's external-state polling)\n ├─→ flowchart (Mermaid priority graph) — step 5 of the default pipeline, drift-checks against priority's output\n └─→ issue-drafts (lifecycle of draft files)\n```\n\n- All topics are independently invocable, **except `priority` which invokes `sync` as Step 0 (HARD STOP)** — triage on stale state is the failure mode the dependency prevents (see [priority.md](./priority.md) Triage workflow Step 0)\n- `verify` is a recommended pre-check before triaging any `[BLOCKED]`/`[ ]` item that cites a specific commit hash or file path — see [verify.md](./verify.md)\n- **Default invocation (no args)**: first runs `move` (or archive-receiver dispatch), then verifies schema via `format`, syncs external state via `sync`, triages blockers via `priority`, and syncs the `## Flow Chart` section's node labels against that triage output via `flowchart` (pm role only — see \"Role-based execution\").\n- `move` topic optionally dispatches to a RAG receiver if the caller supplies `--rag=:` — generic skill stays vendor-agnostic; receiver implementation lives in the caller (e.g., ralph wrapper)\n- `sync` topic optionally dispatches to a secondary-tracker receiver if the caller supplies `--secondary-sync=:` — see [sync.md](./sync.md) \"Secondary-tracker sync cadence\"\n- `draft` topic dispatches to `code-workflow` (`steps`) on promote — turns a deferred stub into a real research → plan\n- `upsert` topic falls back to `add`'s schema when the dup-check finds no matching item — not a separate authoring flow, just the entry point that checks first\n\n## Configuration\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `claim-ttl` | `4` (hours) | Stale-claim TTL for the `claim` topic — a `[CLAIMED::]` lease older than this (or whose session has ended) is takeable by another session. Set via `--claim-ttl=`. See [claim.md](./claim.md) |\n| `archive-receiver` | (unset) | Optional `:` dispatch for **default invocation** (no args). When set, the caller routes the source's `## Completed` section to this receiver for external archiving (weekly report, postmortem log, RAG store, etc.). Receiver harvests + appends to its own report + removes harvested lines from source. Set via `--archive=:` CLI flag. See \"Default invocation\" below |\n| `completed-archive-period` | `monthly` | Period for the **receiver-independent local archive** of the `## Completed` section — `monthly` (`YYYY-MM`) or `weekly` (ISO `YYYY-Www`). On the period boundary, older Completed entries move to `/.bak/-completed-.md` and are removed from the tracker, keeping the live file small. Set via `--completed-archive-period=weekly\\|monthly`. See [move.md](./move.md) \"Completed-section size management\" |\n| `rag-receiver` | (unset) | Optional `:` dispatch for `move` topic semantic indexing — set via the `--rag=:` CLI flag on the `move` topic (see [move.md](./move.md)). No env var or config file is consumed by this skill; the caller routes |\n| `role-profile` | (unset) | Execution-role scoping for the default invocation — CLI `--role=`. Values are **abstract profile names** (`pm` = mechanical bookkeeping/recording, `deep` = large-scale classification & audit, `impl` = implementation); this skill never hardcodes model names. Resolution chain: explicit flag → context self-detection → unset = full pipeline (backward compatible). See \"Role-based execution\" below |\n| `secondary-sync-receiver` | (unset) | Optional `:` dispatch for the `sync` topic — runs a project's non-GitHub backlog tracker (Plane, Jira, etc.) in the same cadence as this skill's GitHub PR/Issue sync, instead of letting it drift independently. Set via the `--secondary-sync=:` CLI flag. No tracker name is hardcoded — the receiver owns all tracker-specific details. See [sync.md](./sync.md) \"Secondary-tracker sync cadence\" |\n| `task-tracker` | `fix_plan.md` | Tracker filename. Use `checklist.md` for non-Ralph workspaces |\n\n## Default invocation (no args)\n\nWhen `/fix-plan` is invoked with **no args**, it must execute the following sequential pipeline (scoped by the resolved role profile — see \"Role-based execution\" below):\n\n**Step 0 — Recency check (HARD STOP, runs before task registration)**: before registering pipeline tasks, scan the tracker's pinned/header block (if the tracker has one) for a \"last full pipeline run\" marker left by a prior invocation of this same default-invocation pipeline. If found and it indicates a very recent completion (same calling context, no new external trigger since), report what that run covered and call `AskUserQuestion` offering: skip entirely (report only) / run selective steps (e.g. Sync only, since external state may have moved) / run the full pipeline anyway. Do not silently start Step 1 when recent-completion evidence is already present in the file being read — the tracker is both the pipeline's operand and, when this marker exists, its own run log. If no marker exists (or the tracker has no pinned block), proceed directly into Step 1 as before — this step is a no-op on trackers that don't use the convention.\n\n**Recency-ask answer reuse (HARD STOP — never re-ask a scope question the user already answered)**: the Step 0 recency ask is a per-day, per-context decision — not a per-invocation ritual. Before calling `AskUserQuestion`, read the tracker's pipeline log for recency-ask answers the user already gave today in the same calling context: (a) if the user already answered a recency ask today, reuse that answer's pattern (e.g. \"core only\" → skip the steps that would duplicate a same-day 0-change run) instead of re-asking; (b) an explicit role-flagged re-invocation (e.g. `--deep`) made after a same-role run already completed today **is itself the scope answer** — do not ask; skip the pipeline steps that would duplicate that run (report what was skipped and why) and proceed straight to that role's remaining actionable work (for `deep`, the dedicated model-triage section's executable items; for `pm`/`impl`, due REPEAT items and surfaced `selfable` candidates); (c) re-ask only when external state has plausibly moved in a way the user has not seen (new merges/closes since the last run), or an explicit scope argument conflicts with the logged answer. The user answering the same scope question twice in one day is a defect, not diligence. **Step-dedup never exempts queue execution (HARD STOP)**: what recency-reuse skips is the *pipeline steps* only — the role's remaining actionable queue (the dedicated deep-audit items, due REPEAT items, surfaced `selfable` candidates) must still be drained, or explicitly enumerated as user-decision remainders. Closing the run on bookkeeping alone because \"today's steps already ran\" is a mandate-shrink this clause does not authorize.\n\n1. **Move / Archive**: Dispatch to the configured **archive receiver** (or fall back to the `move` topic) to harvest/cleanup Completed entries.\n2. **Format**: Verify the schema, markers, and section structure of the tracker.\n3. **Sync**: Poll external GitHub states (`gh pr view` / `gh issue view`) for referenced issues/PRs to auto-resolve completed ones.\n4. **Priority**: Triage and sort the remaining `[BLOCKED]` list based on the synchronized states.\n5. **Flowchart sync**: Compare the `## Flow Chart` section's node labels and dependency edges against the priority tags just produced in step 4 — update any node whose `[P*]` label, or whose backing item's resolved/removed state, has drifted from the live tracker. See [flowchart.md](./flowchart.md) \"Sync procedure\". Immediately after, run the **pinned-mission liveness check** (same step, `pm` role only): check the tracker's pinned header block for ``-cited missions whose backing items have all resolved, and surface any candidate via `AskUserQuestion` — never auto-write. See [flowchart.md](./flowchart.md) \"Pinned-mission liveness check\".\n\n**Recency marker maintenance**: upon completing the full pipeline (through step 5, or through the REPEAT cadence check for the `pm` role profile), stamp/update the \"last full pipeline run\" marker in the tracker's pinned block with the completion timestamp and the role profile used, so Step 0 of a future invocation can find it. If the tracker has no pinned block, skip this — do not create new tracker structure solely for this marker.\n\n**Register BEFORE execute (HARD STOP)**: before Step 1 (Move) begins — after Step 0's recency check has resolved which steps are actually in scope — `TaskCreate` (or `TodoWrite` if `TaskCreate` is unavailable) must register one task per pipeline step actually being run (Move/Format/Sync/Priority/Flowchart-sync for the full pipeline, fewer for a role-scoped subset or a Step-0-narrowed run — see \"Role-based execution\" below). A default-invocation `/fix-plan` run is multi-step by definition; \"the tracker looks small\" is not an exception. If a `TaskCreate` call errors, retry it with the corrected parameters from its own error message before any Move/Sync/Priority/Flowchart Edit proceeds — treating a retry as unnecessary overhead and silently dropping tracking is the exact violation this line prevents. Mirrors `~/.claude/skills/wip/SKILL.md` \"Register BEFORE execute\".\n\n**Subagent-delegated pipeline runs require artifact verification, not just TaskUpdate trust (HARD STOP)**: when a caller delegates this default pipeline to a subagent (`Agent` spawn) rather than executing it directly, a subagent marking its assigned tasks `TaskUpdate(status: \"completed\")` is NOT sufficient evidence the corresponding tracker edits actually happened. **No whole-pipeline hand-off**: never hand the whole registered task set to one subagent call as a single \"run pm\" prompt — dispatch (or check in on) each step individually, and after each reported-done step, independently re-read the tracker yourself (a `git diff`/section-length/marker check against the actual file) before treating the next step as safe to start. Before treating any delegated run as done, the delegating caller must independently confirm at least one concrete artifact change per claimed step — e.g. a new `## Pipeline Execution Log` entry, a diff in the `## Flow Chart` node count, a changed `[BLOCKED:P*]` count, or a new `## Completed` entry. Two consecutive idle/no-evidence status replies from a delegated agent means stop waiting and take the remaining steps over directly, not send a third status request — verify the tracker file directly (line counts, section diffs) and take over the remaining steps yourself if the artifacts show no real change. A subagent's self-reported completion is a claim, not proof. This mirrors a real incident: a subagent given the whole pipeline marked all 6 default-pipeline steps `completed` while leaving the tracker file byte-for-byte unchanged.\n\n### Role-based execution (`role-profile`)\n\n**Plan & Research Reading Prerequisite Gate (HARD STOP)**: When executing tasks from `fix_plan.md` or cited plan snippets, the agent MUST first read the full related research document or plan file (`plan-*.md`, `docs/`) via `view_file` before starting any implementation steps (CLI commands, repo renames, code edits).\n\n**Premise re-verification (HARD STOP)**: reading the plan is not enough. Before the first implementation step, re-verify the plan's external premises against primary sources — every issue / PR / release / tracker item the plan cites as a blocker or precondition (`gh pr view` / `gh issue view` / the cited tracker line). A `status: decided|approved` plan may predate the world: a cited external blocker can resolve (or reverse) between authoring and start. This extends [draft.md](./draft.md) Stage 2 step 1's promote-time re-verification to ALL plan-gated starts, not only draft promotes.\n\n**Plan Generation Complete Deep Audit Registration Gate (HARD STOP)**: When the authoring or revision of any plan document (`plan-*.md`) is completed, stopping after file creation — leaving the plan with no tracker entry that hands it to the next stage — is strictly prohibited (`HARD STOP`). The agent MUST immediately register an audit request entry in the tracker's dedicated deep-audit section (`## Deep Tasks`, or the `## Target Tasks` section described in [model-triage.md](./model-triage.md)) with a `[BLOCKED:P*:selfable]` marker whose priority comes from normal triage ([priority.md](./priority.md)) and the caller's configured `audit_status: pending_*` token, citing the plan and research documents. Implementation work may not proceed until the `deep` profile's audit completes and the entry reaches an `audit_status: approved_by_*` value, at which point [model-triage.md](./model-triage.md)'s implementation-queue move obligation applies. Concrete model names stay caller-side — see the role-resolution note below.\n\nThe default pipeline is scoped by the execution role, so a high-capability session is not spent on mechanical bookkeeping — and a bookkeeping session does not attempt deep-analysis passes it is unsuited for.\n\n**Role resolution chain** (first match wins):\n\n1. Explicit `--role=` CLI flag\n2. **Context self-detection** — when the invoking agent can identify the model it is running on (from its own runtime context, e.g. a model identifier exposed by the harness) AND the workspace declares a model→profile mapping (a local operating note in the tracker, a project rule — caller-side, never in this skill), resolve the profile from that mapping\n3. Neither available → run the **full pipeline** (backward compatible — unchanged behavior for existing users and environments without role mappings)\n\n**Pointer-tracker resolution (HARD STOP)**: Before concluding \"no candidates\" for a workspace's local `fix_plan.md`/`checklist.md`, check whether its active-work section has been replaced with a redirect note pointing to a parent/org-level tracker (e.g. an HTML comment or line like \"this repo's items live in `` — see there\" / \"moved to ``\"). If found, resolve the referenced path and treat **that parent tracker's own top-level `##` sections** (not just the specific subsection the note points at) as in-scope for this invocation's Move/Sync/Priority/impl-candidate steps. A redirect narrowing to one subsection (e.g. `## Fable Target Tasks`) is not evidence the rest of the parent tracker (`## Priority Work`, `## REPEAT`, `## TODO`, etc.) is out of scope — those sections are exactly where `pm`/`impl` candidates live.\n\n**Full-header self-check (HARD STOP)**: If you ran `grep \"^#\"` (or equivalent) to get the tracker's section list, you must Read **every** top-level `##` section from that list before reporting candidate counts — not just the section you most recently wrote to. Recency (having just edited a section) is not grounds to skip sibling sections; it is exactly the bias that causes a populated `## Priority Work` / `## REPEAT` section to be missed while a freshly-touched `## Fable Target Tasks` gets re-read.\n\n**Sub-tracker → redirect-file consolidation (write side of Pointer-tracker resolution)**: when a sub-repo/sub-workspace is found to have mistakenly grown its own standalone `.ralph/fix_plan.md` (or `checklist.md`) instead of using the parent/org-level tracker — i.e. the exact state the read-side resolution above is designed to detect and follow — consolidate it:\n\n1. **Merge content into the parent tracker.** Move each checklist item (Progress/Plan Drafts/etc.) into the matching top-level section of the parent, prefixed with the sub-repo name (e.g. `turborepo-web apps/vpp scaffolding ...`) so it stays greppable by that prefix.\n2. **Archive supporting files** (`.bak/*`, `issue-drafts/.bak/*`) into the parent workspace's equivalent directories, renamed with the sub-repo prefix to avoid collisions with the parent's own archived files of the same name.\n3. **Replace the sub-tracker directory with a single plain **text file** at the same path** (e.g. `/.ralph` — not `/.ralph/fix_plan.md`, the directory itself). The file's body states the redirect (where the real tracker now lives + which prefix to grep for) and explicitly says not to recreate the path as a directory. Converting the directory to a file is the mechanical guard: a later attempt to write a nested path like `.ralph/fix_plan.md` fails outright instead of silently recreating the mistake.\n4. **Back up before merging** — the sub-tracker is typically a git-ignored, untracked file; snapshot the parent tracker (its edit target) before writing, since the merge is often happening in a workspace another concurrent process may also be actively editing.\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Delete the sub-tracker outright once its content is \"duplicated\" in the parent | Merge first (with the sub-repo prefix), archive the originals, only then remove — never delete a sub-tracker without a verifiable copy of its content landing in the parent |\n| 2 | Leave the reclaimed path as an empty directory \"for later\" | Replace it with the plain-text redirect file in the same turn — an empty directory invites the same mistake to recur silently |\n| 3 | Skip the parent-tracker backup because \"it's just an append\" | Back up before merging — the parent tracker in a shared/multi-session workspace can be under concurrent edit; a backup is cheap insurance against a lost merge |\n\n**Per-profile default pipeline**:\n\n| Profile | Steps executed | Skipped (reported as remainder) |\n|---------|----------------|--------------------------------|\n| `pm` | move → format → sync → priority → flowchart-sync (incl. pinned-mission liveness check) → **REPEAT cadence check** (run all due REPEAT items) → **Plan Drafts trigger scan** (surface, never author — see [draft.md](./draft.md) \"Role ownership\") → **Task Allocation & Channel Dispatch** (categorize triaged backlog into In-Session, Orca, Deep Tasks, Clawo, User Decision channels) | — |\n| `deep` | sync (cheap state refresh) → priority (judgment-quality gain) → [model-triage](./model-triage.md) re-discovery + plan-audit candidate scan → **deep-fit execution-candidate surfacing** (see \"deep-profile completion handoff\" below) | move, format, flowchart-sync (incl. pinned-mission liveness check) — surfaced as a delegation remainder for a `pm` session |\n| `impl` | sync → priority → **REPEAT overdue check** (run REPEAT items overdue by 24h+) → **Plan Drafts promote execution** (premise re-verify + `code-workflow` research→plan dispatch for triggered drafts — see [draft.md](./draft.md) \"Role ownership\"), then surface `selfable` implementation candidates | move, format, model-triage, flowchart-sync |\n| (unresolved) | full pipeline | — |\n\n**First-edit timebox (impl profile — HARD STOP)**: an `impl`-profile run exists to land implementation edits. If N minutes (default 15) elapse after the first tool call with zero deliverable edits (no Edit/Write on a non-tracker file), STOP front-loading (triage reading, option pre-verification, plan re-reads) and either (a) start the smallest viable implementation step now, or (b) report the blocker to the user. Front-loading gates (recency check, full-header read, Plan Reading Gate, premise re-verification) bound *what* to read — they never authorize unbounded *time* before the first edit. In high-latency environments (large trackers, heavy hook chains), also batch reads: prefer 1-2 large Read calls over many small shell reads, and keep pre-edit lookup calls to roughly 10 or fewer.\n\n- **REPEAT Section Execution Cadence Rule**:\n - **`/fix-plan --pm`**: Check `## REPEAT` section. If any item's due period (its \"period\" field) has elapsed since its \"last run\" field, execute it immediately.\n - **`/fix-plan --impl`**: Check `## REPEAT` section. Execute ONLY items whose due period has elapsed AND has been neglected for an additional 24+ hours (period + 24h overdue). Skip others.\n\n- A skipped step is never silently dropped: the run report must list the skipped steps and their pending workload (e.g. \"N completed `[x]` items awaiting move\") so a later `pm` session picks them up.\n- Model names never appear in this skill. The caller-side mapping translates concrete models to `pm` / `deep` / `impl` — the same supply pattern as the `--archive` / `--rag` receiver contracts.\n\n**pm-profile task allocation & channel dispatch handoff (HARD STOP)**: when a `pm` role-profile default-invocation pipeline finishes (through the REPEAT cadence check and Plan Drafts scan), concluding the run with bookkeeping alone, an open-ended \"what's next\" prompt, or passively surfacing only a single lightweight candidate is strictly prohibited (`HARD STOP`). The core identity of the PM role is active work distribution. The PM agent MUST synthesize the live `sync`/`priority` triage results into a comprehensive **Task Allocation Matrix across all 5 execution channels**:\n1. **Channel 1 (In-Session Direct Execution)**: simple P2/P3 single-file mechanical edits, documentation updates, or quick parameter fixes suitable for immediate turn execution without worktree isolation.\n2. **Channel 2 (Orca Split Terminal / Worktree)**: P0/P1 multi-file implementations, TDD cycles, or isolated feature/fix branches requiring dedicated worktree and session isolation (`wsl -- claude --model `).\n3. **Channel 3 (Deep Tasks Audit Queue)**: architectural, ontology, multi-agent topology, or large-scale design evaluations requiring deep reasoning auditor models (`fable` / `opus`).\n4. **Channel 4 (Clawo / Server Runtime)**: persistent background daemons, webhook listeners, or heavy batch RAG/archive sweeps.\n5. **Channel 5 (External Wait / User Decision)**: blockers requiring explicit human infrastructure decisions, policy choices, or remote device access.\n\nThe agent MUST physically emit this structured Task Allocation Matrix in the visible response output and present clear channel-level dispatch options in `AskUserQuestion`, enabling immediate progression of high-priority work across roles.\n\n**Post-handoff batch continuation (context-budget aware — HARD STOP)**: when the user selects candidates from a role-run's surfaced set, execute ALL selected items sequentially in the same turn. After exhausting them, check the **live** context budget (a fresh measurement, not a stale injected reading): if usage is comfortably below the session model's cleanup threshold AND same-flow follow-ups or this run's triage-surfaced `selfable` candidates remain, **continue into them in the same turn** rather than closing with another ask — pacing asks between items (or ending the turn so the user must manually re-invoke a next-action skill) are the recurrence failure mode. Asks stay reserved for genuine decision branches (deploy / push / destructive ops / scope change / items the user explicitly deferred this session). Consent gates are never overridden by remaining budget — only the pacing ask is removed.\n\n**deep-profile completion handoff (HARD STOP)**: when a `deep` role-profile run finishes its pipeline, do not close report-only. A re-discovery pass that proposes zero NEW dedicated-section entries is **not** evidence there is nothing for this session to execute — discovery (filling the section) and execution surfacing (working the backlog the section already holds) are separate axes. The current session IS the matching high-capability session, so surface **deep-fit execution candidates** from state this same run already computed:\n\n1. **Dedicated-section items** — top `## Target Tasks` entries by priority ([model-triage.md](./model-triage.md) \"Operating Loop\": the section is executed top-down within a matching model session)\n2. **Promote-ready Plan Drafts** — `## Plan Drafts` stubs whose complexity fits the deep tier; user selection of one counts as the promote decision (then [draft.md](./draft.md) \"Promote\" → `code-workflow`)\n3. **Complex-tier implementation items** — entries explicitly marked complex / autonomous-implementation-blocked that need deep-session judgment to advance\n\nPresent them via a multiSelect `AskUserQuestion` alongside any bookkeeping follow-ups — a candidate set composed only of bookkeeping items (marker fixes, registrations, cheap re-checks) plus a close option is the failure mode this handoff prevents. Consent gates stay intact: execution starts only on user selection, and drafts are never auto-promoted. If the dedicated section, Plan Drafts, and complex-tier pool are ALL empty this run, skip this handoff and close normally.\n\n**pm-profile completion handoff**: when a `pm` role-profile default-invocation pipeline finishes (through the REPEAT cadence check), do not close the turn with an open-ended \"what's next\" prompt. Reuse the `sync`/`priority` state this same run already computed and surface exactly one simple `selfable` candidate from what the `impl` row's own candidate-surfacing step would otherwise report — then confirm it via `AskUserQuestion` (proceed with it / pick something else / skip for now) instead of a generic next-step prompt. This draws from a single already-known role profile's own candidate set computed in this same run, not a speculative multi-source scan — it is a narrower, cheaper handoff than general next-action option construction. If no `selfable` candidate exists this run, skip this step and close normally.\n**Simple-vs-session self-check (HARD STOP — run before drafting the `pm-profile completion handoff` `AskUserQuestion`, not after)**: having read this paragraph once is not the same as applying it at the moment the ask is drafted — do not default straight to a \"proceed now\" option. Explicitly ask: does the candidate touch 2+ files, or does it require authoring/updating regression tests, or is it otherwise `impl`/`deep`-tier work rather than a single-file mechanical edit? If yes, it is NOT a simple in-session item — go to the Orca check below *before* finalizing the ask's options, and do not present \"proceed now\" as the sole or Recommended option without first completing that check.\n\n**Orca session-launch recommendation (conditional on Orca detection)**: when the `pm-profile completion handoff` above identifies a candidate that is not a simple in-session `selfable` item but genuinely needs a `deep` or `impl` role session, check whether the Orca IDE runtime (`stablyai/orca` — see the `orca` skill) is available: attempt ` status --json`, resolving the CLI per the `orca` skill's \"Resolve the CLI\" convention (`ORCA_CLI_COMMAND` → `orca-dev` in a dev checkout → `orca-ide` outside a managed terminal on Linux → `orca`).\n\nIf Orca is available, add a \"launch via Orca\" option to the `pm-profile completion handoff` `AskUserQuestion` for that candidate — the `orca` skill's `launch` topic (`worktree create --agent claude --prompt \"\"`) — instead of only surfacing it for later manual pickup.\n\n**If the call errors or `result.app.running` is `false`, do NOT silently skip — ask direction.** Extend the same `pm-profile completion handoff` `AskUserQuestion` with these additional options for this state (still one decision, not a second ask):\n\n- **Diagnose/install Orca, then retry** — point at the `orca` skill's own troubleshooting (\"Resolve the CLI\" errors are reported verbatim, never silently swallowed); if a dedicated `orca doctor` diagnostic topic exists by the time this runs, prefer it\n- **Use an alternative session-launcher skill already available** (e.g. `clawo`, `openclaw`) — fix-plan stays abstract here: it names the alternative skill and defers to *that* skill's own launch/send convention, the same way it already defers to caller-supplied `--archive`/`--rag` receivers rather than hardcoding their internals\n- **Dispatch as a subagent** (`Agent` tool, in-process) — a valid option, but never the Recommended one; session isolation and independent context are worth more than the convenience for `deep`/`impl`-tier work\n- **Fall back to today's surface-only behavior** (no session action, just report the candidate) — always available regardless of detected state\n\n**Duplicate-check is mandatory before recommending a NEW `deep`-role launch (HARD STOP)** — concurrent `deep`-role sessions duplicate the same large-scale classification/audit work, which is wasteful (unlike `impl`, where independent parallel implementation on different candidates is normal and this check does not apply). Before offering \"launch a new deep session,\" list running terminals (` terminal list --json`) and filter for one already working this tracker's deep-tier candidates (title/preview matching the tracker path or a `deep`-role marker — reuse the `orca` skill's `send` topic filtering convention, but skip its `ORCA_PANE_KEY` self-exclusion requirement here, since this is a check, not a delivery). A match found → offer \"send to the existing session\" (`orca` skill's `send` topic) instead of \"launch a new one.\" 2+ matches found → do not auto-pick — list every match as a separate option (same disambiguation rule as `orca/send.md`).\n\n| # | Don't | Do |\n|---|-------|----|\n| 1 | Recommend `orca launch` for every deep/impl candidate regardless of environment | Detect Orca first (`status --json`); skip the option entirely if unavailable |\n| 2 | Launch a new `deep` session without checking for one already running | `orca terminal list --json` + title/preview filter first; route to an existing match instead of duplicating |\n| 3 | Auto-select among 2+ matching running sessions | List every match as a separate `AskUserQuestion` option — never guess |\n| 4 | Apply the same duplicate-check requirement to `impl` launches | `impl` sessions may run concurrently on independent items — duplicate-check is `deep`-only |\n| 5 | Silently skip the recommendation when Orca detection fails | Ask direction instead — diagnose/install Orca / use an alternative launcher (`clawo`, `openclaw`) / subagent (not recommended) / surface-only |\n| 6 | Default the `pm-profile completion handoff` ask straight to \"proceed now\" because the candidate seems short to describe | Run the simple-vs-session self-check first — a short description can still be multi-file/impl-tier work; length of the candidate's own text is not the signal |\n\n**Mandatory Output Reporting Contract (HARD STOP)**: The agent must physically emit the Step 4 Priority Triage candidate list (P0–P3 sorted by `:selfable` vs `:external`) in the visible response text BEFORE marking the task as completed (`[x]`) or invoking `AskUserQuestion`. Suppressing Step 4's summary table output or marking tasks completed prior to physical output emission is strictly forbidden.\n\n### Receiver contract\n\nThe fix-plan skill stays vendor-agnostic — no hardcoded receiver name. The caller (Claude in the user's environment) routes to whichever receiver is registered.\n\n| Field | Value |\n|-------|-------|\n| Dispatch flag | `--archive=:` (CLI) |\n| Receiver responsibility | (1) Read source's `## Completed` section, (2) Append items to its own report format, (3) Edit source to remove harvested lines |\n| Idempotency | Receiver must be safe to re-invoke — already-harvested items must not double-append |\n| Failure handling | If receiver unavailable / errors → log + fall back to `move` topic without touching source |\n\n### Caller auto-dispatch heuristic\n\nThe caller decides at invocation time:\n\n1. Check `--archive=:` CLI arg → if present, use it\n2. Otherwise scan registered skills for a Completed-archive contract (matching topic name or declared `fix-plan-archive` keyword in description)\n3. Exactly one match → dispatch automatically\n4. Multiple matches → ask the user\n5. Zero matches → fall back to `move` topic\n\n### Example receivers (illustrative — not bundled)\n\nThe following are environments in which an archive receiver might be registered:\n\n| Environment | Receiver pattern | What it does |\n|-------------|-----------------|--------------|\n| Weekly-report workflow | a topic that ingests fix_plan Completed into weekly reports | Append by ISO-week + remove from source |\n| Postmortem log | a topic that appends to a rolling postmortem document | Append + remove |\n| RAG store | a topic that upserts Completed entries into a vector DB | Upsert + remove |\n\nThese are **examples**, not dependencies. The fix-plan skill does not import any of them; the caller supplies the receiver.\n\n## Quick Reference\n\n### Default invocation\n\n```bash\n/fix-plan # dispatch to configured archive-receiver (or fall back to move)\n/fix-plan --archive=: # explicit receiver\n```\n\nSee \"Default invocation (no args)\" section above.\n\n### Schema (format)\n\n```markdown\n# Fix Plan\n\n## Progress\n\n- [ ] {Action}\n - **Why**: {motivation}\n - **How to apply**: {procedure}\n- [BLOCKED:P0:external] {Action} (awaiting X)\n- [x] {Completed item — pending move}\n\n## Completed\n\n- 2026-06-07 12:00 — {one-line summary} (commit {sha}, PR #{N})\n```\n\nSee [format.md](./format.md) for full schema.\n\n### BLOCKED priority + reason (priority — NEW convention)\n\n```markdown\n- [BLOCKED:P0:external] PR #45 user merge decision\n- [BLOCKED:P1:selfable] consolidate Step 2.4 PR create (branch + body ready)\n- [BLOCKED:P2:external] CodeRabbit re-review awaiting\n```\n\n- **P0**–**P3**: GitHub priority label-aligned (P0 highest)\n- **external**: true external dependency\n- **selfable**: progressable now (P-rank for immediate action)\n- **Triage Step 0 — sync external state first (HARD STOP)**: `/fix-plan priority` invokes `sync` topic before classifying — `gh pr view ` + `gh issue view ` on every referenced PR/Issue. Auto-resolves merged/closed entries to `[x]` so stale items don't get sorted as live BLOCKERs\n\nSee [priority.md](./priority.md) for full convention. When a workspace mirrors backlog into Plane, `P0`-`P3` maps 1:1 onto Plane's native `urgent`/`high`/`medium`/`low` priority (`../backlog/scripts/plane_sync.py`'s `normalize_priority()`; see [sync.md](./sync.md) \"Secondary-tracker sync cadence\" and `backlog/SKILL.md` \"Plane Issue DELETE Prohibition & Priority Mapping (HARD STOP)\").\n\n### Add new item\n\n```markdown\n- [ ] {one-sentence Action}\n - **Why**: {motivation 1-2 sentences}\n - **How to apply**: {procedure / tools / commands}\n```\n\nSee [add.md](./add.md) for length budget + deliverable separation.\n\n### Upsert (dup-check before authoring)\n\nBefore writing a new item, grep the whole tracker for its core keywords:\n\n```bash\ngrep -n \"<2-3 core keywords>\" \n```\n\nNo hit → fall back to `add`'s schema above. Hit on the same Action → update that item in place (preserve `Why`, add a delta, state any priority reclassification as `old → new` + reason). See [upsert.md](./upsert.md).\n\n### Claim an item in progress (multi-session)\n\nRe-read the tracker, then stamp a lease tag before starting work so a concurrent session does not duplicate it:\n\n```markdown\n- [ ] [CLAIMED::] {Action}\n- [BLOCKED:P1:selfable] [CLAIMED::] {Action}\n```\n\n`[CLAIMED]` is a lease annotation (not a checkbox state). Completion (`[x]` → Completed) drops it; a claim older than the TTL (default 4h) or from an ended session is takeable. See [claim.md](./claim.md).\n\n### Record a deferred plan draft\n\n```markdown\n## Plan Drafts\n\n- [BLOCKED:P2:selfable] {Purpose — one line}\n - **Defer reason**: {why postponed}\n - **Resume trigger**: {what promotes it}\n - **Expected deliverable**: research | plan | checklist\n```\n\nInvoked `/fix-plan draft`. Stub only (no full plan) → promote to `code-workflow` research→plan when the trigger fires.\n\nPlan Drafts are **always** `[BLOCKED:P*:selfable]`, never `[ ]` — `[ ]` would let autonomous loops (e.g. Ralph wrapper) act on the entry, but promote requires a user decision. The reason is always `:selfable` (body file ready, waiting on a user signal, not on a third party). Priority `P0`-`P3` ranks promote urgency relative to other drafts. See [draft.md](./draft.md) and [priority.md](./priority.md).\n\n### Move to Completed\n\nAfter `[x]` checked, summarize to one line + move to Completed section. See [move.md](./move.md).\n\n### Archive Completed periodically (keep the tracker small)\n\nOn a period boundary, move older `## Completed` entries to a local partition file so the tracker never bloats:\n\n```text\n/.bak/-completed-YYYY-MM.md # monthly (default)\n/.bak/-completed-YYYY-Www.md # weekly (--completed-archive-period=weekly)\n```\n\nReceiver-independent (no external receiver needed). Entries before the current period move out; the current period stays. See [move.md](./move.md) \"Completed-section size management\".\n\n### Sync GitHub state\n\n```bash\ngh pr view --json state,mergedAt # PR\ngh issue view --json state,closedAt # Issue\n```\n\nMERGED PR or CLOSED issue → auto `[x]`. PR CLOSED-without-merge → `[BLOCKED:P2:external]`. See [sync.md](./sync.md).\n\n### Issue Drafts lifecycle\n\n`issue-drafts/.md` → `gh issue create` → archive to `.bak/` → delete from fix_plan. See [issue-drafts.md](./issue-drafts.md).\n\n### Plane Intake Ingestion Gate for PR & Completed Items (HARD STOP)\n\nWork items backed by GitHub PRs or completed during sessions without a Plane identifier (`[ES6KR-]`, `[INFRA-]`, etc.) MUST be ingested into Plane via Intake (`plane_create_issue.py`) to preserve historical audit logs and decisions. See `backlog` skill.\n\n## See Also\n\n- `github-flow` (depends-on) — `gh` CLI conventions for sync + register\n- `backlog` (depends-on) — Plane issue/intake lifecycle and sync engine\n- `orca` (optional, conditional) — session-launch recommendation for deep/impl role candidates when the Orca IDE runtime is detected; see \"Orca session-launch recommendation\" above\n- Ralph integration is a separate workstream maintained outside this published skill. A Ralph wrapper, when present, owns Ralph-specific concerns: the `## REPEAT` persistent-item section, autonomous-loop `[BLOCKED]` skip semantics, and the caller-side `--rag=:` dispatch (this skill exposes only the abstract flag contract). See the Ralph project's documentation for wrapper details\n\nFile v0.17.1:_meta.json\n\n{\n \"ownerId\": \"kn74k8yfvftx6f062qa8fzyd8h8373jd\",\n \"slug\": \"fix-plan\",\n \"version\": \"0.17.1\",\n \"publishedAt\": 1791273355701\n}\n\nFile v0.17.1:add.md\n\n# Add\n\nNew item authoring schema. Action / Why / How three-element format, length budget, deliverable separation rules.\n\n## Item format (HARD STOP)\n\nEvery new fix_plan entry contains three required elements. Single-line action-only entries are forbidden.\n\n```markdown\n- [ ] {Action: imperative verb-form, one sentence}\n - **Why**: {motivation — purpose, background, intent in 1-2 sentences}\n - **How to apply**: {procedure / tools / verification approach}\n - {optional sub-steps, command examples, file paths}\n```\n\n### RAG pre-lookup gate (HARD STOP — context direction)\n\n**Before adding or upserting an item, run a RAG (vector-memory) semantic search on the item's core keywords.** This gate answers a different question than the Canonical medium gate below: canonical-medium asks \"is this tracker the record of truth?\"; this gate asks \"is there already known context on this topic?\" Writing a new entry without checking prior context risks re-investigating a problem that a past session already diagnosed, or duplicating an item that already exists in a different phrasing.\n\n1. **Search first**: run the skill domain's standard semantic-search script (e.g. `qdrant-search.py --semantic \"\" --limit 5`) before touching the tracker file's content. Prefer the domain's own script over an ad-hoc MCP call — see the workspace's tool-selection-priority rule (script/CLI first, MCP only when no script exists).\n2. **Fold hits into the entry**: if the search surfaces prior diagnosis, an existing related item, or a linked plan/research document, reference it in the new entry's body (`**Why**` or a one-line sub-bullet) instead of re-deriving the same analysis from scratch.\n3. **No hits is not skip-worthy evidence of anything but absence**: zero results means proceed with authoring normally — it does not excuse skipping the search itself.\n\n#### Don't / Do\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Read/edit the tracker file directly to add an item without running a semantic search on the item's topic first | Run the semantic search first, then open the tracker file to place the entry |\n| 2 | Re-derive a diagnosis or procedure from scratch when the search surfaces a matching prior session's finding | Cite the prior finding (one-line pointer) and build on it instead of repeating the investigation |\n| 3 | Treat the Canonical medium gate's pinned-header check as covering this | The two gates are independent axes — pinned-header answers \"where does this belong\", RAG search answers \"what is already known about it\". Both run, in either order relative to each other, but RAG search runs before the item body is drafted |\n\n#### Self-check before drafting a new entry\n\n1. Did you run a semantic search on the item's core keywords before drafting the entry body?\n2. If the search returned relevant hits, does the entry body reference them (rather than silently ignoring them)?\n3. If the search returned nothing, did you still author the entry normally rather than treating the empty result as a reason to skip the check next time?\n\n### Canonical medium gate (HARD STOP — creation direction)\n\n**Before adding a new item, determine whether this tracker is the canonical backlog or an index into an external one.** When an external tracker is canonical, an entry written only here is not a record — it is a pointer with nothing behind it, and it disappears the moment the file is regenerated or overwritten by a concurrent writer.\n\nDetect the canonical medium from **both** signals — either alone is insufficient:\n\n1. **Pinned header declaration** — read the file's top block (roughly the first 10 lines) before the session's first add. A tracker that delegates to an external system declares it there.\n2. **Existing index lines** — count entries carrying an external reference suffix (e.g. `→ ()`). A file where such entries dominate is an index in practice, whatever the header does or does not say.\n\n| Canonical medium | How to add |\n|------------------|-----------|\n| This file | Add the three-element entry normally (see below) |\n| External tracker | **Create the item in the external tracker first**, then write the local entry as an index line carrying the returned URL |\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Add `- [ ]` here and consider the item recorded, without checking whether an external tracker owns this backlog | Read the pinned header + count existing index lines first. External canonical → create there, then index here |\n| 2 | Reach the file by targeted read (`offset`) or grep and therefore never see the header | The header is where delegation is declared. A targeted read that skips it also skips the rule governing the write you are about to make — under context pressure this is the normal access pattern, not an edge case |\n| 3 | Defer the external write (\"record locally now, sync later\") | The local file is not durable against regeneration or a concurrent writer. Unsynced local-only entries are the exact loss this gate exists to prevent |\n| 4 | Treat the completion-direction guard (verify the external item before flipping `[x]`) as covering this | Completion and creation are separate directions. Guarding only completion leaves every new item unprotected |\n\n### Why each element is required\n\n| Element | Purpose | What breaks if omitted |\n|---------|---------|------------------------|\n| **Action** | The work itself, in imperative form | Reader has no clue what to do |\n| **Why** | Information transfer to future sessions | Future session asks the user — context decays between sessions |\n| **How to apply** | Concrete procedure / tools / verification | Future session has to re-derive the approach |\n\n### Why is mandatory — future-session test\n\nfix_plan is a **session-to-session information transfer medium**. The context in the author's head right now will be gone in the next session. Action-only entries force future sessions to guess context and ask the user.\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | `- [ ] Register SSH deploy key → push → trigger downstream sync` (action chain only) | `- [ ] Register SSH deploy key on GitHub`
`- **Why**: downstream GitOps tool needs a deploy key to fetch the repo over git+ssh`
`- **How to apply**: ed25519 keypair → public to repo Settings/Deploy keys → private as downstream Secret` |\n| 2 | `- [ ] Change identity provider settings` (target ambiguous) | `- [ ] Change identity provider's invalidation flow`
`- **Why**: OIDC logout then redirect bounces back to sign-in (regression)`
`- **How to apply**: IaC manifest → plan → apply` |\n| 3 | `- [ ] X migration (see plan doc)` (plan doc reference only) | `- [ ] X migration`
`- **Why**: {core motivation, 1-2 sentences}`
`- **How to apply**: {core procedure summary}`
`- See: docs/generated/plan-X.md for the full spec` |\n| 4 | `- [ ] step → next step → final step` (chain only, no Why) | Split each step into a separate item OR keep one main item + Why + sub-bullet steps |\n\n### Self-check before adding\n\n1. **Action**: clear imperative verb-form, one sentence?\n2. **Why**: 1-2 sentences explaining the motivation?\n3. **How to apply**: core procedure / tools / commands?\n4. **Future-session test**: \"Can a future session proceed from this entry alone without asking the user?\" — If no, the entry is information-incomplete\n5. **Canonical medium**: did you confirm, from the pinned header **and** the existing index-line count, whether an external tracker owns this backlog? If it does, was the item created there first and is this entry carrying its URL? — A local-only entry under an external canonical medium is not a record\n\n## Length budget — verbose body forbidden (HARD STOP)\n\nfix_plan item body content = Action + Why + How (summary) + artefact reference + external link. Maximum **5-7 lines** per item. Verbose content goes in separate artefacts.\n\n### What does NOT belong inline\n\n- Full diagnostic results\n- Reproduction evidence tables\n- Fix-option matrix (A / B / C / D trade-off)\n- Trade-off discussion\n- Related-context lists (4 or more items)\n- Multi-step checklists (5 or more)\n\n### Deliverable separation matrix\n\n| Content kind | Medium | Location |\n|--------------|--------|----------|\n| Item identification (Action one-line) | **fix_plan body** | `- [ ] ...` |\n| Why 1-2 sentences | **fix_plan body** | sub-bullet |\n| How to apply summary (≤ 5 steps) | **fix_plan body** | sub-bullet |\n| Artefact path (research / plan) | **fix_plan body** | 1-line sub-bullet |\n| Issue / PR / comment link | **fix_plan body** | 1-line sub-bullet |\n| Decision record (one-line) | **fix_plan body** | 1-line sub-bullet |\n| Symptom detail / root-cause flow / reproduction table | **research artefact** | `docs/generated/research-.md` or `.ralph/docs/generated/research-.md` |\n| Fix-option matrix / trade-offs / Test Plan / implementation procedure | **plan artefact** | `docs/generated/plan-.md` |\n| Related-context list (4 or more items) | **inside the research/plan artefact** | same as above |\n| Multi-step checklist (5 or more items) | **checklist artefact** | `docs/generated/checklist-.md` |\n| Progress / status updates for an item that references a plan artefact | **linked plan artefact — its `## Progress Checklist` section** (create the section if missing) | inside the referenced `plan-.md` |\n| Open action items (the referenced plan's remaining `[ ]` next-actions) | **fix_plan body — as `- [ ]` sub-checkboxes** | surface the immediate next-phase open items under the item; deeper phases stay pointer-only (keep the length budget). Distinct from \"progress/status updates\" above: what remains *to do* stays visible/trackable in the tracker, while status narrative goes to the plan |\n\n### Don't / Do\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Embed diagnostic / reproduction / option matrix inline in the fix_plan body | Author `research-.md` + `plan-.md` → fix_plan body has the path only, one line |\n| 2 | List 4 or more related-context items as sub-bullets in the fix_plan body | Move to a \"Related context\" section inside the research / plan artefact. fix_plan doesn't mention them |\n| 3 | Write \"Decision record\" / \"User decision\" as a paragraph in the body | One-line sub-bullet: `- **User decision (YYYY-MM-DD)**: Option D — short rationale` |\n| 4 | Allow a fix_plan body item to exceed 10 lines | Cap at 5-7 lines. Anything over → split into artefacts |\n| 5 | Include the A/B/C/D comparison table in fix_plan | Move to `plan-.md` \"Trade-offs\" section |\n| 6 | Relocate item detail into a NEW artefact without Reading the research/plan artefacts the item already references | Read each referenced artefact first — progress/status content routes into the plan's `## Progress Checklist` (create the section if missing); create a new artefact only for content with no owning research/plan doc |\n| 7 | Reduce an in-progress plan (one that has open `[ ]` Progress-Checklist items) to a prose-only pointer with zero checkboxes in the tracker item | Surface the immediate next-phase open items as `- [ ]` sub-checkboxes under the tracker item (within the length budget); keep deeper phases as a pointer to the plan's `## Progress Checklist`. A tracker item for in-progress work must stay actionable — the \"slim pointer\" rule governs status narrative, not the open action list |\n\n### Self-check before saving an entry\n\n1. Is the body 5-7 lines or fewer? If over, split into artefacts\n2. Does the entry contain diagnostics / reproduction / option matrix / related context? If yes, move to research/plan artefacts\n3. Is each artefact path expressed as a one-line sub-bullet?\n4. Are decision links one line each?\n5. Does the item already reference a research/plan artefact? Read it BEFORE relocating any content — progress/status updates belong in that plan's `## Progress Checklist` (create it if missing), not in a new standalone file\n6. Does the referenced plan have open `[ ]` Progress-Checklist items? If yes, did you surface the immediate next-actions as `- [ ]` sub-checkboxes in the tracker item, rather than leaving a prose-only pointer?\n7. Did the task finalize a plan artefact (`plan-*.md`)? If yes, did you register an audit entry in the tracker's deep-audit section with the full shape SKILL.md's \"Plan Generation Complete Deep Audit Registration Gate\" requires — `[BLOCKED:P*:selfable]` marker, `audit_status: pending_*` token, and citations of both the plan and research documents?\n\n### Example — Bad (verbose)\n\n```markdown\n- [ ] SSO re-login auto-logout fix\n - **Why**: …30 lines of diagnostics / reproduction evidence / option matrix / related context, four items…\n```\n\n### Example — Good (split)\n\n```markdown\n- [ ] SSO re-login anonymous-logout guard\n - **Why**: Logout → immediate re-login triggers a first-cycle auto-logout. Affects all environments / apps / accounts\n - **Reproduction env**: dev-cluster / sample app / admin role\n - **Decision (2026-05-21)**: Option D (proxy + login route) — single PR\n - **Artefacts**: `docs/generated/research-sso-relogin-anonymous.md` + `plan-sso-relogin-anonymous-guard.md`\n - **Issue**: #255 comment (link)\n```\n\n## See also\n\n- [format.md](./format.md) — section structure and markers\n- [priority.md](./priority.md) — `[BLOCKED:P0-P3:reason]` annotation when an item is blocked\n- [move.md](./move.md) — how `[x]` entries get summarised into Completed\n- [upsert.md](./upsert.md) — dup-check the tracker before running this topic's schema; this file is upsert's fallback path for genuinely new items\n\nFile v0.17.1:CHANGELOG.md\n\n# Changelog\n\n## [0.17.1](https://github.com/es6kr/skills/compare/fix-plan-v0.17.0...fix-plan-v0.17.1) (2026-10-04)\n\n\n### Bug Fixes\n\n* **fix-plan:** add a general attribute slot to update_item ([#582](https://github.com/es6kr/skills/issues/582)) ([7610a95](https://github.com/es6kr/skills/commit/7610a95552136a7a29622b6b48c75830a24f765e))\n\n## [0.17.0](https://github.com/es6kr/skills/compare/fix-plan-v0.16.1...fix-plan-v0.17.0) (2026-09-30)\n\n\n### Features\n\n* **fix-plan, consolidate:** consolidate task coordination, review collection, and docs ([d6162d8](https://github.com/es6kr/skills/commit/d6162d8d25bb80c85aa2c5cd475afdf0ee638535))\n* **fix-plan:** add task lock, artifact scanner, prune, and cleanup utilities ([90c8d34](https://github.com/es6kr/skills/commit/90c8d342a0e56ab312b0b59473857ebc149fab1b))\n\n\n### Bug Fixes\n\n* **fix-plan:** enforce flowchart precedent, residual verification, and triage rules ([acea09d](https://github.com/es6kr/skills/commit/acea09dd37a62479ffd90e82e6fccdeadac2d5b4))\n* **fix-plan:** make the task lock a real mutex and the tracker write atomic (green) ([4dc2f7e](https://github.com/es6kr/skills/commit/4dc2f7e433a0f6fa19fee5120c7b0ec58f49477c))\n\n## [0.16.1](https://github.com/es6kr/skills/compare/fix-plan-v0.16.0...fix-plan-v0.16.1) (2026-09-27)\n\n\n### Bug Fixes\n\n* **fix-plan:** add [ASSIGNED:<target>] tag to claim.md for workspace-aware task assignment ([#555](https://github.com/es6kr/skills/issues/555)) ([8d3ad37](https://github.com/es6kr/skills/commit/8d3ad37245dc53bae748879f27bcd4db9dbcd72b))\n* sync claude-memory refs to agent-memory-personal collection alias ([5f7fed1](https://github.com/es6kr/skills/commit/5f7fed113de84196df3a74688ea464b5c594d587))\n\n## [0.16.0](https://github.com/es6kr/skills/compare/fix-plan-v0.15.0...fix-plan-v0.16.0) (2026-09-24)\n\n\n### Features\n\n* **fix-plan:** add hook-integrity source<->cache reverse sync check ([77aa86b](https://github.com/es6kr/skills/commit/77aa86ba3f9b74a51c3ea02bb9fd0adb58b46660))\n* **fix-plan:** add pipeline log and hook integrity check scripts ([e93a432](https://github.com/es6kr/skills/commit/e93a4323b54a311fcda6855163ffe14c2c146412))\n\n\n### Bug Fixes\n\n* **fix-plan:** add pinned-mission liveness check to flowchart-sync step ([#527](https://github.com/es6kr/skills/issues/527)) ([5c962a7](https://github.com/es6kr/skills/commit/5c962a71ffab690e3844855026ca21d0c141d968))\n* **fix-plan:** add task allocation and channel dispatch stage to pm profile ([342a572](https://github.com/es6kr/skills/commit/342a5726a75da01467b4ada57d41dbd1df305136))\n* **fix-plan:** carry k3s_workload through the v2 profile translation ([73e2994](https://github.com/es6kr/skills/commit/73e29949563689befe23c6f8f999fd8bff86664b))\n* **fix-plan:** document the Pipeline Execution Log section and its writer scripts ([4b42a94](https://github.com/es6kr/skills/commit/4b42a948f9d5cbd06a7362b25c5f910eab783520))\n* **git-repo:** add prune_merged_worktrees.py + 7 accumulated fixes ([3d2ee94](https://github.com/es6kr/skills/commit/3d2ee9425285347d8f7e7698049d6e5769f73f92))\n* make the Plane K3s fallback reach its cluster, and stop the retag guard firing on citations ([ce0abde](https://github.com/es6kr/skills/commit/ce0abded29d992ac89b865e806aed9b531d4909d))\n\n## [0.15.0](https://github.com/es6kr/skills/compare/fix-plan-v0.14.0...fix-plan-v0.15.0) (2026-09-20)\n\n\n### Features\n\n* **fix-plan:** add sync_shared_artifacts.py for CollabMD frontmatter upsert and sync ([a866685](https://github.com/es6kr/skills/commit/a8666857a83b056a692560a77bfe8d93e7f891c0))\n\n\n### Bug Fixes\n\n* address code review feedback ([0c08bfb](https://github.com/es6kr/skills/commit/0c08bfbf2b5b737fdce685c8f15ead56c64290f4))\n\n## [0.14.0](https://github.com/es6kr/skills/compare/fix-plan-v0.13.0...fix-plan-v0.14.0) (2026-09-18)\n\n\n### Features\n\n* **fix-plan:** add archive_pipeline_log.py script for Pipeline Execution Log rotation ([f550841](https://github.com/es6kr/skills/commit/f550841de81f5fda64bd55b7e97958e5a419e0a2))\n\n\n### Bug Fixes\n\n* address code review feedback ([8c1c058](https://github.com/es6kr/skills/commit/8c1c05896c99983a401d4a725ce3cc2cf005e524))\n* **fix-plan:** add --delete to update_item.py and codify plan audit gate ([aa6fd97](https://github.com/es6kr/skills/commit/aa6fd97dbf41eaf03c6efff99fe82d4dbb622dfe))\n* **fix-plan:** add in-place sub-bullet append to add_item.py ([cc0a6af](https://github.com/es6kr/skills/commit/cc0a6af7718e9bcd9d699c69bfea4f912ce6a2a7))\n* **fix-plan:** align default memory collection resolution with works-config ([3f84946](https://github.com/es6kr/skills/commit/3f84946da6a23379ebe18cf05716ceb88d9b8a48))\n* **skills:** document canonical Do/Don't tables for Plane URLs, plan sync, and pre-merge reviews ([7069da8](https://github.com/es6kr/skills/commit/7069da85bb11bdcf0da8d9dc93619eeafc972dd2))\n\n## [0.13.0](https://github.com/es6kr/skills/compare/fix-plan-v0.12.1...fix-plan-v0.13.0) (2026-09-13)\n\n\n### Features\n\n* commit-tag package-count guard + hook-kit relocations (promotes develop batch to main) ([a9a5282](https://github.com/es6kr/skills/commit/a9a5282489301412405a2f1024a396ba17da1e48))\n\n\n### Bug Fixes\n\n* **fix-plan:** align add_item.py's default section, add Windows-safe lock, fix priority.md example ([2f811f2](https://github.com/es6kr/skills/commit/2f811f2fc8250cceb57259c3880a0bd9f8c0655c))\n* **fix-plan:** default add_item backlog section to ## TODO ([#473](https://github.com/es6kr/skills/issues/473)) ([a032d78](https://github.com/es6kr/skills/commit/a032d789b4669e2a4d98c5712640dcfca6d1bf4c))\n* **fix-plan:** first-edit timebox, premise re-verification gate, workaround linkage notation ([#472](https://github.com/es6kr/skills/issues/472)) ([cdca046](https://github.com/es6kr/skills/commit/cdca04649a41b335ab668f6eabf7780ea391492d))\n* **fix-plan:** make Plan Drafts role ownership explicit in Per-profile table ([#475](https://github.com/es6kr/skills/issues/475)) ([6c6127f](https://github.com/es6kr/skills/commit/6c6127f6cb90ff7c42775359ded6d14379d86e66))\n\n## [0.12.1](https://github.com/es6kr/skills/compare/fix-plan-v0.12.0...fix-plan-v0.12.1) (2026-09-08)\n\n\n### Bug Fixes\n\n* **fix-plan:** add a mechanical --move mode to update_item.py ([#459](https://github.com/es6kr/skills/issues/459)) ([e198675](https://github.com/es6kr/skills/commit/e1986758f1edecf72e3db1075cde0110da337876))\n* **tdd:** scope the Red-only commit ban to shared branches ([fc2e6ec](https://github.com/es6kr/skills/commit/fc2e6ecdd1906c41d47955226e247aeb03a6f367))\n\n## [0.12.0](https://github.com/es6kr/skills/compare/fix-plan-v0.11.1...fix-plan-v0.12.0) (2026-09-06)\n\n\n### Features\n\n* **fix-plan:** add claim_item.py and wire it to plane_sync started-transition ([add4069](https://github.com/es6kr/skills/commit/add40691c3a68c1160a43259ca358b74e4bd7518))\n\n\n### Bug Fixes\n\n* **fix-plan:** validate lease inputs, serialize claim transactions, restore hooks.json fallback ([bc32fa8](https://github.com/es6kr/skills/commit/bc32fa8546df351aa8751b83a38bddad09465c83))\n\n## [0.11.1](https://github.com/es6kr/skills/compare/fix-plan-v0.11.0...fix-plan-v0.11.1) (2026-09-05)\n\n\n### Bug Fixes\n\n* **fix-plan:** add simple-vs-session self-check before Orca recommendation ask ([46e5d77](https://github.com/es6kr/skills/commit/46e5d77e3faefb0524fb4e4e6e80aa056d2d66ca))\n* **fix-plan:** hold the update lock across the write and reject invalid section markers ([b70f95d](https://github.com/es6kr/skills/commit/b70f95d3de46f0b78ff432c007c47ff798b3b54c))\n* **fix-plan:** move the update lock out of the tracker's directory ([da58b2d](https://github.com/es6kr/skills/commit/da58b2d9081c6e1bbfad12d55078749a329a43a8))\n* **fix-plan:** require RAG pre-lookup before authoring add/upsert items ([#419](https://github.com/es6kr/skills/issues/419)) ([1cff476](https://github.com/es6kr/skills/commit/1cff4767b37443fa57ff7841da3ee6a1bd9e81c0))\n* **fix-plan:** resolve remaining PR [#407](https://github.com/es6kr/skills/issues/407) review findings ([708475b](https://github.com/es6kr/skills/commit/708475bd3a882d3c27dd29f3e7b594f53f961e24))\n\n## [0.11.0](https://github.com/es6kr/skills/compare/fix-plan-v0.10.0...fix-plan-v0.11.0) (2026-09-01)\n\n\n### Features\n\n* staging branch next-feat sync into main ([e582ea2](https://github.com/es6kr/skills/commit/e582ea248beefa70886716741b8965d91cfb7414))\n\n\n### Bug Fixes\n\n* **fix-plan:** recommend Orca session-launch on pm-profile handoff ([dbbde8a](https://github.com/es6kr/skills/commit/dbbde8a74709b963c62adfc880884fdf02830c17))\n* **fix-plan:** warn against issue-comments-only AI Review Summary check ([#401](https://github.com/es6kr/skills/issues/401)) ([2ec416d](https://github.com/es6kr/skills/commit/2ec416d1e1a7c518747ea0f4fd3cb568694c9cb5))\n\n## [0.10.0](https://github.com/es6kr/skills/compare/fix-plan-v0.9.1...fix-plan-v0.10.0) (2026-08-29)\n\n\n### Features\n\n* **backlog:** migrate prune_p2p3.py to backlog and implement Option A+B (anchored regex & anomaly gate) ([7bc4fd1](https://github.com/es6kr/skills/commit/7bc4fd197fb5f9cc8bb2b662a8f72f02ed827b9b))\n* promote next-feat batch (backlog skill, hooks JS port, git-repo doctor, pre-push guard) ([0d76a4c](https://github.com/es6kr/skills/commit/0d76a4c01180fbdc78bfeec8dea91373b4912470))\n* **works-config:** implement v0.2.0 role-based resolution & neutral SSOT guards config ([e22e117](https://github.com/es6kr/skills/commit/e22e117371370c59b18b77c72bdb926dcb1897cb))\n\n\n### Bug Fixes\n\n* address CodeRabbit and Copilot review feedback on PR [#385](https://github.com/es6kr/skills/issues/385) ([e94de34](https://github.com/es6kr/skills/commit/e94de34ce5e075c79b7edc5d672813cea94a0acc))\n* address CodeRabbit and Copilot review feedback on PR [#389](https://github.com/es6kr/skills/issues/389) ([db4dfff](https://github.com/es6kr/skills/commit/db4dfff2829632bf263d93e0bbfdd1244772a5b2))\n* **fix-plan:** resolve full list-item block before toggling a sync marker ([#378](https://github.com/es6kr/skills/issues/378)) ([342d414](https://github.com/es6kr/skills/commit/342d4146b919c64ddf3d89c211e3e3e44bce2477))\n* **hook-kit:** add conditional-deferral gate to check-ask-bypass-keywords.sh ([1a32fe0](https://github.com/es6kr/skills/commit/1a32fe0c716ec4583a09a54004fb9fb86191ea1c))\n* **hook-kit:** add conditional-deferral gate to check-ask-bypass-keywords.sh ([49cae3f](https://github.com/es6kr/skills/commit/49cae3f96f08cc54c6dadf4eaf99369e0e9750ef))\n* **hook-kit:** document --json mode and scope WSCFG_* to hook scripts ([373634c](https://github.com/es6kr/skills/commit/373634c022b0e2b114a3bbb799bb9a8934c9fbb2))\n* **hook-kit:** scope PR-URL bare-ref check to per-number match, allow force-push in worktrees ([dd50dce](https://github.com/es6kr/skills/commit/dd50dced989eed4847daaf9a0cd4be12a04426e1))\n* promote next-fix batch (task plugin split, claudify matcher, pr recheck, omz chezmoi fix) ([3e90fd5](https://github.com/es6kr/skills/commit/3e90fd56ade0522d6773eb03f38760a317dd5180))\n* **review:** apply copilot review feedback on hooks and test suites ([cba86f4](https://github.com/es6kr/skills/commit/cba86f4ebbf274a0c979ab21aeea6d483f8cb8f3))\n\n\n### Refactor\n\n* **hooks:** port check-completed-bloat and wip-task-complete-detect to Node.js ([7097526](https://github.com/es6kr/skills/commit/7097526ca208c3106b38a3ac5c317d0eb49eff30))\n\n## [0.9.1](https://github.com/es6kr/skills/compare/fix-plan-v0.9.0...fix-plan-v0.9.1) (2026-08-26)\n\n\n### Bug Fixes\n\n* accumulate 16 patch-level bug fixes and guard enhancements across skills ([d214e5d](https://github.com/es6kr/skills/commit/d214e5dcc7fac1bc07baf3b6cec62999aea732f0))\n* **fix-plan:** accept ASCII arrow delimiter in plane_sync index lines ([c2fd069](https://github.com/es6kr/skills/commit/c2fd06927ab253b81566047f7bfa9ccded7a97d9))\n* **fix-plan:** decouple plane_create_issue to plane-backlog and update schema validation ([42273f4](https://github.com/es6kr/skills/commit/42273f46180b0f13bf7e094f6c5bb75adda6ad45))\n* **fix-plan:** judge item schema against the file, not the edit window ([e619e33](https://github.com/es6kr/skills/commit/e619e337064687ccb5d79a304a0737004d9d0cda))\n* **fix-plan:** parse nested hooks.json schema in hook_integrity_check ([b9bde23](https://github.com/es6kr/skills/commit/b9bde23cf4a60dee28b8ea43462c4d37200e33f4))\n* **fix-plan:** require recency-ask answer reuse in default-invocation Step 0 ([c7ad963](https://github.com/es6kr/skills/commit/c7ad963223e50e187442f7eeb271a75baafd4c96))\n* **fix-plan:** resolve plane_bulk_update config from workspace profile ([35a664b](https://github.com/es6kr/skills/commit/35a664b460834f4fb2185a48e3b040d72a6707d6))\n* **fix-plan:** stop cleanup from dropping non-list lines and the final newline ([36106d1](https://github.com/es6kr/skills/commit/36106d1be814529df933f1a480e3a6bc815dc783))\n* promote accumulated skill fixes from the working checkout ([770bed2](https://github.com/es6kr/skills/commit/770bed2386266fc13f7d605505c2996037d4c371))\n* promote next-fix batch (consolidate fabrication guard, session rewind, config-driven PR base) ([7ca0ccb](https://github.com/es6kr/skills/commit/7ca0ccbf13cefafedc33a16a7361756c95f8b8f6))\n* resolve PR [#363](https://github.com/es6kr/skills/issues/363) audit Pending findings (plane_bulk_update profile, hook checker schema, regex, dedup) ([19ffc83](https://github.com/es6kr/skills/commit/19ffc83f296ad5568b82a85b104fcf419580c102))\n* **review-feedback:** apply review feedback for session rewind, cleanup regex, rag test, and resume urls ([543d88f](https://github.com/es6kr/skills/commit/543d88f189c415c5f7a911aa861cde9b382016bd))\n\n## [0.9.0](https://github.com/es6kr/skills/compare/fix-plan-v0.8.0...fix-plan-v0.9.0) (2026-08-20)\n\n\n### Features\n\n* **fix-plan:** read the role-shaped v2 workspace config, falling back to v1 ([83ec4f0](https://github.com/es6kr/skills/commit/83ec4f016d1f99c00ffa2d612a0b49e7467d48a5))\n* promote next-feat batch (hook registry schema, self-reference path anchoring) ([0c33ffa](https://github.com/es6kr/skills/commit/0c33ffac99a9237f4530566470dabeaea128c209))\n* promote next-feat staging (lifecycle guards, triage automation, and workflow safety procedures) ([77d58ac](https://github.com/es6kr/skills/commit/77d58ac3a771a4897043c9eea8b149ea1e8ba2ff))\n\n\n### Bug Fixes\n\n* **cleanup,fix-plan:** anchor script paths to the skill directory ([8a2f9be](https://github.com/es6kr/skills/commit/8a2f9be6f5bba1f9a9ec35ca2616fabf7addf847))\n* **fix-plan,cleanup:** replace absolute self-reference script paths with relative form ([91e99e2](https://github.com/es6kr/skills/commit/91e99e2f4f2657b7646a886d4d98ec5e2dbb09c0))\n* **fix-plan,cleanup:** replace absolute self-reference script paths with relative form ([8b6a1e6](https://github.com/es6kr/skills/commit/8b6a1e627584866cef43f1866548f3ef32d2a849))\n* **fix-plan:** add add_item.py and track the checklist-edit guard ([#339](https://github.com/es6kr/skills/issues/339)) ([b9bbc08](https://github.com/es6kr/skills/commit/b9bbc0829f23ecf8b63d0d4e0f65888dcac5344e))\n* **fix-plan:** match multi-segment cwd_match tokens in workspace_profile ([90f942a](https://github.com/es6kr/skills/commit/90f942a25a668b778bedde9d28996c102e91966f))\n* **fix-plan:** reconcile plane_create_issue with the repaired plane-backlog copy and inject User-Agent into plane_sync ([69cce36](https://github.com/es6kr/skills/commit/69cce36f645c3106e4bea2c8305330978785f37f))\n* **fix-plan:** require artifact verification for subagent-delegated pipeline runs ([7a4e1c0](https://github.com/es6kr/skills/commit/7a4e1c0cb6b8065e4dd3ed3079923967e1d545dc))\n* **hook-kit,fix-plan,consolidate:** resolve review findings on registry fail-fast, add-item safety, and mechanical verification ([72fb280](https://github.com/es6kr/skills/commit/72fb28054ccd858aa56617e8a6a5d1fb5b9d2384))\n* **hook-kit:** detect v2 config by version, not per-profile roles; probe interpreter in RAG guard ([13042e6](https://github.com/es6kr/skills/commit/13042e6f95ee3e566dd4e029d029bfdcfdb34de6))\n* promote next-fix batch (hook path repair, topic-dispatch scoping, conflict diagnosis) ([eb7ecb6](https://github.com/es6kr/skills/commit/eb7ecb61dda9701d78f12dc810781dc7cb687caa))\n* repair plane script defects — WAF-safe User-Agent + K3s fallback template ([d8c2871](https://github.com/es6kr/skills/commit/d8c287132867b88225e01f5031e658df1e05d027))\n\n## [0.8.0](https://github.com/es6kr/skills/compare/fix-plan-v0.7.0...fix-plan-v0.8.0) (2026-08-17)\n\n\n### Features\n\n* **plane-backlog:** add Plane backlog skill with client and indexify scripts ([3bcc8cd](https://github.com/es6kr/skills/commit/3bcc8cd8f570bb53697f290e9e6e53069991822b))\n\n\n### Bug Fixes\n\n* **fix-plan:** add relocated es6kr skill path to post-ingest fallback chain ([56a8e74](https://github.com/es6kr/skills/commit/56a8e7454f64d70404f393f0ec34ba38a2f7d4ad))\n* **fix-plan:** compress SKILL.md description under the 1024-char lint budget ([28edaf2](https://github.com/es6kr/skills/commit/28edaf211196f174adb5f6313356447301dea70b))\n* **fix-plan:** keep open plan checklist items as tracker sub-checkboxes on add ([963a4d5](https://github.com/es6kr/skills/commit/963a4d59c01ceb8303156e5b27bcff8ab072394b))\n* **fix-plan:** require artifact verification for subagent-delegated pipeline runs ([#333](https://github.com/es6kr/skills/issues/333)) ([44dbf54](https://github.com/es6kr/skills/commit/44dbf5459390efc12b91a1334a1b23542b38aa10))\n* **fix-plan:** restore artifact-verification HARD STOP dropped by main merge ([084c669](https://github.com/es6kr/skills/commit/084c66908bceea07f067b9308c15ae88ed206766))\n* promote next-fix staging (30 fixes across 14 skills) ([ee467c0](https://github.com/es6kr/skills/commit/ee467c045d779d7b80d30f160763ec3534a9742b))\n* **wip:** cross-ref PR-URL and TaskCreate subject repo-qualifier rules ([#186](https://github.com/es6kr/skills/issues/186)) ([4982364](https://github.com/es6kr/skills/commit/49823641a7b08123ebd0325273892bee41bc3280))\n\n## [0.7.0](https://github.com/es6kr/skills/compare/fix-plan-v0.6.2...fix-plan-v0.7.0) (2026-08-16)\n\n\n### Features\n\n* **fix-plan:** add claim topic — multi-session in-progress lease ([#300](https://github.com/es6kr/skills/issues/300)) ([7bd1439](https://github.com/es6kr/skills/commit/7bd14396cef45738207d400053c8e8aade8d3c94))\n* merge next-feat into main ([#313](https://github.com/es6kr/skills/issues/313)) ([2d9308a](https://github.com/es6kr/skills/commit/2d9308ab3e7e0086a88a7f64d3ed4d5c4d36e017))\n\n## [0.6.2](https://github.com/es6kr/skills/compare/fix-plan-v0.6.1...fix-plan-v0.6.2) (2026-08-12)\n\n\n### Bug Fixes\n\n* **fix-plan:** reclassify model-triage BLOCKED marker as external, not selfable ([#291](https://github.com/es6kr/skills/issues/291)) ([60e687c](https://github.com/es6kr/skills/commit/60e687c36a9e9b16493d8c48711bf14cf01d3441))\n* **fix-plan:** route cleanup.py and plane_sync.py through resolve_tracker_root ([#285](https://github.com/es6kr/skills/issues/285)) ([a42af9d](https://github.com/es6kr/skills/commit/a42af9d02cf2f56d9ae082ae7594976484bd7baa))\n* promote accumulated next-fix fixes to main ([803bbd3](https://github.com/es6kr/skills/commit/803bbd3b9e4f8367ee1b955cfa2b6a536f85cee0))\n\n## [0.6.1](https://github.com/es6kr/skills/compare/fix-plan-v0.6.0...fix-plan-v0.6.1) (2026-08-11)\n\n\n### Bug Fixes\n\n* **fix-plan:** resolve Plane issue state via separate states endpoint ([a027c74](https://github.com/es6kr/skills/commit/a027c744bf142fd1b6aec5275d372ba705e6c37d))\n\n## [0.6.0](https://github.com/es6kr/skills/compare/fix-plan-v0.5.1...fix-plan-v0.6.0) (2026-08-09)\n\n\n### Features\n\n* **fix-plan:** implement plane_sync.py as a real Plane sync engine ([a901895](https://github.com/es6kr/skills/commit/a90189595e3d3487509c4fd0b4889630e438bc39))\n* **fix-plan:** implement plane_sync.py as a real Plane sync engine ([4607f13](https://github.com/es6kr/skills/commit/4607f13c15e3572e904dd56b56b4ce36ed462d26))\n\n\n### Bug Fixes\n\n* **consolidate:** address CodeRabbit/Copilot review findings on PR [#270](https://github.com/es6kr/skills/issues/270) ([3b11a73](https://github.com/es6kr/skills/commit/3b11a730b5ad68803d35a8264eda540e48265d75))\n* **fix-plan:** externalize detect_bloated_tasks.py locale patterns to git-ignored data/ ([#258](https://github.com/es6kr/skills/issues/258)) ([0616217](https://github.com/es6kr/skills/commit/0616217a779aac7471e841626e22ba058d16d28f))\n* **fix-plan:** guard plane_sync.py write against concurrent tracker edits ([0d34339](https://github.com/es6kr/skills/commit/0d343399d6a7c9f97114c5e85254e65ed93e9d67))\n* **fix-plan:** workspace-aware tracker root + broaden stale_check detection ([#255](https://github.com/es6kr/skills/issues/255)) ([b6d041a](https://github.com/es6kr/skills/commit/b6d041a2babb5ed8d9c29979eef96fa4a4fa92ab))\n* promote accumulated next-fix fixes to main ([95656e9](https://github.com/es6kr/skills/commit/95656e9b551ee0bb77904a0a571d49c53bc01cc9))\n\n## [0.5.1](https://github.com/es6kr/skills/compare/fix-plan-v0.5.0...fix-plan-v0.5.1) (2026-08-05)\n\n\n### Bug Fixes\n\n* promote next-fix staging (38 fixes across 16 skills) ([94f8c33](https://github.com/es6kr/skills/commit/94f8c33800ce411ae63e22c5259cdae8435508a4))\n\n## [0.5.0](https://github.com/es6kr/skills/compare/fix-plan-v0.4.0...fix-plan-v0.5.0) (2026-08-03)\n\n\n### Features\n\n* promote next-feat to main ([4fbe313](https://github.com/es6kr/skills/commit/4fbe31332c58bf24327d819cc9204ebda2d4afa8))\n\n## [0.4.0](https://github.com/es6kr/skills/compare/fix-plan-v0.3.3...fix-plan-v0.4.0) (2026-07-28)\n\n\n### Features\n\n* bundle next-feat — fix-plan expansion, next reactive guard, github-repo extraction ([#195](https://github.com/es6kr/skills/issues/195)) ([cd65a85](https://github.com/es6kr/skills/commit/cd65a8519c88f080321d746ef197e90713039fa6))\n* **fix-plan:** add flowchart layout-ordering with invisible priority columns ([#158](https://github.com/es6kr/skills/issues/158)) ([a216c97](https://github.com/es6kr/skills/commit/a216c97d727e15f88507e866d1c81dc95857a121))\n* **fix-plan:** add model-triage and completion-criteria topics ([38ccd87](https://github.com/es6kr/skills/commit/38ccd87da8a4c09c752f8b9023a0236da77ebb77))\n* **fix-plan:** add model-triage, completion-criteria, and Plane sync ([f47246a](https://github.com/es6kr/skills/commit/f47246ad158add45448e93734abf3d7414971561))\n* **fix-plan:** add Plane REST API sync and multi-workspace profile engine ([3a74bd7](https://github.com/es6kr/skills/commit/3a74bd76f64903eb8582fba17be28c4e128207cf))\n* **fix-plan:** harden Completed lifecycle and forbid section-header fragmentation ([5fffdfc](https://github.com/es6kr/skills/commit/5fffdfc252830068685385d297761052618d1cfe))\n* **fix-plan:** scope default invocation by role-profile (--role=pm|deep|impl) ([d290c7a](https://github.com/es6kr/skills/commit/d290c7ad4145860ced78f35e7483a21595688695))\n\n\n### Bug Fixes\n\n* **fix-plan:** add secondary-tracker sync cadence contract ([5f0cea9](https://github.com/es6kr/skills/commit/5f0cea9749fe735c0d3fb061afe08212162cd93f))\n* **fix-plan:** add secondary-tracker sync cadence contract ([f7b1ee5](https://github.com/es6kr/skills/commit/f7b1ee5c9c151e9cebe46bef0dbc4e024b7f9ed8))\n* **fix-plan:** add whole-file grep sub-step to flowchart Sync procedure ([7fb859f](https://github.com/es6kr/skills/commit/7fb859facdb057e29e63f60a7e0cc3457c2d8686))\n* **fix-plan:** block stale-Completed edits with exit 2, add python fallback ([7dfc178](https://github.com/es6kr/skills/commit/7dfc178d85212ffe585f42482bc49565a6e9c38d))\n* **fix-plan:** correct plane_sync.py's docstring to match its actual scope ([b26a76e](https://github.com/es6kr/skills/commit/b26a76eb9ae2b9f9c3bcb5c68bd119fb2b9ca84e))\n* **fix-plan:** document secondary-sync-receiver in Configuration table ([c975300](https://github.com/es6kr/skills/commit/c9753004f53fa89e3383c076b714b69d696dbf14))\n* **fix-plan:** document secondary-sync-receiver in Configuration table ([39492c0](https://github.com/es6kr/skills/commit/39492c03d4e0be0946acc1bdd0307d23eab820fb))\n* **fix-plan:** document secondary-sync-receiver in Configuration table ([#165](https://github.com/es6kr/skills/issues/165)) ([c975300](https://github.com/es6kr/skills/commit/c9753004f53fa89e3383c076b714b69d696dbf14))\n* **fix-plan:** forbid hybrid pending/blocked marker in tracker schema ([f1bfcd8](https://github.com/es6kr/skills/commit/f1bfcd83137f6e80156896ebbcd32e2548c75a59))\n* **fix-plan:** forbid hybrid pending/blocked marker in tracker schema ([9262ce0](https://github.com/es6kr/skills/commit/9262ce0665fdb9f72b82f6272a40a48ed5abdfae))\n* **fix-plan:** implement register_tasks_to_fix_plan write-back ([cb6d351](https://github.com/es6kr/skills/commit/cb6d351c35209665602258fb4b5a1c6ec57d65d3))\n* **fix-plan:** kill schema-hook insert-before false positive + add draft promote premise re-check ([#143](https://github.com/es6kr/skills/issues/143)) ([e826d59](https://github.com/es6kr/skills/commit/e826d5923c491ac6b8a5f915694e751fedf65756))\n* **fix-plan:** preserve subtree children when moving completed entries ([080a61d](https://github.com/es6kr/skills/commit/080a61dbe244a2fbd8d3fa8dbf85938a146a037c))\n* **fix-plan:** reconcile default-pipeline order across SKILL.md/format.md ([7a3aea5](https://github.com/es6kr/skills/commit/7a3aea5d282a3933e18be341ee2508b6085eab55))\n* **fix-plan:** register tasks before default-invocation pipeline runs ([#168](https://github.com/es6kr/skills/issues/168)) ([e796862](https://github.com/es6kr/skills/commit/e796862a558f72c4c9094a7b50f8ae93c6c492bd))\n* **fix-plan:** require full session UUID in Completed references ([90f8c3f](https://github.com/es6kr/skills/commit/90f8c3f7daf8d713d3d91c927fdbda11805b36b2))\n* **next-fix:** promote staged fixes across hook-kit, next, cleanup, fix-plan ([34f1c67](https://github.com/es6kr/skills/commit/34f1c67beee3a8279e0e80de4ab3a87ba2223d5c))\n* resolve PR [#197](https://github.com/es6kr/skills/issues/197) review findings (CodeRabbit + Copilot + Internal Review) ([b54236a](https://github.com/es6kr/skills/commit/b54236a4fa4b3fef23645dfc3b184916980b7f65))\n\n## [0.3.3](https://github.com/es6kr/skills/compare/fix-plan-v0.3.2...fix-plan-v0.3.3) (2026-07-23)\n\n\n### Bug Fixes\n\n* **fix-plan:** record model name alongside session ID in move.md ([#126](https://github.com/es6kr/skills/issues/126)) ([78b5471](https://github.com/es6kr/skills/commit/78b5471f26b51dd7dc523d7fc1b4e96d7cd77d9c))\n* **next-fix:** accumulate bug fixes for docxport, wip, fix-plan, and hook-kit ([6eec083](https://github.com/es6kr/skills/commit/6eec083b7fbc429bdabcfcc89d7778b185dd7497))\n\n## [0.3.2](https://github.com/es6kr/skills/compare/fix-plan-v0.3.1...fix-plan-v0.3.2) (2026-07-16)\n\n\n### Bug Fixes\n\n* **consolidate,fix-plan:** promote next-fix staging (review hardening + periodic archive) ([24726e9](https://github.com/es6kr/skills/commit/24726e99a5b2972f706d8749ea3a45cbc358984b))\n* **fix-plan:** add receiver-independent periodic archive for Completed section ([#73](https://github.com/es6kr/skills/issues/73)) ([122b179](https://github.com/es6kr/skills/commit/122b179d381f33f8345848f2a364c01ce8cb0ab1))\n* **fix-plan:** batch GitHub API queries and allow automated cleanup ([8f35c45](https://github.com/es6kr/skills/commit/8f35c4588d465acffa58f19f61795c364936688f))\n* **fix-plan:** guard subtree-archival against burying open children ([#91](https://github.com/es6kr/skills/issues/91)) ([3389987](https://github.com/es6kr/skills/commit/33899876e1c6f12ee059d19f2f811c27672d3d0c))\n\n## [0.3.1](https://github.com/es6kr/skills/compare/fix-plan-v0.3.0...fix-plan-v0.3.1) (2026-06-25)\n\n\n### Bug Fixes\n\n* **fix-plan:** require sync as Step 0 of priority triage ([0ce37e9](https://github.com/es6kr/skills/commit/0ce37e9af80e0d453d8441ad730ea2d6d88b226e))\n* **fix:** split Step 2 medium by content type — case history to failed-attempts.md ([#62](https://github.com/es6kr/skills/issues/62)) ([747b3f9](https://github.com/es6kr/skills/commit/747b3f957ca0fefdbc5044eb08f66b8aafc1e26a))\n\n## [0.3.0](https://github.com/es6kr/skills/compare/fix-plan-v0.2.0...fix-plan-v0.3.0) (2026-06-19)\n\n\n### Features\n\n* **fix-plan:** add priority + draft topics + refine move procedure ([c1b3cb5](https://github.com/es6kr/skills/commit/c1b3cb57b3e340bc06fb1639b0542ea9664b8bec))\n* skill-kit graph topic + harness Phase 1 + auxiliary improvements ([01437f2](https://github.com/es6kr/skills/commit/01437f2135d5729eee16f074cb77e52b3cb1772c))\n\n## [0.2.0](https://github.com/es6kr/skills/compare/fix-plan-v0.1.0...fix-plan-v0.2.0) (2026-06-11)\n\n\n### Features\n\n* **fix-plan:** introduce standalone schema/lifecycle skill ([#47](https://github.com/es6kr/skills/issues/47)) ([4c356f8](https://github.com/es6kr/skills/commit/4c356f8daf16bcd78c9cad871e46c686145e845b))\n\nFile v0.17.1:claim.md\n\n# Claim — Multi-session In-progress Lease\n\nPrevents two contexts — two interactive sessions, or an interactive session plus an autonomous Ralph loop / background dispatch — from independently working the same tracker item. A **claim** is a lightweight, self-expiring lease stamped onto an item the moment a session starts working it, so any concurrent reader sees the item is already in flight.\n\n## Why\n\n`fix_plan.md` / `checklist.md` are frequently edited by more than one context at once. The `[ ]` / `[x]` / `[BLOCKED]` markers describe an item's *state*, not *who is currently acting on it*. Without a claim, two sessions can both read a `[ ]` item, both decide it is available, and both do the same work — the exact duplicate-progress hazard this topic prevents.\n\nA claim is **not** a new checkbox state. It is a concurrency annotation (a lease) that rides alongside the existing marker, orthogonal to pending / blocked / done.\n\n## Marker syntax\n\nAppend a `[CLAIMED::]` suffix tag **after** the standard checkbox marker, before the item text:\n\n```markdown\n- [ ] [CLAIMED:84f9e320:2026-08-13T11:20] Recover Plane index 84 lines\n- [BLOCKED:P1:selfable] [CLAIMED:5bfda407:2026-08-13T09:05] consolidate Step 2.4 PR create\n```\n\n| Piece | Value | Notes |\n|-------|-------|-------|\n| `[CLAIMED]` | literal | The lease tag |\n| `` | first 8 chars of the session id | Same source as `format.md`'s completion convention (`.ralph/.claude_session_id` in Ralph, else the current session id) |\n| `` | ISO `YYYY-MM-DDTHH:mm` (24h) | The moment the claim was stamped or last refreshed — doubles as the lease clock for staleness |\n\n**Not a hybrid marker.** `format.md` forbids `- [ ] [BLOCKED...]` because `[ ]` and `[BLOCKED]` are two mutually-exclusive *state* markers. `[CLAIMED:...]` is a *lease annotation*, not a state — so `- [ ] [CLAIMED:...]` and `- [BLOCKED:P*:selfable] [CLAIMED:...]` are both valid. The checkbox marker (`[ ]` / `[BLOCKED:...]`) is unchanged; the claim tag sits after it exactly like `[TRACKED]` / `[REVIEW_FEEDBACK]`.\n\nClaim only `[ ]` and `[BLOCKED:P*:selfable]` items (both are workable-now). Never stamp a claim on `[x]` (already done) or `[BLOCKED:*:external]` (not progressable — nothing to claim).\n\n## Lifecycle\n\n### 1. Claim (before starting work) — HARD STOP: re-read first\n\nBecause the tracker is often under concurrent edit, **re-read the file from disk immediately before claiming** — an in-context snapshot may be stale.\n\n1. Re-read the tracker; grep the target item for an existing `[CLAIMED` tag\n2. If unclaimed (or the existing claim is stale — see \"Stale claim & takeover\") → add `[CLAIMED::]` after the checkbox marker\n3. Save (and commit, in a git-tracked tracker) the claim edit **before** beginning the actual work, so concurrent readers see it promptly\n\n### 2. Refresh (long-running work, optional)\n\nFor work spanning longer than the stale TTL, re-stamp `` to the current time periodically so a live claim is not mistaken for an abandoned one.\n\n### 3. Release\n\n- **On completion**: the `[ ]` → `[x]` transition and the move to `## Completed` (per [move.md](./move.md)) drop the `[CLAIMED]` tag — completion supersedes the claim. Do not carry a claim tag into the Completed summary line (the Completed entry records the session id via its own convention).\n- **On abandonment**: if a session stops without completing, remove the `[CLAIMED]` tag during wind-down, or leave it to expire via the stale TTL.\n\n## Stale claim & takeover\n\nA claim is **stale** when either:\n\n- its `` is older than the **stale TTL — default 4h** (override via `--claim-ttl=`), **or**\n- the claiming session is known to have ended (its session id is no longer active)\n\nBefore working an item that already carries a `[CLAIMED]` tag:\n\n| Existing claim | Action |\n|----------------|--------|\n| Fresh (within TTL, different live session) | **Do not work it.** It is in flight elsewhere. Pick a different candidate; if it is the only priority, report the conflict to the user rather than racing |\n| Fresh (your own session id) | Continue — it is your claim. Refresh the timestamp if long-running |\n| Stale (TTL elapsed or claiming session ended) | **Take over**: replace the old tag with `[CLAIMED::]` in the same edit, then proceed |\n\n## Interaction with triage & the default pipeline\n\n- **Candidate surfacing** ([priority.md](./priority.md) triage, `impl` / `pm` `selfable`-candidate handoff): exclude items carrying a **fresh** `[CLAIMED]` tag — they are in flight, not available. Stale-claimed items stay eligible (with takeover).\n- **Completion / move**: [move.md](./move.md)'s `[x]` → Completed migration drops the tag automatically.\n- **Autonomous loops**: a Ralph wrapper (caller-side) should treat a fresh-claimed `[ ]` as skip, the same way it skips `[BLOCKED]`. This skill only defines the tag; loop enforcement lives in the wrapper, consistent with how the wrapper owns `[BLOCKED]` loop semantics.\n\n## Don't / Do\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Start working a `[ ]` item without checking for an existing `[CLAIMED]` tag | Re-read the tracker + grep `\\[CLAIMED` on the item first; claim before starting |\n| 2 | Claim from an in-context snapshot without re-reading disk | The tracker is often under concurrent edit — re-read immediately before the claim edit |\n| 3 | Work a fresh claim owned by another live session | Fresh + different session = in flight. Choose another item or report the conflict |\n| 4 | Introduce a new checkbox marker like `[/]` / `[WIP]` for in-progress | Forbidden by the marker contract. Use the `[CLAIMED:...]` suffix tag on the existing `[ ]` / `[BLOCKED:*:selfable]` marker |\n| 5 | Carry a `[CLAIMED]` tag into the `## Completed` summary line | Completion drops the tag — the Completed entry records the session id via its own convention |\n| 6 | Leave a stale claim blocking a genuinely available item forever | Stale (TTL elapsed / session ended) = takeover: re-stamp with your own session + now |\n\n## Self-check (before claiming an item)\n\n1. Did I re-read the tracker from disk this turn (not an in-context snapshot)?\n2. Does the target item already carry a `[CLAIMED]` tag? — grep `\\[CLAIMED` on the line\n3. If claimed: is it mine, fresh-other, or stale? — mine → continue; fresh-other → do not work it; stale → takeover\n4. Is the item `[ ]` or `[BLOCKED:*:selfable]`? — never claim `[x]` or `:external`\n5. Did I save / commit the claim edit before starting the actual work?\n\n## Assignment vs Lease (`[ASSIGNED:]` vs `[CLAIMED::]`)\n\nA claim (`[CLAIMED]`) is a **dynamic runtime lease** stamped by an active session that is physically executing the task right now. In contrast, an assignment (`[ASSIGNED]`) designates the **intended executor or owner** (an AI agent or a team member) before execution begins:\n\n| Tag | Purpose | Format | Example |\n|---|---|---|---|\n| `[CLAIMED::]` | Active runtime execution lock | Session ID + timestamp | `[CLAIMED:c3163b80:2026-09-19T23:15]` |\n| `[ASSIGNED:agent:]` | Delegated AI agent | `agent:` | `[ASSIGNED:agent:fable]`, `[ASSIGNED:agent:task-exec]` |\n| `[ASSIGNED:user:]` | Assigned team member | `user:` | `[ASSIGNED:user:alice]`, `[ASSIGNED:user:bob]` |\n\n### Workspace-Aware Assignment Rules\n- **Solo / Agentic Workspaces**: Assign to specialized AI agents (`agent:research`, `agent:push`, `agent:task-exec`, `agent:ralph`, etc.). The PM delegates rather than executing everything in a single thread.\n- **Collaborative / Team Workspaces**: Assign to team members (`user:`) and sync to the issue tracker `assignees` field. The PM balances team workload and facilitates human-agent collaboration.\n\n## See also\n\n- [format.md](./format.md) — marker syntax; `[CLAIMED]` is a suffix annotation, not a checkbox state\n- [move.md](./move.md) — `[x]` → Completed migration drops the claim tag\n- [priority.md](./priority.md) — triage excludes fresh-claimed items from candidate surfacing\n\nFile v0.17.1:completion-criteria.md\n\n# Completion Criteria\n\nDefines **what \"done\" means per item output type**, and how markers transition when the deliverable is finished. Without an explicit definition of done (DoD), completion judgment falls to ad-hoc discretion — and discretion that leans conservative produces items that stay blocked forever despite their deliverable already existing.\n\n## When to Use\n\n- Before flipping any tracker item to `[x]`, or deciding to leave it `[BLOCKED]`\n- When an item's deliverable looks finished but some scope named in its body is still untouched\n- Periodic audit: \"is anything blocked that actually has nothing left to block on?\"\n\n## Core Rule: `Why` is scope narrative, `How to apply` is the deliverable\n\nAn item's body has two fields that are routinely conflated. Only one of them defines done.\n\n| Field | Role | Defines DoD? |\n|-------|------|--------------|\n| **Why** | Narrative of the problem area and its motivation. Names systems, axes, and concerns the item *relates to* | **No** — it is context, not an acceptance checklist |\n| **How to apply** | The concrete artifact or action the item must produce | **Yes** — this is the acceptance criterion |\n\nPromoting every subject named in `Why` into a completion condition is the primary failure mode. A planning item whose `Why` mentions five subsystems does not require all five to be implemented — it requires the artifact named in `How to apply` to exist.\n\n## DoD by output type\n\n| Output type | Signal in `How to apply` | Done when | NOT required for done |\n|-------------|--------------------------|-----------|----------------------|\n| **Analysis / plan** | \"author a plan\", \"review\", \"assess\", \"produce a design\", \"supplement the plan\" | The document exists and covers the axis it claims to cover | Implementation, runtime verification, resolution of the analyzed problem |\n| **Implementation** | \"implement\", \"apply\", \"migrate\", \"wire up\", \"fix\" | Code/config changed **and** verified by the item's own stated verification means | Downstream adoption, follow-up refactors |\n| **Registration / record** | \"register\", \"record\", \"file an issue\", \"document\" | The record exists at the named destination | Any action the record describes |\n| **Decision** | \"decide\", \"choose\", \"settle\" | The decision is made and written to a durable medium | Executing the decision |\n| **External-gated** | \"await\", \"track\", \"monitor\" | The external party responded | Anything the responder controls |\n\n**The discriminator is the verb in `How to apply`, not the size of the subject matter.** A plan covering a large system is still a plan.\n\n## Marker transition\n\n> **Model-triage audit-stage exception**: items in a dedicated model-triage section (see [model-triage.md](./model-triage.md)) whose **audit stage** completes (`audit_status: approved_by_*`) do NOT follow the generic \"deliverable complete → `[x]` + residual split\" rows below. Audit approval is a stage transition — the item stays unchecked and relocates to the tracker's implementation-queue section (e.g. `## TODO`) per model-triage's move obligation; `[x]` comes only when the implementation itself completes.\n\n| Situation | Marker | Action |\n|-----------|--------|--------|\n| Deliverable per `How to apply` complete, no residual scope | `[x]` | Append dated result annotation, then move per the `move` topic |\n| Deliverable complete, but a scope named in `Why` remains unaddressed | `[x]` on the parent | **Split the residual into a new item** with its own `Why` / `How to apply`. Do not hold the parent open |\n| Deliverable partially written (artifact exists but incomplete on its own stated axis) | keep `[ ]` / `[BLOCKED:P*:selfable]` | Annotate what is missing; the artifact itself is the remaining work |\n| Blocked on a third party | `[BLOCKED:P*:external]` | Record the trigger that unblocks it |\n| Blocked on a decision only the user can make | `[BLOCKED:P*:selfable]` | Surface the decision via an ask — do not leave it as prose |\n\n### `:selfable` never means \"wait\"\n\n`:selfable` marks an item as **progressable now**. If an item carries `:selfable` and nothing external is pending, the correct action is to advance it, not to leave it parked. When a `:selfable` item cannot advance, the reason belongs in the annotation — and if that reason is a third party, the suffix should have been `:external`.\n\n## Residual scope: split, don't hold\n\nWhen the deliverable is done but part of the `Why` narrative remains untouched, holding the parent open buries the finished work and makes the tracker misreport progress. Split instead:\n\n1. Flip the parent to `[x]` with an annotation stating exactly which axes the deliverable covered\n2. Create a new item for the residual axis, with its own `How to apply` naming a concrete deliverable\n3. Cross-reference the two so the lineage is traceable\n\n## Don't / Do\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Treat every subject named in `Why` as an acceptance condition | Read DoD from `How to apply` only. `Why` is context |\n| 2 | Hold a planning item open until the analyzed problem is actually fixed | A plan is done when the plan exists. Implementation is a separate item |\n| 3 | Keep a parent `[BLOCKED]` because one sub-axis is untouched | Close the parent, split the residual into its own item |\n| 4 | Leave `:selfable` items parked with no pending external input | `:selfable` = advance it now, or restate the blocker (and re-suffix to `:external` if it is one) |\n| 5 | Import verification/adoption standards from implementation items into analysis items | Match the DoD to the output type in the table above |\n| 6 | Decide completion silently and move on | Every transition gets a dated annotation naming the axes covered and the axes deferred |\n\n## Self-check (before leaving any item `[BLOCKED]` or flipping it to `[x]`)\n\n1. What does this item's **`How to apply`** name as the deliverable? Quote it.\n2. Which output type does that verb map to in the DoD table?\n3. Does the deliverable exist and cover its own stated axis? → If yes, the item is done regardless of untouched `Why` subjects.\n4. Is there residual scope? → Split it into a new item; do not hold the parent.\n5. If leaving it blocked: is the blocker a third party (`:external`) or a user decision (`:selfable` + an ask this turn)? If neither, it is not blocked — advance it.\n6. Did I write a dated annotation stating which axes were covered and which were deferred?\n\n## Visibility of the judgment\n\nA completion judgment the user cannot see has not been communicated. When the tracking medium does not render a checklist in the interface — for example when a CLI fallback is used because the native task tool is unavailable — the item states and transitions must additionally be surfaced as readable text in the response. Tool output alone is not user-facing presentation.\n\n## See Also\n\n- [format.md](./format.md) — marker schema and section structure\n- [priority.md](./priority.md) — `P0`-`P3` ranking and `external` / `selfable` classification\n- [move.md](./move.md) — `[x]` → Completed summary lifecycle\n- [model-triage.md](./model-triage.md) — dedicated target-model section operation\n\nFile v0.17.1:draft.md\n\n# Draft\n\nRecords a **lightweight plan stub** when a piece of work needs planning but full planning is being **deferred**. Captures just enough to resume later, without doing the research → plan work now.\n\nInvoked as `/fix-plan draft ...` (short keyword). The descriptive concept is \"deferred plan draft\", but the call stays short.\n\n## When to Use\n\n- A task surfaces that clearly needs a real plan (research + design), but you are deferring it — not now.\n- You want the deferred intent **tracked** so it does not vanish from chat / the next session.\n- Use for \"defer this plan\", \"draft stub\", \"record plan draft\", \"plan-draft\", \"park this for later\".\n\n**Not for**: items ready to act on now (use `add`), or items blocked on an external dependency (use `priority` `[BLOCKED]`). Draft = \"needs planning, deliberately postponed\", not \"blocked\".\n\n## Section + entry schema\n\nPlan-draft stubs live in a dedicated `## Plan Drafts` section of the tracker (`fix_plan.md` / `checklist.md`), parallel to `## Issue Drafts`.\n\n```markdown\n## Plan Drafts\n\n- [BLOCKED:P2:selfable] {Purpose — one line: what the eventual plan is for}\n - **Defer reason**: {why it is postponed (priority, missing input, scope unclear, …)}\n - **Resume trigger**: {when / what condition should promote this to a real plan}\n - **Expected deliverable**: research | plan | checklist\n```\n\n### Why `[BLOCKED]` (not `[ ]`)\n\nPlan-draft entries are **always** `[BLOCKED]`. A draft represents work the user has deliberately deferred — promote requires a user decision, which an autonomous agent cannot make on its own. Marking the entry `[ ]` would let autonomous loops (e.g. Ralph) pick it up and try to act on it, contradicting the \"deferred until trigger fires\" semantics.\n\nThe reason is **always** `:selfable` because the body file (or inline stub) is prepared — the wait-state is on a user signal to promote, not on an external third party. Priority (`P0`-`P3`) ranks promote urgency relative to other drafts. See [priority.md](./priority.md) for the priority scale and triage workflow.\n\nDefault when uncertain: `[BLOCKED:P2:selfable]` (next-session promote candidate).\n\n### Minimal fields (all required, keep terse)\n\n| Field | Purpose | Example |\n|-------|---------|---------|\n| Purpose (title) | One line — what the future plan accomplishes | `Abstract the qdrant integration backend` |\n| Defer reason | Why not planning now | `Other work first / missing input / scope undecided` |\n| Resume trigger | What promotes it to a real plan | `After current PR merges / on user request / once X is decided` |\n| Expected deliverable | Which output the promote will produce | `research` / `plan` / `checklist` |\n\nPriority + `:selfable` reason go in the marker suffix (`[BLOCKED:P*:selfable]`), not as separate fields.\n\nA stub is intentionally **small** — purpose + 3 fields. If the draft already needs more than a few lines, it is no longer a stub; promote it.\n\n### Three storage modes (pick before writing)\n\nDrafts have three storage modes, not a binary stub-or-promote choice. Pick the\nmode by inspecting **what context already exists at draft time**, not by guessing\nfuture expansion.\n\n| Mode | When to pick | Where the body lives |\n|------|-------------|---------------------|\n| **Inline only** (default) | No substantive research/measurement has been gathered yet. Stub captures pure intent + 3 fields | `## Plan Drafts` entry |\n| **Inline + body file** | Substantive research/measurement **already exists in this session's chat** (findings, numbers, classified results, methodology fixes) that would otherwise be lost when chat is compressed | Entry cites `plan-drafts/.md`; body file holds the findings |\n| **Promote** | Body would exceed a few paragraphs **and** the user has not deferred — go straight to `code-workflow` research → plan | (no draft entry — real plan artifact instead) |\n\nThe middle mode (inline + body file) mirrors `issue-drafts/`. Default is inline\nonly, but **escalate to body file whenever this session has already produced\nresearch that the inline 3 fields cannot hold**. Chat content is ephemeral; the\ndraft body file is the persistence medium.\n\n## Lifecycle\n\nA plan-draft follows three stages.\n\n| Stage | Action | Owner (role) |\n|-------|--------|---------------|\n| 1. Write | Add a `- [BLOCKED:P*:selfable]` entry to `## Plan Drafts` (optionally a `plan-drafts/.md` body file) | This topic, when the user defers |\n| 2. Promote | When the resume trigger fires, re-verify the stub's premises against first sources, then hand the stub to the planning workflow (research → plan) and convert the entry into active work | `impl` (default) → `code-workflow`. Architecture-scale output (model-triage Category I/III fit) is registered for `deep` audit after promote — see \"Role ownership\" below |\n| 3. Archive | When a stub is superseded / abandoned, move any body file to `.ralph/.bak/` and remove the entry | This topic |\n\n### 1. Write\n\n1. Confirm the item genuinely needs a plan and is being deferred (not act-now, not external-blocked).\n2. Ensure a `## Plan Drafts` section exists; perform a full-file header audit (`grep_search` with `Query: \"^##\\s+\"` or `CaseInsensitive: true`) first. Create a new `## Plan Drafts` header ONLY if zero existing matches are found. If present, append the new stub to the existing section.\n3. Pick a priority (`P0`-`P3`) reflecting promote urgency relative to other drafts (default `P2` when uncertain). The reason is always `:selfable` for Plan Drafts — see [priority.md](./priority.md).\n4. Append the entry as `- [BLOCKED:P*:selfable] {Purpose}` with the four minimal fields underneath.\n\n### 2. Promote\n\nA `deep` role-profile default invocation surfaces promote-ready drafts (stubs whose complexity fits the deep tier) as execution candidates at the end of its run — see SKILL.md \"deep-profile completion handoff\". User selection there counts as the promote decision and enters this procedure; drafts are never auto-promoted.\n\nWhen the resume trigger is met or the user requests promotion:\n\n1. **Re-verify the stub's premises against first sources before planning.** A stub is a defer-time snapshot; by promote time its premises drift — the config it targets may already be fixed, the question it poses may already be answered, or its proposed flag/approach may now conflict with a changed contract. Check each premise at a first source (grep the code/config, `gh`/`git`/`npm`/registry state, the tracker's `## Completed`). If any premise is invalidated, record it at the head of the research seed (passed to `code-workflow`) so the plan starts from current reality, not the stale stub.\n2. **Draft-to-Plan Mandatory Authoring Gate (HARD STOP)**: When the user requests draft promotion (\"promote draft\", \"promote remaining drafts\", etc.), **skipping `code-workflow` plan authoring or leaving draft stubs unauthored in `## Plan Drafts` is STRICTLY FORBIDDEN**. You MUST immediately dispatch the stub to `code-workflow` (Research → Plan → User Review) and produce the formal `plan-*.md` document.\n3. After the real research/plan artifact exists and user review is completed, move the entry to `## Fable Target Tasks` (with `audit_status: pending_opus_fable_audit` / `[BLOCKED:P*:selfable]`) for Fable/Opus+ model deep audit before implementation. Leaving `[PROMOTED]` stubs in `## Plan Drafts` is strictly prohibited.\n4. If a `plan-drafts/.md` body file existed, add valid YAML frontmatter (`title`, `status: superseded`, `created`, `share_eligibility: public|private`, `relates_to`, `archived: true`, `archived_at`, `archive_reason`) and move it to the unified `.ralph/` backup directory (`mkdir -p .ralph/.bak && mv plan-drafts/.md .ralph/.bak/draft-.md`). All `.ralph/` sub-document backups MUST be unified in `.ralph/.bak/` (never create sub-folder `.bak/` directories like `plan-drafts/.bak/` or `docs/generated/.bak/`).\n\n### Role ownership (promote execution)\n\nWhich role profile (see `SKILL.md` \"Role-based execution\") executes Stage 2:\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | `deep` authors architecture-scale drafts from scratch, `impl` limited to \"lightweight\" drafts only | `impl` executes Stage 2 by default for **all** complexity tiers — the same premise-reverify → `code-workflow` dispatch procedure |\n| 2 | `pm` executes any part of Stage 2 (premise re-verify, dispatch, authoring) | `pm` only surfaces drafts whose resume trigger has fired, during its default-pipeline scan of `## Plan Drafts` — it never authors |\n| 3 | `deep` waits idle for drafts to author, or drafts are pre-classified by scope before promote to route some to `deep` | After `impl` produces the plan artifact, if it fits [model-triage.md](./model-triage.md) Category I (greenfield architecture) or III (stale plan↔reality resync), register it into `## Target Tasks` via that topic's existing Discovery Procedure — `deep` audits/strengthens the artifact `impl` already produced, it does not draft from zero |\n\nThis reuses model-triage's existing dedicated-section queue as the sole hand-off mechanism between `impl` and `deep` — no new state field or separate audit queue is introduced.\n\n### 3. Archive (superseded / abandoned)\n\nWhen a draft is no longer wanted (duplicated by another plan, scope dropped):\n\n```bash\n# Add YAML frontmatter (title, status: superseded, share_eligibility, relates_to, archived: true, archive_reason)\nmkdir -p .ralph/.bak\nmv plan-drafts/.md .ralph/.bak/draft-.md # only if a body file exists (all .ralph backups unify under .ralph/.bak/)\n```\n\nThen remove the `## Plan Drafts` entry. **Order**: archive the file first, remove the entry second (same rule as `issue-drafts` — reverse order leaves an orphan file mis-read as pending).\n\n## Don't / Do\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Write a full research/plan document when the user defers | Record only the stub (purpose + 3 fields). Full plan is produced at promote time via `code-workflow` |\n| 2 | Use a long topic name in the invocation | Call `/fix-plan draft ...` — the topic keyword stays short regardless of descriptive name |\n| 3 | Put a deferred-plan item in `## Progress` as a normal `[ ]` | Deferred-needs-planning items go in `## Plan Drafts`. Act-now items go in Progress (`add`); external-blocked go to `priority` `[BLOCKED]` |\n| 4 | Leave a promoted stub in `## Plan Drafts` after the real plan exists | Remove the stub on promote — the plan artifact supersedes it |\n| 5 | Archive the entry before the body file | File first, entry second (orphan-file avoidance) |\n| 6 | Record only the inline 3-field stub when this session has already gathered substantive research/measurements (the chat contains numbers/tables/classified findings) | **Inline + body file mode** — write the findings to `plan-drafts/.md` first, then cite the file from the entry. Inline-only here loses the research when chat is compressed |\n| 7 | Use `- [ ]` for Plan Draft entries | Use `- [BLOCKED:P*:selfable]`. `[ ]` lets autonomous loops (e.g. Ralph) try to act on the entry — but a deferred plan cannot be promoted by an agent on its own. `[BLOCKED]` ensures the entry is skipped until the user signals promote |\n| 8 | Use `:external` reason on Plan Draft entries | Always `:selfable`. The body file / stub is prepared — the wait-state is on a user signal, not on a third party. `:external` is reserved for true external dependencies (`priority.md`) |\n| 9 | Promote a stub straight into `code-workflow` on its defer-time premises | Re-verify each premise at a first source first (Stage 2 step 1); note any invalidated premise at the head of the research seed — a deferred stub drifts and its assumptions may already be resolved or contradicted |\n\n## Self-check (before recording a draft)\n\n1. Does this item need real planning (research/design), or is it act-now? → act-now uses `add`, not `draft`.\n2. Is it deferred by choice, or blocked on an external dependency? → external-blocked uses `priority` `[BLOCKED:P*:external]` in `## Progress`. Plan Drafts are always `:selfable`.\n3. Are all four fields (purpose, defer reason, resume trigger, expected deliverable) filled with one terse value each?\n4. **Has this session already produced substantive research / measurements / findings** that the inline 3 fields cannot hold? → **Inline + body file mode** (`plan-drafts/.md`). Do not let the research die in chat. Symptom: chat contains numbers, tables, classified results, or methodology fixes that the entry omits.\n5. Is the stub small **and no body to preserve**? Then inline only. If the body would still exceed a few paragraphs **and** the user has not deferred, promote via `code-workflow` instead of stubbing.\n6. Have you picked a priority (`P0`-`P3`)? → Default `P2` when unsure. Marker is `[BLOCKED:P*:selfable]`, never `[ ]`.\n\n## See also\n\n- [add.md](./add.md) — authoring act-now items (`## Progress`)\n- [priority.md](./priority.md) — `[BLOCKED]` for external-blocked items\n- [issue-drafts.md](./issue-drafts.md) — parallel draft-file lifecycle\n- `code-workflow` (`steps` topic) — promote target: research → plan → user review\n\n## Plan Artifact CollabMD Sync & Plane Comment Linkage (HARD STOP)\n\nWhen authoring or updating architecture and planning artifacts (`plan-*.md`), stopping after writing to local workspace directories (`.agents/docs/generated/`) is strictly prohibited.\n1. **Security Isolation & CollabMD Sync Path Compliance**: Because `.agents/docs/generated/` is reserved for raw AI generation isolation, authoritative deliverables intended for CollabMD (`plan-*.md`, etc.) MUST be copied or placed in the secure sharing path **`.agents/docs/shared/`** so they are synchronized via Syncthing to the collaborative editor/viewer (CollabMD, `https://collabmd.dgs.ai.kr`), and the frontmatter must declare `collabmd_url` (`https://collabmd.dgs.ai.kr/#file=daegunsoftdev-agents-docs/`).\n2. **Parent Plane Issue Comment Linkage**: Prompt instructions prohibiting Plane issue mutations (\"read-only research/planning\") forbid modifying issue state or description, NOT posting reference comments. Agents MUST use `plane_create_comment.py` to post a comment to the corresponding parent Plane issue containing the CollabMD viewer link, local artifact path, executive summary, and audit status, ensuring end-to-end traceability in Plane SSOT.\n\n| # | Don't | Do |\n|---|-------|----|\n| 1 | Leave plan artifacts only in `.agents/docs/generated/` causing CollabMD `file not found` | Place in `.agents/docs/shared/` per security isolation policy, verify CollabMD URL, and link in Plane comment |\n| 2 | Conflate \"prohibit Plane issue mutations\" with posting artifact reference links | Distinguish state/body mutations from reference comment posting, completing comment linkage |\n\n## Plan & Research Artifact Mandatory Frontmatter Schema & Creation Date (HARD STOP)\n\nWhen authoring or revising architecture, plan, or research artifacts (`plan-*.md`, `research-*.md`), omitting mandatory YAML frontmatter metadata or using non-standard keys (such as bare `date:`) is strictly forbidden.\n1. **Canonical Frontmatter Schema Compliance**: Every plan and research artifact MUST begin with standard YAML frontmatter containing the mandatory field **`created: `** (initial creation date). Replacing `created` with arbitrary keys like `date` is prohibited.\n2. **Revision & Modification Tracking**: When modifying or augmenting an existing plan or research document, agents MUST preserve the original `created` date, update **`last_modified: `**, and prepend a document metadata banner (`> **Document Metadata**: Initial created date / Last modified date / Status`) at the top of the body.\n3. **Proactive Creation Date Declaration in Reports**: When presenting, quoting, or reporting plan/research deliverables in chat or checklists, agents MUST explicitly declare whether the document is newly authored or an existing document along with its initial creation date, preventing ambiguity over document history and provenance.\n\n| # | Don't | Do |\n|---|-------|----|\n| 1 | Use non-standard `date:` key or omit creation timestamp | Mandate `created: ` in frontmatter, appending `last_modified` upon revision |\n| 2 | Present existing plans ambiguously without stating age/creation date | Proactively declare document provenance (new vs existing with original creation date) in chat reports |\n\nFile v0.17.1:flowchart.md\n\n# Flowchart\n\nStandardizes priority flowchart (dependency graph) authoring and plan document mapping in `fix_plan.md` / `checklist.md`.\n\n## When to Use\n\n- Creating or updating the Mermaid dependency flowchart (`graph TD`) in `fix_plan.md` (e.g. under a `## TODO` section).\n- Mapping flowchart nodes to specific plan documents (`llm-wiki/outputs/`, `.ralph/plan-drafts/`, `.ralph/docs/generated/`).\n- Structuring precedent relationships (`A --> B`) across infrastructure, deployment, and feature plans.\n- Invoked via `/fix-plan flowchart` or when managing task execution roadmaps.\n\n## Placement check — parent tracker precedent (HARD STOP)\n\n**Before creating a NEW `## Flow Chart` section in a project-local/subordinate tracker (a project inside a larger workspace that has its own workspace-root `fix_plan.md`), check whether the workspace-root tracker already has a `## Flow Chart` with a node for the same or a related initiative.** Grep the root tracker's node labels and Node Plan Mappings for the project name or a related plan-document path. If a precedent node exists there for related work (e.g. a sibling initiative in the same subsystem), the **default** is to add the new node to that existing root-level graph — not to spin up a duplicate local Flow Chart. A local Flow Chart is only correct when the workspace root has none, or the initiative is genuinely scoped to that project alone with no cross-workspace counterpart.\n\nThis does not affect where the actual checklist items live — `## Priority Tasks` / `## Plan Drafts` entries stay in the project-local tracker; only the Flow Chart *diagram node* follows the root-level precedent, mirroring the existing pattern where a root-level node's \"Node Plan Mappings\" entry points at the project-local tracker/plan doc.\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Default an AskUserQuestion's Recommended option to \"create local Flow Chart\" based on scope-narrowness alone | Grep the workspace-root tracker's Flow Chart first; if a related-initiative node exists there, make \"add to root tracker\" the Recommended option |\n| 2 | Treat \"narrowest scope = safest default\" as a placement heuristic | Precedent in the very document being edited (or its workspace root) overrides a generic narrowness heuristic |\n\n## Schema & Placement\n\nPlacement: At the top of `fix_plan.md` under a `## TODO` section.\n\n```markdown\n\n## Flow Chart\n\n```mermaid\n graph TD\n VaultSecret[\"Vault Credentials Index Build\"]\n IaC[\"K3s IaC Share Improvement\"]\n K3sAdvance[\"K3s Advancement\"]\n Domain[\"Domain Registration\"]\n Cert[\"cert-manager Domain Integration\"]\n ClawoRuntime[\"clawo Server Runtime Prep\"]\n Clawo[\"clawo Server Build\"]\n Roles[\"Model Role Allocation\"]\n PRAuto[\"PR Automation\"]\n Pipeline[\"AI Pipeline Build\"]\n WikiRAG[\"Internal Wiki RAG Exposure\"]\n PlaneExposure[\"Internal Plane Exposure\"]\n CNPGDrill[\"CNPG HA Failover Drill\"]\n\n VaultSecret --> Domain\n VaultSecret --> ClawoRuntime\n\n IaC --> K3sAdvance\n K3sAdvance --> ClawoRuntime\n K3sAdvance --> Cert\n K3sAdvance --> CNPGDrill\n\n Domain --> Cert\n Cert --> WikiRAG\n Cert --> PlaneExposure\n\n ClawoRuntime --> Clawo\n Clawo --> PRAuto\n Clawo --> Pipeline\n Roles --> Pipeline\n\\```\n - **Node Plan Mappings**:\n - **VaultSecret (Vault Credentials Index Build)**: `.ralph/plan-drafts/vault-workspace-credentials-index.md`\n - **IaC (K3s IaC Share Improvement)**: `daegunsoftDev/gitops` (`apps/`, `clusters/dev36/`) / `llm-wiki/outputs/plan-plane-dev36-gitops.md`\n - **K3sAdvance (K3s Advancement)**: `llm-wiki/outputs/plan-plane-dev36-gitops.md` / `llm-wiki/outputs/plan-cnpg-failover-drill.md` / `llm-wiki/outputs/plan-qdrant-oci-deploy.md`\n - **Domain (Domain Registration)**: `.ralph/docs/generated/handoff-cloudflare-letsencrypt-dgs-ai-kr.md` / `.ralph/plan-drafts/wiki-dgs-ai-kr-exposure.md`\n - **Cert (cert-manager Domain Integration)**: `.ralph/docs/generated/handoff-cloudflare-letsencrypt-dgs-ai-kr.md`\n - **ClawoRuntime (clawo Server Runtime Prep)**: `llm-wiki/outputs/plan-clawo-container-completion.md`\n - **Clawo (clawo Server Build)**: `llm-wiki/outputs/plan-webhook-pr-review.md`\n - **Roles (Model Role Allocation)**: `.ralph/plan-drafts/model-role-triage-sonnet-opus-fable.md`\n - **PRAuto (PR Automation)**: `llm-wiki/outputs/plan-webhook-pr-review.md`\n - **Pipeline (AI Pipeline Build)**: `llm-wiki/outputs/plan-clawo-container-completion.md` / `llm-wiki/outputs/plan-webhook-pr-review.md`\n - **WikiRAG (Internal Wiki RAG Exposure)**: `llm-wiki/outputs/plan-wiki-rag-buildout.md` / `.ralph/plan-drafts/wiki-dgs-ai-kr-exposure.md`\n - **PlaneExposure (Internal Plane Exposure)**: `llm-wiki/outputs/plan-plane-dev36-gitops.md` / `.ralph/docs/generated/handoff-cloudflare-letsencrypt-dgs-ai-kr.md`\n - **CNPGDrill (CNPG HA Failover Drill)**: `llm-wiki/outputs/plan-cnpg-failover-drill.md`\n```\n\n## Layout ordering — serialize dependency-free items (HARD STOP)\n\n`graph TD` puts every node that has **no incoming edge on the same top row**. A set of\ndependency-free items therefore fans out **horizontally** and the chart grows unreadably\nwide to the right. Give those items a priority-ordered layout with **invisible ordering\nedges** so they stack top-to-bottom instead — without drawing a misleading arrow.\n\nDistinguish two edge kinds:\n\n| Edge | Syntax | Meaning |\n|------|--------|---------|\n| **Dependency edge** | `A --> B` (solid) | Real prerequisite — A must finish before B |\n| **Ordering edge** | `A ~~~ B` (**invisible**) | **No** real dependency — a pure layout hint that ranks B below A by priority. Mermaid draws it `stroke-width:0` (no visible line), so it never implies a prerequisite that doesn't exist |\n\n**Why invisible, not dotted:** ordering is not a relationship at all — even a dotted arrow\nsuggests a link between two unrelated items. `~~~` still creates the rank constraint that\nstacks the nodes vertically, but draws nothing. (Dotted `-.->` is a fallback only for a\nMermaid version that predates `~~~`.)\n\n### Split many items into balanced priority columns (not one tall spine)\n\nChaining *all* dependency-free items into a single invisible spine only trades a too-wide\nchart for a too-tall one. Instead, split them into **K balanced groups** (by theme/domain)\nand give **each group its own invisible priority chain** (highest → lowest). Every group\nhead is a root, so `graph TD` places the heads on the same top rank and the groups render\nas **side-by-side columns** — a compact priority grid, not one long line.\n\n```mermaid\n graph TD\n A0[\"[P0] Group A\"] ~~~ A1[\"[P1] A\"] ~~~ A2[\"[P2] A\"] ~~~ A3[\"[P3] A\"]\n B0[\"[P0] Group B\"] ~~~ B1[\"[P1] B\"] ~~~ B2[\"[P2] B\"]\n C0[\"[P0] Group C\"]\n```\n> `~~~` edges are **invisible priority-ordering only**, not dependencies.\n\nBecause every head is a root and each `~~~` adds one rank, priority levels **align across\ncolumns**: all `P0` on the top row, all `P1` on the next, etc. — a readable grid.\n\n**Alignment caveat:** cross-column rank alignment holds only when a group's priority levels\nare **consecutive**. If a group skips a level (e.g. `C0 (P0) ~~~ C2 (P2)` with no `P1`),\nthat `P2` lands one rank too high and misaligns with the other columns' `P2` row. To force\nalignment, insert an invisible spacer node at the skipped level; otherwise accept the local\nmisalignment.\n\nWhen a real dependency tree and independent items coexist, keep the tree on solid edges and\ngive the leftover independent items their own invisible priority columns beside it.\n\n## Sync procedure (pm-role default-pipeline step 5)\n\nThe `pm` role's default pipeline (see `SKILL.md` \"Default invocation\") runs this as its final step, right after `priority` triage produces its sorted `[BLOCKED:P*:reason]` list. This is a **mechanical drift check** against that output — not a full re-authoring pass.\n\n1. **Read** the current `## Flow Chart` Mermaid block and its `Node Plan Mappings` list.\n2. **Cross-reference** each `[P*]`-labeled node against the tracker item it maps to (via the Node Plan Mappings entry or an inline reference):\n - **Stale label** — the node's `[P*]` tag no longer matches that item's current `[BLOCKED:P*:reason]` tag → update the label.\n - **Resolved item** — the backing item is now `[x]` / moved to `## Completed` → remove the node and any edges touching it.\n - **New item, no node** — a `[BLOCKED:P*:reason]` item from this run's priority triage references a plan document but has no corresponding node → propose adding one (does not require re-laying-out the whole graph; append per \"Layout ordering\" above).\n - **Path correction, whole-file grep** — when a Node Plan Mappings entry's document path was stale/wrong and gets corrected, grep the entire tracker file for the same stale path string before considering the correction done. A path can be cited in more than one place — most commonly inside the backing `[BLOCKED]` item's own body (`Why` / `Options` prose) — and fixing only the Node Plan Mappings line leaves those other citations pointing at the old, possibly non-existent path.\n3. **Apply** only the drift found — do not redesign layout, columns, or dependency edges beyond what the drift requires. Semantic re-authoring (splitting into new priority columns, adding real dependency edges between unrelated nodes) stays a deliberate `/fix-plan flowchart` invocation, not part of this mechanical step.\n4. **Report** `N node(s) relabeled / M node(s) removed / K node(s) proposed` before the pipeline's overall run report closes — mirrors the priority topic's own \"N entries auto-resolved\" reporting contract (see [priority.md](./priority.md) Don't/Do #4).\n\n| # | Don't | Do |\n|---|-------|-----|\n| 1 | Skip flowchart sync because \"the graph still looks fine\" | Cross-reference every `[P*]` node against its tracker item every `pm` run — drift is invisible without the check |\n| 2 | Use this step to also redesign columns/layout | Layout redesign is a separate, deliberate `/fix-plan flowchart` call — this step only corrects drift |\n| 3 | Silently drop a node for a resolved item without reporting it | Report removed/relabeled/proposed counts, same as priority's sync-resolution reporting |\n| 4 | Fix a stale document path only where it was first noticed (the Node Plan Mappings line) and stop | Grep the whole tracker file for the same stale path string and correct every citation, including the backing item's own `Why` / `Options` body |\n\n## Pinned-mission liveness check (pm-role default-pipeline step 5, continued)\n\nRuns immediately after the flowchart-sync procedure above, same `pm`-role scoping, same \"mechanical drift check, not a full re-authoring pass\" spirit. No-op on a tracker that has no pinned header block.\n\n**Problem this solves**: a tracker's pinned header block (`> 📌 ...` at the top of `fix_plan.md`/`checklist.md`) often names a top-priority mission and prose-cites the backing items that must finish before it. That prose citation rots silently — a cited item can complete weeks before anyone notices the pinned block still calls the mission \"in progress,\" or a cited item's own title can drift out from under the citation entirely. This step makes that citation mechanically checkable instead of trusting prose to stay accurate.\n\n### Citation convention (opt-in)\n\nAppend an HTML comment to a pinned bullet line that already has a `**bold label**`:\n\n```markdown\n> - **Loop governance adoption**: ... \n```\n\n- `todo:\"\"` — the citation lives in `## TODO` (or has moved to `## Completed`)\n- `deep:\"\"` — the citation lives in `## Deep Tasks` (or has moved to `## Completed`)\n- Multiple citations are comma-separated inside one marker; a mission is only a resolved candidate when **all** of its citations resolve.\n\nA pinned bullet with no marker is reported `unmonitored` and never becomes a candidate — **there is no fuzzy-text fallback**. Guessing citations from prose risks a false \"this mission is done\" claim, which is worse than under-reporting. Adopt the marker line by line as pinned entries are next edited; this is a new convention, not a retroactive requirement.\n\n### Procedure\n\n1. Run `python3 /scripts/pinned_liveness_check.py [--roadmap-doc=] --json` — reuses the tracker text already in hand from this same pipeline run; no external network calls.\n2. For each mission the script reports `resolved`, do **not** auto-write the pinned block. Surface via `AskUserQuestion`: \"Pinned mission '