docs: update Gaze documentation for multi-language support

[jflowers]

Summary

Updates the Unbound Force website to document Gaze's evolution from a Go-only test quality tool to a multi-language analysis framework. This change addresses four upstream PRs that introduced the external analyzer protocol, breaking JSON changes, an expanded side effect taxonomy, and a new --test-short flag.

Key changes:

• New External Analyzers section on the Gaze project page documenting the JSON-RPC 2.0 protocol, three-tier discovery mechanism, and --language flag
• Migration Notes section with breaking JSON changes (go_version → language_version) and coverage behavior change
• Expanded side effect taxonomy with 10 new universal types (48+ total)
• Three new CLI flags: --analyzer, --language, --test-short
• Four new architecture packages: protocol, provider, adapter, cliutil
• Cross-page consistency: homepage badge, tester guide, team page, and projects index updated to "Go-native with multi-language support" framing

Closes #227, closes #228, closes #229, closes #230

How to Test

1. Run npm run build — should succeed with no new warnings
2. Run npm run dev and verify:
   • /docs/projects/gaze/ — External Analyzers section, expanded CLI flags table (7 flags), Universal Side Effect Types, Migration Notes, updated architecture table (15 packages)
   • / — Gaze card badge shows "Go + Multi-Language"
   • /docs/getting-started/tester/ — migration callout, --test-short example, "48+ types" count
   • /docs/team/gaze-tester/ — multi-language framing, no "for Go" language
   • /docs/projects/ — Gaze description says "Go-native, with multi-language support"
3. Toggle dark mode on each modified page

How to Demo

1. Navigate to the Gaze project page — scroll through the new External Analyzers section showing JSON-RPC 2.0 protocol and three-tier discovery
2. Check the CLI flags table — three new flags visible at the bottom
3. Scroll to Universal Side Effect Types — 10 new types listed by tier
4. Scroll to Migration Notes — JSON output changes and coverage behavior change documented
5. Return to homepage — Gaze card badge reads "Go + Multi-Language"

Key Files Changed

File	Changes
content/docs/projects/gaze.md	+63/-5 — External Analyzers section, CLI flags, taxonomy, architecture, migration notes, limitations update
content/docs/getting-started/tester.md	+7/-1 — --test-short migration callout, CI example, side effect count update
content/docs/team/gaze-tester.md	+4/-4 — Multi-language framing in frontmatter and body
content/docs/projects/_index.md	+1/-1 — Gaze description framing
layouts/home.html	+1/-1 — Badge text change
openspec/changes/gaze-multi-language-docs/	OpenSpec artifacts (proposal, design, specs, tasks)

Known Issues

The following findings from the review council were acknowledged but not resolved:

• MEDIUM: Missing blog tracking issue for Gaze's multi-language expansion (content pipeline gap, not a documentation defect)
• LOW: Migration notes lack version pinning (upstream release version not yet finalized)

This PR was generated by /uf.finale (AI-assisted).

[yvonnedevlinrh]

PR Review: REQUEST CHANGES

Well-structured, spec-complete documentation PR that accurately reflects Gaze's multi-language evolution across all pages. The OpenSpec workflow is complete and npm run build passes cleanly. One HIGH-severity content-accuracy defect blocks approval; everything else is minor. All findings below are introduced by this PR — none are pre-existing (the Migration Notes / alias content does not exist on main).

CI Status

No CI checks are configured on the branch. Local npm run build passes (140 pages, no new warnings). The only build warnings (Description too short on /tags/*) are pre-existing auto-generated pages, unrelated to this PR.

Findings

🔴 HIGH — Fabricated/mislabeled alias list

File: content/docs/projects/gaze.md (Migration Notes → JSON Output Changes)

The "Seven language-neutral SideEffectType aliases" are listed as:

AsyncTaskSpawn, FFICall, ErrorSignal, GeneratorYield, ContainerMutation, StreamOutput, ResourceManagement

Verified against upstream gaze#180, the actual 7 aliases are:

AsyncTaskSpawn, AsyncMessageSend, AsyncChannelClose, BarrierOp, PanicRecovery, FFICall, ObjectPoolOp

Only 2 of 7 are correct. The other 5 (ErrorSignal, GeneratorYield, ContainerMutation, StreamOutput, ResourceManagement) are the new universal types from gaze#184, conflating two upstream PRs. This violates the non-negotiable Content Accuracy mandate (AGENTS.md) and would ship incorrect identifiers to JSON consumers relying on the migration guide.

Fix: Replace with the correct 7 alias names from gaze#180, or reword to a non-exhaustive example (e.g., "language-neutral aliases such as AsyncTaskSpawn and FFICall").

🟡 MEDIUM — Formatting not applied

Table pipes in the new CLI/architecture tables are unaligned and layouts/home.html has a long line (FT-003). Run npm run format before merge. Non-blocking — Prettier is not enforced by CI.

🟡 MEDIUM — Missing blog/website tracking issue (acknowledged)

Deferred in design.md Non-Goals — reasonable scoping decision, follow-up only.

⚪ LOW

• "48+" overstates a fixed count — upstream states an exact 48 (38 + 10). Consider "48 types".
• Protocol v1.1.0 bump not documented — issue #229 explicitly requests noting the bump; the docs omit it.
• Migration notes lack version pinning (acknowledged in PR body) — name the version the breaking changes landed in for actionability.

Security

No issues. The home.html change is a static text label; the .uf/dewey/learnings/*.md files contain no secrets; external links point to the legitimate upstream repo.

Constitution / Workflow Compliance

• ✅ OpenSpec workflow complete (proposal, design, spec, tasks, .openspec.yaml); branch matches opsx/ convention.
• ✅ Zero-Waste, Neighborhood Rule, and frontmatter all pass — no placeholder content, anchors resolve, cross-page consistency handled.

Linked Issues

Issue	Coverage
#227 — External analyzer protocol + CLI flags	✅ Covered & accurate
#228 — JSON go_version→language_version	⚠️ Rename accurate; alias list wrong (see HIGH)
#229 — Expanded taxonomy (10 new types)	✅ 10 types match; ⚠️ v1.1.0 bump omitted
#230 — --test-short + coverage change	✅ Covered & accurate

Verdict

REQUEST CHANGES — 1 HIGH, 2 MEDIUM, 3 LOW.

Required before merge: correct the alias list (HIGH).
Recommended: run npm run format, document the protocol v1.1.0 bump (#229), and consider "48 types" over "48+".

---

*This review was generated with AI assistance._

[jflowers]

Thanks @yvonnedevlinrh — all feedback addressed in the following commits:

1. Fabricated/mislabeled alias list (HIGH — ACCEPT)
Fixed in aac2011. Replaced the incorrect 7-alias list with a non-exhaustive example using verified names from the gaze taxonomy (AsyncTaskSpawn, AsyncMessageSend, BarrierOp, PanicRecovery, FFICall) and linked to the protocol documentation for the full list.

2. Formatting (MEDIUM — ACCEPT)
Fixed in 84b035f. Ran npm run format — table pipes aligned and long lines reformatted across the site.

3. Missing blog/website tracking issue (MEDIUM — ACCEPT)
Created tracking issue #268 for a companion blog post covering multi-language support.

4. "48+" count (LOW — MODIFIED)
Fixed in aac2011. Changed to "dozens of types" rather than the exact count to avoid staleness as the taxonomy grows.

5. Protocol v1.1.0 bump (LOW — ACCEPT)
Fixed in aac2011. Added a "Protocol Version Bump" subsection to Migration Notes documenting the v1.1.0 bump and backward compatibility with v1.0.0 analyzers.

6. Version pinning (LOW — ACCEPT)
Fixed in aac2011. Migration notes now explicitly reference "Gaze v1.7.0".

[yvonnedevlinrh]

PR Review: APPROVE

Re-review verifying resolution of the findings from my earlier CHANGES_REQUESTED review. All required and recommended items have been addressed across commits aac2011, 56bc878, and 84b035f.

Prior Findings — Resolution Status

Sev	Finding	Status
HIGH	Fabricated/mislabeled alias list in gaze.md Migration Notes	✅ Resolved — rewritten as a non-exhaustive example (e.g., AsyncTaskSpawn, AsyncMessageSend, BarrierOp, PanicRecovery, FFICall) with a link to the protocol docs. No universal-type names leak into the alias list.
MEDIUM	Prettier formatting not applied	✅ Resolved — prettier -c is now clean on all substantive files.
MEDIUM	Missing blog/website tracking issue (acknowledged)	⚠️ Deferred in design.md Non-Goals — non-blocking follow-up.
LOW	"48+" overstates a fixed count	✅ Resolved — now "dozens of types".
LOW	Protocol v1.1.0 bump not documented (#229)	✅ Resolved — documented in Migration Notes.
LOW	Migration notes lack version pinning (acknowledged)	✅ Resolved — pinned to Gaze v1.7.0.

Content Accuracy Note

Cross-checking upstream, the authoritative count is 11 language-neutral aliases (not the 7 I referenced in my prior review from gaze#180). This makes the author's choice to reword to a non-exhaustive "e.g." example with a link to the canonical protocol docs the correct, robust fix — it sidesteps the exact-count problem entirely. AsyncTaskSpawn (= GoroutineSpawn) and FFICall (= CgoCall) are directly confirmed upstream; the remaining names map to confirmed Go effect types. No fabrication remains.

Verification

• npm run build (hugo --minify --gc): passes — 140 pages, only pre-existing /tags/* "Description too short" warnings (unrelated to this PR).
• prettier -c on all changed substantive files: clean.
• Linked issues #227–#230: all covered and accurate, including the previously-omitted protocol v1.1.0 bump.

Security & Constitution

No issues. The home.html change is a static text label, the .uf/dewey/learnings/*.md files contain no secrets, external links point to the legitimate upstream repo, and the OpenSpec workflow (proposal, design, spec, tasks) is complete with the opsx/ branch convention.

Verdict

APPROVE — every blocking and recommended item resolved. The only remaining item is the acknowledged, deferred blog-tracking issue (a content-pipeline follow-up, not a documentation defect).

This review was generated with AI assistance.