Architecture

docs/architecture.md · 16332 B · source sha256 3634667cf956

control-surface is the execution-protocol repo for ASK workflow architecture assets.

on this page

Role Model

ASK projects run an adversarial-collaboration operating model — an ASK-apexed advisor–executor topology. ASK is the source-of-intent and authorization apex, the relay across surfaces, and the final adjudicator. A non-writing advisor surface supplies external challenge, reconstruction, and verification from outside the execution thread. A repo-attached execution surface plans and performs authorized work under AGENTS.md, under single-writer-per-branch discipline. In the current stack a GPT advisor fills the advisor role and Claude Code fills the execution role; model identity is operational, not architectural.

Direct execution is the bounded variant — ASK driving the executor without an advisor pass where a separate pass would not materially reduce uncertainty. It is a proportional path within the same model, not a separate model.

Compactly: multi-surface in reasoning, single-writer in mutation, single-apex in authority.

The methodology layer that articulates the method has graduated upstream to apexSolarKiss/method-ASK. This repo carries the execution-protocol layer that operationalizes the method per session. control-surface sits upstream of downstream project repos while remaining downstream of method-ASK.

An earlier split-execution model, historically Model A, shaped this repo's early design and is retired as a live option; its artifacts remain in the repo and git history as frozen provenance under retired-status headers.

The workflow rules are agent-agnostic; the rules in AGENTS.md apply to whoever is executing.

Two current working examples anchor the family:

apexSolarKiss/design-system-ASK is a distinct kind of surface — an externalized ASK visual / aesthetic-intent implementation. It is the family's upstream visual-inheritance reference surface: the public, repo-shaped carrier of externalized aesthetic intent that child artifacts inherit by reference. Source-of-intent proper remains operator-side; this repo carries the implementation surface. urban-observatory's Example 2 prototype is a downstream inheritance proof. apexSolarKiss/method-ASK/examples/design-system-ASK.md carries the method-altitude account. Not a project pressure surface in the same sense as the two current working examples above.

Layer Map

This repo sits in the middle of a three-tier structure:

  • Methodology layer — adversarial iteration / cross-phase swing discipline. Lives upstream in apexSolarKiss/method-ASK; docs/method.md in this repo is a compact bridge pointing there.
  • Execution-protocol layer — this repo's core purpose. AGENTS.md, the shared protocol carrier (protocol/AGENTS.shared.md, resolved locally into each consumer's own AGENTS.md; protocol/manifest.json; protocol/profiles/; and the protocol/check.sh local validator), templates, review cadence, and branch discipline encode how work gets done within a session.
  • Project repos — applications of the method and protocol to concrete domains. apexSolarKiss/asset-pipeline-ASK is the primary pressure surface for rule evolution; apexSolarKiss/urban-observatory is the second active working example, exercising the protocol repo at the source-of-intent recovery, post-bootstrap grounding-note freshness, and architecture-uncertain instantiation surfaces.

Alongside the project repos, apexSolarKiss/design-system-ASK is the family's upstream visual-inheritance reference surface — an externalized ASK visual / aesthetic-intent implementation, not a project pressure surface. Child surfaces inherit Tier 1 + Tier 2 by reference and resolve Tier 3 (instance identity) locally by source-of-intent + brand-distance. ASK-the-entity carries ASK Tier 3 by identity, but it is not the only surface that may render the ASK wordmark: ASK may assign that Tier-3 value locally to an ASK-family project. The assignment does not make the project ASK-the-entity, and Tier 3 never comes from the shell. urban-observatory carries a downstream inheritance proof. The method-altitude account lives in apexSolarKiss/method-ASK/examples/design-system-ASK.md.

The control-surface repo owns the execution-protocol layer. The methodology layer lives upstream in method-ASK.

An illustrative tree of this architecture and its operator-side ecology is at docs/diagrams/control-surface_architecture-tree.html. The routed-instance lifecycle owned by §Inbound Handoff TBI Marker has its own standalone figure at docs/diagrams/control-surface_intent-inbox-lifecycle.html — the architecture tree carries an intent-inbox group because the tree must show the plane exists, which is a different job. Both diagrams are illustrative; repo prose is source truth.

Source-of-Truth Split

ASK project work uses three durable sources of truth, plus two non-durable surfaces that are not interchangeable:

  • Repo = project state (artifacts, decisions, current navigation)
  • AGENTS.md (in-repo) = workflow rules, agent-agnostic
  • Grounding note (external) = repo-external context (intent, audience, philosophy, foundational premises, durable loose threads)
  • Per-conversation / task state (current chat, task lists, in-flight session context) = ephemeral; does not flow into the durable sources
  • Private agent memory (Claude Code's auto memory) = persistent, not ephemeral: a non-authoritative, read-mostly operator cache; never a durable owner, never the home for in-flight tracking, and every mutation governed by AGENTS.md §Learning Disposition and §Private-Memory Write Gate

The last two are separated by persistence, not just by authority. Collapsing them is what lets an invisible surface accumulate operative rules: ephemeral state is discarded, while a cache that survives the session keeps whatever was written to it.

Aging-Rate Principle

The split is separation by aging rate:

  • Docs that track state age fast.
  • Docs that point to state age slowly.
  • Rules docs age slowly when they contain rules only.
  • Context docs age slowly when they contain context only.
  • Mixed docs age at the rate of their fastest-aging contents.

This is the load-bearing rationale for keeping these durable and non-durable surfaces separate.

Lifecycle Phases

  • Instantiation: the project is being defined and the target repo does not yet exist; the grounding note and any pre-repo prompts carry the workflow.
  • Bootstrap: the target repo exists, repo-local truth begins to form, and starter templates are adopted.
  • Operational: repo-local files are authoritative, normal workflow rules apply, and the grounding note remains the external context anchor.

Artifact Model

  • AGENTS.md — live repo-local execution rules for this execution-protocol repo
  • CLAUDE.md — the Claude Code adapter; its @AGENTS.md import is what delivers the resolved carrier into an executor's context. Required for a Claude-operated repo, not a convenience pointer
  • docs/architecture.md — this doc; explains the execution-protocol architecture
  • templates/ — reusable starters for downstream repo-local files and the external grounding note
  • protocol/ — the distributable execution-protocol layer: the shared AGENTS core (AGENTS.shared.md, resolved verbatim into each consumer's own AGENTS.md between the shared markers), the normative manifest.json registry, downstream profiles/, the opt-in standing-upstream-conformance-grant fragments/ entry, and check.sh (a deterministic local validator, not CI); consumers resolve the shared block locally rather than holding an independent copy
  • protocol/adapters/ — typed, executor-specific artifacts providing runtime enforcement for a supported write path of an agent-agnostic shared rule on a given runtime, not OS-level enforcement over arbitrary subprocess writes (the shared protocol prohibits that circumvention semantically; sandbox hardening is a separate out-of-scope question); not shared-protocol text and never inherited into a consumer's AGENTS.md. adapters/claude-code/ carries the native permission fragment for the private-persistent write gate, a static owner-repo check, a machine-local verifier, and their fixtures, run separately so the portable checker stays agent-agnostic
  • prompts/ — reusable prompts and coordinator runbooks. project-instantiation-initial-prompt.md carries the agent-agnostic pre-repo instantiation phase; AGENTS.md invokes others by path as operative instruments — the cross-repo propagation wave and inter-session coordination. README.md §Prompts is the current inventory
  • examples/ — concise mappings from real ASK projects to this structure
  • tools/read/ — the site build, adapted from method-ASK's: when the hosted site is built from docs/, it renders the home page and reading pages for the workflow docs, protocol notes, templates, prompts and examples from their Markdown, and read-only views of the diagram sources. The generated pages are build output, never committed; the Markdown stays the source

Session Topology

ASK project work routinely involves multiple writer-capable sessions: parallel executor threads, subagents in separate worktrees, a human editor alongside an executor. The repo and remote are the audit trail when sessions disagree. (The advisor surface is not a writer — it reviews from outside the execution thread and never mutates the repo.)

The single-writer-per-branch rule encoded in AGENTS.md handles this. Operators must verify state freshly when picking up a branch, treat the working tree as authoritative over their own memory, and stop on suspected concurrent mutation.

Single-writer discipline governs who may write. Two companion rules govern what operations against shared mutable state may claim: Write Guarantee Levels names the exact guarantee level — observation only, cooperative exclusion, or backend-enforced conditional mutation — and prohibits silent downgrade; the Bounded-Region Byte Contract governs partial-file writes and bounded-region identity claims alike, requiring each to declare its boundary, separator ownership, encoding, and structural handling rather than inherit a tool's defaults.

Those sessions sometimes need to coordinate mid-task — one clears a gate another is blocked on, or reports that an explicitly checked gate is still blocked. That is a within-surface concern; coordination across an operating-surface boundary stays with ASK's relay. prompts/inter-session-coordination.md is the coordinator runbook for that case. For a transition event, the evidence object and the durable owner land first. For an explicitly checked gate that is still blocked, the notice points at the existing source actually checked and creates no durable write, no new artifact, and no polling obligation — reporting that nothing changed is not a reason to write. Either way the peer notice owns no state, evidence, or authority — it carries only locators and bounded, non-authoritative summaries pointing back to that owner. It separates the durable pull (what is true now) from the ephemeral push (go re-read it), so neither substitutes for the other.

Why The Rules Exist

Most rules make reasoning inspectable across ASK, the executor, and any configured advisor while preserving one write authority. In the standard paired path they make the advisor/executor boundary productive; in direct execution they give ASK the same reviewable objects before mutation:

  • Plan-Before-Execute makes the executor's reasoning inspectable before it becomes a diff. It is what an advisor — or ASK — can challenge on scope, assumptions, non-actions, and intended terminal state.
  • Structured Change Summary and exact-scoped-diff approval are the review objects themselves: what actually crosses the boundary, in a form precise enough to disagree with.
  • Single-writer discipline keeps exactly one write authority while other surfaces read and review. Multi-surface reasoning only works if mutation stays single-writer.

Historically these were calibrated against what the retired split-execution model provided by default; that framing is preserved in the article record. Stated forward, they are the machinery of the current model rather than compensation for a retired one.

When proposing rule changes, ask which failure mode the rule addresses and whether it is still load-bearing.

Current Shape

This repo is intentionally small:

  • one set of live operating files for this repo
  • the protocol/ layer: the shared AGENTS core resolved locally into each consumer's own AGENTS.md, a normative manifest.json registry, downstream profiles/, an opt-in standing-upstream-conformance-grant fragment, check.sh (a deterministic local validator, not CI), and typed adapters/ for the executor-specific enforcement of an agent-agnostic rule
  • a small downstream template set — the repo-local and external-context starters (AGENTS.template.md, grounding-note.template.md, architecture.template.md) plus the executor adapter and the further carriers the resolved profiles call for; starters adopted alongside, not instead of, the locally resolved shared protocol. README.md §Reusable templates for downstream ASK repos carries the current set
  • one agent-agnostic instantiation prompt
  • a minimal example set
  • the hosted site's build (tools/read/), which generates the site's reading pages from the Markdown at deployment and commits nothing: its output, _site/, is gitignored build output

Beyond the bounded protocol/ resolution-and-validation layer — a distributable shared execution-protocol core resolved locally into each consumer's own AGENTS.md, a normative manifest, downstream profiles, an opt-in standing-grant fragment, and check.sh (a deterministic validator run locally, by hand) — and that site build, it does not include automation, sync tooling, CI, other generators, or a larger framework system. check.sh is a local validator, not continuous integration; the protocol/ layer resolves and checks existing rules, it does not generate artifacts or constitute a product build framework.