diff --git a/workplans/RREG-WP-0018-agentic-hierarchy-and-intent-scope-review.md b/workplans/RREG-WP-0018-agentic-hierarchy-and-intent-scope-review.md new file mode 100644 index 0000000..c556d20 --- /dev/null +++ b/workplans/RREG-WP-0018-agentic-hierarchy-and-intent-scope-review.md @@ -0,0 +1,215 @@ +--- +id: RREG-WP-0018 +type: workplan +title: "Agentic Hierarchy And Intent/Scope Review" +domain: capabilities +repo: repo-scoping +status: active +owner: codex +topic_slug: foerster-capabilities +created: "2026-05-15" +updated: "2026-05-15" +state_hub_workstream_id: "83df7082-789f-440e-b7a8-d1f8ecd01cc6" +--- + +# Agentic Hierarchy And Intent/Scope Review + +The Railiance and related repository datasets exposed a gap in the current +generation pipeline. Deterministic scanning produces useful facts and content +chunks, but most repositories without an `INTENT.md` stop at a single candidate +ability and do not produce candidate capabilities, features, or evidence. The +dependency graph then appears empty because it only renders edges from approved +characteristics; it does not yet render fact-only, candidate, or partial +hierarchies. + +This workplan shifts the next improvement from deterministic acceptance toward a +reviewable agentic support layer. Deterministic scanners should continue to +produce transparent facts and formal rejection signals. Agentic generation should +stand in for the human abstraction step: deriving features, capabilities, +abilities, and draft scope from facts, source-linked text, and existing +`SCOPE.md` content when present, while keeping every result reviewable. + +## Dataset Assessment + +The current `var/repo-scoping.sqlite3` dataset contains eight repositories. The +new non-repo-scoping repositories all completed analysis, but only +`ops-warden` produced a candidate capability and feature. Railiance repos mostly +produced one candidate ability, zero candidate capabilities, zero candidate +features, and zero candidate evidence. + +Observed patterns: +- `repo-scoping`: complete approved hierarchy and dependency graph + (`92` nodes / `241` edges). +- `railiance-cluster`, `railiance-infra`, `railiance-apps`, + `railiance-platform`, `railiance-enablement`, and `vergabe-teilnahme`: + facts and content chunks exist, but no lower candidate hierarchy is produced. +- `ops-warden`: interface facts produce one generic capability and feature, but + the ability name is polluted by template README text instead of the specific + `SCOPE.md` one-liner. +- Repositories with rich `SCOPE.md` files already contain useful one-liners, + relevant/not-relevant boundaries, related repos, entry points, and + `Provided Capabilities` blocks, but those are currently treated as + `derived_scope` facts and not promoted into candidate capabilities. +- Repositories without `INTENT.md` need a proposed intent draft, not an + automatic source-file mutation. The draft should be an ambitious design-intent + version of the abstracted current scope and should require review before it is + written. + +## T01: Capture Sparse-Hierarchy Dataset Baseline + +```task +id: RREG-WP-0018-T01 +status: todo +priority: high +state_hub_task_id: "dd00a642-7c69-4ae2-b7ac-954c31a1c72a" +``` + +Create a repeatable local assessment command or artifact that summarizes each +repository's latest run across facts, content chunks, candidate layers, approved +layers, document presence, and dependency graph element counts. + +Acceptance criteria: +- The Railiance/ops/vergabe dataset can be compared before and after generation + changes without relying on screenshots or manual DB inspection. +- The report distinguishes approved, candidate, draft, and fact-only graph + coverage. +- The report flags suspicious abstraction quality issues such as template README + contamination and empty lower layers despite rich `SCOPE.md` content. + +## T02: Generate Candidate Hierarchies From Facts And Scope Text + +```task +id: RREG-WP-0018-T02 +status: todo +priority: high +state_hub_task_id: "01eb03da-7a0e-4e22-ae2d-7596752d178e" +``` + +Extend generation so a repository can get candidate features, capabilities, +abilities, and draft scope even when no `INTENT.md` exists. Existing `SCOPE.md` +content may be used as review input for current-state candidates, but it should +remain labeled as derived/current scope rather than design intent. + +Acceptance criteria: +- `SCOPE.md` `Provided Capabilities` blocks become source-linked candidate + capabilities/features when present. +- `One-liner`, `Core Idea`, `Relevant When`, `Not Relevant When`, related repo, + and entry point sections contribute to candidate ability/scope drafts without + being auto-approved. +- Configuration, manifest, Makefile, Helm/Kubernetes, Terraform, Ansible, CLI, + and test facts can produce concrete feature candidates rather than stopping at + a generic ability. +- Candidate naming prefers repo-specific scope/readme evidence over template + boilerplate such as `repo-seed`. + +## T03: Add Agentic Draft Generation Layer + +```task +id: RREG-WP-0018-T03 +status: todo +priority: high +state_hub_task_id: "fd572f4d-d2f6-4c85-bbf5-f77829fd6e6a" +``` + +Introduce an agentic generation step after deterministic facts and before human +approval. The agent should receive facts, source-role metadata, content chunks, +and deterministic candidate seeds, then propose a grounded draft hierarchy. + +Acceptance criteria: +- Agentic generation can fill missing abstraction levels from facts and source + text, including scope when no reviewed scope exists. +- Every agentic draft carries source references and a rationale explaining how + the abstraction was derived. +- The agentic step does not write `INTENT.md`, does not auto-approve registry + truth, and does not bypass quality gates. +- Failures or unavailable agent configuration leave deterministic facts and + candidates intact with an explicit review decision. + +## T04: Review And Edit INTENT.md / SCOPE.md Drafts + +```task +id: RREG-WP-0018-T04 +status: todo +priority: high +state_hub_task_id: "286d96e0-ec5a-4a55-bb50-62d20ab25830" +``` + +Add review surfaces for repository `INTENT.md` and `SCOPE.md` without mutating +source files automatically. If `INTENT.md` is missing, produce a proposed intent +draft as an ambitious design-intent version of the abstracted current scope. + +Acceptance criteria: +- Users can view existing `INTENT.md` and `SCOPE.md` content from the checkout. +- Users can review, edit, diff, and explicitly apply generated drafts. +- Missing `INTENT.md` produces a draft artifact with provenance, not an + automatic file write. +- Draft intent is clearly separated from current scope: intent describes desired + utility; scope describes current understood behavior. +- SCOPE updates remain reviewable and do not overwrite user files without an + explicit write action. + +## T05: Make Dependency Graph Work For Partial Hierarchies + +```task +id: RREG-WP-0018-T05 +status: todo +priority: high +state_hub_task_id: "80bc671c-2361-47e5-8135-7c945de66437" +``` + +Dependency graph generation should degrade gracefully when approved abilities, +capabilities, or features are absent. It should be able to show facts, +candidate entries, draft scope/intent nodes, and partial hierarchy edges. + +Acceptance criteria: +- Repositories with facts never render as an empty dependency graph solely + because approved characteristics are missing. +- Graph nodes are visibly labeled as approved, candidate, draft, or fact-only. +- Candidate and draft edges use distinct dependency types from approved truth. +- The graph supports partial chains such as `fact -> candidate feature`, + `fact -> candidate capability`, `candidate capability -> candidate ability`, + and `candidate ability -> draft scope`. +- Existing approved dependency graph behavior remains stable for repo-scoping. + +## T06: Transparent Quality Criteria For Generated Abstractions + +```task +id: RREG-WP-0018-T06 +status: todo +priority: medium +state_hub_task_id: "4b74a058-b759-42d2-a243-7134dd907093" +``` + +Add reviewable quality criteria that apply to generated features, +capabilities, abilities, scope drafts, and intent drafts. + +Acceptance criteria: +- Criteria cover source grounding, native utility, abstraction coherence, + sibling-repo boundary awareness, template contamination, and scope-vs-intent + separation. +- Criteria can invalidate or downgrade generated items before review, but do not + deterministically accept them as truth. +- Criteria outcomes are exposed in API/UI reports and assessment artifacts. +- Railiance layer boundaries are treated as evidence for review, not as + automatically accepted architecture claims. + +## T07: Re-Run And Compare The Dataset + +```task +id: RREG-WP-0018-T07 +status: todo +priority: medium +state_hub_task_id: "cd1a3c14-076b-42da-8319-48310a964611" +``` + +After implementation, rerun the current repository dataset and compare the new +results against the sparse baseline. + +Acceptance criteria: +- Each Railiance repo has source-linked candidate capabilities/features or a + documented reason why generation withheld them. +- `ops-warden` and `vergabe-teilnahme` no longer prefer template README text + over repo-specific evidence. +- Dependency graph element counts are non-zero for repositories with facts. +- The comparison report makes it easy to judge whether the new result is better + than the previous sparse output.