driver: ignore package documentation sources

docs/spec.md

@@ -319,6 +319,87 @@ ImportPath    = ident { "." ident } .
   delegated graph-import scan or tools. An ordinary build compares production
   names only; one test product compares its production, same-package test, and
   external-test selections without merging their units.
+- After existing filename, target, kind, and test-role eligibility, a selected
+  source whose package/import header successfully declares the exact name
+  `documentation` is omitted before semantic source membership and import
+  scanning. The loader accepts the ordinary leading BOM, whitespace, comments,
+  internal line directives, and package-clause trivia when recognizing this
+  exact candidate. `documentation_test`, `documentationx`, and all other names
+  remain ordinary sources.
+
+  Candidate recognition is silent. A malformed package clause, malformed
+  contiguous import, reached header NUL, or unterminated header-trivia comment
+  retains its existing positioned load error before omission. After a valid
+  exact package/import prefix, a non-`i` first raw byte establishes the body
+  boundary and the remaining bytes are not parsed. A first raw `i` that does
+  not form the exact `import` token is instead diagnosed at that byte as
+  `expected top-level decl`; exact `import` followed by malformed import syntax
+  retains the ordinary import-parser diagnostic. Thus syntax, types, late
+  imports, imports missing only in the body, declarations, initializers,
+  tests, and runtime behavior after a successful non-`i` boundary are not
+  observed.
+
+  An omitted documentation source creates no package member or family,
+  source-file import occurrence, binding or graph edge, qualifier,
+  initializer, declaration, symbol, `.wwi`, action, publication destination,
+  or persistence identity. A mixed package is semantically identical to the
+  same source set without that file. A doc-only dotted directory provider has
+  no package sources and cannot satisfy an import. A same-named `.ww` file is
+  still not an import provider under the directory-only import rule; when such
+  a file is selected as a logical CLI root, it receives the established
+  `__root` identity only if retained as ordinary. The rule applies equally to
+  selected literal and logical roots, directory members, raw tests, recursive
+  discovery, and dotted directory providers.
+
+  Named-file documentation preflight applies only after symlink-following
+  `stat` classifies the literal or resolved source as regular, including a
+  symlink to a regular file. It retains one exact read buffer: documentation
+  bytes are suppressed from that buffer, while ordinary bytes from the same
+  preflight are reused by graph loading rather than reopened. FIFO and other
+  nonregular named-source routes keep their prior behavior and are not touched
+  by this preflight.
+
+  Coordinator directory discovery records metadata only. Selected paths are
+  canonicalized and deduplicated before source reads; each unique source is
+  then classified exactly once. For an ordinary result, the same buffered bytes
+  feed existing coordinator source validation. Direct-root failure and
+  recursive pattern/group accounting are performed per request after
+  classification, without rereading or reclassifying a source reached by more
+  than one spelling or pattern. Independently, one delegated driver request
+  enumerates each canonical directory once and lazily snapshots each
+  role-eligible regular source once; that observation supplies classification,
+  package/test attestation, import scanning, copied test actions, and unit
+  emission across every variant in the request. A production-only request does
+  not open excluded `*_test.ww` entries. Coordinator and delegated-driver
+  observations remain separate process boundaries; concurrent rewriting between
+  them gains no new atomic-snapshot guarantee.
+
+  Test-role precedence remains route-specific. A visible literal named
+  `_test.ww` passed to `ww build` validates its package/import header and then
+  follows the test-only empty-selection rule below without documentation
+  classification. A production directory build leaves `*_test.ww` unopened.
+  Raw `ww test` and selected directory test variants do classify documentation
+  sources. A logical request whose resolved provider merely has an `_test.ww`
+  physical basename is not the literal named-build special case. Directory
+  `ww test -S` without its required `-o` rejects as
+  `ww test: -S needs -o`; with a valid `-o`, a directory rejects as
+  `ww test: -S needs a single test file`. Both checks precede classification.
+
+  A doc-only direct build or run root takes its route's existing
+  `directory contains no WW package sources` result; recursive doc-only
+  directories do not become packages, while mixed roots are exactly the
+  source-absent control. No compiler, assembler, archiver, linker, generated
+  test support/main, test child, initializer, or program runtime is attributable
+  to the omitted source, and it creates no unit, interface, assembly, object,
+  archive, executable, output, transaction, capture, or retained result.
+  Changing only an ignored documentation body cannot invalidate or replace a
+  committed semantic generation. Cold failure publishes nothing; warm
+  no-source or header failure preserves prior public and semantic bytes.
+  Classification state is ephemeral: a process-local named-root preload is
+  cleared at the build boundary, and directory observations die with the
+  request graph. No state is shared or persisted across requests, and no lock,
+  schema, cache, or serialized identity is added. Build workdir format remains
+  18, test workdir format remains 19, and semantic storage format remains 3.
 - A single existing raw `.ww` operand is also subject to the unconditional
   leading-name rule: if its final requested basename begins `.` or `_`, it is
   ignored before the source is opened. Named raw sources otherwise retain their
@@ -983,6 +1064,26 @@ support, generated main, link, binary, captured runtime result, or process. The
 coordinator reports that successful validation exactly as
 `?    <package> [no test files]\n`.
 
+An exact `package documentation` source that reaches a test selection is
+suppressed by the package rule in §4 before production, same-package, or
+external-test family construction. It contributes no `@test`, dependency,
+initializer, support action, generated-main input, binary, process, captured
+result, or retained output. In a mixed directory the test product is exactly
+the product of the ordinary sources alone; a doc-only directory is not the
+successful production-with-no-tests case. A direct running directory request
+instead fails with `FAIL\n` and the coordinator's
+`directory contains no WW package sources` diagnostic, while `-c` omits
+`FAIL`. A selected named or logical raw running request likewise emits `FAIL`
+and its physical parent's driver no-source diagnostic; raw `-c` and `-S` omit
+the marker. Directory `-S` without the required `-o` retains
+`ww test: -S needs -o`; after a valid `-o`, it retains
+`ww test: -S needs a single test file`. Both precede source classification.
+Recursive doc-only matches are omitted as packages: running test reports the
+per-pattern no-match warning followed by `ww test: no packages to test`, while
+mixed recursive selections run only ordinary groups. A documentation-header
+error retains precedence over every no-source result; an explicit running test
+adds `FAIL`, but compile-only and assembly-only routes do not.
+
 Every test-bearing directory product links one request-private runnable.
 The test output-option name is exactly `o`, with the accepted forms `-o VALUE`,
 `--o VALUE`, `-o=VALUE`, and `--o=VALUE`. Equals forms split only at their