driver: ignore package documentation sources

docs/build-system.md

@@ -10646,8 +10646,9 @@ suffix.
 - **behavior derived from the pinned implementation** — the rule does not
   complete the remaining suffix-first run front, multiple named sources,
   finite `.ww` FIFO capture, shared test-process state/failure topology,
-  Go-compatible `-run` regular expressions, or `package documentation`
-  suppression. Existing `.ww` directory slices, hidden-source exclusion,
+  or Go-compatible `-run` regular expressions. Exact `package documentation`
+  suppression was still open when section 11.54 closed and is completed in
+  section 11.55. Existing `.ww` directory slices, hidden-source exclusion,
   named `_test.ww` build omission, recursive/multiple-root coordination,
   package syntax, and import syntax remain intact.
 
@@ -10655,6 +10656,202 @@ Build workdir format remains `18`, test workdir format remains `19`, and
 semantic storage format remains `3`. No schema, action descriptor, cache/result
 record, manifest, transaction protocol, or lock changes.
 
+### 11.55 Implemented exact `package documentation` source suppression
+
+A selected source whose successfully parsed package name is exactly
+`documentation` is a documentation source, not a semantic package source. It
+is removed by loading before source-family folding, import-edge construction,
+or any build, run, or test action. `documentation_test`, `documentationx`, and
+every other package name remain ordinary.
+
+#### Pinned authority, header boundary, and applicability
+
+- **behavior directly implemented or asserted by pinned Go** — the sole
+  authority is official Go 1.26.5 commit
+  `c19862e5f8415b4f24b189d065ed739517c548ba`. Its `go/build` loader records a
+  package/import-header error before excluding an exact parsed package name
+  `documentation`, and does so before `_test.go` or package-family
+  classification. Named Go files pass through the same rule. Public Go command
+  help also reserves the name and says such files are ignored.
+- **behavior directly implemented or asserted by pinned Go** — the pinned
+  loader reads the package clause and contiguous import section, not an
+  arbitrary body. A successful ordinary-body stop removes its one-byte
+  lookahead. It first probes a raw following `i` as a possible `import`,
+  however, so an `i` that does not form that exact keyword is a malformed
+  attempted import rather than a successful body boundary. Exact `import`
+  followed by malformed import syntax retains the ordinary import-parser
+  diagnostic.
+- **behavior directly implemented or asserted by pinned Go** — official
+  `src/go/build/read_test.go` tests the ordinary-body stop and malformed-import
+  recovery, but no test or testdata in the pinned tree directly names
+  `package documentation`. `cmd/go/testdata/script/mod_doc.txt` concerns module
+  documentation and is not evidence for this rule. This absence is explicit;
+  host-Go observations do not fill it.
+- **directly measured WW behavior** — before suppression, both driver stages
+  incorrectly treated documentation files as ordinary sources: doc-only roots
+  produced semantic artifacts, mixed roots conflicted, imported providers
+  created edges and actions, and test routes created test products. Valid
+  malformed bodies also exposed stage-specific recovery diagnostics, while
+  malformed package and contiguous-import headers already failed before an
+  action.
+- **behavior derived from the pinned implementation** — the quiet candidate
+  recognizer admits one leading BOM, leading whitespace, comments, internal
+  line directives, and trivia around `package`, exact identifier
+  `documentation`, and `;`. It emits no diagnostic and sends only a plausible
+  exact candidate through the existing package/import-header parser, so
+  ordinary sources acquire no new early diagnostics. Malformed candidate
+  headers retain that parser's positioned errors.
+- **behavior derived from the pinned implementation** — after a valid exact
+  header, a non-`i` first raw byte at the body boundary ends loading and every
+  later byte is ignored. If that first raw byte is `i` but does not form the
+  exact `import` token, both stage drivers and the shared coordinator emit
+  exactly `<FILE>:<LINE>:<COL>: error: expected top-level decl\n`, owned by
+  that byte. A malformed exact import retains its existing diagnostic. A
+  malformed package clause, malformed contiguous import, reached header NUL,
+  or unterminated header-trivia comment also remains an error. No no-source
+  diagnostic follows any such header error.
+
+#### Selection, package identity, and imports
+
+- **behavior derived from the pinned implementation** — existing CLI and
+  operand-shape errors, logical resolution and file-kind checks, and suffix,
+  hidden-prefix, target, and test-role eligibility retain precedence. The rule
+  then applies to selected directory members, literal and logical named roots,
+  raw tests, direct and recursive coordinator discovery, and every dotted
+  dependency resolving to a directory. Source imports remain directory-only;
+  a logical one-file provider is only a CLI-root compatibility route.
+- **behavior derived from the pinned implementation** — named-file
+  documentation preflight is entered only after symlink-following `stat`
+  classifies the selected source as regular. A symlink to a regular file is
+  therefore included. The preflight owns one exact read buffer: a suppressed
+  documentation source is discarded from that buffer, while an ordinary source
+  carries the same bytes into graph loading instead of being reopened. FIFO and
+  other nonregular named-source routes retain their existing handling and are
+  neither classified nor otherwise changed by this preflight.
+- **behavior derived from the pinned implementation** — coordinator directory
+  discovery collects metadata only. It canonicalizes and deduplicates selected
+  paths before reading source, classifies each unique source exactly once, and
+  passes the retained ordinary-source buffer to its existing source validation.
+  Direct-root errors and recursive pattern/group accounting are computed per
+  request from those classification results; a directory member is not
+  reclassified for each spelling or pattern that found it. The delegated stage
+  driver owns a separate request-graph observation: it enumerates each reached
+  canonical directory once, lazily opens only role-eligible files, and reuses
+  each observed path, classification, package-name/`@test` attestation, and byte
+  snapshot across production, same-package-test, external-test, and copied test
+  actions. A production-only request therefore still leaves `*_test.ww`
+  unopened. The coordinator and delegated driver are distinct existing process
+  boundaries; this slice does not add a cross-process atomic snapshot for a
+  source concurrently rewritten between those observations.
+- **behavior derived from the pinned implementation** — the three test-source
+  routes remain distinct. A visible literal named `_test.ww` build first
+  validates its package/import header and then omits it by the already completed
+  test-only rule; documentation classification, including the raw-`i` check,
+  does not run. Directory production keeps eligible `*_test.ww` entries
+  unopened. Raw `ww test` and selected directory test variants do run the
+  documentation classifier. A logical request whose resolved file merely has
+  an `_test.ww` physical basename is not the literal named-build special case.
+- **behavior derived from the pinned implementation** — an omitted source
+  contributes no package member, declared-family or test-family candidate,
+  import occurrence, binding or edge, qualifier, initializer, declaration,
+  symbol, graph action, unit, `.wwi`, or persistence identity. Its physical
+  pathname, parent, and symlink information remain loader observations only.
+  A logical one-file CLI source receives `__root` identity only when retained
+  as ordinary. A doc-only dotted directory provider has no package sources and
+  cannot satisfy an import; a same-named `.ww` file remains an import decoy
+  under the pre-existing directory-only import rule.
+- **behavior derived from the pinned implementation** — a mixed directory
+  retains exactly the canonical local or dotted identity and source graph of
+  the same tree with the documentation file absent. Imports appearing in the
+  valid contiguous documentation header are checked only to establish the
+  header; they never become dependency edges. Imports, declarations,
+  initializers, tests, aborts, nonzero mains, missing dependencies, and syntax
+  after a successful non-`i` body boundary are unobserved.
+
+#### Build, run, and test empty selections
+
+- **behavior derived from the pinned implementation** — a direct
+  non-coordinator doc-only `ww build DIR` exits 1 with empty stdout and exact
+  stderr `ww: DIR: directory contains no WW package sources\n`. A selected
+  named or logical non-test source uses its physical containing directory in
+  the same diagnostic, and `-S`, output, and `/dev/null` modes do not displace
+  it. A direct root already routed through the coordinator, including an
+  output-directory request, instead uses exact stderr
+  `wwtest package: DIR: directory contains no WW package sources\n` with the
+  same status and stdout.
+- **behavior derived from the pinned implementation** — the literal visible
+  named `_test.ww` build retains section 11.51's outcome even when its valid
+  declared name is `documentation`: no effective `-o` (including an
+  assembly-only request), or exact `/dev/null`, succeeds silently; a
+  non-directory output exits 1 with
+  `ww: no packages to build\n`; an output-directory request exits 1 with
+  `ww: no main packages to build\n`. Header errors still precede those
+  outcomes.
+- **behavior derived from the pinned implementation** — `ww run` on a selected
+  doc-only physical or logical directory exits 1 with empty stdout and
+  `ww: DIR: directory contains no WW package sources\n`. The existing private
+  `/tmp/ww_run_<pid>` is acquired before directory enumeration and then
+  removed. A named or logical one-file run uses its physical parent's
+  no-source diagnostic before acquiring run scratch. The separately open
+  suffix-first run behavior may select a visible `_test.ww`; when it does, this
+  rule suppresses that source. A `.ww`-spelled directory keeps the earlier
+  stat-first run rejection.
+- **behavior derived from the pinned implementation** — direct doc-only
+  `ww test DIR` exits 1 with stdout `FAIL\n` and the coordinator no-source
+  stderr; `ww test -c DIR` exits 1 with empty stdout and the same stderr.
+  Directory `test -S` without the required `-o` retains status 2 and exact
+  `ww test: -S needs -o\n`; after a valid `-o`, the directory retains status 2
+  and exact `ww test: -S needs a single test file\n`. Both checks precede
+  source classification. Named or logical raw `ww test FILE` exits 1 with
+  `FAIL\n` and the physical parent's driver no-source stderr; raw `-c` and
+  `-S` exit 1 with empty stdout and the same stderr. No requested output or
+  work state changes.
+- **behavior derived from the pinned implementation** — a recursive build
+  pattern retaining only doc-only directories exits 0 with empty stdout and
+  one `ww: warning: "PATTERN" matched no packages\n`; recursive test exits 1
+  with empty stdout, that warning, then
+  `ww test: no packages to test\n`. A pattern also containing ordinary
+  directories builds or tests only those groups without warning. Multiple
+  patterns warn once for each no-match pattern. Any directly named doc-only
+  sibling root fails the complete request during discovery before any ordinary
+  group starts.
+- **behavior derived from the pinned implementation** — the positioned raw-`i`
+  header error has empty stdout for build, run, `test -c`, and raw `test -S`.
+  An explicit running raw or directory/recursive test adds exactly `FAIL\n`.
+  Literal named `_test.ww` build and directory `test -S` retain their earlier
+  precedence and never reach this classifier.
+
+#### Actions, lifecycle, parity, formats, and scope
+
+- **behavior derived from the pinned implementation** — a doc-only source
+  causes no compiler, assembler, archiver, linker, generated test support/main,
+  test child, initializer, or program runtime. It creates no unit, `.wwi`,
+  assembly, object, archive, executable, output directory, sidecar, workdir
+  stamp, transaction, capture, or retained result. Mixed outputs and comparable
+  semantic artifacts are byte-identical to the source-absent control.
+- **behavior derived from the pinned implementation** — a documentation source
+  has no publication destination or persistent key. Adding, removing, or
+  changing only an ignored documentation body does not invalidate, refresh,
+  replace, or become a reuse input for committed ordinary actions. Doc-only
+  cold failure publishes nothing; a warm no-source or header failure preserves
+  prior public and semantic bytes. Ordinary sibling publication, producer
+  failure, transaction rollback, and invalidation remain unchanged.
+- **behavior derived from the pinned implementation** — classification state
+  is ephemeral and request-owned: the named-root preload is process-local and
+  cleared at the build boundary, while directory observations live only in the
+  request graph. Neither is persisted or shared across requests, and no lock,
+  schema, cache, or cross-request identity is added. Normal and controlled
+  failure use the existing reader and request-private cleanup. The verified
+  direct-SIGTERM fixed-`.new` poisoning gap remains open and is neither reached
+  nor repaired by this slice.
+- **behavior derived from the pinned implementation** — Cstage and WWstage
+  must agree on selected status, stdout, stderr, source membership, graphs,
+  actions, semantic artifacts, and lifecycle. The producer-provenance
+  `.wwtool.ww` remains intentionally stage-specific. Build workdir format
+  remains `18`, test workdir format remains `19`, and semantic storage format
+  remains `3`; no action descriptor, cache/result record, transaction marker,
+  manifest, database, or lock is added.
+
 ## 12. Candidate architectures and hard-gate decision
 
 Five candidates were developed as coherent systems, not as feature bins.

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

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