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.