Add INTENT/SCOPE improvement notes, the Forgejo-backed redesign proposal, and uv.lock.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Assistant: claude-code
Assistant-Model: opus
Assistant-Process: 7458@bnt-lap001
Assistant-Session: 62534cdf-8348-48a7-9c0d-46e0f74c8eae

ImprovementSuggestions.md

@@ -0,0 +1,161 @@
+# Improvement Suggestions
+
+## Purpose
+
+All managed repositories should publish two orientation documents:
+
+- `INTENT.md` describes the repository's stable purpose and direction.
+- `SCOPE.md` describes its current responsibilities, boundaries, and known gaps.
+
+Fabric should use these documents as repository evidence and compare them with
+the structured facts it collects. The comparison should expose drift and
+missing evidence without treating prose as an automatic replacement for
+accepted graph facts.
+
+## Current behavior
+
+Fabric does inspect `INTENT.md` and `SCOPE.md`, but only in a limited way.
+
+The deterministic scanner's `repo-text-metadata` extractor records:
+
+- whether each file exists;
+- its first heading;
+- a small source snippet and provenance anchor.
+
+The optional LLM extraction receives compact README/INTENT/SCOPE signals. The
+graph explorer's semantic attractor feature can also use `SCOPE.md` text to
+estimate whether a repository is associated with topics such as security,
+development, or operations.
+
+Fabric does not currently parse the substantive claims in `SCOPE.md` into a
+structured repository profile, nor does it compare those claims systematically
+with discovered services, interfaces, deployments, capabilities, or ownership.
+Presence and headings therefore do not constitute scope alignment.
+
+## UI provider detection
+
+Fabric should determine whether a repository provides a user interface through
+layered evidence:
+
+1. An explicit `InterfaceDeclaration` with `interface_type: web-ui` is the
+   strongest repository-owned assertion.
+2. A discovered HTTP route, frontend build, deployment manifest, and browser
+   endpoint together form a strong candidate.
+3. Frontend files, static assets, or build tooling alone are weak inferred
+   evidence.
+4. Repository names and prose alone are insufficient.
+
+Every UI candidate should retain its source paths, Forgejo commit, route or
+deployment evidence, authentication details, environment, confidence, and
+review state. Fabric should distinguish "contains frontend code" from
+"provides an intentionally exposed operational or user-facing interface."
+
+The accepted graph representation should be a repository or service providing
+a `web-ui` interface, with the endpoint, deployment, access zone, policy
+authority, and evidence references attached to that interface.
+
+## Proposed structured SCOPE profile
+
+Keep `SCOPE.md` as human-readable plain text, but define a small vocabulary of
+claims that Fabric can extract and compare. The initial profile should cover:
+
+- repository identity and aliases;
+- primary purpose;
+- owned capabilities;
+- provided services and interfaces;
+- consumed dependencies;
+- deployment or infrastructure responsibilities;
+- security responsibilities;
+- explicit exclusions;
+- current gaps and confidence;
+- freshness or last-reviewed date.
+
+The profile can be derived from headings, stable phrases, links, declarations,
+and optionally reviewed LLM extraction. It should be stored as structured
+evidence linked to the exact `SCOPE.md` commit and relevant line or section.
+
+Fabric should not require a rigid machine-readable replacement for the prose.
+The useful contract is a stable set of extractable claims with explicit
+confidence and review state.
+
+## Alignment analysis
+
+For each repository, Fabric should compare the SCOPE-derived profile with
+accepted structured facts.
+
+Examples of alignment checks:
+
+| SCOPE claim | Structured comparison |
+|---|---|
+| Provides a web UI | Accepted `web-ui` interface or reviewed UI candidate exists |
+| Does not provide a UI | No accepted UI, or a contradiction requiring review |
+| Owns a capability | Capability declaration or accepted discovered capability exists |
+| Deploys or operates infrastructure | Deployment, host, cluster, or automation evidence exists |
+| Consumes a platform service | Dependency or observed integration exists |
+| Explicitly excludes a responsibility | No accepted fact contradicts the exclusion |
+| Current gap is recorded | Corresponding unresolved or review item exists |
+
+The result should classify each claim as:
+
+- `aligned`;
+- `missing_evidence`;
+- `contradicted`;
+- `ambiguous`;
+- `stale`.
+
+An alignment report should include the SCOPE commit, structured snapshot
+identity, claim text or normalized claim, comparison result, and source links.
+It should be available both per repository and in the combined graph's
+unresolved review view.
+
+## INTENT versus SCOPE
+
+`INTENT.md` and `SCOPE.md` serve different roles. Intent is aspirational and
+stable; scope is current and evidenced. Fabric should therefore avoid declaring
+an intent mismatch merely because the current graph does not yet implement the
+full aspiration.
+
+Useful checks include:
+
+- intent describes a capability absent from current scope;
+- scope claims a responsibility absent from intent or declarations;
+- scope excludes a responsibility that discovery attributes to the repository;
+- the repository lacks either required orientation file;
+- the files are stale relative to the current Forgejo branch;
+- the files disagree with one another on repository identity or boundary.
+
+These are review signals and documentation-quality facts. They should not
+silently mutate ownership or financial Fabric membership.
+
+## Forgejo-backed operation
+
+When Fabric moves to Forgejo-backed scanning, `INTENT.md` and `SCOPE.md` should
+be read at a selected Forgejo commit rather than from a local checkout. The
+evidence record should contain:
+
+- Forgejo instance and repository identity;
+- branch, tag, or commit SHA;
+- path and content digest;
+- section or line anchor when available;
+- extractor and tool version;
+- extraction confidence and review state.
+
+Fabric stores the extracted claims and hashes, not complete source content.
+Forgejo remains the source for the prose itself.
+
+## Suggested implementation order
+
+1. Make `INTENT.md` and `SCOPE.md` required inventory checks for managed repos.
+2. Add a repository orientation evidence record to discovery snapshots.
+3. Add deterministic extractors for UI declarations, routes, frontend markers,
+   deployment exposure, and explicit scope claims.
+4. Add a normalized SCOPE claim vocabulary and alignment report.
+5. Add contradiction and stale-evidence review artifacts.
+6. Add Forgejo commit-scoped source retrieval for the orientation files.
+7. Project accepted UI facts and alignment status into the financial graph and
+   graph explorer.
+
+The first useful milestone is a per-repository report that answers: which UI
+surfaces the repository claims or appears to provide, which structured evidence
+supports that conclusion, whether `SCOPE.md` agrees, and what remains for
+human review.