Tunet Cognition

Whitepaper / Agent Systems / InfraGlyph

Cross-Repository Lineage for Agentic Software Engineering

A source-grounded design paper on InfraGlyph, a minimal file convention and MCP-facing tool surface for making cross-repository software change propagation explicit to coding agents.

Status

Design and reference implementation paper

Evidence base

Local source repositories only

Scope

No external benchmarks or market claims

Abstract

InfraGlyph is a small agent-oriented software system whose repository describes it as cross-repo lineage and tooling for AI agents, delivered via MCP. Its implementation consists of a Python package, a command-line interface, a stdio JSON-RPC server, workspace discovery and validation logic, markdown lineage rule lookup, and a scoped mechanism for registering and executing Python scripts placed under a workspace-local tools directory. This paper presents InfraGlyph as a design pattern rather than as an empirically validated system: it studies what the current codebase implements, what assumptions are encoded by its file convention, and what limitations remain visible in the source.

The central claim of this paper is intentionally modest: InfraGlyph offers a concrete representation for a class of operational knowledge that is otherwise easy to leave implicit in multi-repository or multi-surface engineering work. That knowledge is lineage: the relation between an initiating change and the other code, configuration, generated artifacts, deployment definitions, and tools that may need to change with it. The current implementation represents lineage as plain markdown files indexed by name and simple keyword search, with a YAML workspace file describing participating code surfaces and roles. The system exposes that knowledge to agents through a fixed set of MCP tools.

This paper does not claim that InfraGlyph improves agent success rates, reduces engineering cost, or outperforms any other system. The available repository contains tests for protocol handling, workspace operations, validation, tool registration, and tool execution. It does not contain controlled user studies, runtime telemetry, benchmark results, or comparative evaluation data. The contribution here is therefore architectural and methodological: a source-grounded account of a minimal lineage layer for agentic software workflows.

Keywords

agent systems; cross-repository workflow; lineage; software engineering; MCP; workspace convention; operational memory; generated code; tool orchestration

1. Source Basis and Method

This paper is written only from local repository material. The primary source is the InfraGlyph repository, including its README, VISION document, Python source files, tests, package metadata, and GitHub Actions workflow. The strategic placement of this paper is based on the Tunet site repository, where Tunet Cognition is described in page copy as model behaviour becoming usable infrastructure and as a home for agent systems, workflows, integrations, execution layers, and skills.

The paper treats implementation files as stronger evidence than aspirational text. The README and VISION files are used to identify intended framing and vocabulary. The source files are used to identify actual mechanisms. The tests are used to identify behaviours that the implementation currently pins down. Where the code does not provide evidence, this paper says so explicitly.

2. Problem Statement

The InfraGlyph README states the motivating problem in terms of change propagation across repositories: when one change is made, other repositories or code surfaces may also need to be updated. The README gives examples such as adding a database table and needing related migrations, backend generation, and possible frontend updates. The current repository does not prove that this problem occurs at any particular frequency, nor does it provide external survey data. It does, however, encode a design response: make cross-surface workflows explicit, local, inspectable, and queryable by an agent.

The problem can be stated without external measurement. In a software workspace with more than one meaningful code surface, some tasks are not fully described by the files immediately edited. A task may require coordination between application code, generated artifacts, infrastructure, deployment workflows, shared packages, and local automation. If that coordination is only remembered by humans, encoded in scattered README files, or discovered through ad hoc search, an agent has no stable interface for asking what else should change.

InfraGlyph's design response is to create a small contract between the workspace and the agent. The workspace declares its parts in `workspace.yaml`. It records cross-surface workflows in `lineage/*.md`. It optionally exposes local scripts through `tools/*.py` and a manifest. The agent queries these through MCP tools rather than having to infer every workflow from raw repository search on each task.

3. Design Objectives Visible in the Codebase

The current implementation indicates five design objectives.

3.1 Locality

InfraGlyph stores its state inside a `.infraglyph` directory under a workspace root. The workspace discovery function walks upward from the current directory until it finds `.infraglyph/workspace.yaml`. There is no database dependency in the implementation.

3.2 Legibility

The workspace file is YAML. Lineage rules are markdown. Tool registrations are JSON. The conventions text exposed by the server instructs agents to use human-readable role names and to write one markdown file per workflow. This makes the representation inspectable without running the server.

3.3 Agent Accessibility

The server exposes a fixed tool list through JSON-RPC methods: initialization, tool listing, tool calls, and ping handling. Tool call results are serialized as JSON text content. The code identifies the server as `infraglyph` and provides tool definitions for workspace inspection, validation, rule listing, lineage lookup, tool listing, tool registration, tool execution, and conventions.

3.4 Bounded Tool Execution

Registered tools must be Python scripts inside `.infraglyph/tools/`. The implementation resolves tool entrypoints and checks that they remain inside the tools directory. It also constrains configured working directories to remain inside the workspace root. The runner supports timeouts and confirmation metadata for tools marked as requiring confirmation.

3.5 Diagnostic Feedback

The CLI includes `scan` and `doctor` commands. The workspace validation logic reports errors, warnings, and informational notes for missing workspace files, malformed YAML, invalid repo lists, missing roles or tags, duplicate roles, unknown role references in lineage files, invalid tool manifests, and missing tool entrypoints.

4. System Model

InfraGlyph's system model contains four primary entities.

4.1 Workspace

A workspace is a filesystem root containing `.infraglyph/workspace.yaml`. The YAML file is expected to include a workspace name and a list of participating paths. Each path may have a role and tags. The implementation validates the shape of this file but leaves role taxonomy open-ended.

workspace: "my-workspace"

repos:
  - path: ./my-db-repo
    role: database
    tags: [postgresql, migrations]

  - path: ./my-api-repo
    role: backend
    tags: [python, fastapi]

The term `repos` appears in the convention, but the validator only checks paths relative to the workspace root. This means the representation can describe true Git repositories, subdirectories in a monorepo, or other bounded code surfaces, provided they are reachable as paths under the workspace root.

4.2 Lineage Rule

A lineage rule is a markdown file under `.infraglyph/lineage/`. Its filename supplies the rule name. The conventions text recommends a human-readable title and an ordered list whose bold text names roles from `workspace.yaml`.

# Add Database Table

When adding a new database table:

1. **database** - Create the table and migration
2. **backend** - Update generation inputs and run code generation
3. **frontend** *(optional)* - Update user-facing UI if applicable

The implementation does not parse the workflow into a formal execution graph. It returns the markdown content to the agent. Validation scans bold role references and warns if a lineage rule refers to a role not present in the workspace file.

4.3 Registered Tool

A registered tool is an entry in `.infraglyph/tools.json` pointing to a Python script inside `.infraglyph/tools/`. Registration metadata includes name, description, legacy argument descriptions, optional JSON schema, entrypoint, working directory, timeout, confirmation requirement, and whether the tool may write files.

The tool runner invokes the current Python executable with the script path and provided CLI arguments. It captures stdout, stderr, and exit code. Timeout expiration is returned as structured data rather than being silently swallowed.

4.4 Agent Interface

The MCP-facing interface is implemented as a stdio JSON-RPC server. It exposes these tools:

  • `infraglyph_conventions`
  • `infraglyph_workspace`
  • `infraglyph_validate_workspace`
  • `infraglyph_list_rules`
  • `infraglyph_what_changes`
  • `infraglyph_list_tools`
  • `infraglyph_register_tool`
  • `infraglyph_run_tool`

This interface does not by itself decide whether a change is required. It gives the agent a stable way to ask for workspace structure, validation state, known workflows, and registered automation.

5. Lineage Lookup

The implementation supports exact and fuzzy lineage lookup. An exact lookup attempts to read `.infraglyph/lineage/{name}.md`. Search uses a simple scoring function over rule names and, when needed, rule content. Exact name matches, substring relationships, word overlap, and content keyword hits contribute to a score. The server returns confidence metadata capped at 100 and may include alternatives.

This lookup method is intentionally simple. It is not semantic retrieval. It has no embedding index, no learned ranker, and no formal ontology. Its benefit is inspectability: the behaviour is easy to read in source. Its limitation is also clear: ambiguous or vocabulary-mismatched queries may miss rules or return weak matches. The current tests cover exact, fuzzy, and no-match cases, but they do not establish retrieval quality under realistic project workloads.

6. Validation as an Agent Safety Primitive

The addition of `infraglyph_validate_workspace` and `infraglyph doctor` makes validation part of the workflow rather than an external maintenance task. This matters because lineage is only useful if its references remain trustworthy. If a rule names a role that no longer exists, or a registered script points to a missing file, the agent should be told before it relies on that instruction.

The validator is conservative. It distinguishes errors from warnings and informational notes. Missing `.infraglyph/` and malformed workspace files are errors. Missing roles and tags are warnings. An empty lineage directory is informational. This classification is not proven optimal, but it is explicit in the implementation and visible to both humans and agents.

7. Tool Execution and Trust Boundaries

InfraGlyph includes a tool runner, but its current implementation does not attempt to sandbox arbitrary code beyond path restrictions, working-directory checks, timeout handling, and confirmation metadata. This is an important limitation. The README states that InfraGlyph trusts scripts placed in the tools folder. The code supports that statement: once a tool is registered and confirmation conditions are satisfied, it is executed as Python on the user's machine.

For this reason, registered tools should be treated as local automation owned by the workspace, not as untrusted third-party plugins. `requires_confirmation` and `writes_files` provide metadata that can help agents behave more carefully, but metadata is not an enforcement mechanism for filesystem writes or network calls inside the script. The runner enforces where the script may be loaded from; it does not enforce what the script may do after it starts.

8. Example Workflow Classes Supported by the Design

The InfraGlyph repository gives generic examples such as adding a database table or deploying a service. The local `micro_horses` repository provides a concrete adjacent example of the same shape, although it is not itself part of the InfraGlyph implementation. It contains multiple applications under `apps/`, shared packages under `packages/`, Terraform infrastructure under `infrastructure/`, GitHub deployment workflows, and a Firebase/Next.js generation pipeline under `tools/generation/firebase_next`. This is the kind of workspace that can be represented by InfraGlyph roles even when the surfaces live in one monorepo.

The following workflow classes are directly supported by InfraGlyph's representation because they can be expressed as markdown lineage rules:

  • Adding a new application surface and remembering root workspace scripts, deployment workflows, runtime secrets, and infrastructure directories.
  • Changing a Firebase blueprint and remembering generated TypeScript types, validators, Firestore repositories, React hooks, API routes, and orphan detection.
  • Changing shared payment logic and remembering app-local configuration, API route handlers, environment examples, deploy workflow secret names, and Secret Manager infrastructure.
  • Deploying a service and remembering application build commands, container startup commands, cloud service names, secrets, and cleanup conventions.

These are not measured outcomes. They are representational examples: the current file convention can store them, the server can return them, and an agent can read them.

9. Reference Implementation

The Python package is declared in `pyproject.toml` as `infraglyph` version `2.0.0`, requiring Python 3.11 or newer and depending on PyYAML. The package exposes a console script named `infraglyph` and supports module execution via `python -m infraglyph`.

The CLI provides four commands:

  • `init`, with optional `--bootstrap`, creates `.infraglyph`, `lineage`, `tools`, and a workspace file.
  • `scan` reports discovered Git repositories and current InfraGlyph state.
  • `doctor` validates the current workspace and exits nonzero when validation fails.
  • `serve` starts the stdio JSON-RPC server.

The test suite covers server protocol handling, tool listing, conventions, workspace discovery, workspace loading, lineage listing and reading, search, tool registration, path traversal rejection, working-directory restriction, confirmation-gated execution, malformed YAML, validation diagnostics, malformed tool manifests, and scanning. At the time this paper was written, the local suite contained 39 tests and passed locally. This is evidence of implementation-level checks, not evidence of field performance.

10. Placement Inside Tunet Cognition

The strategic site defines Tunet Cognition as the area where model behaviour becomes usable infrastructure and where agent systems cover workflows, integrations, execution layers, and skills. InfraGlyph fits the latter category. It is not a model behaviour module like memory, cache, or decoding. It is an agent-system layer: it gives agents a structured way to discover workflow memory and invoke workspace-local tools.

For this reason, the most accurate placement is not under a general engineering utility page alone. InfraGlyph is engineering infrastructure, but its primary user interface is an agent interface. Its public explanation belongs under Cognition because the relevant object of design is not only the developer CLI; it is the coordination boundary between a coding agent and a multi-surface software workspace.

11. Limitations

The current system has several visible limitations.

  • Lineage rules are plain markdown and are not parsed into a formal dependency graph.
  • Search is lexical and simple; it is not semantic retrieval.
  • The tool runner executes local Python scripts and does not sandbox their internal effects.
  • The repository does not include empirical studies, telemetry, user research, or comparative benchmarks.
  • The role taxonomy is intentionally open-ended, which preserves flexibility but can lead to inconsistent naming across workspaces.
  • The system relies on humans or agents to maintain lineage files as workflows evolve.

These limitations are not incidental. They follow from the design choice to keep the system local, small, text-based, and inspectable. Whether that trade-off is appropriate depends on the workspace and the risk of workflow drift.

12. Future Work Grounded in the Existing Design

The current codebase suggests several natural extensions that do not require changing the core premise.

  • A stricter optional schema for lineage rules, while preserving markdown readability.
  • Workspace-specific role linting to reduce naming drift.
  • Dry-run metadata for tools, so agents can preview intended effects before execution.
  • More detailed validation of tool argument schemas.
  • Export of workspace diagnostics as a stable machine-readable report.
  • Example `.infraglyph` workspaces for monorepos and multi-repo systems, clearly marked as examples rather than benchmarks.

None of these extensions are required for the current reference implementation to express lineage rules. They would make the representation more robust and easier to operate at scale.

13. Conclusion

InfraGlyph has merit as a public idea because it names and implements a small missing layer: explicit lineage between a requested software change and the other surfaces that may need to move with it. The present implementation is not a comprehensive orchestration platform and should not be described as one. It is a minimal convention, a validator, a lookup server, and a scoped local tool runner.

The strongest public framing is therefore not novelty of infrastructure. It is operational clarity. InfraGlyph proposes that agentic software engineering needs a workspace-local memory of cross-surface workflows, written in formats humans can read and agents can query. That claim is supported by the design and source code. Stronger claims about productivity, correctness, or market impact should wait for evidence that is not yet present in the repository.

Internal Source Register

This page was drafted from the following local source artifacts only:

  • `infra_glyph/README.md`
  • `infra_glyph/VISION.md`
  • `infra_glyph/pyproject.toml`
  • `infra_glyph/src/infraglyph/cli.py`
  • `infra_glyph/src/infraglyph/server.py`
  • `infra_glyph/src/infraglyph/workspace.py`
  • `infra_glyph/tests/test_server.py`
  • `infra_glyph/tests/test_workspace.py`
  • `strategic_001_tunet/templates/marketing/cognition.html`
  • `strategic_001_tunet/marketing/views.py`
  • `strategic_001_tunet/README.md`
  • `micro_horses/README.md`, `micro_horses/infrastructure/README.md`, and `micro_horses/tools/generation/firebase_next/README.md` as local examples of multi-surface workflow shape