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

Debug mode: enabled

Completion Contract

Ordinary Docs discovery/direct URLs deliver correctly owned list items/paragraphs, literal ordered numbers and safe links in PHP and copied full/shared releases. Unsupported blocks retain keyboard-readable source, neighboring content and existing safety. Require phone/theme acceptance, corpus evidence and successful publication-failure retention/restoration/retry. No live deployment, external acceptance, wider-layout change or recovery-storage disposal; report unverified boundaries explicitly.

Key Risks

• High risk: wrong ownership changes instructions; validate real multiline steps and nested bullets first, stop dependent stages until boundary fixtures pass.

• High risk: fallback swallows adjacent content or exposes comments; test embedded fences/tables/quotes and comment safety before browser/delivery work, preserve source within approved safety boundaries.

• High risk: nesting hides links or failed publication retires usable readers; validate deep phone fixtures and actual failure/retry, retain local overflow containment and active-release recovery.

Stage 1 — Paragraph ownership and numbering

• Goal: keep flat procedures and loose paragraphs together.

• Dependencies: Step 3 approval; fresh branch and planning commit.

• Expected changes: canonical list-block boundaries, content-column continuations, blank paragraphs, sibling marker changes and literal ordered numbers; preserve existing renderer signature.

• Verification approach: ordinary retraction guide; repeated/gapped/restarted numbers, wrapped/loose paragraphs and standalone following prose/headings.

• Risks or open questions: misattached prose; test dedent/blank boundaries first, reject uncertain ownership.

• Canonical components/API contracts touched: PublicMarkdownRenderer, existing reader regression assertions.

Stage 2 — Nested list relationships

• Goal: retain mixed parent/child items through eight levels.

• Dependencies: Stage 1 verified and committed.

• Expected changes: established marker columns, child content alignment, sibling/dedent ownership and nested type changes.

• Verification approach: account-key plan risk bullets and mixed ordered/unordered fixtures; assert semantic ancestry, paragraphs and numbers.

• Risks or open questions: wrong parent on dedent; validate uneven marker widths early, retain uncertain blocks as source.

• Canonical components/API contracts touched: canonical list rendering and focused list tests registered in tests/run.php.

Stage 3 — Unsupported-block recovery and safety

• Goal: preserve unsupported lists without corrupting adjacent content.

• Dependencies: Stage 2 verified and committed.

• Expected changes: whole-block escaped-source recovery for tabs, ambiguous indentation, over-limit nesting and embedded tables/quotes/fenced/indented code; preserve prose-comment and metadata rules.

• Verification approach: source preservation/code bytes, standalone following tables/fences, hostile HTML/URLs, symlink/traversal boundaries, image alternatives and literal task markers.

• Risks or open questions: fallback extent or safety changes; adversarial fixtures block dependents until content/boundary policy passes.

• Canonical components/API contracts touched: renderer, existing catalog inline/link policy and table regressions.

Stage 4 — Accessible ordinary reader

• Goal: read nesting, follow links and reach fallback content.

• Dependencies: Stage 3 verified and committed.

• Expected changes: reuse list/reader styles and browser harness; replace obsolete six-separate-list assertions with semantic six-step/paragraph assertions.

• Verification approach: Tools→Docs→guide and nested fixture; JavaScript-off desktop/390px × default/Word97/Chicago/Midnight, real Tab/link/scroll/focus, eight-level/over-limit content and standalone table behavior.

• Risks or open questions: deep indentation hides text; inspect loaded screenshots and overflow early, contain fallback scrolling without widening Docs.

• Canonical components/API contracts touched: reader template/styles as needed and existing browser harness.

Stage 5 — Portable publication and recovery

• Goal: ship the same list outcome through normal releases.

• Dependencies: Stage 4 verified and committed.

• Expected changes: copied-package/static assertions and durable delivery evidence.

• Verification approach: full/shared publication, dynamic/static list/fallback/link parity, stale/deleted-reader refresh, injected renderer failure/503, retained active release and restoration/retry; generated theme/keyboard matrix.

• Risks or open questions: partial publication or stale readers; exercise actual CLI/FrontController delivery with source docs stable during snapshots.

• Canonical components/API contracts touched: existing controller/static builder, publication tests and recovery harness.

Stage 6 — Corpus acceptance and closeout

• Goal: substantiate the supported/fallback boundary.

• Dependencies: Stage 5 verified and committed.

• Expected changes: refreshed/frozen corpus reports, structural supported/fallback classifications, runbook and cycle/ledger closeout.

• Verification approach: metrics fixture, zero-error renders with frozen source hashes; focused Docs/list/table/catalog checks; classify measured nested-list documents, inspect representative guide/theme output, record unsupported forms and visual-review limits.

• Risks or open questions: candidates conceal wrong structure; assert semantic parent/paragraph ownership and source preservation, not render counts alone.

• Canonical components/API contracts touched: existing metrics/probe, runbook, cycle artifacts and study ledger.

Execution and study checkpoint

Six stages target ≤1 hour each; split oversized work before starting, return to Step 2 for changed scope. After approval create a fresh list-feature branch from synchronized main; organize this cycle, commit approved Steps 1–3/debug log and necessary reference/index fixes first, then each verified stage with its summary before advancing. Substantive ledger/evidence belongs in stage commits. No new dependencies, schema/navigation changes or todo.txt edits; preserve recovery backups.

Steps 1–3 explicitly approved; implementation authorized. Stable v3/markdown_list_structure, v1/R1/P2, baseline b9d1cc874, same exposed single rater; 0.90 total reaffirmed, including corpus/theme and recovery work. Checkpoint/diagnostics. No implementation or accepted outcome.