Feature plan: Step 1 · Step 2 · Step 3 · Step 4

Debug mode: enabled

Completion Contract

Existing /docs/ and direct document URLs remain safe/readable dynamically and statically, with supported links, keyboard/mobile access and recoverable publication. Save syntax counts and before/after render evidence before removing the eight-package Markdown bundle. Deliver the rare-syntax decision table and host dependency-consent policy; defer new syntax to the separate extension cycle. Complete removal requires verified absence of targeted source/generated infrastructure across every agreed current/historical repository and copy, including retained objects; unverified external cleanup remains incomplete. No schema or unrelated dependency changes.

Key Risks

• High risk: restoration can break safe links or critical instructions. Historical 0e13f9db^ renderer lacks the current context parameters and catalog URL policy; preserve those contracts, compare the frozen corpus and review critical fallbacks before cleanup.

• High risk: history replacement can lose work or leave copies behind. Inventory paths/blobs, refs, shared worktrees and controlled external copies first; validate an isolated rewrite and recovery before publication or object disposal. Unknown owners/access block those dependent actions.

• Miscounting can hide uncommon syntax. Cross-check source variants against parsed/rendered outcomes and hand-counted samples; never equate line counts with occurrences or unsupported/ambiguous cases with zero.

Planning decisions — approved with external cleanup prerequisites

• Proposed rarity rule: at most five distinct documents per syntax variant, including zero-use variants; retain occurrence counts and flag critical uses regardless of frequency. Accepted with Step 3 approval.

• Local inventory: common Git directory .git; worktrees at /home/wsl/agent/v3-codex, /home/wsl/.codex/worktrees/{39c4,7bff,d69d}/v3-codex and a prunable registration at /tmp/forum-image-baseline. Do not delete registrations or other work without checking ownership/state.

• Four locally known refs contain introduction 0e13f9db: refs/heads/main, refs/remotes/origin/HEAD, refs/remotes/origin/main, refs/remotes/origin/feature/docs-discovery. This is a starting inventory, not a full path/blob or live remote audit. Other refs/reflogs/detached worktrees must also be checked.

• origin is https://github.com/gulkily/v3; fdp points to an unrelated workflow upstream and must not be rewritten. Other clones, forks, deployment copies, archives/backups, hosting retention and coordination owner/access remain unknown; user clarification is pending. Resolve target/owner/access/verification records before dependent history work; measurement/restoration can proceed without silently limiting the original removal request to one checkout.

Stage 1 — Freeze and measure the current reading flow

• Goal: preserve reproducible syntax-use and render evidence before restoration.

• Dependencies: rarity rule accepted; Step 3 approval, feature branch and planning-only commit under Railspike organization rules.

• Expected changes: a maintainer-only measurement harness and reports over a fixed eligible Markdown corpus from PlatformDocsCatalog, with revision and per-file hashes. Count block/inline occurrences and source variants (list items/containers separately; table/cells separately); identify overlap, code examples, zero-use and unresolved constructs. Record errors and outcomes without vendor source dumps.

• Verification approach: hand-count representative nested lists, emphasis delimiters, reference/autolinks, tables, fences and ambiguous forms; compare source counts with existing parser events/tree/render output and inventory taxonomy. Record exclusions and uncertainty explicitly.

• Risks or open questions: parser nodes lose delimiter variants; use source locations plus independent source classification, never a successful-node-only counter.

• Canonical components/API contracts touched: PublicMarkdownRenderer::render(string, ?string, ?string): string, catalog inventory, maintainer measurement/report tooling; no serving-path telemetry.

Stage 2 — Restore and compare the dependency-free reader

• Goal: ordinary Docs reading/publication works through the earlier project-owned renderer.

• Dependencies: Stage 1 evidence saved and committed.

• Expected changes: restore historical parsing with current context/error contracts, catalog link policy, safe source fallbacks and essential keyboard/reader integration; remove CommonMark imports/adapters and the bundle. No new formatting support. Produce same-corpus comparisons and the rare-syntax table required by Step 2, leaving extension decisions pending.

• Verification approach: focused Docs page/catalog/static tests, adversarial links/HTML/file boundaries and command-byte preservation; compare critical guide/navigation behavior. Review any critical regression before moving on; an extension needed to satisfy acceptance requires replanning.

• Risks or open questions: pre-dependency parsing is not current-format parity; record unsupported formatting and safe fallbacks without weakening safety assertions.

• Canonical components/API contracts touched: shared renderer, Docs adapters, catalog resolver, controller/static callers, templates and affected tests.

Stage 3 — Verify delivery and prevent reintroduction

• Goal: validate the restored flow and make dependency consent explicit.

• Dependencies: Stage 2 comparison accepted; no unresolved critical reader failures.

• Expected changes: apply host AGENTS/CONTRIBUTING policy from findings; update renderer runbook and release checks to remove reinstall instructions and bundle assumptions. Preserve historical incident prose and metric evidence.

• Verification approach: existing focused checks plus dynamic/static, JavaScript-off, desktop/390px, keyboard and affected default/Word97/Chicago/Midnight reader states; copied-package full/shared publication, failed-build retention and recovery. Run the full suite once, investigate failures and distinguish baseline failures. Verify zero external additions and zero targeted current source files.

• Risks or open questions: stale generated pages can mask failures; generate isolated complete releases and test real URLs and recovery, not only renderer output.

• Canonical components/API contracts touched: Docs browser/release tests, static publisher recovery, host instructions and operator guidance.

Stage 4 — Rehearse and verify complete history removal

• Goal: produce a validated, reviewable replacement before changing shared history.

• Dependencies: Stage 3 committed; agreed complete cleanup inventory, freeze and recovery ownership.

• Expected changes: isolated full-ref rewrite removing targeted historical paths/renames and copied source/generated blobs; record old/new ref mappings and cleanup evidence without retaining targeted contents in reports. Preserve unrelated changes and the cycle's staged implementation record.

• Verification approach: inspect all rewritten refs/trees and reachable objects, file-content/rename candidates and required subtree metadata; rerun focused normal-flow/release checks. Verify no targeted content enters metrics or new artifacts. Compare unrelated trees and prove recovery before destructive cleanup.

• Risks or open questions: hidden/host refs and contaminated recovery copies can defeat erasure; enumerate them and their disposal/verification procedure before proceeding. Any rewrite tool must be already available or separately approved under the dependency policy.

• Canonical components/API contracts touched: isolated Git repository, rewrite inventory, mappings and cleanup runbook; serving code unchanged.

Stage 5 — Coordinate publication and finish cleanup

• Goal: complete removal for every agreed controlled target.

• Dependencies: Stage 4 verified/committed; concrete replacement refs, collaborator freeze and recovery package reviewed. Obtain final authorization for coordinated shared-history publication when the exact result is available; Step 3 approval alone does not authorize it.

• Expected changes: publish validated replacement refs, reconcile controlled clones/worktrees/deployment copies/artifacts, then dispose of contaminated backups and retained Git objects after acceptance. Preserve unrelated upstreams and active work; use current official host procedures when preparing that action.

• Verification approach: independently retrieve published refs and scan targeted content; verify each controlled target and retained-object cleanup, rerun ordinary Docs/recovery acceptance where deployed, and record inaccessible host/fork copies as pending. No complete-removal claim while agreed targets remain unverified.

• Risks or open questions: stale clones can reintroduce history; coordinate replacement before unfreezing writes. Do not expire/prune shared storage while any active worktree or recovery requirement depends on it.

• Canonical components/API contracts touched: origin and agreed controlled copies/storage, cleanup report and release/recovery handoff.

Execution and approval state

Step 2 is approved. Step 3 explicitly approved. The five-document rarity proposal is accepted; controlled-copy/owner decisions remain prerequisites to dependent history work. No implementation, commits or rewrite has started. Each stage targets about one hour of authored work, excluding mechanical corpus/rewrite execution and external coordination. Split oversized work before implementation; return to Step 2 if completion exceeds a day/eight stages. After Step 3 approval, create feature/markdown-dependency-removal, organize only this cycle's artifacts, make the permitted planning commit, then commit each stage with its Step 4 summary before starting the next. Keep findings and deferred extension artifacts outside the initial planning commit unless explicitly permitted by Railspike's file gate; incorporate authorized incident evidence in the appropriate implementation stage. No branch reuse, merge or production activation is presumed.