Skip to content

docs: restructure flat docs to link to site-owned facts - #30

Merged
replygirl merged 2 commits into
mainfrom
docs/flat-docs-ownership
Jul 16, 2026
Merged

docs: restructure flat docs to link to site-owned facts#30
replygirl merged 2 commits into
mainfrom
docs/flat-docs-ownership

Conversation

@replygirl

Copy link
Copy Markdown
Contributor

Summary

  • docs/apply-archive.md, validation.md, schemas.md, stores.md, blocking-changes.md, harness-integration.md, and architecture.md no longer restate rule tables, exit-code tables, artifact matrices, and command semantics that apps/docs (cospec.aligned.team) now owns — each keeps its repo-internal/contributor-facing content and links out to the owning site page.
  • docs/eval.md, docs/self-hosting.md, and docs/release.md were audited; no site-owned duplication found, left unchanged.
  • Verified CLAUDE.md / .agents/shared.md references to docs/architecture.md and docs/stores.md still resolve correctly.
  • apps/docs content is untouched.

Per-file summary

file kept linked out
apply-archive.md "gate enforced twice" rationale, sync-blockers/core/blockers.ts pointer exit codes, step order, JSON shape → /concepts/apply-and-archive
validation.md rule-family composition/delegation logic full rule registry → /reference/validation-rules
schemas.md canon file pointers, matrix-parity test, requires graph, fork/init refusal mechanics artifact matrix, Surfaces block, per-type rationale → /concepts/types-and-artifacts, /concepts/verification
stores.md Root internals (base/cwd/store args) setup, resolution order, context/workset → /concepts/stores
blocking-changes.md entry-grammar regex, core/blockers.ts pointer template, sync diagnostics prose → /concepts/blocking-changes
harness-integration.md per-workflow behavior descriptions, managed-file writeManaged pseudocode file tree, smoke checklist → /guide/harness-setup
architecture.md wrapped-call discipline, static-matrix invariant, module map, archive gate ordering failure-mode intro → /concepts/how-it-relates-to-openspec

Deviations

Test plan

  • mise run check (lint, typecheck, format, unit/contract/integration/release tests, generate:check, agents:check, schema validate) — all green
  • cospec validate flat-docs-ownership --strict — pass
  • cospec apply / cospec archive — gate clear, archived cleanly, blockers fanned out
  • Grepped all docs/*.md relative links — all resolve

🤖 Generated with Claude Code

replygirl and others added 2 commits July 16, 2026 16:05
Trim docs/apply-archive.md, validation.md, schemas.md, stores.md,
blocking-changes.md, harness-integration.md, and architecture.md so they
stop restating rule tables, exit-code tables, artifact matrices, and
command semantics now owned by pages on apps/docs (cospec.aligned.team).
Each page keeps its genuinely repo-internal/contributor-facing content
(canon pointers, parser grammar, implementation mechanics) and links out
for everything the site already owns.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings July 16, 2026 21:06

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@replygirl
replygirl merged commit d391ea5 into main Jul 16, 2026
11 checks passed
@replygirl
replygirl deleted the docs/flat-docs-ownership branch July 16, 2026 22:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants