docs(specs): bootstrap linked specs and isolate build sources#245
Merged
Conversation
### Summary Bootstrap a small Linked Specs corpus that maps Flakebox and its Nix library without duplicating user documentation. Explicitly prune recursively nested `specs` directories from repository-derived package, documentation, check, fixture, and template-project build sources so governing records cannot invalidate builds. Keep the general source APIs composable rather than changing `fromPaths` defaults. ### Details Add the project adoption instruction and the root `ARCH-flakebox` overview plus the independently useful `lib/` architecture record. Omit CLI, decision, requirement, and functional records because the root overview owns the CLI boundary and no surveyed candidates met the stricter thresholds. Apply `source.filters.excludeDirectoriesNamed [ "specs" ]` at each relevant source construction, including Flakebox packaging, mdBook, ast-grep, Cargo check fixtures, the default template's build, and user-facing source examples. Preserve the `checks/source-tests.nix` fixture directories and sharpen their existing source-identity assertions to name Linked Specs edits and selected build-input edits explicitly. ### Reviews An independent maintainability/code review and the required focused Linked Specs review both passed without findings. The reviewer also noted an unrelated, pre-existing stale template-lock problem; this change does not introduce or worsen it. ### Validation - `nix develop -c treefmt` - `nix flake check --no-build -L` - focused builds for source tests, ast-grep rules, custom stdenv, docs, and Flakebox - `nix develop -c selfci check --candidate tvppzrtn`
dpc
marked this pull request as ready for review
July 24, 2026 19:15
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.mdspecsdirectories from repository-derived package, docs, check, fixture, and template-project build sourcesThe source filters remain explicit at each integration point; the general
fromPaths/fromFilesetsemantics do not change. The intentionalchecks/source-tests.nixfixturespecsdirectories remain test inputs.Records added
specs/ARCH-flakebox.mdlib/specs/ARCH-flakebox-nix-library.mdThe root overview owns the small CLI boundary. This bootstrap intentionally adds no DECISION, REQ, SPEC, CLI component record, or index.
Validation
nix develop -c treefmtnix flake check --no-build -Lnix develop -c selfci check --candidate tvppzrtnAn independent code/maintainability review and the required focused Linked Specs review passed without findings.