---
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 initial `var/repo-scoping.sqlite3` dataset contained 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: done
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: done
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: done
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: done
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: done
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: done
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: in_progress
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.

## Implementation Update

Implemented the comparison and generation infrastructure needed to rerun the
dataset:
- Added `repo-scoping assess-dataset` to summarize latest runs by facts,
  chunks, candidate/approved hierarchy counts, graph coverage, document
  presence, and sparse-hierarchy quality issues.
- Updated candidate generation so `SCOPE.md` one-liners and `Provided
  Capabilities` blocks seed reviewable current-state abilities/capabilities,
  while deterministic fact fallback now requires stronger configuration facts
  and does not promote dependency-only repositories.
- Added review-only `INTENT.md`/`SCOPE.md` API and UI draft views. Missing
  `INTENT.md` now produces an ambitious draft derived from scope/candidates
  without writing the file.
- Added dependency graph fallback nodes/edges for candidate and draft
  hierarchies so repos with facts no longer render empty just because approved
  characteristics are absent.
- Added transparent quality criteria for template contamination and
  scope-vs-intent separation; deterministic gates can require review but do not
  accept registry truth.

The latest local assessment command currently sees nine repositories because
`vantage-point` has been added. It still reports old sparse Railiance candidate
counts because those stored analysis runs predate this implementation. T07 stays
open until the affected repositories are rerun and compared against the sparse
baseline.