Architect Files Contract

1.Two-layer contract — global defines types, local fills the instance

The contract has two layers. The global layer (this files-contract.md) defines the type system; the local layer (each variant's <variant>/config.yaml § manifest) fills in a manifest instance.

The principle: global defines the type system and the manifest schema; local fills in a manifest instance. A file's mechanical rules (which folder, can it be mutated, when is it written) are inherited from its type; the local manifest only adds identity (purpose, shape, who touches it). Adding a new variant file never edits the global contract — you classify it.

2.Folder layout

workspace/                                  # FROZEN inputs — architect NEVER writes
└── architect/exp_profiles/{graph}.yaml      #   per-graph eval profile (an `input` file)

outputs/design_runs/
└── {method}/                                # variant slug: adas-subagent | aflow | myloop | ...
    └── {graph}/                             # one dir per graph this method has worked on
        ├── _archive/                        # method+graph-scoped historical snapshots
        └── v{N}/                            # major version (manual --new-version)
            ├── <vN-scoped files>            # type ∈ {input, working-memory, rollup}
            ├── iteration/
            │   ├── iter_0/                  # baseline (no parent, no mutation)
            │   │   └── <per-iter files>     # type ∈ {mutation, eval-output, phase-artifact, iter-record}
            │   ├── iter_1/
            │   └── ...
            ├── .staging/iter_M/             # bookkeeping — transient pre-commit area
            └── .loop_state/                 # bookkeeping — resume / termination state

• Placement is decided by type, not by filename (see the next section). A skill that wants to know "where does file X go" reads X's type from the variant manifest, then applies that type's placement rule.
• Method-scoped roots: the run-dir root is outputs/design_runs/{method}/{graph}/v{N}/ — each method owns its own tree, nothing is shared across methods (including _archive/).
• Iteration container: per-iter dirs live under v{N}/iteration/iter_{M}/, not directly under v{N}/.
• Backward-compat read rule: pre-migration iters use a flat workspace_snapshot/ instead of active_workspace/; read-only skills try active_workspace/ first, then fall back.

3.The 8 file types

Every file an architect run writes belongs to exactly one of 8 types. A type fixes three mechanical rules — placement (which folder), mutability (can it change after first write), lifecycle (when it is written). The variant manifest classifies its files; it does not restate these rules.

Two boundary notes: lineage pointers (parent.txt, a per-iter graph.json copy, eval_run_id.txt) are not a separate type — they are phase-artifacts written by whichever phase records them; the lineage model is declared once in the manifest. tools/*.py (a variant's self-authored analysis code) is working-memory — placement / mutability / lifecycle all match.

4.The one universal file — active_workspace/

Regardless of the search algorithm, exactly one named file is mandatory for every variant:

It is universal because it is coupled to the framework, not to the search algorithm: the backend's eval API consumes it through the active_workspace_dir field (see §9).

Two further per-iter properties are roles bound in the manifest, not universal files:

• metrics payload — the file holding this iter's eval result. The variant declares which file plays this role (ADAS-family: metrics.json; myloop: record.json).
• lineage — how iter_M finds its parent. The variant declares a lineage model: implicit_linear (parent = iter_{M-1}) or parent_pointer (the parent id is recorded in a variant-declared location — a standalone pointer file, or a field in a phase-artifact's frontmatter).

5.Variant manifest — the local layer

Every variant must ship a manifest: block in <variant>/config.yaml. It is the single source of truth for file identity; file shape stays in the variant's schemas.md (or equivalent), pointed to by each entry's schema: field.

manifest:
  lineage:
    model: implicit_linear        # implicit_linear | parent_pointer
    pointer: <location>           # required iff parent_pointer — a file path,
                                  # or "<file>:<field>" for a frontmatter field
  metrics_payload: record.json    # which file plays the "metrics payload" role (§4)
  files:
    <filename-or-dir>:
      type:       <one of the 8 types>      # required
      purpose:    "<one line — what this file is for>"  # required
      schema:     <pointer, e.g. schemas.md#4>  # optional; omit for trivial files
      mutation:   <append-only|mutable|immutable>  # optional; refines the type default
      written_by: [<skill>, ...]            # access matrix
      read_by:    [<skill>, ...]
  phase_sentinels:
    <skill>:
      needs:  <file produced by the previous phase, or null>
      writes: <file this phase produces>

Global rules attached to the manifest:

• A variant with no manifest: block is non-conformant — understand and validators ERR.
• The manifest is the authoritative source of file identity. A variant's own skills (<variant>/*.md) MAY name their own files directly — they are variant-specific by construction, so this is not a violation. But shared _common/ skills and any cross-variant consumer (validators, a fresh session reconstructing run state) SHOULD resolve file identity through the manifest so they stay correct as variants diverge.
• The manifest classifies files into the §3 types; it does not restate placement / mutability / lifecycle.
• Entry-point skills (experiment / evaluator class) have no needs in phase_sentinels — they may open a fresh iter_{max(M)+1}.

Form-1 default iter is driven by the phase-sentinel table

In phase_sentinels: needs = the file that must exist before this skill starts (proof the previous phase finished); writes = the file this skill produces. The Form-1 default iter is "the latest iter where needs exists and writes does not".

6.Resolve protocol — user input to disk path

Every /architect:* skill uses the same rules to resolve command-line arguments into a (graph, vN, iter_M) triple. Three input forms, mixable.

Form 1 — all defaults

/architect:<skill>

• graph = the most-recent-mtime entry under the skill's graph source
• version = max N of v<N>/; if none, v0
• iter = driven by the variant's phase_sentinels (see §5); entry-point skills default to iter_{max(M)+1}

Form 2 — named flags

/architect:<skill> --graph <name> --version <N> --iter <M>

Any subset; unset slots fall back to Form-1 defaults.

Form 3 — positional

/architect:<skill> <graph> [<version> [<iter>]]

Fixed order, trailing slots optional, but no skipping.

Graph uses fuzzy matching (graph only)

Resolution order: (1) exact; (2) case-insensitive exact with -/space normalised to _; (3) case-insensitive substring.

version / iter accept a bare or prefixed integer (0/v0/iter_3), exact match only — no fuzzy.

Why graph, not nodeset

A nodeset is derived from a graph: each node's <nodeset>__<node> prefix in graph.json already enumerates every nodeset used. An iter is the atomic unit of evolution; one iter may edit several nodesets at once, but there is no "per-nodeset iter" concept.

7.vN versus iter_M

Write-skill version protection: any skill whose phase_sentinels writes is non-empty, plus entry-point skills, refuse to write a non-latest vN without an explicit --allow-old-version. Read-only skills (analyze, report, understand) need no flag. The current version is max(N), derived from the filesystem — no pointer file.

8.Edit whitelist — two boundaries

Write skills are bounded by two edit boundaries of different strength. They differ because the active_workspace/ overlay only covers workspace/{graphs,nodesets}/ — anything outside it has no sandboxed copy.

Hard wall (always BLOCK)

agentcanvas/backend/app/** (framework) and third_party/** (vendored) are never editable. These paths have no overlay: writing them is a real, global, cross-session mutation that also hits the user's :8000 backend. A patch touching them → BLOCKED, surfaced to the user. The overlay cannot save this wall — it does not reach here.

Soft scope (warn, do not block)

Everything under {ITER}/active_workspace/{graphs,nodesets}/ is writable — the overlay sandboxes it, so a bad edit is discarded with the iter and never touches frozen workspace/. The expected scope of one iter is that iter's graph plus the nodesets it uses (the <nodeset>__<node> prefix of each node's type; a nodeset may be a flat <ns>.py, a package <ns>/**, or a server-mode server/<ns>(.py|/**)). A patch touching a graph or nodeset outside that expected scope makes the implementer warn, not block — a nodeset imported transitively by another never appears in any type prefix, is legitimately "off-scope", and must remain editable.

Server-mode nodesets (nodesets/server/**) are editable when the graph uses them (TODO #60, 2026-05-15): an overlay edit to a parallelism="shared" server nodeset triggers an ephemeral auto_host child at eval-admit time.

9.Backend API + the active_workspace bridge

This section looks like a network-protocol note, but it is really the rule that pins the disk file contract to runtime behaviour.

• All skills use /api/eval/v2/{start,status,export,stop}
• Health probe: {BACKEND_URL}/health (not /api/health)
• No stride — episodes run consecutively from start_episode_index

The active_workspace overlay — the contract's "bridge"

POST /api/eval/v2/start
{
  ...
  "active_workspace_dir": "{ITER}/active_workspace"   ← must be an absolute path
}

Every start must include active_workspace_dir so the eval subprocess overlays this iter's mutation set on frozen (frozen → active, last-write-wins). Without it the run uses pure frozen workspace — correct only for an iter with no mutations. POST /api/eval/v2/introspect accepts the same field.

10.Frozen workspace contract

<repo>/workspace/ is the frozen faithful baseline; architect skills never write to it directly. All mutations land in {ITER}/active_workspace/ and the backend overlays them at run time.

Legal writers to frozen workspace

• Canvas UI (/api/canvas/graphs.py) — the human editor
• One-shot user setup scripts (data preprocessing)
• experiment auto-creating a missing workspace/architect/exp_profiles/{g}.yaml on first run (an input file, not method code)

Source-of-truth quick reference