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

Debug mode: enabled

Effort study: railspike-effort / v3/markdown_dependency_removal; host ledger.

Execution state

• Approved Step 3 received; Option C and five-document rarity threshold accepted. Extension cycle stays deferred with its own pending approvals.

• Branch: feature/markdown-dependency-removal. Planning commit: c3f3653a.

• User and assistant coordinate GitHub cleanup. Stage 4 rehearsal is verified and the six approved replacement refs are published. Stage 5 clone synchronization is verified; retained-object/backup disposal and external-retention acceptance remain incomplete; see the publication record below.

• Initial planning commit contains only approved plans, existing debug log and plan-index organization. Incident findings are included with Stage 3 remediation; the separately deferred extension Step 1/debug log remain uncommitted under that cycle’s planning gate.

Stage 1 - Freeze and measure the current reading flow

• Changes: maintainer-only PHP render/reference-AST probe and dependency-free Python source-variant counter; frozen manifest and baseline JSON plus human-readable count/method report. 1,312 catalog-eligible tracked Markdown documents at planning revision; per-file hashes, independent AST totals, source candidates/locations, render tag counts/hashes and error fields. No source/vendor/HTML dumps in evidence.

• Verification — passed: all 1,312 reference renders (zero errors); php -l scripts/markdown_render_probe.php; python3 -B tests/markdown_metrics_test.py (hand-counted mixed syntax, nested overlap, repeated occurrences, code exclusion, metadata, zero use and locations); git diff --check.

• Notes: counts label heuristic/ambiguous candidates explicitly; reference AST counts provide independent semantic totals. They are not a complete syntax-conformance guarantee. Runtime/UI/release checks are pending later stages, not established by this probe. Stage commit: 41a958fd.

Stage 2 - Restore and compare the dependency-free reader

• Changes: restored parsing from project-owned 0e13f9db^, preserving current three-argument render/error contract, catalog URL boundary, heading navigation, metadata/image safety, code captions and keyboard regions. Source-number preservation prevents repeated step 1 across split procedural lists; pipe tables use escaped scrollable source rather than implementing tables. Removed 425 bundled files and three CommonMark adapter classes. No replacement dependency or new syntax extension.

• Changes: frozen-corpus restored report/comparison and 17-row rare-syntax table; all extension implement/defer/omit choices remain pending. Source counts and independent semantic counts remain separately labeled.

• Verification — passed: all 1,312 frozen documents rendered without errors and with matching source hashes; 26 page/catalog tests; two static publication/on-demand tests including all inventory readers, browse parity and stale-reader deletion; metrics fixture; PHP lint; git diff --check. Code bytes, safe URL/symlink policy, source alternatives and critical guide numbering/CLI fragment have focused assertions.

• Notes: initial static run detected concurrent report changes and aborted as designed; stable-document rerun passed. Old reference-format assertions were replaced with explicit approved fallback assertions, retaining security checks. Broader browser/copied-package/full-suite verification remains Stage 3. Deferred limitations include nested/loose lists, tasks, reference/autolinks, underscore emphasis, strikethrough and tilde fences; they remain readable source. Stage 2 commit: 14fffd22.

Stage 3 - Verify delivery and prevent reintroduction

• Changes: applied the host dependency-consent policy in AGENTS/CONTRIBUTING, requiring explicit review of the complete direct/transitive inventory and delivery method; generic step approval is insufficient. Updated both rendering and production deployment runbooks to remove bundle installation/restoration instructions. Retired current reference-parser imports; maintainer reference mode now rejects execution and points to archived measurements, without reinstalling anything. Semantic count tables now also show distinct-document counts derived from the archived AST rows.

• Changes: copied-package test ships root documents and verifies the restored source fallback, controlled renderer failure and rollback without a vendor tree. Saved incident findings, all 32 browser scenario measurements, copied-package recovery results, full-suite classification and preliminary cleanup inventory beside these plans. Dependency delta: eight Markdown packages removed, zero new external packages/assets/tools; existing Node manifests unchanged.

• Verification — passed: 28 focused Docs checks (page/catalog/static), repeated in the full suite; current metrics fixture and PHP probe lint/smoke; desktop/390px reader and discovery across default/Word97/Chicago/Midnight, dynamically and statically (32 scenarios). JavaScript-off reader tests verify six source-numbered procedure steps, four scrollable table-source regions, real Tab/ArrowRight focus/scroll, no page-wide overflow and the CLI fragment destination. Discovery verifies search/return, empty/missing/retry states, inert assets/download headers and both existing Docs icon surfaces. Screenshots inspected in default, Word97, Chicago and Midnight; theme CSS was exercised with preference scripts disabled in reader scenarios.

• Verification — passed: copied complete dependency-free application, actual full/shared CLI publication, dynamic/static content parity, stale refresh, injected rendering failure/503, failed-build retention, restored renderer and regeneration. Latest fixture: /tmp/markdown-release-fhmtnymk; dynamic fixture/screenshots: /tmp/markdown-removal-dynamic-3veklbvj. Durable JSON measurements are committed here; no production release was activated.

• Verification — failed with causes classified: full suite ran once, 1,398 run / 1,388 passed / 10 failed. Six exact failures reproduce in clean starting revision 02512b8e (profile copy ×2, static-progress copy ×2, read-model timing, and a private-release assertion that also matches asset names mentioned in existing public documentation). Three offline-diagnostic assertions pass both in clean baseline and in the current tree with explicit public-fixture configuration; this workspace's existing access settings intentionally disable anonymous offline reading. These settings were not changed. One publication test detected an agent documentation edit during its snapshot; its stable-document rerun passed. No unclassified failures; this is not an unqualified full-suite pass. Exact cases/messages and rerun evidence: verification evidence.

• Verification — passed: no physical/tracked Markdown vendor directory, no parser imports/autoloader in application or current metric probe, no Node manifest changes, document links and git diff --check. Initial dynamic harness failures were corrected by using an isolated image root and the real FrontController asset handler. An interrupted package run was repeated in an isolated process session. No application source change was needed for these harness corrections.

• Notes: six unrelated baseline assertions remain follow-up work; workspace-default offline tests need explicit fixture configuration for a hermetic run. Extension choices in the 17-row table remain pending in the separately deferred cycle. Stage 3 commit is recorded in the next authorized summary update; no completed commit is amended.

Stages 4–5 - Pending prerequisites; not executed

• Read-only inventory found live origin main 269b44ac ahead of local starting main 02512b8e. Newer reply-viewport and backup/import changes must be preserved in any replacement; no refs were updated here or on origin. Preliminary inventory records advertised refs and known shared worktrees, not a complete cleanup boundary.

• Initial handoff left coordinator and copies unresolved; the preparation update below identifies the coordinators and seven local repositories. Collaborator freeze, remaining copies, preservation audit and host-retained boundaries still require reconciliation. Stage 5 requires review/authorization of the concrete replacement refs; generic Step 3 approval did not authorize shared publication.

• The temporary remote-inspection/baseline Git repository and its reconstructed historical bundle were disposed of after verification. Original shared Git storage/worktrees and remote history remain intact; no expiration, pruning, force push or production activation occurred. Current-tree deletion does not constitute historical erasure.

• When rewriting, preserve the corpus old/new revision mapping so the frozen source can still be located after commit IDs change; retain per-file hashes and original incident/measurement evidence without restoring third-party source. No removal-complete claim until every agreed target is verified.

Stage 4 preparation - Coordinated rewrite and clone synchronization

• Request: coordinate the GitHub rewrite together; user brings other clones up to main and pushes their work first; prepare synchronization instructions and wait for OK. Other clone updates may follow publication.

• Disposition: in-scope refinement of the history-cleanup stage. Recommend an isolated rewrite after consolidation, followed by sequential clone synchronization; defer mutation of existing clones while writes are frozen. An immediate in-place rewrite is unsuitable for the observed uncommitted files, stashes, many local branches and linked worktrees.

• Approval status: inventory and instructions authorized; user explicitly reserves OK before rewrite. No force push, history rewrite, reset, stash deletion, worktree removal or object pruning performed.

• Changes: clone synchronization runbook and refreshed local inventory. Actual clone pattern is ~/agent/v3-*; ~/agents/v3-* matched nothing. Stage 3 commit: 957e786a. Preserved subsequent external commit eb5d49da and the two untracked deferred extension plans.

• Verification: read-only status/branch/stash/shared-Git/worktree inventories of seven repositories; document links and git diff --check. Runtime/UI tests inapplicable to this coordination-only update. Linked-worktree contents and local branch reachability require a fresh audit at the freeze; stale tracking refs do not establish that work is pushed.

• Outcome: waiting for user consolidation and OK. Rewrite rehearsal, concrete replacement-ref review, publication and clone cleanup remain pending; this preparation does not complete Stage 4.

Stage 4 preparation - Preservation checklist refinement

• Request: turn the consolidation/push prerequisites into a checklist.

• Disposition: in-scope documentation refinement; authorized by the user's request.

• Changes: added unchecked per-clone working-file, stash, branch and linked-worktree preservation items and final freeze/OK handoff to the synchronization runbook, using the recorded inventory without claiming a fresh audit. Previous preparation commit: e6686747.

• Verification: checklist covers all seven recorded primary repositories, all recorded working-file entries, stashes and linked worktrees; git diff --check. Runtime tests inapplicable to this documentation-only refinement.

• Outcome: checklist saved; no preservation items marked complete and no clone/history mutations performed. Rewrite remains pending user OK.

Merge preparation — 2026-10-23

• Request: user confirmed readiness to proceed and that other copies are synced. Normal merge proceeds; shared-history rewrite/publication remains separate, with concrete replacement refs still requiring review.

• Changes: integrated origin/main d969817c9c1262bc2561689abc8badc4209f6a1e into removal branch 33154d8d. Resolved four documentation conflicts by preserving both sides: dependency-consent and pagination guidance, all plan-index entries, all effort-study records, and the Railspike upgrade record. Current main's upgraded vendored Railspike product is preserved unchanged. No new application changes or dependency additions during integration; Markdown bundle removal remains eight packages removed. Existing main changes, including its todo.txt contents, are carried through unchanged.

• Verification — passed: 48 Docs/catalog/static/Railspike checks; Markdown metrics fixture; renderer PHP lint; whitespace check of the merge result against origin/main. The complete staged merge also contains three pre-existing whitespace findings from main (one plan and two legacy label fixtures); these were preserved.

• Verification — passed: copied complete package on PHP 8.1.2, full/shared publication, dynamic/static content parity, stale refresh, injected renderer failure/503, failed-build retention, renderer restoration and regeneration, vendor absence, eight static reader and eight static discovery browser scenarios. Phone screenshots reviewed in default/Word97/Chicago/Midnight. Evidence fixture /tmp/markdown-release-czb9ipph; durable merge evidence. No production activation.

• Verification — incomplete: optional full-suite integration run stopped after 65 completed passes and 0 failures, while another import/publication test was running. This is not a full-suite pass and does not replace the earlier classified full-suite result. Focused/release coverage above completed independently.

• Notes: existing clones were only inspected, not reset or cleaned. Fresh read-only inventory found retained stashes and new uncommitted planning files in another clone; preservation and coordinated freeze remain prerequisites to history cleanup. Stages 4–5 and universal-removal acceptance remain incomplete.

Stage 4 resumption — 2026-10-23T07:15:12.398025+00:00

• Request: “Let's rewrite history now,” followed by “please continue.” This authorizes the isolated rewrite rehearsal; the approved plan retains concrete-ref review before shared publication. Normal merge is published as afe40311e5013075326a8f597877e00556fd5e9a. Continue the existing approved cycle on chore/markdown-history-rewrite because its earlier branch was merged. No new feature cycle or repeated planning approval.

• Preservation boundary: snapshot every advertised origin branch/tag and seven known local clones, including linked worktrees, stashes and local-only heads. Rehearsal operates on independent temporary mirrors; existing clones remain recovery sources pending per-copy reconciliation. No unrelated upstream rewrite.

• Study checkpoint: first enrolled checkpoint for this existing cycle under standing P2; prior intake/Steps 1–3/initial Step 4 scores are missing, not reconstructed. Scope v1 remains restoration, evidence, dependency consent, historical removal and coordinated copy recovery; starting revision 02512b8e2b1b44dabb3966eac21295bea9626412. Codex single exposed rater, after reviewing prior implementation and merge evidence. R1 report/diff hashes verified at /home/wsl/railspike-dev/docs/research/effort_estimation/; exact feedback recovered from 4f6cfe2b436fae8d939b1349fe724a3879ee0a0e, with its frozen hash verified.

• Projected total: 1.20, a late total-cycle projection including completed restoration/verification and remaining controlled history/copy work, not remaining effort or measured labor. Compared with the R1 startup-recovery anchor, this adds corpus compatibility evidence and coordinated multi-repository preservation/recovery. The above-one score warrants treating remaining cleanup as individually reviewed target handoffs; the existing isolated-rehearsal/publication gate already separates destructive execution. External storage acceptance remains unresolved and does not become a completed outcome. No independent rating or accepted-count increment.

Stage 4 — Verified isolated rewrite

• Changes: isolated Git built-in index-filter rewrite of third_party/markdown/; no new third-party tool or dependency. Source inventory identifies 425 paths / 424 unique blobs / two tree versions. Across 12,037 remote-reachable blobs, exact-blob, package-namespace/generated-autoloader and rename scans found no copies outside that inventory. Arbitrary fragment copying is not proven absent by these scans.

• Verification — passed: all 2,988 remote-reachable commits retained; 139 rewritten and 2,849 identical. Every changed commit preserves all non-target files, commit message, author/committer metadata and mapped parent order. Main's entire tree and the Railspike subtree are byte-identical. Six branch refs change, 13 branches and the annotated tag stay identical. Commit map, pure rewrite ref map, and verification. The final publication main will additionally include this audit-only stage commit.

• Verification — passed: fresh transport clone and isolated rewritten mirror pass git fsck; all stored objects, including unreachable storage, contain zero targeted blobs after disposable backup-ref/reflog cleanup. Existing clone storage was not pruned. Frozen corpus maps c3f3653a199997a1e2fc7bbcac7da21d95ce3649 to f0801ef43e53a92a7f5afc2b523fbb9ed561d570; every one of 1,312 source hashes matches, and a fresh restored-render measurement has zero errors. Original measurement artifacts remain unchanged.

• Verification — passed: fresh rewritten checkout runs 48 focused Docs/catalog/static/Railspike tests, the metrics fixture, and copied-package full/shared publication with dynamic/static parity, stale refresh, renderer-failure 503, retained active release, restoration/regeneration and 16 static browser scenarios. Main source is unchanged; earlier browser visual review remains applicable. Full suite not rerun for this history-only transformation.

• Recovery: seven original clones and their ignored configuration/runtime data remain in place. Private snapshots preserve 553 refs, seven stashes, detached worktree commits and tracked/untracked working changes. The private clean recovery graph preserves 3,135 commits (143 rewritten), all non-target content and metadata; 81 saved refs change and 472 stay identical. Exact local mappings and recovery bundles are private under /home/wsl/.local/state/v3-history-rewrite/20261023T0723Z; they must not be pushed to GitHub. Reflog-only unreachable work outside these explicit refs remains in original storage and still requires review before disposal.

• Host boundary: GitHub API reports zero forks, PRs, releases, Actions artifacts/caches and rulesets. Current host evidence. GitHub's published policy does not offer support purging for non-sensitive source; a branch rewrite cannot establish erasure of cached/unreachable host objects. Other deployment/archive copies remain unverified. No universal-removal or production-deployment claim.

• Gate: the user authorized rehearsal. Shared publication remains pending review of the exact six replacement refs and final authorization required by the approved Stage 5 plan. Use an atomic push with an explicit expected-old value for each changed ref; recheck the entire advertised ref snapshot first. Never mirror-push the mixed-remotes workspace. Clone synchronization and disposal remain separate preservation-aware actions.

• Study: total-cycle projection 1.20 reaffirmed, scope v1/R1/P2, single exposed rater; technical Stage 4 verification does not complete the full removal outcome or increment accepted outcomes.

Stage 5 — Shared-history publication verified; copy cleanup pending

• Request/authorization: user explicitly instructed “Publish now” after reviewing the six exact replacements and preservation boundary. Stage 4 audit commit is 1a358bc9be3cdb725277c792625a678e7bc85436.

• Changes: rechecked all 20 advertised refs against the captured snapshot, then atomically published the six approved branch replacements with an explicit expected-old-value lease for each. Main is 1a358bc9; the other 13 branches and annotated tag are unchanged. No private preservation refs, stashes or working-file backups were uploaded. No new dependency or application change.

• Verification — passed: immediate remote-ref comparison and independent fresh HTTPS mirror clone match every approved ref and the complete reviewed 2,989-commit graph (2,988 retained commits plus the audit commit). No target path remains in fetched history; zero of the 424 targeted blobs occur in reachable history or the fresh clone's complete object storage. git fsck --full passed. Publication verification.

• Validation boundary: the published graph is exactly the reviewed candidate whose 48 focused checks, copied-package recovery and 16 browser scenarios passed. No application changes or production activation occurred during publication; no full-suite pass is claimed. This publication record is a local follow-up audit commit, not an additional change to the approved remote main tip.

• Recovery/remaining work: seven original clones, their linked worktrees, ignored runtime/configuration and private recovery bundles remain preserved. Synchronization and stale-ref reconciliation must precede resumed pushes; do not pull/merge old ancestry into the rewritten history. Per-copy recovery acceptance and explicit cleanup authorization remain prerequisites to reflog expiration, backup removal or object pruning. Original/temporary copies and GitHub internal retention prevent a universal-erasure claim.

• Study: projected total 1.20 reaffirmed, v1/R1/P2, single exposed rater. Publication is complete; the original full-removal outcome, retrospective closeout and maintainer acceptance remain pending. No accepted-count increment.

Stage 5 — Existing clones synchronized; recovery retained

• Request/authorization: user explicitly requested synchronizing the existing clones with published history while preserving local work, stashes, configuration and recovery backups; preserve local audit ad7e8f5f and resume extension Step 1 afterward. This authorizes preservation-aware mapped updates, not disposal or another publication.

• Changes: seven primary repositories, fourteen registered worktrees (two missing), all retained refs and eight stashes reconciled. Every main/origin-main is 1a358bc9; current audit branch retains ad7e8f5f. Historical feature branches retain their mapped content. Private fresh bundles, config/log/worktree metadata and staged/unstaged/untracked backups augment the untouched prior recovery bundles. No todo.txt edits by this task.

• Changes: a newer private stash in v3-claude-2 required supplemental mapping of three commits (two changed, one identical), preserving all non-target tree content and raw commit metadata/messages. Stash reflogs retain all original entries/order/messages with mapped IDs; no extra update-ref entries remain. No private refs were uploaded.

• Verification — passed: per-clone mapped refs and worktree heads, unchanged staged/unstaged patches and untracked hashes, stash count/order/messages, Git config hashes and final ignored-file hashes; git fsck; all retained refs, all stash reflog tips and all registered worktree HEADs contain zero of 424 targeted blobs and zero target path history. Per-clone evidence. The supplementary stash bundle verifies. Local main in this checkout was fast-forwarded from its mapped earlier tip to published main while the audit branch stayed checked out.

• Corrections/limitations: concurrent planning edits and a new branch in another clone caused safe verification stops and fresh snapshots, without overwriting those changes. Initial stash ref update created an extra reflog entry; restored original entries from fresh backup and mapped them before successful checks. An ignored runtime-file hash changed during tests; final stable hashes matched. Initial focused Docs run: 27/28 passed; static publication correctly aborted because this task edited documentation during its snapshot. Stable-document rerun recorded below. No full-suite, new UI, service/deployment or universal-erasure claim.

• Remaining: old objects, non-stash reflogs, stale worktree registrations and all recovery backups remain intentionally available. Cleanup requires its own explicit disposal authorization; host/external retention and maintainer full-removal acceptance remain pending. Renderer Step 1 is resumed separately; no extension approval or implementation inferred. Dependency delta: zero.

• Study checkpoint: existing removal scope v1/R1/P2, Codex single exposed rater, projected total 1.20 reaffirmed. Synchronization is technically verified; original full-removal outcome and acceptance remain incomplete, no retrospective full-outcome score or accepted-count increment.

• Stable verification — passed: static Docs rerun 2/2, including complete inventory publication and on-demand parity. Together with the initial 27/28 (snapshot-change abort classified above), every one of the 28 focused Docs/catalog/static cases passed on a stable snapshot; separate Railspike checks 8/8 and hand-counted metrics fixture passed. All eight stash work/index/untracked trees independently match originals outside the target subtree. Full suite and new table support were not tested or claimed.