doc3gpp 0.2.1__tar.gz → 0.3.2__tar.gz

doc3gpp-0.3.2/.superpowers/sdd/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

doc3gpp-0.3.2/.superpowers/sdd/2026-09-24-spec-doc-metadata-and-portal-fix/final-fix-report.md

@@ -0,0 +1,179 @@
+# Final Review Fix Report
+
+## Status
+
+Implemented and committed as `c37f292` (`fix(spec-doc): close final metadata review gaps`).
+
+The approved untracked implementation plan,
+`docs/superpowers/plans/2026-09-24-spec-doc-metadata-and-portal-fix.md`, was not
+modified or staged. Pre-existing worktree changes outside this final fix wave
+were also left untouched.
+
+## Findings Addressed
+
+### FTS5 nullable metadata
+
+`SQLAlchemySpecDocSearchRepository.upsert_for_version()` now preserves
+`None` for nullable `sections` and `tables` instead of converting them to empty
+strings. FTS5 `null` and `not-null` predicates therefore match the relational
+chunk contract.
+
+Added explicit integration coverage for both fields and all related rich-filter
+branches:
+
+- `null`
+- `not-null`
+- positive LIKE
+- negated `!pattern`
+- simultaneous `sections` and `tables` filters with AND semantics
+
+### Overlap metadata scope
+
+`chunk_blocks()` now tracks metadata at source-token granularity. When overlap
+tokens are prepended, only metadata attached to the trailing token range is
+merged into the following chunk. Ordered deduplication and current-chunk
+metadata remain unchanged.
+
+Regression coverage includes:
+
+- a previous chunk with earlier and later section metadata where only the later
+  section overlaps;
+- the equivalent table-overlap case;
+- repeated section/table metadata deduplication.
+
+Existing atomic-table, chunk-boundary, character-ceiling, file-tag, and empty
+metadata behavior remains covered.
+
+### Stable stale-only rebuild cutoff
+
+`rebuild_batch(stale_only=True)` captures `last_indexed_parsed_at` once before
+iterating batches and binds that stable cutoff for every page. Per-version
+`upsert_for_version()` watermark updates can no longer remove older stale rows
+from later pages.
+
+The regression seeds two stale versions and rebuilds with `batch_size=1`; both
+versions must be indexed.
+
+### Configured cache path expansion
+
+`SpecDocSettings.cache_dir` now applies `Path.expanduser()` after Pydantic
+validation. TOML-style `~/.cache/doc3gpp/specs` values resolve under the user
+home, while absolute explicit paths and the absolute default remain unchanged.
+
+### Contract coverage
+
+The final wave pins:
+
+- exact `_SPEC_DOC_SNIPPET_COLUMNS` ordering;
+- removal of all split chunk/hit/filter DTO fields;
+- nullable FTS metadata behavior;
+- complete rich-filter semantics for both combined metadata fields;
+- overlap deduplication and table overlap;
+- configured cache path behavior.
+
+### Vector-side `release` semantics
+
+The existing semantic implementation intentionally uses exact equality for
+vector-side `spec_id`, `version`, and `release`, while vector-side `sections`
+and `tables` use plain LIKE. The FTS side remains the rich-filter path.
+
+This is now explicit and consistent in:
+
+- `src/doc3gpp/storage/repositories/spec_doc_vector_sql.py`;
+- `src/doc3gpp/services/spec_doc_semantic_service.py`;
+- `docs/architecture.md`;
+- `docs/cli.md`;
+- `AGENTS.md`.
+
+An optional sqlite-vec regression asserts that `release="Rel-18"` matches and
+`release="Rel-1%"` does not, preserving the intentional exact contract.
+
+## TDD Evidence
+
+The new regression tests were written before production changes.
+
+Initial red run:
+
+```text
+rtk pytest tests/unit/test_spec_doc_models.py tests/unit/test_spec_doc_settings.py tests/unit/test_spec_doc_chunker.py tests/integration/test_spec_doc_search_repo.py -q
+Pytest: 33 passed, 7 failed
+```
+
+The failures were the expected reviewer defects:
+
+- configured `~` cache path stayed literal;
+- section overlap copied the earlier metadata;
+- table overlap copied the earlier metadata;
+- nullable FTS filters returned no matching rows;
+- stale-only batch size 1 indexed only one of two stale versions.
+
+Green focused run after the minimal fixes:
+
+```text
+rtk pytest tests/unit/test_spec_doc_models.py tests/unit/test_spec_doc_settings.py tests/unit/test_spec_doc_chunker.py tests/integration/test_spec_doc_search_repo.py -q
+40 passed
+```
+
+The covering spec-document/web/MCP run then passed:
+
+```text
+rtk pytest tests/unit/test_spec_doc_*.py tests/integration/test_spec_doc_*.py tests/unit/test_web_routes.py tests/integration/test_mcp_end_to_end.py -q
+330 passed
+```
+
+## Verification
+
+Full offline SQLite suite:
+
+```text
+rtk ./scripts/test_sqlite.sh
+2405 passed, 1 skipped, 109 warnings in 103.45s
+```
+
+The skip is the existing optional-dependency skip. Existing collection and
+datetime deprecation warnings remain; the stale-rebuild path also exercises the
+project's existing `datetime.utcnow()` warning in
+`spec_doc_search_service.py`.
+
+Lint:
+
+```text
+rtk ruff check .
+clean, exit 0
+```
+
+Whitespace:
+
+```text
+rtk git diff --check
+clean, exit 0
+```
+
+The focused fix files also passed their targeted Ruff check before the full
+gate.
+
+## Files In Commit
+
+- `AGENTS.md`
+- `docs/architecture.md`
+- `docs/cli.md`
+- `src/doc3gpp/parsers/spec_doc_chunker.py`
+- `src/doc3gpp/settings/schema.py`
+- `src/doc3gpp/storage/repositories/spec_doc_search_sql.py`
+- `tests/integration/test_spec_doc_search_repo.py`
+- `tests/unit/test_spec_doc_chunker.py`
+- `tests/unit/test_spec_doc_models.py`
+- `tests/unit/test_spec_doc_settings.py`
+
+No migration, public repair command, unrelated TDoc behavior, or generated
+artifact was added.
+
+## Concerns
+
+- Vector-side semantic behavior was not changed from exact `release` matching;
+  the docs now state that contract instead of claiming release LIKE behavior.
+- sqlite-vec-specific assertions are skipped when the optional extension is not
+  installed; the core FTS, chunker, cache, and stale-rebuild coverage is
+  extension-independent.
+- The repository retains its pre-existing warning set, including UTC datetime
+  deprecations.

doc3gpp-0.3.2/.superpowers/sdd/2026-09-24-spec-doc-metadata-and-portal-fix/task-2-report.md

@@ -0,0 +1,129 @@
+# Task 2 Report
+
+## Status
+
+DONE_WITH_CONCERNS
+
+## Files Changed
+
+- `src/doc3gpp/parsers/docx_converter.py`
+  - Recognizes alphanumeric section identifiers such as `7.2A.3` and `7.2A.3A`.
+  - Recognizes table captions with 3GPP identifiers and colon, dash, or whitespace separators.
+  - Collapses caption whitespace while retaining caption paragraphs in the block stream.
+- `src/doc3gpp/parsers/spec_doc.py`
+  - Adds a natural section sort key that compares numeric tokens numerically and alphabetic tokens case-insensitively.
+  - Preserves front-matter and unnumbered-file ordering rules.
+- `tests/unit/test_spec_doc_blocks.py`
+  - Adds real in-memory `python-docx` tests for alphanumeric headings and table captions.
+- `tests/unit/test_spec_doc_parser.py`
+  - Adds alphanumeric file-ordering and TOC preservation tests.
+
+No chunker, ORM, search, web, or unrelated files were modified. `HeadingBlock.section_no`, `TableBlock.table_no/table_title`, and TOC split fields remain unchanged.
+
+## TDD Verification
+
+### Red
+
+Command:
+
+```bash
+rtk pytest tests/unit/test_spec_doc_blocks.py tests/unit/test_spec_doc_parser.py -v
+```
+
+Result: `10 passed, 3 failed`.
+
+The three expected failures were:
+
+- `test_heading_accepts_alphanumeric_section_suffixes`: the numeric-only section regex returned `None`.
+- `test_table_caption_accepts_3gpp_identifier_and_separator`: the numeric-only caption regex returned no table number.
+- `test_order_numbered_files_handles_alphanumeric_sections`: the numeric-only `_first_section` path could not order the alphanumeric section.
+
+### Green
+
+Command:
+
+```bash
+rtk pytest tests/unit/test_spec_doc_blocks.py tests/unit/test_spec_doc_parser.py -v
+```
+
+Result: `13 passed`.
+
+Additional checks:
+
+- `rtk ruff check src/doc3gpp/parsers/docx_converter.py src/doc3gpp/parsers/spec_doc.py tests/unit/test_spec_doc_blocks.py tests/unit/test_spec_doc_parser.py`: no findings.
+- `rtk git diff HEAD^ HEAD --check`: clean.
+
+The broader command `rtk pytest tests/unit/test_spec_doc_*.py -v` reports `34 passed, 5 failed`. The five failures are existing Task 3 chunker failures caused by the Task 1 `ChunkDraft` contract change before the chunker has been updated; they are outside this task and were not changed.
+
+## Commit
+
+- Hash: `b00a2eb`
+- Message: `fix(spec-doc): recognize alphanumeric sections and tables`
+
+## Self-Review Findings
+
+- No Task 2 defects found in the focused review.
+- The heading regex requires an identifier to start with a digit, permits alphanumeric dotted components, and still requires following whitespace.
+- Caption parsing supports the requested identifier and separator forms, normalizes whitespace, and leaves caption paragraphs as `ParagraphBlock` entries.
+- Natural sorting uses token types that are safe to compare in Python tuple ordering and keeps numeric section ordering natural (`7.2` before `7.10`).
+- Existing numeric-section, front-matter, unnumbered-file, and TOC tests remain green.
+- The commit contains only the four files specified by the Task 2 brief.
+
+## Concerns
+
+- The full spec-document unit-test glob is not green until the planned Task 3 chunker implementation updates its constructors and metadata handling for the Task 1 DTO contract. This was intentionally left untouched to preserve Task 2 scope.
+- The approved plan file `docs/superpowers/plans/2026-09-24-spec-doc-metadata-and-portal-fix.md` remains pre-existing and untracked; it was not added to the Task 2 commit.
+
+## Fix Round: Alphanumeric Hyphenated Table Suffixes
+
+### Finding Addressed
+
+The table-caption identifier grammar previously allowed only numeric suffixes after
+the hyphen. It split identifiers such as `4.4.2-1A` and `4.6.1-4.0A` before the
+suffix. The grammar now permits alphanumeric and dotted components after the
+hyphen, while retaining the existing base identifier rules.
+
+The real in-memory DOCX regression coverage now parameterizes colon, dash, and
+whitespace separators for table captions, covers both reviewed identifiers, and
+asserts that the caption remains a `ParagraphBlock` in the block stream.
+
+### TDD Verification
+
+Red command:
+
+```bash
+rtk pytest tests/unit/test_spec_doc_blocks.py tests/unit/test_spec_doc_parser.py -v
+```
+
+Result: `13 passed, 2 failed`. The two new hyphenated-suffix cases failed with
+the old numeric-only suffix grammar; for example, `4.4.2-1A` was parsed as
+`4.4.2`.
+
+Green command:
+
+```bash
+rtk pytest tests/unit/test_spec_doc_blocks.py tests/unit/test_spec_doc_parser.py -v
+```
+
+Result: `15 passed`.
+
+Targeted lint:
+
+```bash
+rtk ruff check src/doc3gpp/parsers/docx_converter.py src/doc3gpp/parsers/spec_doc.py tests/unit/test_spec_doc_blocks.py tests/unit/test_spec_doc_parser.py
+```
+
+Result: no findings.
+
+### Fix Commit
+
+- Hash: `1836c50`
+- Message: `fix(spec-doc): accept alphanumeric table suffixes`
+
+### Remaining Concerns
+
+- The broader `rtk pytest tests/unit/test_spec_doc_*.py -v` scope still has the
+  previously recorded five Task 3 chunker failures caused by the Task 1 DTO
+  contract; no unrelated chunker changes were made in this fix round.
+- The pre-existing untracked plan file remains untracked and was not included in
+  either fix commit.

doc3gpp-0.3.2/.superpowers/sdd/2026-09-24-spec-doc-web-portal/final-fix-report.md

@@ -0,0 +1,255 @@
+# Final Review Fix Report
+
+## Context
+
+This fix wave addresses the final review findings for the spec-document web
+portal branch at `9e44230`. The pre-existing untracked approved plan,
+`docs/superpowers/plans/2026-09-24-spec-doc-web-portal.md`, was not modified or
+staged.
+
+## Files Changed
+
+- `src/doc3gpp/storage/repositories/spec_doc_sql.py`
+  - Removed the `parsed_at` and `chunk_count` success-state mutation from
+    `replace_chunks()`.
+  - `record_parsed()` is now the only repository operation that marks a source
+    parsed or records its final chunk count.
+- `tests/integration/test_spec_doc_service.py`
+  - Added a regression test that fails the markdown-cache write after chunks
+    are stored, verifies `parsed_at` remains unset, and verifies a subsequent
+    non-force parse succeeds rather than being skipped.
+- `tests/integration/test_spec_doc_repo.py`
+  - Updated the repository round-trip to assert that chunk replacement alone
+    leaves the source unparsed, then explicitly records the successful parse.
+  - Added coverage that direct chunk replacement still creates an explicitly
+    unparsed source row when no source row exists.
+- `src/doc3gpp/web/templates/spec_doc_show.html`
+  - Hides the force checkbox unless the source is parsed.
+  - Adds an explicit parsed-state data attribute for defensive client logic.
+- `src/doc3gpp/web/static/js/spec_doc_parse.js`
+  - Forces the submitted `force` value to `false` unless the form declares a
+    parsed source, even if a stale or injected checkbox is present.
+- `src/doc3gpp/web/templates/partials/spec_doc_show_results.html`
+  - Renders the stored TOC file summary, including source filename, file order,
+    and first section.
+- `src/doc3gpp/web/templates/partials/spec_doc_chunks.html`
+  - Distinguishes a parsed zero-chunk source from a non-matching section
+    filter.
+- `tests/unit/test_web_routes.py`
+  - Covers force-control availability for unparsed and parsed states, the TOC
+    file summary, the zero-chunk message, and the JS parsed-state guard.
+- `docs/web-server.md`
+  - Clarifies that the endpoint accepts optional `release`, while the version
+    page form submits `spec_ids`, the selected exact `version`, and `force`
+    without a release selector.
+
+## Tests And Commands
+
+- `rtk pytest tests/integration/test_spec_doc_service.py -k post_chunk_cache_failure -q`
+  - Initial TDD red run: failed because `replace_chunks()` had already set
+    `parsed_at`; this confirmed the regression exercised the reported bug.
+- `rtk pytest tests/integration/test_spec_doc_service.py tests/integration/test_spec_doc_repo.py -q`
+  - `10 passed`.
+- `rtk pytest tests/unit/test_web_routes.py -k 'spec_doc_show or spec_doc_parse_js' -q`
+  - `8 passed`.
+- `rtk pytest tests/unit/test_spec_doc_service_reads.py tests/unit/test_spec_doc_source.py tests/integration/test_spec_doc_service.py tests/integration/test_spec_doc_repo.py tests/integration/test_spec_doc_search_repo.py tests/integration/test_spec_doc_search_service.py tests/integration/test_spec_doc_web.py tests/unit/test_web_routes.py tests/unit/web/test_landing_version.py -q`
+  - `225 passed`.
+- `rtk pytest tests/integration/test_spec_doc_cli.py tests/unit/test_spec_doc_settings.py tests/unit/test_spec_doc_models.py tests/unit/test_spec_doc_parser.py tests/unit/test_spec_doc_chunker.py -q`
+  - `23 passed`.
+- `rtk ./scripts/test_sqlite.sh`
+  - `2356 passed, 1 skipped, 108 warnings`.
+  - Warnings are the repository's existing pytest collection and deprecation
+    warnings; no test failures occurred.
+- `rtk ruff check .`
+  - Clean.
+- `rtk git diff --check`
+  - Clean.
+
+## Self-Review
+
+- A failed parse after chunk replacement and before markdown-cache completion
+  no longer creates a false successful parse marker. The retry path uses the
+  existing ZIP cache and reaches `record_parsed()` normally.
+- Existing force re-parse behavior remains available for parsed sources. The
+  browser checkbox is absent for unparsed/downloaded sources, and the client
+  independently clamps `force` to `false` in that state.
+- The version page's TOC now includes the complete stored file summary using
+  the same fields as the existing standalone TOC page.
+- A parsed source with `chunk_count == 0` gets an incomplete/corrupt/zero-chunk
+  message. A parsed source with chunks but no rows after filtering retains the
+  filter-empty message.
+- The documentation now separates endpoint query support from the form's
+  exact-version job payload.
+- No CLI, MCP, JSON, schema, or job contract was changed.
+- No direct semantic nested-hit route test was added; this remains the
+  explicitly accepted test-only residual from the prior review.
+
+## Concerns
+
+- TOC persistence, chunk replacement, filesystem cache writes, and the parsed
+  ledger remain separate operations because the existing repository architecture
+  does not provide one cross-storage transaction. A failed attempt can leave
+  intermediate TOC/chunk/cache data, but `parsed_at` remains unset and the
+  next parse replaces those intermediates before recording success.
+- The full suite retains the existing 108 warnings noted above; they are not
+  introduced by this fix wave.
+
+## Fix Round 2
+
+### Finding Addressed
+
+A forced re-parse of an already parsed version could leave the old non-null
+`parsed_at` marker in place when post-chunk/cache work failed. A later
+non-force parse then treated the failed re-parse as an immutable success and
+skipped it.
+
+### Files Changed
+
+- `src/doc3gpp/storage/repositories/spec_doc_sql.py`
+  - `record_download()` now clears `parsed_at` and resets `chunk_count` when
+    refreshing an existing source row. This invalidates the previous success
+    marker at the force-download boundary while preserving the existing method
+    signature and repository flow.
+- `tests/integration/test_spec_doc_service.py`
+  - Added coverage that parses a version successfully, forces a re-parse that
+    fails during markdown-cache writing, verifies the old marker is cleared,
+    and verifies a subsequent non-force parse succeeds.
+- `.superpowers/sdd/2026-09-24-spec-doc-web-portal/final-fix-report.md`
+  - Appended this fix-round record. The approved untracked plan remains
+    untouched and unstaged.
+
+### Tests And Commands
+
+- `rtk pytest tests/integration/test_spec_doc_service.py -k 'failed_force_reparse_invalidates_old_marker_for_retry or post_chunk_cache_failure or force_reparses' -q`
+  - `3 passed`.
+- `rtk pytest tests/integration/test_spec_doc_repo.py -q`
+  - `2 passed`.
+- `rtk pytest tests/integration/test_spec_doc_service.py tests/integration/test_spec_doc_repo.py tests/integration/test_spec_doc_search_repo.py tests/integration/test_spec_doc_search_service.py tests/integration/test_spec_doc_web.py tests/unit/test_spec_doc_service_reads.py tests/unit/test_web_routes.py tests/unit/web/test_landing_version.py -q`
+  - `220 passed`.
+- `rtk ./scripts/test_sqlite.sh`
+  - `2357 passed, 1 skipped, 108 warnings`.
+- `rtk ruff check .`
+  - Clean.
+- `rtk git diff --check`
+  - Clean.
+
+### Self-Review
+
+- A successful force re-parse still reaches `record_parsed()` and restores a
+  non-null marker with the new chunk count.
+- A non-force immutable skip does not call `record_download()` when the ZIP
+  cache and parsed source already exist, so existing skip behavior is
+  unchanged.
+- If a forced download or a cache-miss download replaces an existing source,
+  its previous success marker is invalidated before parse work begins; any
+  later failure therefore remains retryable.
+- `record_parsed()` remains the only operation that marks a source as
+  successfully parsed.
+- The fix changes no schema, service signature, CLI, HTTP, MCP, or job
+  contract.
+
+### Concerns
+
+- As in the first fix round, TOC/chunk/cache writes and the source ledger use
+  separate repository/filesystem transactions. A failed force re-parse may
+  leave intermediate replacement data, but the source remains unparsed and a
+  subsequent retry replaces those intermediates before recording success.
+- The full suite retains the existing 108 warnings; no new warning category
+  was introduced by this round.
+
+## Fix Round 3
+
+### Finding Addressed
+
+The round-2 placement was still too late for a forced network failure:
+`SpecDocService.fetch(force=True)` called `_fetcher()` before
+`record_download()`, so a failed download left an already parsed source's old
+`parsed_at` marker intact. The final fix invalidates parse state before the
+forced fetch, without recording a download that did not succeed.
+
+### TDD Failing-Test Evidence
+
+Added `test_failed_force_download_invalidates_old_marker_for_retry` to
+`tests/integration/test_spec_doc_service.py`. The first focused run was:
+
+```text
+rtk pytest tests/integration/test_spec_doc_service.py -k failed_force_download_invalidates_old_marker_for_retry -q
+Pytest: 0 passed, 1 failed
+AssertionError: source.parsed_at is None
+```
+
+The failure reproduced the confirmed root cause: the source remained parsed
+after the forced `_fetcher()` raised `OSError("upstream unavailable")`.
+
+### Files Changed
+
+- `src/doc3gpp/repository/protocols.py`
+  - Added the clearly named `SpecDocRepository.invalidate_parse_state()`
+    operation.
+- `src/doc3gpp/storage/repositories/spec_doc_sql.py`
+  - Implemented `invalidate_parse_state()` as a committed update of only
+    `parsed_at` and `chunk_count` for an existing source row.
+  - Kept `record_download()` responsible for successful-download metadata;
+    it no longer doubles as parse-state invalidation.
+- `src/doc3gpp/services/spec_doc_service.py`
+  - On `force=True`, resolves the existing source and invalidates its parse
+    state before invoking `_fetcher()`.
+  - Does nothing for a missing source, preserving the first-download path.
+- `tests/integration/test_spec_doc_service.py`
+  - Added the required already-parsed, forced-network-failure, then
+    non-force-retry regression.
+- `tests/integration/test_spec_doc_repo.py`
+  - Verifies explicit invalidation clears only parse state while preserving
+    release, FTP URL, download timestamp, and DOCX count.
+- `.superpowers/sdd/2026-09-24-spec-doc-web-portal/final-fix-report.md`
+  - Appended this round-3 record. The approved untracked plan remains
+    untouched and unstaged.
+
+### Tests And Commands
+
+- `rtk pytest tests/integration/test_spec_doc_service.py -k failed_force_download_invalidates_old_marker_for_retry -q`
+  - Initial TDD red run: `0 passed, 1 failed`, with the expected stale
+    `parsed_at` assertion failure.
+- `rtk pytest tests/integration/test_spec_doc_service.py -k 'failed_force_download_invalidates_old_marker_for_retry or failed_force_reparse_invalidates_old_marker_for_retry or post_chunk_cache_failure or force_reparses' -q`
+  - `4 passed` after the fix.
+- `rtk pytest tests/integration/test_spec_doc_repo.py -q`
+  - `2 passed`.
+- `rtk pytest tests/integration/test_spec_doc_service.py tests/integration/test_spec_doc_repo.py tests/integration/test_spec_doc_search_repo.py tests/integration/test_spec_doc_search_service.py tests/integration/test_spec_doc_web.py tests/unit/test_spec_doc_service_reads.py tests/unit/test_web_routes.py tests/unit/web/test_landing_version.py -q`
+  - `221 passed`.
+- `rtk ./scripts/test_sqlite.sh`
+  - `2358 passed, 1 skipped, 108 warnings`.
+- `rtk ruff check .`
+  - Clean.
+- `rtk git diff --check`
+  - Clean.
+
+### Self-Review
+
+- A forced re-parse with an existing source clears the success marker before
+  any network, ZIP-size, cache-write, or parse operation can fail.
+- The invalidation operation preserves truthful download metadata and does not
+  create a source row or claim that a forced download succeeded.
+- Successful force re-parse still runs `record_download()` after bytes arrive,
+  then `record_parsed()` after all required parse/cache work completes.
+- A non-force immutable skip does not call the invalidation operation because
+  it returns through the existing cache/parsed check without entering the
+  forced path.
+- First-parse failures and the prior post-chunk/cache failure regression remain
+  covered and retryable.
+- The round-2 reset inside `record_download()` was removed; round 3 replaces
+  that late invalidation with the explicit pre-fetch operation requested by the
+  review.
+- No web portal behavior, schema, job payload, CLI contract, or public service
+  signature changed.
+
+### Concerns
+
+- Parse-state invalidation and the later network/cache/parse work remain
+  separate transactions under the existing repository architecture. After a
+  forced network failure, prior download metadata and cached bytes remain, but
+  `parsed_at` is intentionally null so the source is not treated as a
+  successful parse and the next non-force run retries.
+- A failure after TOC/chunk replacement can still leave intermediate data; the
+  existing retry path replaces it before `record_parsed()` marks success.
+- The full suite retains the existing 108 warnings; no new warning category
+  was introduced by this round.

doc3gpp-0.3.2/.superpowers/sdd/2026-09-24-spec-doc-web-portal/task-2-report.md

@@ -0,0 +1,62 @@
+# Task 2 Report: Add Spec Document Version Read Page
+
+## Files Changed
+
+- `src/doc3gpp/web/routes/spec_docs.py`
+  - Added `GET /specs/{spec_id}/docs` before the existing TOC route.
+  - Resolves the parent spec and exact requested version through the injected `SpecService`.
+  - Reads source, TOC, and chunks only through `SpecDocService.get_source`, `get_toc`, and `list_chunks`.
+  - Supports release/section filters, bounded chunk pagination, one-row probe fetching, and HTMX `#results` fragments.
+  - Preserves the existing error mapping for missing specs, missing versions, disabled spec-doc services, and invalid query values.
+- `src/doc3gpp/web/templates/spec_doc_show.html`
+  - Added the full version document page with spec/version identity, parent-spec link, source links, and metadata.
+- `src/doc3gpp/web/templates/partials/spec_doc_show_results.html`
+  - Added the `#results` fragment with source state, parsed metadata, TOC, and chunk composition.
+- `src/doc3gpp/web/templates/partials/spec_doc_chunks.html`
+  - Added chunk cards, section/table metadata, source filenames, preformatted text, and filter-preserving pagination.
+- `src/doc3gpp/web/static/style.css`
+  - Added responsive source/chunk page styles while reusing existing portal primitives.
+- `tests/unit/test_web_routes.py`
+  - Added fake public spec-document service data and focused tests for unparsed state, parsed TOC/chunks, probe pagination, HTMX fragments, and unknown versions.
+- `.superpowers/sdd/2026-09-24-spec-doc-web-portal/task-2-report.md`
+  - Added this report.
+
+The pre-existing untracked `docs/superpowers/plans/2026-09-24-spec-doc-web-portal.md` was not modified or staged.
+
+## Tests And Commands
+
+- `rtk pytest tests/unit/test_web_routes.py -k "spec_doc_show" -q`
+  - Initial TDD red run: `0 passed, 5 failed`; the expected failure was HTTP 404 because the new route did not yet exist.
+- `rtk pytest tests/unit/test_web_routes.py -k "spec_doc_show" -q`
+  - Final result: `5 passed`.
+- `rtk pytest tests/integration/test_spec_doc_web.py -q`
+  - Final result: `3 passed`.
+- `rtk pytest tests/unit/test_web_routes.py -q`
+  - Final result: `178 passed`.
+- `rtk ruff check src/doc3gpp/web/routes/spec_docs.py tests/unit/test_web_routes.py`
+  - Final result: clean (`[]`).
+- `rtk git diff --check`
+  - Final result: clean.
+- `rtk pytest`
+  - Collection did not start because three existing integration/unit modules import `tests.integration.test_web_end_to_end` and the plain executable entry point did not expose the repository root as the `tests` package (`3 ModuleNotFoundError` collection errors).
+- `rtk python -m pytest -q`
+  - Final result: `2346 passed, 1 skipped, 10 deselected, 18 warnings` in `401.75s`.
+- `rtk grep '_doc_repo|fetch|parse form|spec-doc-parse-form|jobs/parse' src/doc3gpp/web/routes/spec_docs.py`
+  - Final result: no route/private-repository/fetch/parse-control matches.
+
+## Self-Review
+
+- The route is registered before `/specs/{spec_id}/docs/toc`, so the static TOC path remains reachable.
+- Exact version identity is verified after `SpecService.list_versions(..., version=version)`; unknown versions include available version strings in the normal 404 envelope.
+- `parsed_at` is the authoritative gate: unparsed or missing source rows do not trigger TOC/chunk reads.
+- A missing TOC for an otherwise parsed source is treated as absent while chunks continue to render, as required.
+- Pagination requests `limit + 1`, renders only `limit`, and preserves `version`, `release`, and `section` in next/previous links.
+- HTMX responses render only `partials/spec_doc_show_results.html` with the required outer `#results` element.
+- No JSON contract, storage schema, CLI, MCP, fetch route, version-table link, or synchronous parse behavior was added or changed.
+- The direct task instruction defers parse controls to Task 3, so the page intentionally renders read/source state without a parse form or parse JavaScript despite the broader plan's future parse-form design.
+- Tests use the public `SpecDocService` surface and do not access `_doc_repo`.
+
+## Concerns
+
+- The page currently has no parse action by design; Task 3 must add the parse form/job poller integration.
+- The pre-existing untracked plan file remains in the worktree and was intentionally left untouched.