one time bootstrap path

docs/characteristic-evidence-model.md

@@ -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.
 

docs/terminology.md

@@ -42,6 +42,20 @@ normalization.
   facts or to lower-level characteristics.
 - Observed fact: deterministic scanner output such as files, manifests,
   languages, tests, APIs, routes, commands, or documentation references.
+- Intent: a design-time statement of expected repository utility. `INTENT.md`
+  is the preferred file for this. It can guide candidate generation because it
+  describes why the repository should exist.
+- Derived scope: a current-state statement of what the repository is understood
+  to provide. `SCOPE.md` is the preferred file for this. It is generated or
+  curated from evidence and approved characteristics, so it should not be used
+  as ordinary evidence for rebuilding those same characteristics.
+- Intent bootstrap: a one-time migration that creates `INTENT.md` from an
+  existing `SCOPE.md` when no intent file exists. The generated file carries a
+  provenance note and should be reviewed as design intent.
+- Source role: provenance metadata on a fact or content chunk, such as
+  `intent_summary`, `derived_scope`, `product_documentation`,
+  `implementation_source`, `dependency_declaration`, `configuration`,
+  `ci_tooling`, `test_evidence`, or `agent_guidance`.
 - Candidate: proposed characteristic or evidence from deterministic heuristics
   or optional LLM assistance. Candidates are review inputs, not registry truth.
 - Approved: curated registry truth that appears in ability maps, search, exports,