[GH-ISSUE #2444] [Design] Source-bound repository context for grounded reconstruction briefs #819

New issue

Open

opened 2026-10-15 18:28:44 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:28:44 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 13, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2444

Contexto

GitReverse shows a useful outcome: turn repository context into a short reconstruction request. Its reviewed snapshot is github.com/filiksyos/gitreverse@20864c6a05; no code or prompt text is proposed for copying from that snapshot, which declares no license.

REA already imports committed historical source graphs. #2442 proposes compact inventory summaries and #2443 exposes caller exclusions. A further context/briefing capability would need README and manifest declarations as source-bound observations rather than unsupported claims about the original user prompt or actual runtime behavior. General finished-investigation Markdown reporting is already discussed in #1142 and should not be duplicated here.

Objetivo

Define an evidence-grounded local repository briefing that an analyst or existing external agent can use to write a reconstruction request, preserving each statement's source and unknowns.

Escopo

Caller-selected local scope, README candidates and manifest files, read through the existing stable/no-follow owner.
Bind admitted text and parsed declarations to exact path, byte digest and source inventory identity.
Distinguish README claims, manifest declarations, static relationships and unverified runtime behavior.
Retain missing, excluded, malformed or multiple README/manifest candidates explicitly; accept caller-selected text bounds and report exact coverage.
CLI/MCP contracts should reuse shared facts and make any retained complete context accessible.
No automatic LLM service, network upload, package installation, build execution, billing service or claim to recover an authentic original prompt.

Critérios de aceite

A maintainer decision settles the useful primitive/briefing surface and overlap with #1142 before a first-party integration.
Owned fixtures cover missing and conflicting declarations, malformed encodings, excluded input and stale source identity.
Every brief assertion references admitted context; absent evidence remains an explicit question.
Public CLI/MCP verification and representative agent-context measurements distinguish actual outcomes from serialized byte counts.

Perguntas para decisão

Should REA expose a reusable repository-context primitive, a deterministic briefing projection, or only an agent workflow around existing source and Evidence operations? README-body retention is not added implicitly to the historical graph format.

Observações técnicas

Use a single domain feature spec under docs/specs/reference-source/grounded-repository-brief/ after that decision. Keep new observations with their owner and reference the existing reconstruction ledgers for runtime closure rather than inventing a second verification system.

Originally created by @matbrgz on GitHub (Oct 13, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2444 [![Type: Architecture / RFC](https://img.shields.io/badge/type-architecture_%2F_RFC-darkred.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Contexto GitReverse shows a useful outcome: turn repository context into a short reconstruction request. Its reviewed snapshot is https://github.com/filiksyos/gitreverse/tree/20864c6a05ea6080a5d25f151919eb19721eea11; no code or prompt text is proposed for copying from that snapshot, which declares no license. REA already imports committed historical source graphs. #2442 proposes compact inventory summaries and #2443 exposes caller exclusions. A further context/briefing capability would need README and manifest declarations as source-bound observations rather than unsupported claims about the original user prompt or actual runtime behavior. General finished-investigation Markdown reporting is already discussed in #1142 and should not be duplicated here. ## Objetivo Define an evidence-grounded local repository briefing that an analyst or existing external agent can use to write a reconstruction request, preserving each statement's source and unknowns. ## Escopo - Caller-selected local scope, README candidates and manifest files, read through the existing stable/no-follow owner. - Bind admitted text and parsed declarations to exact path, byte digest and source inventory identity. - Distinguish README claims, manifest declarations, static relationships and unverified runtime behavior. - Retain missing, excluded, malformed or multiple README/manifest candidates explicitly; accept caller-selected text bounds and report exact coverage. - CLI/MCP contracts should reuse shared facts and make any retained complete context accessible. - No automatic LLM service, network upload, package installation, build execution, billing service or claim to recover an authentic original prompt. ## Critérios de aceite - [ ] A maintainer decision settles the useful primitive/briefing surface and overlap with #1142 before a first-party integration. - [ ] Owned fixtures cover missing and conflicting declarations, malformed encodings, excluded input and stale source identity. - [ ] Every brief assertion references admitted context; absent evidence remains an explicit question. - [ ] Public CLI/MCP verification and representative agent-context measurements distinguish actual outcomes from serialized byte counts. ## Perguntas para decisão Should REA expose a reusable repository-context primitive, a deterministic briefing projection, or only an agent workflow around existing source and Evidence operations? README-body retention is not added implicitly to the historical graph format. ## Observações técnicas Use a single domain feature spec under `docs/specs/reference-source/grounded-repository-brief/` after that decision. Keep new observations with their owner and reference the existing reconstruction ledgers for runtime closure rather than inventing a second verification system.

bsakaguchi added the

area: domain

enhancement

labels

2026-10-15 18:28:44 +00:00

bsakaguchi referenced this issue

2026-10-16 21:16:27 +00:00

[PR #819] [MERGED] refactor: add incremental capability migration safeguards #2264

bsakaguchi added

enhancement

and removed

enhancement