railiance-fabric/ImprovementSuggestions.md

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