Surface present-but-unparseable workspace managers in architecture discovery (#558) (#561)

* Surface present-but-unparseable workspace managers in architecture discovery (UWP4XK)

Closes #558. A workspace manager present at the repo root but unparseable
(malformed go.work, unreadable Cargo [workspace] members, flow-style
pnpm-workspace.yaml) used to return undefined from its detector — conflating
"absent" with "present-but-unparseable" — and contribute zero packages with no
marker, so a whole language could vanish from the map at the discovery layer,
before the ZRW21K per-package "not introspected" marker could fire.

Each detector now returns a discriminated `absent | parsed | unreadable`. The
unreadable set is surfaced advisory-only: a `## Coverage gaps` section in the
generated root index naming each unreadable config, plus a non-blocking
`safeword architecture` / `--check` warning. It is folded into the root
fingerprint only when non-empty, so a clean repo (this one) never re-renders.

Reuses the existing union+dedupe discovery pipeline and toml table readers; no
new detector module, no blocking gate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NRGYnMkxo3yim7qdFs7s19

* Refine unreadable-workspace detection to avoid valid-config false alarms (UWP4XK)

From the independent /quality-review of #558. The detector classified a workspace
as "unreadable" whenever the manager's table/file was present but yielded no
parseable globs — false-alarming on valid configs where the member-list
declaration is simply absent. Narrowed to: unreadable only when the member-list
declaration is PRESENT but unparseable.

- Cargo [workspace] with no `members` key -> absent (valid root-package
  auto-discovery / default-members; verified vs the Cargo reference). New
  hasTomlTableKey helper.
- pnpm-workspace.yaml with no `packages:` key -> absent (catalog/settings-only is
  valid; verified vs the pnpm reference).
- go.work with no `use` directive -> absent (a fresh `go work init` file).
- uv unchanged: `members` is required in [tool.uv.workspace], so a table with no
  usable members is genuinely malformed.

Added U9/U10/U11 asserting each valid case is absent, not a false alarm.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NRGYnMkxo3yim7qdFs7s19

* refactor: extract parsed()/unreadable() constructors for WorkspaceDetection

The discriminated-union variants were built inline as object literals at five
detector sites each — so changing the shape meant editing five places. Extract two
small constructors and route every detector through them; each detector still
decides WHICH variant to return, so no per-manager semantics are lost.
Behavior-identical (52 monorepo + 27 document tests green).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NRGYnMkxo3yim7qdFs7s19

* chore(UWP4XK): advance ticket to phase verify (verification complete)

Verification complete — 55 monorepo unit tests + 14 architecture scenarios, full
CI green, real-CLI polyglot live-fire (incl. the false-alarm fixes), and an
independent quality-review (false-alarm fix applied). Matches the merged MGWZ4P
example's final state (phase: verify, status: todo); completion is the PR #561 merge.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NRGYnMkxo3yim7qdFs7s19

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: TheMostlyGreat

.project/tickets/UWP4XK-unparseable-workspace-coverage/dimensions.md

@@ -0,0 +1,34 @@
+# Behavioral dimensions — UWP4XK (present-but-unparseable workspace managers)
+
+Behavior: `discoverWorkspaces(dir) → { patterns, unreadable[] }`, and how the
+`unreadable[]` set is surfaced (root-index advisory, `architecture`/`--check`
+warning) and folded into the root fingerprint. The input space is "for each
+manager at the root, is it absent, parseable, or present-but-unparseable, and do
+any OTHER managers still yield packages."
+
+| # | Dimension | Partitions | Covered by |
+| - | --------- | ---------- | ---------- |
+| D1 | **Per-manager detection outcome** | (a) absent; (b) parsed; (c) present-but-unparseable | U1–U5 (one per manager × each outcome) |
+| D2 | **Which manager is unparseable** | (a) go.work; (b) Cargo `[workspace]`; (c) uv `[tool.uv.workspace]`; (d) pnpm flow-style; (e) package.json malformed shape | U1/AC1, U2/AC2(Cargo), U3, U4, U5 |
+| D3 | **Co-present readable manager** | (a) none (only the unreadable one) → no root index, warning-only surface; (b) ≥1 other readable → root index lists readable packages + carries the advisory | AC1–AC3 + U6 (b); AC4 (a: warning-only) |
+| D4 | **Absent vs present-but-unparseable boundary** | (a) manifest absent → absent; (b) workspace table/field absent → absent; (c) **member-list key absent though a table exists** (Cargo `[workspace]` no `members` / pnpm no `packages:` / go.work no `use`) → absent, NOT a false alarm; (d) member-list key present but unparseable → unreadable; (e) explicitly-empty (e.g. `workspaces: []`) → absent | U7 (Cargo no-table), U8 (empty array), U9 (Cargo no-members), U10 (pnpm catalog-only), U11 (go.work no-use); U1–U5 (d) |
+| D5 | **Fingerprint freshness** | (a) unreadable set empty → fingerprint unchanged vs today (no churn); (b) unreadable appears/disappears → fingerprint moves | FP1/FP2 (fingerprint tests) |
+| D6 | **Surface non-blocking** | (a) `architecture` exit unchanged; (b) `--check` exit unchanged (advisory ≠ stale) | AC4 (command warns, exit 0) |
+
+## Load-bearing partitions (where this change actually bites)
+
+- **D1(c) for every manager (D2 a–e)** — the bug: a present-but-unparseable
+  manifest must become an `unreadable` signal, not `undefined`. New behavior.
+- **D3(b)** — the readable side is never blinded: a malformed go.work next to a
+  working manager still lists the working packages AND names go.work. This is the
+  coverage-honesty property (the union from #554 must survive one bad manager).
+- **D4(b) vs D4(c)** — the boundary that must NOT over-fire: a `Cargo.toml` with no
+  `[workspace]` (single crate) stays absent; only a present table with unparseable
+  members is unreadable. Guards against advisory false alarms.
+- **D5(a)** — no churn: a repo with zero unreadable configs keeps its fingerprint.
+
+## Out-of-partition (not exercised; noted)
+
+Nested/recursive workspaces (a member that is itself a workspace root) — out of
+scope; current behavior (treat as one leaf, or not discovered) is unchanged.
+Repairing the unparseable manifest — never attempted.

.project/tickets/UWP4XK-unparseable-workspace-coverage/spec.md

@@ -0,0 +1,98 @@
+# Spec: Surface a present-but-unparseable workspace manager (UWP4XK)
+
+## Jobs To Be Done
+
+### UWP4XK.J1 — A polyglot map that admits what it could not read
+
+**Persona:** Technical Builder (TB)
+
+When safeword discovers my monorepo and one workspace manager's root manifest is
+present but unparseable (a malformed `go.work`, an unreadable Cargo `[workspace]
+members`, a flow-style `pnpm-workspace.yaml`), I want the generated map to **say
+so out loud** instead of silently listing zero packages for it, so I can trust
+"the map is complete" or see exactly which config to fix. (The NTB can't audit
+the diff to notice the Go services are missing — silence reads as "complete.")
+
+#### UWP4XK.J1.AC1 — Present-but-unparseable is surfaced, not dropped
+
+A root manifest that declares a workspace whose member list can't be parsed is
+named as unreadable (manager + config file) wherever the architecture surface is
+shown — it never contributes zero packages with no marker.
+
+#### UWP4XK.J1.AC2 — Absent stays silent
+
+A manager that is genuinely absent (no `go.work`; a `Cargo.toml`/`pyproject.toml`
+with no workspace table; a single-crate/single-package repo) produces no
+unreadable signal — only *present-but-unparseable* is surfaced, so the advisory
+is never a false alarm.
+
+#### UWP4XK.J1.AC3 — The readable side is never blinded
+
+When other managers are readable, their packages are still discovered and listed;
+the unreadable manager is surfaced *alongside* them (an advisory in the rendered
+root index), not in place of them. One unreadable config never drops a readable
+manager's packages.
+
+#### UWP4XK.J1.AC4 — Advisory, never blocking
+
+The surface is advisory: `safeword architecture` and `architecture --check` print
+a warning but their exit codes are unchanged; the root index renders the advisory
+but no command fails. The human doc / the build is never blocked on it.
+
+#### UWP4XK.J1.AC5 — The advisory stays fresh
+
+The root-index advisory re-renders when an unreadable config appears or is fixed
+(the unreadable set is part of the root fingerprint). A repo with no unreadable
+config keeps its existing fingerprint — no churn.
+
+## Problem
+
+`discoverLeafDirectories` unions managers (#554), but each detector returns
+`string[] | undefined` where `undefined` means BOTH "absent" and
+"present-but-unparseable." The unparseable case is filtered out at discovery,
+before the per-package "not introspected" marker (ZRW21K) can fire — a manager
+that discovered nothing has nothing to mark. So the set vanishes silently.
+
+## Design
+
+Replace each detector's `string[] | undefined` with a discriminated
+`WorkspaceDetection`:
+
+- `{ status: 'absent' }` — no workspace declared (no signal).
+- `{ status: 'parsed'; patterns: string[] }` — globs/dirs to expand (today's path).
+- `{ status: 'unreadable'; manager; config }` — a workspace is declared but its
+  member list can't be parsed.
+
+What counts as *declared but unreadable* per manager — the member-list declaration
+is PRESENT but can't be parsed (a *missing* declaration is absent, never a false
+alarm):
+
+- **go.work**: a `use` directive present but zero member dirs parse (malformed/junk
+  `use`). No `use` directive at all ⇒ absent (a `go work init` file with no modules).
+- **Cargo `[workspace]`**: `[workspace]` + a `members` key present but unparseable.
+  No `[workspace]` ⇒ absent (single crate); `[workspace]` with no `members` key ⇒
+  absent (a valid root-package workspace that auto-discovers members from path deps /
+  `default-members` — out of scope like nested workspaces, verified against the Cargo
+  reference).
+- **uv**: `[tool.uv.workspace]` table present but `members` unparseable (no table ⇒
+  absent). uv *requires* `members`, so a table with no usable members is genuinely
+  malformed → unreadable.
+- **pnpm**: a `packages:` key present but no glob parses (flow-style, empty block).
+  No `packages:` key ⇒ absent (a catalog-only/settings-only file is valid and declares
+  no members — verified against the pnpm reference).
+- **package.json**: a `workspaces` field present but not a usable array /
+  `{packages: [...]}` (malformed shape) ⇒ unreadable; an explicitly empty array
+  ⇒ absent (deliberate). JS precedence (package.json wins over pnpm) is preserved:
+  package.json present — parsed OR unreadable — wins; only an absent package.json
+  falls through to pnpm.
+
+`discoverWorkspaces(dir)` returns `{ patterns, unreadable[] }`. `discoverLeafDirectories`
+becomes a thin wrapper over `.patterns` (unchanged behavior + signature).
+`extractMonorepoModel` gains `unreadableWorkspaces[]`; `monorepoFingerprint`
+includes it only when non-empty. The root index renders a `## Coverage gaps`
+advisory; `architecture`/`--check` print a non-blocking warning.
+
+## Out of scope
+
+Nested/recursive workspaces; new manifest formats; per-leaf extraction; any
+blocking gate; repairing the unparseable manifest.

.project/tickets/UWP4XK-unparseable-workspace-coverage/test-definitions.md

@@ -0,0 +1,66 @@
+# Test definitions (R/G/R ledger) — UWP4XK
+
+Behavior: a workspace manager PRESENT at the root but unparseable is surfaced
+(root-index `## Coverage gaps` advisory + `architecture`/`--check` warning),
+never silently dropped. Black-box scenarios in
+`features/architecture-unreadable-workspace.feature`; detector precision in
+`tests/utils/architecture-monorepo.test.ts`. Dimensions in dimensions.md.
+
+## Black-box scenarios (acceptance lane — `@architecture-unreadable-workspace`)
+
+- [x] **AC1 — malformed go.work + working JS** (`…UWP4XK.AC1`) [J1.AC1/AC3, D2(a), D3(b)]
+  - RED (pre-fix): go.work returns `undefined`, contributes nothing, no marker; root
+    index lists `web` only, NO advisory. Failure: "root index has no Coverage gaps".
+  - GREEN: root index lists `web` AND a `## Coverage gaps` advisory names `go.work`.
+- [x] **AC2 — unreadable Cargo [workspace] members + uv Python** (`…UWP4XK.AC2`) [J1.AC1/AC3, D2(b), D3(b)]
+  - RED: Cargo `undefined` (absent==unparseable), dropped silently; no advisory.
+  - GREEN: lists `pytool` AND advisory names `Cargo.toml`.
+- [x] **AC3 — flow-style pnpm + Go module** (`…UWP4XK.AC3`) [J1.AC1/AC3, D2(d), D3(b)]
+  - RED: pnpm flow-style → `undefined`, dropped; no advisory (today's silent
+    "degrades gracefully" path in monorepo-coverage-honesty).
+  - GREEN: lists `gosvc` AND advisory names `pnpm-workspace.yaml`.
+- [x] **AC4 — only-unparseable case is warned, not blocked** (`…UWP4XK.AC4`) [J1.AC4, D3(a), D6]
+  - RED: a lone malformed go.work → single-repo doc, zero signal, command silent.
+  - GREEN: command exits 0 AND its output warns that `go.work` is unreadable
+    (the warning channel covers the no-root-index path).
+- [x] **AC5 — absent is not a false alarm** (`…UWP4XK.AC5`) [J1.AC2, D4(b)]
+  - Negative case: a single-crate `Cargo.toml` (no `[workspace]`) must NOT raise an
+    advisory. GREEN: lists `gosvc`, no `## Coverage gaps` section.
+
+Each scenario is Arrange-Observe-Decide-Independent: the Given builds the repo, the
+When runs the real CLI, the Then reads only observable output (the rendered doc or the
+command's stdout/stderr) — no package internals.
+
+## Unit tests (detector precision — tests/utils/architecture-monorepo.test.ts)
+
+- [x] **U1 — malformed go.work is unreadable, not absent** [D1(c), D2(a)]
+  - RED: detector returned `undefined`; `discoverWorkspaces` had no `unreadable` field.
+    GREEN: `{ patterns: [], unreadable: [{go.work}] }`.
+- [x] **U2 — Cargo [workspace] present, members unparseable → unreadable** [D1(c), D2(b)]
+- [x] **U3 — uv [tool.uv.workspace] present, members unparseable → unreadable** [D1(c), D2(c)]
+- [x] **U4 — flow-style pnpm → unreadable** [D1(c), D2(d)]
+- [x] **U5 — package.json `workspaces` of wrong shape → unreadable** [D1(c), D2(e)]
+- [x] **U6 — a malformed manager never blinds the readable ones** [J1.AC3, D3(b)]: JS
+  `web` + malformed go.work → patterns keep `packages/*`, leaves keep `web`, unreadable
+  records `go.work`. The coverage-honesty property (#554 union survives one bad manager).
+- [x] **U7 — single-crate Cargo.toml (no [workspace]) raises no signal** [J1.AC2, D4(b)]
+- [x] **U8 — explicitly-empty `workspaces: []` is absent, not unreadable** [D4(e)]
+- [x] **U9 — Cargo `[workspace]` with no `members` key (auto-discovery) is absent** [J1.AC2, D4(c)]:
+  a root-package workspace using `default-members`/path-dep auto-discovery is valid, not a
+  coverage gap — must not false-alarm. (quality-review finding; verified vs the Cargo reference.)
+- [x] **U10 — catalog-only `pnpm-workspace.yaml` (no `packages:` key) is absent** [J1.AC2, D4(c)]:
+  `packages:` is optional in pnpm; a catalog/settings-only file declares no members.
+  (quality-review finding; verified vs the pnpm reference.)
+- [x] **U11 — `go.work` with no `use` directive (fresh init) is absent** [J1.AC2, D4(c)]:
+  a member-less go.work declares nothing — only a present-but-junk `use` is unreadable.
+- [x] **model — `extractMonorepoModel` exposes `unreadableWorkspaces`** [feeds render + fingerprint]
+- [x] **FP1 — fingerprint moves when an unreadable manager appears** [D5(b)]
+- [x] **FP2 — fingerprint does NOT move for a clean repo (no churn)** [D5(a)]: the
+  unreadable key is contributed only when non-empty, so a readable-only repo keeps its hash.
+
+## Reconcile note
+
+Coverage honesty (no silent drop) is the union of U1–U6 + AC1–AC4: every present
+cross-ecosystem manager that can't be parsed reaches a surface (doc advisory and/or
+command warning). U7/U8 + AC5 pin the absent/empty boundary so the advisory is never a
+false alarm. U9/U9b keep the doc advisory fresh without churning clean repos.

.project/tickets/UWP4XK-unparseable-workspace-coverage/ticket.md

@@ -0,0 +1,69 @@
+---
+id: UWP4XK
+slug: unparseable-workspace-coverage
+type: feature
+phase: verify
+status: todo
+created: 2026-06-29T19:30:00.000Z
+last_modified: 2026-06-30T04:11:00.000Z
+scope:
+  - Distinguish "workspace manager absent" from "workspace manager present-but-unparseable" at the detector boundary in `architecture-monorepo.ts` (`detectGoWork`, `detectCargoWorkspace`, `detectUvWorkspace`, the JS package.json/pnpm detectors). Today each returns `string[] | undefined` and `undefined` collapses both cases, so a present-but-unreadable root manifest contributes zero packages with no marker.
+  - SURFACE a present-but-unparseable workspace config (advisory only, never blocking) in two places: a `## Coverage gaps` advisory line in the rendered monorepo root index naming the unreadable config, and a `safeword architecture` / `architecture --check` warning naming the unreadable config.
+  - Fold the unreadable-workspace set into `monorepoFingerprint` (only when non-empty, to avoid churning repos that have none) so the root-index advisory stays fresh as an unreadable config appears or is fixed.
+out_of_scope:
+  - Nested/recursive workspaces (a member that is itself a workspace root).
+  - New language packs / manifest formats; per-leaf polyglot extraction (unchanged).
+  - Any blocking gate — the surface is advisory like the rest of the architecture honesty layer.
+  - Repairing or guessing the contents of an unparseable manifest; we only report it.
+done_when:
+  - A repo with a malformed `go.work` (a `use` directive that yields no member dir) alongside a working manager surfaces the `go.work` as unreadable — its presence is named, not silently dropped.
+  - A repo with a `Cargo.toml` `[workspace]` whose `members` array can't be parsed surfaces `Cargo.toml` as unreadable; a `Cargo.toml` with NO `[workspace]` table (a single crate) stays silent (absent, not unreadable).
+  - A repo with a flow-style `pnpm-workspace.yaml` surfaces `pnpm-workspace.yaml` as unreadable.
+  - When at least one OTHER manager still yields packages, the rendered root index carries a `## Coverage gaps` advisory naming each unreadable config AND lists the packages the readable managers discovered (the readable side is never blinded by the unreadable one).
+  - `safeword architecture` and `architecture --check` print a non-blocking warning naming each unreadable config; neither command's exit code changes because of it.
+  - `monorepoFingerprint` moves when an unreadable config appears or is fixed, but a repo with no unreadable config (this repo) keeps its existing fingerprint — no dogfood churn beyond the one-time regeneration this ticket lands.
+  - No regression: absent managers, single-manager monorepos, and single-repo projects are unchanged; `architecture --check` still passes on this repo.
+---
+
+# Surface a present-but-unparseable workspace manager (coverage honesty)
+
+**Goal:** A workspace manager that is *present* at the repo root but whose member
+list safeword cannot parse must be **surfaced**, not silently dropped. Today it
+contributes zero packages and no marker — the same class of silent omission #554
+fixed (a whole language vanishing from the map), one layer up.
+
+**Origin:** GitHub #558, surfaced by the independent quality-review of #554
+(MGWZ4P). Pre-existing: each detector degraded this way under the old first-match
+chain too; explicitly out of scope for #554, filed so it isn't lost.
+
+## Problem
+
+`discoverLeafDirectories` unions all workspace managers (#554), but each detector
+returns `string[] | undefined`, and `undefined` means **both "absent" and
+"present-but-unparseable."** A malformed `go.work`, an unreadable Cargo
+`[workspace] members`, or a flow-style `pnpm-workspace.yaml` returns `undefined`,
+is filtered out, and contributes zero packages with no marker. The package set
+vanishes at the **discovery** layer — *before* the ZRW21K "not introspected"
+marker can fire (that marker is per-discovered-package; a manager that discovered
+nothing has nothing to mark). The root index looks complete while silently
+omitting, say, every Go service.
+
+safeword's coverage-honesty principle is "incomplete is fine, silently wrong is
+not." A present manager that can't be parsed should be surfaced.
+
+## Decision
+
+Distinguish the two cases at the detector boundary with a small discriminated
+return (`absent` | `parsed` | `unreadable`), carrying the manager label and
+config filename on the `unreadable` case so discovery can surface it. Reuse the
+existing glob-expand + `hasRecognizedManifest` + `Set`-dedupe pipeline unchanged
+— the readable managers still union exactly as before; the only addition is a
+parallel `unreadable[]` channel. Surface it advisory-only (root-index line +
+`--check`/command warning) and fold it into the root fingerprint (non-empty only)
+so the advisory stays fresh. Never block.
+
+## Next
+
+`/bdd`: spec → dimensions → scenarios (malformed go.work, unreadable Cargo
+members, flow-style pnpm — each surfaced, not silently empty) → independent
+scenario review → TDD → verify → audit.