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.