feat(agent): add language-aware repository guidance after v0.4

[styler-ai]

Why

ProjectAtlas can classify and parse many languages, but an agent often needs ecosystem context that syntax alone cannot provide. Fortran modules/includes/preprocessor settings, COBOL copybooks/dialects, and ABAP packages/includes/DDIC/transport context can change where the agent should navigate, what it should trust, and how it should verify a change.

This is a post-v0.4 brainstorm. It must not expand or delay #308 or the v0.4.0 release.

What Changes

• Add versioned, independently gated agent-language profiles on top of the existing language registry and parser/provider facts; do not create a second parser system.
• Enrich existing file summaries, relation navigation, and next-call guidance with compact language-specific context, confidence, coverage, and typed unavailable/ambiguous reasons.
• Evaluate initial profiles for:
  • Fortran: modules, includes, preprocessing, compiler/build flags, and dialect-sensitive behavior.
  • COBOL: copybooks, divisions, dialect/vendor boundaries, data layouts, and build/test entry points.
  • ABAP: packages, classes/function groups, includes, DDIC dependencies, and transport/package context where statically observable.
• Add language-aware task routing so agents can choose the right summary, relation, exact-source, build, and verification path without broad reads.
• Measure representative agent tasks before accepting a profile; abstention is preferable to a confident but unsupported hint.

Capabilities

• Extend the language-intelligence registry with agent-profile capability/state metadata.
• Reuse existing summary, symbol/relation, settings, and packaged-skill surfaces by default.
• Add no MCP tool unless representative tasks prove existing calls cannot express the workflow clearly.
• Preserve parser tier, provider provenance, dialect limits, and exact source selectors in agent-facing output.

Architecture Diagrams

• Optional parser construction, verification, and language-fact publication Mermaid views
• Initial agent task-discovery Mermaid view

The future OpenSpec must add and render a focused Mermaid view for language-profile/build-context ownership before implementation is accepted.

Release Scope

Post-v0.4.0 backlog only. Planning depends on #308 establishing the final language registry, parser/provider, relation, and agent-navigation contracts. Assign a later milestone and create an OpenSpec change before moving this issue to ready. No v0.4.0 code, task, benchmark, or release claim changes are authorized here.

Affected surface: Agent workflow

Agent workflow

overview/folders/files -> language-profile context -> summary or relations -> exact slice/build-context next action -> language-appropriate verification

The profile should reduce wrong-file reads and backtracking while keeping the normal atlas-first funnel and existing compatibility behavior.

Acceptance criteria

• A versioned accepted-profile inventory defines the observable inputs, output fields, confidence/coverage states, invalidation rules, and dialect limits for each supported profile.
• Default behavior remains unchanged when no accepted profile is available; unsupported or ambiguous context returns a typed reason instead of a guess.
• Representative positive, negative, failure, stale-context, and compatibility fixtures cover Fortran, COBOL, and ABAP.
• Build metadata, copybooks/includes, package/module identities, and relation facts retain one authoritative owner and deterministic invalidation.
• Agent evaluations show the profile selects correct sources and verification paths without regressing calls, broad reads, backtracking, output bytes, or correctness against the post-v0.4 baseline.
• Public documentation distinguishes parsing support, semantic/profile support, dialect coverage, and unavailable capabilities without superiority claims.

Non-Goals

• Replacing compilers, language servers, SAP/ABAP systems, or vendor build tools.
• Claiming complete dialect or ecosystem semantics from a grammar alone.
• Running network calls, builds, transports, or source mutations automatically.
• Adding a generic language-plugin framework, a second registry, or speculative per-language MCP tools.
• Changing feat(intelligence): advance Rust-native repository intelligence #308 or the v0.4.0 release scope.

Pre-Mortem

Likely failure modes and planned mitigations to assign to concrete OpenSpec task IDs before implementation:

• Dialect-specific facts are presented as universal truth: require explicit profile/provider identity, confidence, coverage, and abstention.
• Language enrichment bloats every response: keep it bounded and task-selected through existing summary/relation shapes, then measure output and agent outcomes.
• Profiles duplicate parser, graph, or build ownership: derive from existing authorities and reject separately maintained copies.
• Build and enterprise metadata exposes secrets or machine-local paths: allowlist fields, sanitize values, and add adversarial privacy fixtures.
• A wide language matrix ships shallow support: accept profiles independently only after representative task and compatibility proof.

OpenSpec plan and task checklist

OpenSpec change: to be assigned after v0.4.0

OpenSpec Tasks

No implementation tasks are authorized by this backlog brainstorm. Mirror the future OpenSpec checklist here before implementation.

Privacy check

• I removed secrets, tokens, private repository names, and private filesystem paths from this request.