docs(solutions): refresh corpus against shipped reality

[marcusrbrown]

Refresh docs/solutions/ against shipped reality after several architectural arcs accumulated drift.

Scope

21 docs audited across 7 categories. 10 needed action:

Action	Count	Notes
Updated	6	Removed dead references to deleted CEP-sync infrastructure; added last_refreshed: 2026-05-16
Deleted	2	Already explicitly archived; lessons no longer applicable
Replaced	2	Subject reversed (singleton removed) or deleted (sync workflow gone) — rewrote to describe current behavior
Consolidated	1	Newer refinement merged into broader canonical doc
Keep	11	Verified current against shipped behavior

What changed

Updated (6)

• destructive-to-nondestructive-converter — converter still exists; added note that it's now ad-hoc CLI only; removed broken cross-references
• converter-code-block-tool-name-capitalization — replaced deleted-workflow references with pointer to scripts/content-integrity.ts; removed Python sample in favor of the live gate
• workflow-command-prompt-dry-run-integration — flipped status to stale with stale_reason noting the workflow was deleted; kept body for historical context
• zsh-for-loop-word-splitting — replaced "Initiative chore: migrate to OpenCode-native skill loading #3" planning taxonomy with concrete reference to the live content-integrity gate
• reconciliation-sync-reference-integrity — reframed from CEP-sync to content-integrity-gate component; updated tags
• ocx-registry-review-fixes — added V1→V2 schema migration note; removed broken cross-references to deleted docs

Deleted (2)

• structured-manual-override-tracking-Systematic-20260210.md — fully obsolete after CEP divorce; was already status: archived
• batch-import-cep-agents-to-systematic-20260210.md — workflow no longer exists; was already status: archived

Replaced (2)

• opencode-plugin-factory-duplicate-registration-2026-05-04.md — PR refactor(plugin): independent per-load registration with marker-based bootstrap idempotency #352 removed the plugInOnce singleton entirely. Doc now describes the current per-load registration model with marker-based bootstrap idempotency via <SYSTEMATIC_WORKFLOWS> strip-and-replace
• sync-cep-missing-sub-files-SyncCEP-20260219.md — generalized from the deleted sync workflow into a multi-file batch-import integrity pattern; the enforcing mechanism is now checkSubfileReferences in scripts/content-integrity.ts

Consolidated (1)

• discovery-before-validation-lifecycle-2026-05-15.md merged into provider-availability-source-defaults-2026-05-12.md. The newer doc was a refinement of the older's discriminated envelope (adding empty-set collapse) plus two new patterns (lifecycle ordering, parallel-bug check). Canonical doc now has 9 patterns covering the full provider-availability arc across PRs feat(overlay): replace auth.json with client-API availability + provider-grouped source defaults #358, fix(overlay): collapse empty discovery to unknown + run discovery before validation #372, fix(overlay): collapse empty cache to unknown availability status #378.

Verification

Check	Result
content-integrity	clean (160 md + 20 ts scanned, 43 exempt, 0 warnings)
docs:build	110 pages built in 5.10s
Net change	-305 lines (consolidation + deletions)

Net change

• 6 modified
• 3 deleted
• 0 created (replacements overwrote in place to preserve backlinks)

docs: prefix, no release impact.

[fro-bot]

Verdict: PASS

This is a well-executed corpus refresh. All 12 changed files were read. No broken cross-references, no dangling internal links to the three deleted docs, and the content-integrity gate is clean (160 md + 20 ts, 0 warnings).

Blocking issues

None.

Non-blocking concerns

1. destructive-to-nondestructive-converter-Systematic-20260209.md — pre-standard frontmatter schema
This doc uses module: Systematic instead of title:, and has no category: field. Both missing fields were already absent before this PR — the PR only added last_refreshed and a note about ad-hoc CLI usage. Worth normalizing the frontmatter to the current schema in a follow-up, but not a blocker since content-integrity doesn't scan docs/solutions/ for frontmatter shape.

2. workflow-command-prompt-dry-run-integration.md — stale_date vs last_refreshed convention
The doc uses stale_date: 2026-05-16 as the temporal anchor (no last_refreshed). The choice looks intentional — stale_date signals "when was staleness declared" rather than "when was content refreshed" — but it diverges from the pattern used in the other 8 updated docs. If the learnings-researcher agent filters by last_refreshed, this doc will appear older than it is. Consider whether to add last_refreshed alongside stale_date for consistency.

3. provider-availability-source-defaults-2026-05-12.md — Pattern 6's ReadonlySet claim
Pattern 6 states: "Object.freeze on a Set freezes only the container, not the contents — you would need to reassign Set.prototype.add or similar tricks." This is accurate for Object.freeze on a Set (freeze prevents reassigning properties but does not prevent .add/.delete calls). The doc's conclusion (factory + ReadonlySet is the right approach) is correct. The explanation is a bit compressed — Object.freeze on a plain object with Set values is a different story from Object.freeze on the Set itself — but this is documentation for a pattern that's already shipped, so worth noting for a future edit rather than blocking merge.

Missing tests

N/A — this is a documentation-only PR. The content-integrity gate acts as the structural test.

Risk assessment: LOW

• Scope is docs/ only; no TypeScript, no config, no plugin API surface touched.
• The three deletions (structured-manual-override-tracking, batch-import-cep-agents, discovery-before-validation-lifecycle) are all archived/superseded docs. No dangling internal refs confirmed by scan.
• The two "replacements" (plugin registration, sync sub-files) accurately describe the current shipped behavior based on the PR descriptions for #352 and #243.
• The consolidation of discovery-before-validation-lifecycle-2026-05-15.md into provider-availability-source-defaults-2026-05-12.md is clean — Patterns 7, 8, and 9 are present in the canonical doc with no content loss.
• Content-integrity gate: clean on HEAD.
• Docs build: 110 pages, no errors (per PR description; gate output confirms).

---

Run Summary

Field	Value
Event	pull_request
Repository	marcusrbrown/systematic
Run ID	25956454632
Cache	hit
Session	ses_1d0421865ffek2vV1Rqw0JRig0