Add repo-scoping comparison assets

2026-05-23 06:07:18 +02:00
parent 03c9aaf3d1
commit 8f4008ec8f
32 changed files with 1530 additions and 74 deletions
--- a/infospace/evaluations/repo-scoping/canon-benefit-analysis.yaml
+++ b/infospace/evaluations/repo-scoping/canon-benefit-analysis.yaml
@@ -0,0 +1,96 @@
+id: comparison/repo-scoping/canon-benefit-analysis
+title: Repo Scoping Canon Benefit Analysis
+status: candidate
+consumer: repo-scoping
+comparison_report: comparison/repo-scoping/report
+direct_reuse:
+  - canon_surface: model/purpose-demand-extension
+    benefit: Distinguishes producer intent, current scope, consumer purposes, demand signals, purpose fit, scope pressure, and evolution requests.
+    repo_scoping_surfaces:
+      - INTENT.md
+      - SCOPE.md
+      - expectation gaps
+      - self-scoping comparison outcomes
+  - canon_surface: model/governance
+    benefit: Provides Decision, Review, Evidence, Risk, Issue, Exception, Approval, and review-cycle vocabulary for candidate acceptance.
+    repo_scoping_surfaces:
+      - ReviewDecision
+      - approved characteristics
+      - rejected candidates
+      - quality-gate overrides
+      - regression outcomes
+  - canon_surface: model/information-space
+    benefit: Provides artifact, source reference, provenance, retrieval, citation, index, and interface-card concepts.
+    repo_scoping_surfaces:
+      - SourceReference
+      - ContentChunk
+      - ObservedFact
+      - SCOPE.md sections
+      - scope-generation API outputs
+  - canon_surface: model/task
+    benefit: Provides work semantics for review tasks, remediation, refactors, rebuilds, recalculation, and follow-up work.
+    repo_scoping_surfaces:
+      - expectation gaps
+      - rebuild dry-runs
+      - dependency impact analysis
+      - self-assessment actions
+  - canon_surface: standard/tagging
+    benefit: Provides lightweight classification vocabulary for primary class, attributes, source roles, and utility relationships.
+    repo_scoping_surfaces:
+      - primary_class
+      - attributes
+      - source_role
+      - utility_relationship
+candidate_mappings:
+  - repo_scoping_concept: Scope
+    canon_mapping: RepositoryScopeProfile
+    fit: extension_needed
+    rationale: Canon has generic Scope, Profile, and Purpose concepts, but repo-scoping needs a source-linked current-state repository utility profile.
+  - repo_scoping_concept: Ability
+    canon_mapping: ProducerCapability
+    fit: partial_fit
+    rationale: Ability is a high-level useful outcome; ProducerCapability is close but should not hide repository-specific abstraction level.
+  - repo_scoping_concept: Capability
+    canon_mapping: CapabilityClaim
+    fit: extension_needed
+    rationale: Repo-scoping capabilities are reviewable utility claims with confidence, evidence, and source references.
+  - repo_scoping_concept: Feature
+    canon_mapping: FeatureClaim
+    fit: extension_needed
+    rationale: Feature is concrete behavior supporting a capability and needs typed evidence links.
+  - repo_scoping_concept: Evidence
+    canon_mapping: EvidenceLink
+    fit: extension_needed
+    rationale: Governance Evidence exists, but repo-scoping needs a link object that can target facts, chunks, files, or lower-level characteristics.
+  - repo_scoping_concept: ObservedFact
+    canon_mapping: SourceObservation
+    fit: extension_needed
+    rationale: Observed facts are deterministic scanner outputs and should not be collapsed into evidence or truth claims.
+  - repo_scoping_concept: ReviewDecision
+    canon_mapping: Decision
+    fit: direct
+    rationale: ReviewDecision is a governance decision over candidate truth, with reviewer, criteria, evidence, and rationale.
+  - repo_scoping_concept: ExpectationGap
+    canon_mapping: Issue / ScopePressure / EvolutionRequest
+    fit: partial_fit
+    rationale: Some gaps are quality issues, some are out-of-scope expectations, and some create purpose-driven evolution requests.
+  - repo_scoping_concept: DependencyImpactAnalysis
+    canon_mapping: ScopeFreshness / PropagationImpact
+    fit: extension_needed
+    rationale: Canon lacks a precise way to express staleness propagation from observed facts to approved utility claims.
+profile_candidates:
+  - id: profile/repository-scope
+    title: Repository Scope Profile
+    purpose: Define minimal artifacts and relationships needed to represent repository intent, current scope, consumer purposes, approved claims, evidence links, decisions, and freshness.
+  - id: profile/scope-md-interface
+    title: SCOPE.md Interface Profile
+    purpose: Define the SCOPE.md section contract, generation ownership, curator-owned sections, and capability block expectations.
+  - id: profile/self-scoping-assessment
+    title: Self-Scoping Assessment Profile
+    purpose: Define golden profile, challenger assessment, known-bad seed, comparison outcome, and regression evidence structures.
+repo_scoping_value:
+  - Better separation of INTENT, SCOPE, and PURPOSES.
+  - Cleaner review semantics for generated candidates and approved truth.
+  - Source-linked evidence model that can become reusable across canon consumers.
+  - Explicit extension path for self-scoping, scope freshness, and scope propagation.
+  - Interface Card fields that repo-scoping can produce for other repositories.
--- a/infospace/evaluations/repo-scoping/comparison-frame.yaml
+++ b/infospace/evaluations/repo-scoping/comparison-frame.yaml
@@ -0,0 +1,90 @@
+id: comparison/repo-scoping/frame
+title: Repo Scoping Canon Comparison Frame
+status: candidate
+consumer: repo-scoping
+comparison_report: comparison/repo-scoping/report
+created_by_workplan: ITC-WP-0009
+source_context:
+  repo: repo-scoping
+  inspected_sources:
+    - INTENT.md
+    - SCOPE.md
+    - docs/terminology.md
+    - docs/scope-md-spec.md
+    - docs/characteristic-evidence-model.md
+    - docs/dependency-aware-scope-propagation.md
+    - docs/self-scoping/README.md
+    - docs/self-scoping/golden/repo-scoping-golden-profile.v1.json
+comparison_domains:
+  - id: repository-intent
+    title: Repository Intent
+    canon_anchors:
+      - kernel/itc-core
+      - model/purpose-demand-extension
+      - pattern/intent-scope-purposes
+    questions:
+      - How does repo-scoping distinguish design-time INTENT.md from generated or curated SCOPE.md?
+      - Which parts of INTENT.md are allowed to seed candidates, and which require review before becoming current scope?
+      - Does repo-scoping need a canonical RepositoryIntentStatement concept distinct from Purpose and Scope?
+  - id: current-scope
+    title: Current Scope
+    canon_anchors:
+      - model/information-space
+      - model/governance
+    questions:
+      - How does the root Scope characteristic represent current repository utility?
+      - Which SCOPE.md sections are generated, curator-owned, or curator-reviewed?
+      - How are in-scope, out-of-scope, relevant-when, and not-relevant-when statements evidenced?
+  - id: future-scope
+    title: Future Scope
+    canon_anchors:
+      - model/purpose-demand-extension
+      - model/task
+      - model/governance
+    questions:
+      - Which expectation gaps indicate possible future scope rather than current truth?
+      - Which requested capabilities should become EvolutionRequests?
+      - How should scope pressure be reviewed before repo-scoping changes its model?
+  - id: consumers-and-purposes
+    title: Consumers And Purposes
+    canon_anchors:
+      - model/purpose-demand-extension
+      - agent/templates/canon-interface-card.template.yaml
+    questions:
+      - Who consumes repo-scoping outputs: humans, agents, State Hub, capability catalog, and managed repos?
+      - Which consumer purposes are served by scope generation, profile comparison, and self-assessment?
+      - Which demand signals should repo-scoping feed back into InfoTechCanon?
+  - id: decisions-and-evidence
+    title: Decisions And Evidence
+    canon_anchors:
+      - model/governance
+      - model/information-space
+      - model/observability
+    questions:
+      - How do ReviewDecision, approved characteristics, rejected candidates, and expectation gaps map to governance decisions?
+      - How do SourceReference, ObservedFact, ContentChunk, and Evidence map to provenance and evidence concepts?
+      - What evidence is required before a generated candidate becomes registry truth?
+  - id: risks-and-regressions
+    title: Risks And Regressions
+    canon_anchors:
+      - model/security
+      - model/governance
+      - model/task
+    questions:
+      - How are known-bad self-scoping outputs represented as regression seeds?
+      - How does repo-scoping prevent provider, dependency, tooling, or mention-only facts from becoming native capability truth?
+      - Which risks should create tasks, quality gates, or governance review?
+  - id: evolution-requests
+    title: Evolution Requests
+    canon_anchors:
+      - model/purpose-demand-extension
+      - model/task
+    questions:
+      - Which canon extension candidates would make repo-scoping more precise?
+      - Which candidates should remain review proposals instead of immediate standard changes?
+      - Which work belongs in repo-scoping and which work belongs in InfoTechCanon?
+comparison_outputs:
+  - comparison report
+  - canon benefit analysis
+  - canon extension candidate set
+  - repo-scoping consumer workplan brief
--- a/infospace/evaluations/repo-scoping/comparison-report.md
+++ b/infospace/evaluations/repo-scoping/comparison-report.md
@@ -0,0 +1,124 @@
+---
+id: comparison/repo-scoping/report
+title: Repo Scoping Canon Comparison Report
+status: candidate
+consumer: repo-scoping
+created_by_workplan: ITC-WP-0009
+source_context:
+  - repo-scoping/INTENT.md
+  - repo-scoping/SCOPE.md
+  - repo-scoping/docs/terminology.md
+  - repo-scoping/docs/scope-md-spec.md
+  - repo-scoping/docs/characteristic-evidence-model.md
+  - repo-scoping/docs/dependency-aware-scope-propagation.md
+  - repo-scoping/docs/self-scoping/README.md
+---
+
+# Repo Scoping Canon Comparison Report
+
+## Summary
+
+Repo-scoping already contains a strong domain model for repository utility:
+
+```text
+Scope -> Ability -> Capability -> Feature -> Evidence -> Observed Fact
+```
+
+InfoTechCanon can help repo-scoping by giving this model clearer boundaries
+around INTENT, SCOPE, PURPOSES, governance decisions, evidence, tasks, source
+roles, and interface cards.
+
+The comparison also exposes canon gaps. The canon has generic concepts for
+Scope, Purpose, Evidence, Decision, Task, and Profile, but it does not yet have
+precise repository-scoping concepts for source-linked current scope, reviewable
+utility claims, evidence links, source observations, utility relationships,
+scope freshness, or SCOPE.md as a markdown interface profile.
+
+## Direct Fit
+
+| Repo-scoping surface | Canon fit | Notes |
+| --- | --- | --- |
+| `INTENT.md` | INTENT / RepositoryIntentStatement candidate | Intent should seed candidate generation but not prove current scope. |
+| `SCOPE.md` | RepositoryScopeProfile candidate | Current-state utility profile derived from evidence and approved claims. |
+| Review decisions | Governance Decision / Review | Acceptance, rejection, edits, overrides, and rationale map cleanly to governance. |
+| Evidence and source references | EvidenceLink candidate / Information Space provenance | Needs typed support links, not just generic evidence. |
+| Expectation gaps | Issue / ScopePressure / EvolutionRequest | Gaps may be defects, exclusions, or requests for future scope. |
+| Self-scoping assessments | Profile / Evidence / Review | Golden profiles and challenger assessments are reusable evaluation patterns. |
+
+## Important Distinctions
+
+### INTENT vs SCOPE
+
+Repo-scoping explicitly treats intent as design-time expected utility and scope
+as derived current-state utility. This is a strong match for the canon
+INTENT/SCOPE/PURPOSES distinction.
+
+The comparison suggests the canon should add a repository-specific
+`RepositoryIntentStatement` candidate so repositories can declare what they are
+trying to provide without making that declaration current truth.
+
+### Evidence vs Observed Fact
+
+Repo-scoping correctly avoids treating deterministic facts as the same thing as
+evidence. A fact is observed source material. Evidence is support for an
+interpreted characteristic. This suggests a canon `SourceObservation` and
+`EvidenceLink` pair.
+
+### Candidate vs Approved Truth
+
+Repo-scoping has a review boundary: candidates are proposals; approved
+characteristics are registry truth. This maps naturally to Governance Decision
+and Review, but the canon should add `CharacteristicClaim` or a profile-specific
+claim concept to preserve the abstraction level.
+
+### Current Scope vs Future Scope
+
+Expectation gaps and self-scoping outcomes can create scope pressure, but they
+should not alter current scope directly. They should create reviewable
+EvolutionRequests or tasks.
+
+## Benefit To Repo-Scoping
+
+Repo-scoping can benefit from the canon by:
+
+- using Canon Interface Cards to declare repo-scoping intent, scope, purposes,
+  produced concepts, consumed concepts, validation expectations, and requested
+  extensions,
+- mapping Scope, Ability, Capability, Feature, Evidence, and Observed Fact to
+  canon-owned or candidate concepts,
+- using Governance Decision and Evidence concepts to make review outcomes more
+  portable,
+- using PURPOSES to capture consumers such as State Hub, agents, managed repos,
+  and humans,
+- using Task and Governance concepts to separate recalculation, review, rebuild,
+  and adoption work,
+- feeding SourceRole and UtilityRelationship as candidate extensions back into
+  the canon.
+
+## Canon Extension Candidates
+
+The candidate set is recorded in
+`evaluations/repo-scoping/extension-candidates.yaml`.
+
+Highest-value candidates:
+
+- `RepositoryIntentStatement`
+- `RepositoryScopeProfile`
+- `CharacteristicClaim`
+- `EvidenceLink`
+- `SourceObservation`
+- `SourceRole`
+- `UtilityRelationship`
+- `ScopeFreshness`
+- `PropagationImpact`
+- `ScopeMdInterface`
+
+These should remain review candidates for now. They are useful enough to guide
+repo-scoping adoption, but they should be hardened through a consumer workplan
+in the repo-scoping repository before changing stable standards.
+
+## Recommended Next Move
+
+Create the actual adoption workplan in repo-scoping. It should complete a Canon
+Interface Card, map repo-scoping concepts to the comparison artifacts, and
+identify which extension candidates are proven by implementation pressure.
--- a/infospace/evaluations/repo-scoping/consumer-workplan-brief.md
+++ b/infospace/evaluations/repo-scoping/consumer-workplan-brief.md
@@ -0,0 +1,61 @@
+---
+id: comparison/repo-scoping/consumer-workplan-brief
+title: Repo Scoping Consumer Workplan Brief
+status: candidate
+consumer: repo-scoping
+comparison_report: comparison/repo-scoping/report
+---
+
+# Repo Scoping Consumer Workplan Brief
+
+## Purpose
+
+Use this brief as the seed for a repo-scoping workplan. The adoption and
+implementation workplan belongs in the repo-scoping repository, not in
+InfoTechCanon.
+
+## Goal
+
+Compare repo-scoping with InfoTechCanon and adopt the canon where it improves
+repository intent, current scope, purposes, governance decisions, evidence, and
+scope evolution.
+
+## Canon Inputs
+
+- `infospace/evaluations/repo-scoping/comparison-report.md`
+- `infospace/evaluations/repo-scoping/comparison-frame.yaml`
+- `infospace/evaluations/repo-scoping/canon-benefit-analysis.yaml`
+- `infospace/evaluations/repo-scoping/extension-candidates.yaml`
+- `infospace/agent/templates/canon-interface-card.template.yaml`
+- `infospace/models/governance/InfoTechCanonPurposeDemandExtension.md`
+- `infospace/patterns/intent-scope-purposes.md`
+
+## Workplan Tasks For Repo-Scoping
+
+1. Complete a Canon Interface Card for repo-scoping.
+2. Map Scope, Ability, Capability, Feature, Evidence, ObservedFact,
+   ReviewDecision, ExpectationGap, and DependencyImpactAnalysis to canon
+   concepts or extension candidates.
+3. Separate design-time INTENT.md semantics from generated or curated SCOPE.md
+   semantics.
+4. Identify consumer purposes for humans, agents, State Hub, managed repos, and
+   capability catalog consumers.
+5. Evaluate extension candidates and mark which are proven, rejected, deferred,
+   or repo-scoping-specific.
+6. Create repo-scoping tasks for schema, API, UI, and documentation changes.
+
+## Expected Outputs
+
+- completed interface card,
+- mapping table from repo-scoping concepts to canon concepts,
+- list of accepted canon concepts,
+- list of extension candidates with evidence,
+- list of repo-scoping implementation tasks,
+- list of canon EvolutionRequests.
+
+## Non-Goals
+
+- Do not modify InfoTechCanon standards from the repo-scoping workplan without a
+  canon-side EvolutionRequest.
+- Do not collapse intent, current scope, and consumer purposes into one field.
+- Do not treat generated candidates as approved truth without governance review.
--- a/infospace/evaluations/repo-scoping/extension-candidates.yaml
+++ b/infospace/evaluations/repo-scoping/extension-candidates.yaml
@@ -0,0 +1,91 @@
+id: comparison/repo-scoping/extension-candidates
+title: Repo Scoping Canon Extension Candidates
+status: candidate
+consumer: repo-scoping
+comparison_report: comparison/repo-scoping/report
+candidate_set_status: review-required
+candidates:
+  - id: extension/repository-intent-statement
+    title: RepositoryIntentStatement
+    proposed_owner: model/purpose-demand-extension
+    change_type: new-concept
+    problem: Intent is currently generic; repo-scoping needs a design-time repository utility statement that can seed but not prove current scope.
+    proposed_definition: A design-time statement of expected repository utility, distinct from current scope and consumer purpose.
+    review_question: Should this be a specialization of Intent or a repository-scoping profile concept?
+  - id: extension/repository-scope-profile
+    title: RepositoryScopeProfile
+    proposed_owner: model/information-space
+    change_type: new-profile
+    problem: Generic Scope does not capture source-linked current-state repository utility and SCOPE.md generation ownership.
+    proposed_definition: A current-state, source-linked profile describing what a repository is useful for, when it is relevant, and which approved claims support it.
+    review_question: Should this be a profile of Information Space, Governance, or a cross-model application profile?
+  - id: extension/characteristic-claim
+    title: CharacteristicClaim
+    proposed_owner: model/governance
+    change_type: new-concept
+    problem: Repo-scoping uses Scope, Ability, Capability, and Feature as reviewable claims rather than merely descriptive tags.
+    proposed_definition: An interpreted, reviewable claim about a repository at a declared abstraction level with confidence, evidence, provenance, and review status.
+    review_question: Should Ability, Capability, and Feature be levels of CharacteristicClaim or separate profile concepts?
+  - id: extension/evidence-link
+    title: EvidenceLink
+    proposed_owner: model/information-space
+    change_type: new-concept
+    problem: Governance Evidence is too coarse for support links that target observed facts, content chunks, files, and lower-level characteristics.
+    proposed_definition: A typed support relation from a claim to a source observation, content chunk, artifact, or lower-level claim.
+    review_question: Should EvidenceLink live in Information Space while Evidence remains Governance/Observability owned?
+  - id: extension/source-observation
+    title: SourceObservation
+    proposed_owner: model/information-space
+    change_type: new-concept
+    problem: Observed facts are deterministic scanner outputs and should not become evidence or truth claims without interpretation.
+    proposed_definition: A source-linked observation extracted from repository content, metadata, or execution results, before review or promotion.
+    review_question: How should SourceObservation relate to Observability signals and Information Space chunks?
+  - id: extension/source-role
+    title: SourceRole
+    proposed_owner: standard/tagging
+    change_type: new-taxonomy
+    problem: Repo-scoping needs stable labels such as intent_summary, derived_scope, product_documentation, implementation_source, dependency_declaration, and agent_guidance.
+    proposed_definition: A tag or classification describing the role a source artifact plays in repository utility evaluation.
+    review_question: Should SourceRole be a tagging profile or part of Information Space provenance?
+  - id: extension/utility-relationship
+    title: UtilityRelationship
+    proposed_owner: model/governance
+    change_type: new-taxonomy
+    problem: Provider, dependency, tooling, mention, owned, facade, and adapter relationships decide whether evidence can become a provided capability.
+    proposed_definition: A classification of how source evidence relates to claimed repository utility.
+    review_question: Should these labels become governance decision criteria for approving capability claims?
+  - id: extension/scope-freshness
+    title: ScopeFreshness
+    proposed_owner: model/task
+    change_type: new-concept
+    problem: Repo-scoping tracks stale downstream claims when observed facts change, but the canon lacks freshness semantics for repository scope.
+    proposed_definition: A state describing whether a scope claim is current, stale, needs recalculation, needs review, superseded, or rejected.
+    review_question: Should freshness be task state, governance review state, or a profile-specific quality signal?
+  - id: extension/propagation-impact
+    title: PropagationImpact
+    proposed_owner: model/task
+    change_type: new-concept
+    problem: Repo-scoping measures propagation breadth and depth from changed facts to approved scope claims.
+    proposed_definition: A traceable impact result showing which claims may be stale because upstream evidence changed.
+    review_question: Can this generalize to other evidence-driven canon consumers?
+  - id: extension/scope-md-interface
+    title: ScopeMdInterface
+    proposed_owner: model/information-space
+    change_type: new-interface-profile
+    problem: SCOPE.md has a stable section contract and machine-readable capability blocks that should be reusable.
+    proposed_definition: A markdown interface profile for repository orientation, generated sections, curator-owned sections, and provided capability blocks.
+    review_question: Should this become an interface-card specialization?
+disposition:
+  recommended_next_step: Create a dedicated Repository Scope Profile workplan after repo-scoping consumer adoption begins.
+  immediate_standard_changes: []
+  hold_for_review:
+    - extension/repository-intent-statement
+    - extension/repository-scope-profile
+    - extension/characteristic-claim
+    - extension/evidence-link
+    - extension/source-observation
+    - extension/source-role
+    - extension/utility-relationship
+    - extension/scope-freshness
+    - extension/propagation-impact
+    - extension/scope-md-interface