awslabs / awslabs/aidlc-workflows

[Feature]: auditable supplemental-knowledge selection and delivery across stage topologies

Open
#694 0 comments 0 reactions 0 assignees View on GitHub
enhancement rfc
Dominant language
TypeScript
Stars
4.6k
Forks
827
Avg merge
1d 21h
Merged PRs (30d)
165

Description

## Context

#495 and PR #658 (v2.5.33) made required rule delivery deterministic. The engine resolves the active-space rule bundle, emits it as bounded `load-steering` parts, and enforces complete delivery at dispatched-worker boundaries.

Supplemental knowledge still has a different contract. `run-stage.inline_context_paths` inventories framework and active-space knowledge for conductor-owned work, but a present, readable file can still go unread without any receipt. Fully dispatched stages carry no inline roster. Kiro CLI preloads shipped methodology through native `resources`, while other harnesses and active-space team knowledge still depend on agent-directed reads.

This issue is specifically about supplemental knowledge. Dispatched personas already load through harness-native agent definitions, and reviewer checklists are absorbed into reviewer agent bodies at build time. Inline persona content delivery is a separate bounded mechanism problem and should be tracked separately. Kiro IDE native-agent work remains under #555.

## Design boundary

Knowledge is reference material an agent weighs; it is not a mandatory rule. A retrieval tool must therefore guarantee inventory, transport, bounds, integrity, and observability without deciding semantic relevance.

The ownership split should be:

- **Tool:** deterministically catalogs available knowledge, validates requested chunks, returns bounded content, and records integrity-bound delivery receipts.
- **LLM/agent:** selects the knowledge relevant to the current stage and unit of work, or explicitly selects `none` with a rationale.
- **Human/reviewer:** judges whether the selected knowledge and its application were sufficient when that affects an artifact or gate decision.

## Proposed contract

1. Build an active-space knowledge catalog for the executing agent and topology from:
- framework shared knowledge;
- framework agent-specific knowledge;
- active-space shared team knowledge;
- active-space agent-specific team knowledge.
2. Split Markdown at stable heading boundaries and identify each chunk by source path, heading identity, and content hash.
3. Allow stages to declare `required_knowledge` for true hard dependencies, such as a stage-mandated template. Required entries are tool-selected; supplemental entries are not.
4. Have the executing agent request catalog chunk IDs through a deterministic retrieval command, or explicitly record `none` with a rationale.
5. Return content through a bounded transport. Never silently truncate, omit, or claim delivery.
6. Record a receipt bound to the active space, stage, agent, dispatch attempt, catalog hash, selected chunk hashes, and completed delivery.
7. Require a valid receipt before stage completion. An explicit `none` receipt is valid for supplemental knowledge; missing retrieval state is not.
8. Carry the selected content across dispatched-worker boundaries. A harness without a proven delivery channel must report that limitation rather than silently claim success.
9. Preserve `inline_context_paths` as a compatibility bridge during migration.

## Acceptance criteria

- Catalog generation is deterministic and active-space-aware.
- Required knowledge is distinguished from supplemental knowledge.
- Relevance selection remains an agent knowledge decision; there is no opaque semantic retrieval that silently controls context.
- Every selected chunk is delivered completely within documented transport bounds.
- Delivery receipts make selected, delivered, explicitly skipped, and unavailable content distinguishable in stage traces or audit evidence.
- Inline, mob, subagent, and pipeline paths have explicit tested behavior across supported harnesses.
- Existing `inline_context_paths` consumers continue to work during the transition.
- Documentation no longer claims that every harness-native agent definition automatically loads the general knowledge tree.

## Current implementation references

- `core/tools/aidlc-orchestrate.ts`: `inlineAgentsFor`, `inlineContextEntries`, and `inlineContextRoster`
- `core/tools/aidlc-directive.ts`: `RunStageDirective.inline_context_paths`
- `scripts/agent-knowledge.ts`: build-time reviewer-knowledge absorption
- `harness/codex/emit.ts` and `harness/opencode/emit.ts`: native dispatched persona projection
- `harness/kiro/agents/*.json`: Kiro CLI native persona and shipped-knowledge resources
- `tests/unit/t248-steering-content-delivery.test.ts`: current path-roster and warning coverage

Refs: #495, #555, PR #658, CHANGELOG 2.5.33.

Contributor guide

Open the contributing guide

Research direction

Start with core/tools/aidlc-orchestrate.ts and core/tools/aidlc-directive.ts, then inspect tests/unit/t248-steering-content-delivery.test.ts and the harness emitters for current delivery behavior. Done means the proposed catalog, bounded retrieval, receipts, dispatched-worker handling, explicit topology behavior, and inline_context_paths compatibility are implemented and covered across supported paths without silently claiming delivery.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.