Plan agentic hierarchy generation

2026-05-15 22:01:24 +02:00
parent 855f7fef7c
commit f63287a087
1 changed files with 215 additions and 0 deletions
--- a/workplans/RREG-WP-0018-agentic-hierarchy-and-intent-scope-review.md
+++ 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.