coulomb/repo-scoping
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

one time bootstrap path

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-02 00:36:00 +02:00
parent 911ca45618
commit 76f5ecb1b4
12 changed files with 328 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
docs/characteristic-evidence-model.md
View File

@@ -30,6 +30,33 @@ organized under the wrong capability.
Observed facts are deterministic scanner output. They describe what was seen in
the repository: files, languages, frameworks, routes, tests, documentation,
provider names, configuration variables, and similar source-linked observations.
Facts can carry a source role so generation can separate product evidence from
ambient context. Important roles include:
- `intent_summary`: `INTENT.md` or equivalent design-intent material describing
why the repository should exist and what utility it is meant to provide.
- `derived_scope`: `SCOPE.md` or equivalent current-scope material. This is a
derived or curated description of what is believed to be true now, not primary
evidence for rebuilding the same characteristic model.
- `product_documentation`: README, docs, specifications, and user-facing guides.
- `implementation_source`: source code owned by the repository.
- `dependency_declaration`: manifests, imports, lockfiles, and package metadata.
- `configuration`, `ci_tooling`, `test_evidence`, and `agent_guidance`.
`INTENT.md` and `SCOPE.md` deliberately answer different questions. Intent is a
design artifact: what the repository is supposed to become or provide. Scope is
a derived current-state artifact: what the repository is understood to provide
after evidence and review. A good `SCOPE.md` is valuable context, but using it
as ordinary evidence for generated characteristics creates a circular model.
Rebuilds should therefore prefer `INTENT.md`, product documentation, source, and
tests; `SCOPE.md` should be used as comparison material or explicit bootstrap
input only when a curator chooses that mode.
For repositories that already have a useful `SCOPE.md` but no `INTENT.md`,
repo-scoping can perform a one-time bootstrap by copying the scope text into a
new intent file with a clear provenance note. After that bootstrap, the files
should diverge naturally: `INTENT.md` remains design intent, while `SCOPE.md`
remains generated or curated current scope.
Source references point from interpreted claims back to files or facts.