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

Debug mode: enabled, inherited from approved Step 3.

Execution state

• Steps 1–3 explicitly approved; branch feature/markdown-renderer-tables, planning commit 073fb5f6a, parent 09e35c538. No branch reuse, publication, deployment or storage disposal.

• Study entry: railspike-effort / v3/markdown_renderer_extension, v1/R1/P2, Codex single exposed rater, original baseline ad7e8f5f; 0.65 total reaffirmed before implementation. Prior snapshots retained; exact R1 sources verified in planning, no new reference or independent rating. Ledger bookkeeping authorized in approved scope; no measured labor or accepted outcome.

• Zero external dependencies or schema/navigation changes; all recovery storage and unrelated work preserved.

Stage 1 - Supported tables in the ordinary reader

• Changes: canonical renderer recognizes standalone pipe table blocks including optional outer pipes; emits column headers, alignment classes and existing inline formatting through the normal Docs route. Invalid widths/delimiters retain escaped source. Saved refreshed intake metrics and continuing-study checkpoints.

• Verification — passed: renderer PHP lint; all 18 PlatformDocsPageTest cases, including cookbook reader, header-only tables, alignment, adjacent prose/fences, source numbering, code byte preservation and existing link safety. Initial run found one stale Table source label assertion; updated it to the supported table region and reran all 18. git diff --check passed.

• Notes: escaped/code pipes, robust empty-cell boundaries and nested/ambiguous exclusion are Stage 2; alignment stylesheet and real keyboard/browser acceptance remain Stage 3. No full-suite/UI/release claim. Planning commit 073fb5f6a; Stage 1 commit recorded in the next stage update.

Stage 2 - Boundary and safety completion

• Changes: structural-pipe splitting protects escaped pipes, slash parity and single-backtick code spans; keeps empty edge/interior cells. Ambiguous spans, unsupported widths and nested/indented table blocks retain whole-block escaped source. Adjacent headings and fenced examples remain separate. Canonical inline/link policy handles all cell content; no fetching or alternative parser. Registered seven focused table regression methods in the explicit PHP test runner.

• Verification — passed: 25/25 reader/table cases; escaped/code pipes, optional outer delimiters, empty cells, slash parity, uneven rows, malformed separators, unsupported code spans, adjacent blocks, nested/list/quote fallback, unsafe HTML/URLs, image alternatives, local fragments and symlink escapes. PHP lint and git diff --check passed. Earlier command selected the new unregistered class but only ran 18 existing tests; registered it and confirmed all seven new methods executed.

• Notes: Stage 1 commit ec3155f37. Conservative fallback includes two-or-more-space indentation and multi-backtick inline spans; no broader inline/list compatibility claim. Visual alignment and scroll/focus remain Stage 3.

Stage 3 - Accessible reader integration

• Changes: reuse canonical table scroll/focus styling; add explicit alignment classes and readable minimum cell widths/normal word wrapping. Browser harness now expects supported tables, checks visible focus and real Tab/ArrowRight scrolling, and exercises an isolated fixture for aligned headers, escaped/code pipes, safe links, image/HTML alternatives and malformed source fallback. Fixture lives under tests and is served only by isolated acceptance packages.

• Verification — passed: 8 dynamic browser scenarios, desktop/390px × default/Word97/Chicago/Midnight, JavaScript disabled, normal Tools→Docs→guide entry, source-numbered procedure steps/code preservation, no page-wide overflow, safe CLI fragment navigation, fixture alignment and readable header dimensions. Browser syntax and whitespace checks passed. Durable measurements: dynamic_browser_evidence.json; fixture/screenshots /tmp/markdown-tables-dynamic-09h84ssg.

• Visual review — passed: all four phone fixture screenshots plus default desktop. Initial screenshots showed long code squeezing neighboring text vertically despite passing overflow assertions; corrected cell sizing/word breaking, strengthened dimension assertions and reran the entire matrix. Recovery/fallback remains visible, no explanatory UI copy added.

• Notes: Stage 2 commit 2eecbf33e. Dynamic local Chromium only; generated-package/browser parity remains Stage 4. No navigation/icon or UI copy cleanup change.

Stage 4 - Portable publication and recovery

• Changes: copied-package acceptance now includes supported tables, malformed fallback and actual safe cell destinations; a temporary fixture reader is deleted before shared refresh. Updated static-reader assertions and added real table-cell link clicks to browser acceptance.

• Verification — passed: 2/2 static Docs tests, including complete inventory/browse snapshots, safe assets, stale reader/download deletion and on-demand boundary. Copied complete dependency-free package on PHP 8.1.2, actual full/shared CLI publication, dynamic/generated table/fallback parity, safe cell destination, stale refresh and deleted reader removal. Injected renderer failure returns 503, hides internal exception detail and leaves existing published release usable; restoring renderer and rebuilding succeeds.

• Verification — passed: 8 generated reader browser scenarios plus 8 static discovery scenarios on desktop/390px × default/Word97/Chicago/Midnight. Reader verifies real cell-link navigation, keyboard scroll/focus, alignment, readable columns, source fallback, procedure/code behavior and no page overflow. Evidence: release_recovery_evidence.json, static_browser_evidence.json, static_discovery_evidence.json; complete fixture /tmp/markdown-release-kzkewh9u. Python/Node syntax and whitespace checks passed.

• Notes: Stage 3 commit 2a3e27046. Source documentation stayed stable throughout inventory snapshots; no concurrent-doc abort. No production release was activated. Full-suite/live deployment/physical devices remain unverified; final corpus classification and visual acceptance are Stage 5.

Stage 5 - Corpus and theme acceptance

• Changes: frozen/current compact render reports with per-document hashes/tags/errors, classification of all 66 original table documents and a human-readable acceptance report; updated renderer runbook boundaries. Added an orphan-row regression after corpus inspection found two headerless rows separated by blank lines; source remains readable without extending table semantics.

• Verification — passed: all 1,402 frozen source hashes match and render without errors; 1,405 refreshed tracked documents at 483ec05bb render without errors. Original 117 separator candidates resolve to 116 tables plus one nested/list source fallback. Classification: 64 supported documents, one mixed (supported table plus two orphan source rows), one source-only nested table. Every emitted table has matching semantic header/body widths; fallback strings match original source. All 66 classified structurally; individual visual review is representative, not exhaustive.

• Verification — passed: final 34/34 catalog/reader/table cases, followed by 8/8 table cases after adding the orphan-row regression; combined with Stage 4 static tests, 37 distinct focused PHP cases pass. Metrics fixture passed. Final dynamic browser matrix 8/8, now including actual table-cell clicks; combined dynamic/static/discovery matrix has 24 distinct scenarios. Inspected phone fallback/table screenshots in all four themes and desktop theme examples; all relevant measurements and sources are indexed in table_render_acceptance.md. Syntax/whitespace and approved dependency inventory checks passed.

• Notes: Stage 4 commit 483ec05bb; renderer/CSS did not change after the complete package/recovery tests. Final browser fixture /tmp/markdown-tables-dynamic-l5nks7ol; generated fixture /tmp/markdown-release-kzkewh9u. Source documentation was stable during static builds. No full suite, physical-device, live deployment, merge/push or historical-storage disposal. Nested/loose lists, task presentation, broader inline syntax and rare variants keep the approved existing safe behavior; no permanent omission decision inferred.

Study closeout and handoff

• Stable cycle v3/markdown_renderer_extension, scope v1 clarified, R1/P2, Codex single exposed rater; original baseline ad7e8f5f, implementation parent 09e35c538. Planning 073fb5f6a; completed Stages 1–4 ec3155f37, 2eecbf33e, 2a3e27046, 483ec05bb; Stage 5 commit follows this summary. Five planned/five completed stages; no scope split or new feature request. Corrections: stale label assertion, explicit test registration, long-code column squeeze, and orphan-source classification; no deferred implementation within the accepted table boundary.

• Projected total 0.65 preserved/reaffirmed; separate retrospective scope assessment 0.70, reflecting parser boundary/security cases, corrected presentation and corpus classification alongside complete package/recovery evidence. R1 sources and exposed rater unchanged; no measured labor or independent rating. Maintainer comfortable-fit judgment and acceptance pending; accepted count unchanged. Parent dependency/history removal remains incomplete because retained recovery storage and external retention are separate.

• Dependency delta: zero external additions/upgrades/copied sources; package manifests/locks and third-party tree unchanged. No schema/nav changes. Working clone, local publication audit and recovery backups remain preserved. Technically complete local handoff; no claim of production activation or full-suite pass.

Merge handoff and follow-up — 2026-10-23T14:22:42.464645+00:00

• Request: “Looks great, you can merge this and move to the next step. Please note somewhere that at some point we want to unconstrain docs from a narrow column, as this will make tables more accessible (less likely to have horizontal scrolling).”

• Disposition: delivered table slice accepted for merge; preserve all stage commits and local publication/clone-sync audits. User acceptance concerns the delivered result; a separate study comfortable-fit judgment remains unknown.

• Deferred follow-up: relax the Docs reader's narrow-column constraint so wider screens can show more table columns and reduce horizontal scrolling. Keep responsive containment and keyboard scrolling for genuinely wide tables. Record this for later layout work; no layout expansion is included in this merge.

• Next work: a fresh Step 1 assessment for the previously deferred list-structure gap, using existing refreshed metrics; independent approvals apply. Historical dependency-removal storage disposal remains outside this work.