driver: ignore package documentation sources

docs/test-system-v2.md

@@ -265,6 +265,80 @@ directory/recursive selection, package/import identities, graph/action
 identities, persistence formats (build 18, test 19, semantic 3), and test
 process topology are explicit non-effects.
 
+Exact `package documentation` is a separate source-suppression rule after the
+completed filename, target, file-kind, and test-role gates. Official Go 1.26.5
+`go/build` directly implements the exclusion after package/import-header
+loading and before `_test.go` or package-family classification. Its
+`read_test.go` directly tests the ordinary-body stop and malformed-import
+recovery, but the pinned official test/testdata tree has no test that directly
+names `package documentation`; `mod_doc.txt` is unrelated. That test absence is
+recorded rather than replaced with host-Go behavior.
+
+The focused package observer is therefore WW-native dual-stage proof. It
+covers one leading BOM, whitespace/comments/internal line directives and
+package-clause trivia; exact-name controls; malformed package and contiguous
+import headers; the raw body-boundary `i` that does not form exact `import` and
+must diagnose `expected top-level decl`; and ignored non-`i` bodies containing
+late imports, missing imports, declarations, initializers, `@test`, aborts, or
+nonzero mains. It also covers literal and logical single files, direct and
+recursive directories, the unchanged one-file import-decoy boundary, dotted
+directory providers, mixed and doc-only source sets, and exact Cstage/WWstage
+status, stream, source-set, diagnostic, and semantic-artifact parity.
+
+Named-file documentation preflight is restricted to sources whose
+symlink-following `stat` result is regular, including symlinks to regular
+files. It retains one exact read buffer: documentation sources are suppressed
+from it, while ordinary sources carry those same bytes into graph loading.
+FIFO and other nonregular named-source routes are untouched. Coordinator
+directory discovery is metadata-only; after canonicalization and deduplication,
+each unique selected source is classified exactly once. Buffered ordinary
+bytes are then reused for coordinator source validation, and per-request
+direct/recursive error, match, and group accounting follows classification.
+The delegated driver separately owns a request-graph directory observation:
+one canonical membership list and one lazy regular-source snapshot feed every
+reached production/test variant, including package-name/`@test` checks, import
+scanning, copied test actions, and unit emission. Production-only selection
+still does not open excluded `*_test.ww` files. The coordinator and delegated
+driver retain their separate process observations; the slice does not promise
+an atomic source snapshot across a concurrent rewrite between them.
+
+The test route matrix remains intentional. A visible literal named
+`_test.ww` build validates only its package/import header and then follows the
+existing test-only empty-selection rule; it does not run documentation
+classification or the synthetic raw-`i` check. Directory production leaves
+`*_test.ww` unopened. Raw `ww test` and selected directory test variants do
+classify exact documentation sources, while a logical request whose resolved
+provider merely has an `_test.ww` physical basename is not the literal named
+build special case. Directory `test -S` without its required `-o` first rejects
+with `ww test: -S needs -o`; after a valid `-o`, a directory rejects with
+`ww test: -S needs a single test file`. Both branches precede documentation
+classification.
+
+A doc-only direct running directory test exits 1 with exact `FAIL\n` stdout and
+the coordinator's no-source stderr; `-c` has the same error and empty stdout.
+A doc-only named or logical raw running test likewise emits `FAIL\n` plus the
+driver's physical-parent no-source diagnostic; raw `-c` and `-S` have empty
+stdout. A documentation-header error precedes no-source, with `FAIL` added only
+by an explicit running raw or directory/recursive test. Recursive doc-only
+patterns become no matches: running test emits the per-pattern warning then
+`ww test: no packages to test`, while mixed patterns retain and run only
+ordinary groups without warning. A directly named doc-only sibling root fails
+discovery for the complete request before any group starts.
+
+Suppression happens before package folders, internal/external families,
+products, graph edges, support, generated main, or execution. The documentation
+source creates no compiler, assembler, archiver, linker, test child, capture,
+result, retained binary, public output, work-state artifact, transaction, or
+persistence key. Mixed products and semantic artifacts equal the source-absent
+control byte for byte; changing only an ignored documentation body cannot
+invalidate or replace a committed generation. Cold failure publishes nothing,
+warm header/no-source failure preserves prior public and semantic bytes, and
+normal request-private cleanup and concurrency isolation remain unchanged.
+The known external-driver fixed-`.new` interruption poisoning remains open.
+Build workdir format remains 18, test workdir format remains 19, and semantic
+storage format remains 3; no test-result cache, schema, action descriptor,
+transaction marker, or lock is introduced.
+
 An existing local directory whose requested build basename ends `.ww`
 (including a visible `_test.ww` symlink to a directory) remains a directory
 package, not a raw named test source. WWstage `ww build` now uses the same