feat(ITC-WP-0017): establish AgenticDrivesFunctional pattern

Assistant: codex
Assistant-Model: gpt-5.6-sol
Assistant-Session: 01a025c2-407a-7a32-b40a-f37a52f03f62

infospace/patterns/AgenticDrivesFunctional.md

@@ -0,0 +1,369 @@
+---
+id: practice-pattern/agentic-drives-functional
+title: AgenticDrivesFunctional
+type: practice-pattern
+scheme: practice-pattern/0.1
+status: active
+version: "0.1"
+summary: Use agentic cross-repository work as a demand sensor, then turn repeated stable demands into direct functional interfaces.
+aliases:
+  - Agentic Demand-to-Interface Loop
+  - Cross-Repo Demand Compiler
+uses:
+  - model/capability
+  - model/governance
+  - model/observability
+  - model/task
+related_patterns:
+  - practice-pattern/interface-deprecation-strangler
+known_uses:
+  - repo-manager-scoped-identifier-registrar
+owned_concepts:
+  - AgenticDrivesFunctional
+  - AgenticFallback
+  - DemandSignature
+  - FunctionalInterfaceCandidate
+---
+
+# AgenticDrivesFunctional
+
+## Intent
+
+Use agentic cross-repository communication to discover and refine missing
+capabilities, but do not let recurring agent-to-agent work become a permanent
+pseudo-interface. When a stable demand repeats, give its owner a direct API,
+CLI, MCP, or equivalent functional surface so callers can obtain the result
+without carrying a to-do across coding-agent sessions.
+
+The recurring review question is:
+
+> Can we provide the tasks we need do for others as interfaces they can use
+> directly?
+
+Here, *functional* means an interface that directly provides the required
+service capability. It does not refer to the functional-programming paradigm.
+
+## Context
+
+Use this pattern where repositories have distinct ownership and their worker
+agents can exchange suggestions, requirements, tasks, or workplans. A caller
+sometimes needs a result owned by another repository and cannot obtain it from
+an existing service API, CLI command, MCP tool, or other discoverable direct
+surface.
+
+The demand may initially be too novel or ambiguous to justify an interface.
+The target repository's worker can interpret it when that repository next
+handles open work. Over time, similar requests may reveal a stable service
+capability that callers should no longer need an agent to relay.
+
+## Problem
+
+Cross-repository work records are exceptionally flexible: they preserve an
+unresolved need until the right owner can interpret it. That flexibility has a
+high marginal cost. Every relay adds queue time, context reconstruction, agent
+turns, tokens, status checks, and opportunities to lose constraints. When a
+third party must approve part of the work, the to-do and its approval state may
+be carried through several sessions without producing the result.
+
+Building an interface for every first request is not a solution. The first
+request may be exceptional, its inputs and outputs may still be unclear, and a
+premature contract creates maintenance and security obligations. The practice
+must use agentic work to learn the right interface, then recognize when the
+learning channel has become repetitive overhead.
+
+## Forces
+
+- Novel demands need interpretation, negotiation, and repository-owner
+  judgment before their contract is known.
+- Frequent demands need low latency and predictable cost.
+- The target repository owns its capability, security policy, and compatibility
+  obligations; a caller cannot define these unilaterally.
+- Request text varies even when the desired outcome is semantically the same.
+- An interface built from one anecdote can fossilize the wrong abstraction.
+- A work-record queue tolerates exceptions well but scales poorly as a routine
+  integration surface.
+- APIs, CLIs, and MCP tools have development, documentation, versioning,
+  observability, and support costs.
+- Authorization, credential custody, destructive-action confirmation, and
+  third-party approval remain necessary even when the surrounding work is
+  automated.
+- Approvals often outlive one agent session and therefore need durable,
+  queryable state rather than conversational memory.
+- The cheapest interface may expose only the stable preparation, validation,
+  status, or evidence steps while retaining a governed human decision.
+
+## Solution
+
+Therefore, treat agentic cross-repository work as a metered fallback and demand
+sensor, and compile repeated stable demand into a direct functional interface:
+
+1. Search the owner's published API, CLI, MCP, capability, and reuse surfaces
+   before creating cross-repository work.
+2. If no adequate direct surface exists, route a typed record to the owning
+   repository. Use a suggestion for an uncertain opportunity, a requirement
+   for a needed outcome or constraint, and a task or workplan only after the
+   owner accepts implementation work.
+3. Preserve the request's provenance, desired outcome, inputs, constraints,
+   urgency, and approval or authority boundary. Do not prescribe an
+   implementation that belongs to the target owner.
+4. Have the owner classify each inbound request by a semantic demand signature:
+   desired capability, input shape, output or effect, authorization context,
+   approval needs, and important quality constraints.
+5. Review recurring demand signatures. Repetition triggers an interface review,
+   not automatic implementation. Consider frequency, number of callers,
+   stability, latency, token cost, failure rate, approval handoffs, and the cost
+   of maintaining a contract.
+6. Extract the stable functional core into the narrowest suitable direct
+   surface. An API fits service-to-service calls, a CLI fits local or operator
+   workflows, and MCP fits tool-mediated agent use. A combination may share one
+   underlying capability contract.
+7. Keep governed boundaries explicit. The interface may validate, plan,
+   estimate, request approval, report approval state, execute an already
+   authorized operation, and return evidence. It must not invent authority,
+   expose credentials, or bypass a third party's approval.
+8. Publish the interface with ownership, contract, examples, error semantics,
+   authorization requirements, and discovery metadata. Migrate known callers
+   and direct new callers to it.
+9. Meter both direct use and continued agentic fallback. Retain the fallback for
+   novel or exceptional cases, while phasing out the repetitive request shape
+   when evidence shows the interface satisfies it.
+
+The goal is not to eliminate agentic collaboration. It is to reserve that
+expensive, general mechanism for ambiguity and change rather than routine
+execution.
+
+## Structure
+
+```text
+Caller repository
+  -> discover direct surfaces
+       -> adequate: call functional interface
+       -> missing: route typed cross-repo demand
+                      |
+Target repository worker
+  -> interpret and deliver the exceptional request
+  -> record semantic demand signature + cost + approval boundary
+                      |
+Demand review
+  -> novel/unstable: retain agentic fallback
+  -> repeated/stable: define functional interface candidate
+                      |
+Owned API / CLI / MCP capability
+  -> direct result, durable approval state, and evidence
+  -> meter use and remaining fallback
+```
+
+The caller owns a clear statement of need. The target repository owns the
+capability and interface. The approving party retains approval authority. The
+demand review connects observations to an interface decision.
+
+## Dynamics
+
+### 1. Discover before routing
+
+The caller first looks for a supported direct surface. This makes published
+interfaces the normal path and prevents stale agent habits from generating
+unnecessary tasks.
+
+### 2. Route and learn
+
+When the surface is absent, the caller sends the smallest typed demand record
+that preserves the need. The target worker resolves or refines it during its
+normal intake cycle and records the semantic demand signature. The work record
+is both coordination and evidence of an interface gap.
+
+### 3. Detect recurrence
+
+At an owner-defined cadence, the target reviews semantically equivalent
+requests rather than matching titles literally. Recurrence across time or
+callers, repeated approval relays, high latency, or disproportionate token cost
+can justify an interface candidate. Each repository declares thresholds suited
+to its traffic; no universal occurrence count is implied.
+
+### 4. Extract the stable core
+
+The owner separates routine mechanics from judgment. Stable validation,
+planning, execution, status, and evidence become callable operations. Novel
+policy choices and exceptional negotiation remain agentic. Where third-party
+approval is unavoidable, the interface makes the approval request and state
+durable but leaves the decision with the authorized party.
+
+### 5. Shift traffic and keep learning
+
+Known callers adopt the new surface. Direct-use and fallback observations show
+whether the abstraction is right. A fallback request with a new shape refines
+the interface or remains an exception; repeated old-shape requests indicate a
+discovery, usability, or coverage problem.
+
+### 6. Strangle the repetitive relay
+
+Once the direct interface is verified, use the evidence and staged guidance of
+`InterfaceDeprecationStrangler` where appropriate to stop accepting the old
+repetitive route as normal work. Keep an explicit path for genuinely novel
+demands.
+
+## Invariants
+
+1. Callers try an adequate discoverable direct interface before routing work to
+   another repository.
+2. A cross-repository demand identifies the owning repository and preserves
+   provenance, outcome, constraints, and authority boundaries.
+3. Target owners classify recurrence by semantic outcome, not wording alone.
+4. Repetition creates a review obligation, not an automatic obligation to
+   publish an interface.
+5. The target repository owns the extracted capability contract and its
+   lifecycle.
+6. The direct surface performs or returns the recurring function; merely
+   automating creation of the same task is not functional extraction.
+7. No task, API, CLI, or MCP call transfers authority that the caller does not
+   possess.
+8. Credentials and sensitive approval material remain in their governed
+   custody boundary.
+9. The interface exposes durable status and evidence when execution or approval
+   is asynchronous.
+10. Novel and exceptional requests retain a supported agentic path.
+11. Interface and fallback observations are sufficient to decide whether to
+    expand, correct, retain, or retire either path.
+
+## Evidence
+
+The practice should produce privacy-bounded evidence for:
+
+- the direct surfaces checked before routing;
+- typed inbound records and their owning repository;
+- semantic demand signatures, occurrences, distinct callers, and time span;
+- queue-to-result latency, agent turns or estimated token cost, retries, and
+  failure outcomes;
+- approval handoffs and time spent awaiting authorized decisions;
+- the interface-candidate decision and locally chosen threshold or rationale;
+- the stable input, output, effect, error, authorization, and evidence contract;
+- adoption by known callers and direct-interface usage;
+- continued fallback, classified as coverage gap, discoverability problem,
+  exceptional demand, or caller migration debt; and
+- the decision to expand, hold, redesign, or phase out a repetitive path.
+
+Evidence should support an economic and operational judgment. Token count alone
+does not prove an interface is worthwhile, and request frequency alone does not
+prove the requested operation is safe to automate.
+
+## Consequences
+
+Repeated cross-repository work becomes faster, cheaper, more predictable, and
+less dependent on coding-agent continuity. Repository owners learn interface
+requirements from observed demand rather than speculation. Approval waiting
+can become durable and queryable, reducing repeated explanation without
+weakening the approver's control.
+
+The cost is demand classification, metering, interface design, documentation,
+compatibility management, and ongoing ownership. Some requests will remain too
+rare or judgment-heavy to extract. Running both paths during adoption adds
+temporary complexity, and a poorly chosen interface can encode accidental
+workflow details as a long-lived contract.
+
+## Failure Modes
+
+- **TaskQueueAsAPI:** routine callers permanently create work records instead
+  of receiving the function they need.
+- **TaskCreationFacade:** a new API only creates the same downstream task and is
+  presented as functional extraction.
+- **OneRequestPlatform:** an interface is built after one exceptional demand
+  without evidence of stability or recurrence.
+- **LiteralDuplicateCounting:** differently worded instances of the same demand
+  are missed, or similar words with different authority are conflated.
+- **OwnerBypass:** callers dictate or implement another repository's contract
+  without its owner accepting lifecycle responsibility.
+- **ApprovalLaundering:** automation treats a routed task or prior conversation
+  as authorization for a protected operation.
+- **CredentialRelay:** secrets are copied through work records because the
+  interface boundary was designed around convenience rather than custody.
+- **GodInterface:** unrelated recurring requests are combined into an overly
+  broad surface instead of bounded capabilities.
+- **InvisibleInterface:** the owner builds a surface but does not publish it, so
+  agents continue routing tasks.
+- **NoEscapeHatch:** the direct interface replaces the only path for novel or
+  exceptional cases.
+- **UnmeteredMigration:** tasks are closed without evidence that callers use the
+  replacement or that the recurring demand is satisfied.
+
+## When Not to Use
+
+Do not extract a direct interface when demand is genuinely one-off, inputs and
+outcomes are still unstable, the work is principally negotiation or creative
+judgment, or safe execution cannot be bounded by a service contract. Also do
+not delay an obvious, already-defined interface merely to accumulate task
+counts; existing standards, controlled callers, and clear ownership may already
+provide sufficient evidence.
+
+For emergencies, security incidents, or irreversible operations, follow the
+applicable response and approval policy first. The pattern may improve later
+handling, but it does not justify waiting for demand analysis or bypassing a
+required decision.
+
+## Known Uses
+
+### Repo Manager scoped identifier registrar
+
+HelixForge repositories repeatedly needed State Hub work-record UUIDs assigned
+and projected. Coding agents could route the need to the repository or session
+holding registrar authority, but each relay consumed context and could stall on
+the governed mutation boundary.
+
+`repo-manager` extracted the stable operation into
+`rmgr registrar-reconcile`. The command discovers missing workplan and task
+identifiers, checks repository cleanliness and upstream synchronization,
+verifies the authoritative State Hub, serializes registrar use, invokes the
+existing registration adapter, verifies writeback, commits the bounded change,
+and can push it. It does not expose registrar credentials or let an ordinary
+agent impersonate the registrar. Explicit `--confirm-primary` preserves the
+authority-sensitive choice of hub.
+
+This is a concrete demand-to-interface transition: the caller now invokes the
+owned CLI directly and receives structured evidence rather than carrying a UUID
+assignment task across repository agents. `ITC-WP-0017` itself was registered
+through this surface on 2026-08-22.
+
+Implementation references:
+
+- repository: `repo-manager`;
+- command: `rmgr registrar-reconcile`;
+- implementation: `src/repo_manager/commands/registrar_reconcile.py`; and
+- contract: `docs/work-record-uuid-derivation_v1.md`.
+
+### General HelixForge cross-repository routing
+
+HelixForge agents route suggestions, requirements, tasks, and workplans to
+repository owners when no direct surface exists. This is observed use of the
+demand-sensing fallback, not evidence that every routed demand deserves an
+interface. Owners can use the resulting records to identify the next stable
+capability worth extracting.
+
+## Related Patterns
+
+`InterfaceDeprecationStrangler`
+(`practice-pattern/interface-deprecation-strangler`) complements this pattern
+after extraction. `AgenticDrivesFunctional` discovers and establishes the
+successor interface from repeated demand; `InterfaceDeprecationStrangler`
+guides callers, meters remaining use, and gates retirement of the repetitive
+legacy path on evidence.
+
+## Adoption Checklist
+
+- [ ] Publish and make existing API, CLI, MCP, and reuse surfaces discoverable.
+- [ ] Define the typed cross-repository fallback and its ownership rules.
+- [ ] Capture outcome, constraints, provenance, and approval boundaries.
+- [ ] Classify inbound work by semantic demand signature.
+- [ ] Choose a review cadence and locally meaningful candidate criteria.
+- [ ] Compare relay latency and cost with interface lifecycle cost.
+- [ ] Separate stable mechanics from judgment and protected decisions.
+- [ ] Give asynchronous approvals durable status without moving authority.
+- [ ] Publish the narrowest suitable functional surface and examples.
+- [ ] Migrate known callers and meter direct use plus continued fallback.
+- [ ] Preserve an explicit route for novel and exceptional demands.
+- [ ] Record the evidence and decision for expansion, redesign, or retirement.
+
+## Evolution
+
+Version 0.1 names the feedback loop and records Repo Manager's scoped registrar
+as its first complete known use. Further uses should test whether demand
+signatures need a shared machine-readable form and whether repos benefit from a
+common review report for interface-candidate economics.

infospace/patterns/README.md

@@ -12,6 +12,7 @@ frontmatter is described by
 
 | PracticePattern | Status | Purpose |
 | --- | --- | --- |
+| [AgenticDrivesFunctional](AgenticDrivesFunctional.md) | active | Use agentic cross-repo work to discover demand, then extract repeated stable demands into direct functional interfaces. |
 | [InterfaceDeprecationStrangler](InterfaceDeprecationStrangler.md) | active | Phase out an interface through caller guidance, usage evidence, staged retirement, and an evidence-gated removal. |
 
 The older [Intent Scope Purposes Pattern](intent-scope-purposes.md) predates the