[P1] Add evidence-backed context resolution for memory, research, repo state, and design authority

lost-rob0t commented

2026-08-17 06:55:41 +00:00

(Migrated from github.com)

Goal

Implement the context-resolution pass for #68/#69. Before prompt/workflow compilation, resolve the evidence and authority needed to understand the task rather than compiling against stale conversational assumptions.

Required resolution order

The resolver must be able to represent and orchestrate these input classes:

relevant durable/user/project memory;
relevant research repositories and research records;
target repository live state for implementation work;
applicable repository instructions/agent contracts;
open PRs/issues/recent commits/CI/review state when material;
current source/tests/public APIs;
ADR/ADARD/design/specification/architecture records when present and relevant.

Research inspection is an explicit pre-compilation stage. Design discovery is mandatory for implementation workflows when an appropriate design authority may exist.

Authority semantics

Resolved context must carry provenance and authority class. At minimum distinguish:

operator requirement;
durable memory;
research finding;
repository observation;
design/spec authority;
model inference;
verifier/runtime evidence.

Do not silently flatten all inputs into equal-confidence prompt text.

Default precedence must support the invariant that current observed source/tests/repository state override stale remembered behavior. Dedicated project research/design authority must not be replaced by tutorial prose.

Proposed API

Provide host-facing predicates equivalent to:

context_resolution_spec(+TaskIR, +Options, -Spec).
context_resolve_async(+Spec, -Future).
context_resolve(+Spec, -Outcome).
context_fact(+ResolvedContext, ?Fact).
context_authority(+ResolvedContext, ?Source, ?Authority).
context_conflict(+ResolvedContext, ?Conflict).
design_candidate(+ResolvedContext, ?DesignRef).

Follow #54: one canonical async path for latency-bearing connector/tool/provider/repository operations, with sync awaiting the same task.

Exact external retrieval adapters belong behind capability-gated tool/MCP boundaries. This issue defines the resolver/control contract; it must not add ambient GitHub/filesystem/network authority.

Durable-state integration

Use rlm_artifact for immutable/versioned resolved-context snapshots and source references so fresh reasoning roots can consume compact authoritative context without inheriting the exploratory transcript.

A later re-resolution may supersede an older snapshot, but the old snapshot remains inspectable and provenance-preserving.

Design discovery

The resolver must support searches for repository-local authority such as:

AGENTS.md and nested instruction files;
ADR/ADARD records;
design/, architecture/, spec/, docs/ records;
issue/PR-attached design decisions when repository-local authority uses them.

Do not assume such a file exists. Report none_found distinctly from not_checked and from conflicting_candidates(...).

Acceptance

Context resolution is explicit and inspectable rather than hidden prompt preprocessing.
Every material fact carries provenance/source class.
Stale remembered state can be overridden by newer repository observation without deleting the old provenance.
Research-repository inspection can be required before compilation.
Implementation workflows can require design/ADR/ADARD/spec discovery before execution prompt emission.
none_found, not_checked, inaccessible/error, and conflicting-authority states remain distinct.
Resolved snapshots can be persisted/versioned through rlm_artifact and handed to fresh roots by reference.
Retrieval uses explicit capabilities; loading/availability never implies authority.
Deterministic fixture tests cover stale-state reconciliation, competing authorities, missing design, multiple design candidates, and provenance preservation.

Refs #68 #69 #54 #56 #57

## Goal Implement the context-resolution pass for #68/#69. Before prompt/workflow compilation, resolve the evidence and authority needed to understand the task rather than compiling against stale conversational assumptions. ## Required resolution order The resolver must be able to represent and orchestrate these input classes: 1. relevant durable/user/project memory; 2. relevant research repositories and research records; 3. target repository live state for implementation work; 4. applicable repository instructions/agent contracts; 5. open PRs/issues/recent commits/CI/review state when material; 6. current source/tests/public APIs; 7. ADR/ADARD/design/specification/architecture records when present and relevant. Research inspection is an explicit pre-compilation stage. Design discovery is mandatory for implementation workflows when an appropriate design authority may exist. ## Authority semantics Resolved context must carry provenance and authority class. At minimum distinguish: - operator requirement; - durable memory; - research finding; - repository observation; - design/spec authority; - model inference; - verifier/runtime evidence. Do not silently flatten all inputs into equal-confidence prompt text. Default precedence must support the invariant that current observed source/tests/repository state override stale remembered behavior. Dedicated project research/design authority must not be replaced by tutorial prose. ## Proposed API Provide host-facing predicates equivalent to: ```prolog context_resolution_spec(+TaskIR, +Options, -Spec). context_resolve_async(+Spec, -Future). context_resolve(+Spec, -Outcome). context_fact(+ResolvedContext, ?Fact). context_authority(+ResolvedContext, ?Source, ?Authority). context_conflict(+ResolvedContext, ?Conflict). design_candidate(+ResolvedContext, ?DesignRef). ``` Follow #54: one canonical async path for latency-bearing connector/tool/provider/repository operations, with sync awaiting the same task. Exact external retrieval adapters belong behind capability-gated tool/MCP boundaries. This issue defines the resolver/control contract; it must not add ambient GitHub/filesystem/network authority. ## Durable-state integration Use `rlm_artifact` for immutable/versioned resolved-context snapshots and source references so fresh reasoning roots can consume compact authoritative context without inheriting the exploratory transcript. A later re-resolution may supersede an older snapshot, but the old snapshot remains inspectable and provenance-preserving. ## Design discovery The resolver must support searches for repository-local authority such as: - `AGENTS.md` and nested instruction files; - ADR/ADARD records; - `design/`, `architecture/`, `spec/`, `docs/` records; - issue/PR-attached design decisions when repository-local authority uses them. Do not assume such a file exists. Report `none_found` distinctly from `not_checked` and from `conflicting_candidates(...)`. ## Acceptance - [ ] Context resolution is explicit and inspectable rather than hidden prompt preprocessing. - [ ] Every material fact carries provenance/source class. - [ ] Stale remembered state can be overridden by newer repository observation without deleting the old provenance. - [ ] Research-repository inspection can be required before compilation. - [ ] Implementation workflows can require design/ADR/ADARD/spec discovery before execution prompt emission. - [ ] `none_found`, `not_checked`, inaccessible/error, and conflicting-authority states remain distinct. - [ ] Resolved snapshots can be persisted/versioned through `rlm_artifact` and handed to fresh roots by reference. - [ ] Retrieval uses explicit capabilities; loading/availability never implies authority. - [ ] Deterministic fixture tests cover stale-state reconciliation, competing authorities, missing design, multiple design candidates, and provenance preservation. Refs #68 #69 #54 #56 #57

lost-rob0t commented

2026-08-18 07:15:49 +00:00

(Migrated from github.com)

Draft PR #92 adds the project-state observation boundary needed by #70 without defining the final project-KB ontology or building a language parser. Static project assertions are resolved by trusted semantic providers over snapshot/revision-bearing project knowledge; planner and verifier fixtures consume the same project-state abstraction.

#70 remains open. The actual project parser/indexer, context acquisition policy, invalidation/re-index implementation, and durable project-context integration still need to land.

Draft PR #92 adds the project-state observation boundary needed by #70 without defining the final project-KB ontology or building a language parser. Static project assertions are resolved by trusted semantic providers over snapshot/revision-bearing project knowledge; planner and verifier fixtures consume the same project-state abstraction. #70 remains open. The actual project parser/indexer, context acquisition policy, invalidation/re-index implementation, and durable project-context integration still need to land.