# fndry.sh Architecture Specification Version: 1.4.0 Status: Normative specification ## 1. Purpose This specification translates the fndry.sh architecture philosophy into requirements an agent can apply while researching, planning, designing, implementing, reviewing, migrating, or operating a system. It is a decision framework, not a prescribed workflow. An agent MUST apply the requirements in proportion to the consequence of the work. It MUST NOT create documents, approvals, or process steps merely to demonstrate compliance. Project-specific instructions govern when they conflict with this specification. The agent MUST identify a material conflict rather than silently blending incompatible directions. ## 2. Normative language The terms **MUST**, **MUST NOT**, **SHOULD**, **SHOULD NOT**, and **MAY** are normative. - **MUST** and **MUST NOT** define requirements for conformance. - **SHOULD** and **SHOULD NOT** define strong defaults that require a concrete reason to override. - **MAY** identifies an allowed option. “Architecturally significant” means a decision materially affects one or more of the following: - user-visible meaning or behavior; - authority, ownership, or a state transition; - a durable data model, identity, or external contract; - security, privacy, legal, policy, or compliance obligations; - reliability, recovery, or irreversible consequence; - adoption, distribution, or the operating model; - a long-lived technology dependency or material cost; or - the ability to migrate, replace, or extend the system. Contained and easily reversible implementation choices do not require separate architecture ceremony. Their reasoning MAY remain in the normal work artifact. ## 3. Primary directive An agent MUST design accountable systems in which meaning, authority, evidence, state, change, and recovery remain legible from the user experience through the implementation. The agent MUST treat information architecture and system architecture as one design problem. Concepts presented to a person, actions made available, and states communicated by an interface MUST correspond to distinctions and truths the system preserves. The preferred solution is the smallest constructive system that: - accomplishes a real outcome; - respects the full set of material constraints; - can be understood and adopted; - establishes a stable boundary; - governs routine work internally; - produces durable evidence; and - can become a trustworthy input to what happens next. ## 4. The architecture decision frame Before making an architecturally significant decision, the agent MUST be able to answer the following questions. The answers may be brief and may live in an existing plan, specification, decision record, or implementation document. 1. **Outcome:** What becomes possible when this succeeds? 2. **Meaning:** Which concepts and distinctions must remain truthful? 3. **Authority:** Who or what may decide, change state, accept, or publish? 4. **Temporal context:** Which mutable facts must an operation preserve so that later changes do not rewrite its meaning? 5. **Constraints:** Which technical, legal, policy, platform, financial, resource, adoption, organizational, or operating realities shape the problem? 6. **Smallest constructive solution:** What useful result can exist now without pretending to provide more than it does? 7. **Adoption:** How will someone first understand and receive value from it? 8. **Governance:** Which rules belong in capabilities, contracts, state transitions, validation, or failure behavior instead of human process? 9. **Evidence:** What will establish the result, and what will remain unknown? 10. **Technology fit:** Why do the selected mechanisms fit this responsibility beyond being familiar or conventional? 11. **Legacy:** What obligations does the decision create for operation, support, evolution, and replacement? 12. **Handoff:** What must the next responsible actor receive and be allowed to assume? These are decision questions, not mandatory sequential gates. The agent SHOULD answer them in the order that best fits the problem. ## 5. Meaning, authority, and state ### 5.1 Assign authority before mechanism Every architecturally significant state MUST have an identified authority. A derived view, execution engine, presentation layer, cache, generated file, or downstream consumer MUST NOT silently acquire authority over the state it observes. When relevant, the architecture MUST distinguish authority over: - intent and requested outcomes; - execution and attempts; - evidence and observations; - verification and acceptance; - publication, deployment, and operation; and - policy, consent, or consequential human judgment. A component MAY perform several responsibilities when the boundary remains explicit. Architectural separation does not require a separate service, repository, runtime, or team. For architecturally significant work involving delegated decisions or consequential state transitions, the agent MUST produce or update an authority map. The map MUST identify: - the state being changed; - authority to prepare, apply, verify, accept, and publish, where applicable; - required evidence; - stopping conditions when authority, evidence, or scope is insufficient; - recovery ownership; and - what the next person, agent, or system may safely assume. The authority map MAY be embedded in an existing specification, design brief, decision record, or handoff. Its detail and presentation MUST be proportional to the consequence of the work. It MUST NOT introduce separate actors, approvals, or sequential gates merely to populate the map. For a proposed system, the map MUST identify intended authority. For an existing system, the agent MUST distinguish observed authority from intended authority and identify material differences or unverified assignments. A documented map alone MUST NOT be treated as evidence that the system enforces its boundaries. ### 5.2 Preserve distinctions that affect conclusions The architecture MUST preserve states that lead to different actions or conclusions. In particular, an agent MUST NOT equate: - selection with execution; - execution completion with outcome completion; - production with verification; - automated verification with human acceptance; - acceptance with deployment; - deployment with health or promotion; - a canonical source with a projection; - missing evidence with a negative or successful result; or - a planned capability with an available capability. The user experience SHOULD reveal a distinction when it changes what a person can understand or do next. It SHOULD hide distinctions that are merely incidental implementation detail. ### 5.3 Represent uncertainty honestly Unknown, unavailable, stale, incomplete, unverified, and not applicable MUST remain distinct when the difference affects action. Missing information MUST NOT be converted into zero, false, safe, complete, accepted, or healthy unless an explicit domain rule justifies that conversion. The system SHOULD remain useful when evidence is incomplete, but MUST communicate the boundary of that usefulness. ### 5.4 Preserve operational context at the boundary When an operational record depends on mutable facts owned by another system, the architecture MUST preserve enough context to interpret that record after those facts change. It MUST do so by either storing an immutable snapshot of the required context with the operation or referencing an effective-dated version that is guaranteed to remain available for the required retention period. The operational record MUST retain the stable identity of the defining entity separately from its contextual snapshot. The defining system remains authoritative for the entity's current definition. The operational record is authoritative for the context used by that operation. A later change to the current definition MUST NOT silently rewrite the meaning, presentation, or searchability of historical operations. The snapshot SHOULD contain only the facts required to interpret, reproduce, search, or defend the operation. The architecture MUST account for the privacy, security, retention, archival, and deletion obligations created by each copied fact. When material, the record SHOULD also preserve when the context was captured, when it was effective, and which source version supplied it. The architecture MUST distinguish a change in an entity from a correction to an erroneous historical record. A change SHOULD create new effective context for subsequent operations. A correction MAY amend historical context, but MUST preserve attribution and enough provenance to explain what was corrected and why. ### 5.5 Use shared models and versioned contracts When multiple surfaces express the same concept, they SHOULD use one shared domain model or a formally versioned contract. Parallel approximations MUST be treated as a risk to meaning, not merely as duplicate code. When separate implementations are justified, the architecture MUST define: - the shared semantics and stable identity; - authority and ownership; - version and compatibility behavior; - required conformance evidence; and - failure behavior when equivalence cannot be established. A new layer that changes an established identity, contract, source of truth, or operating assumption MUST identify the resulting migration consequences. Providers, languages, runtimes, and storage mechanisms SHOULD remain behind stable boundaries when replacing them should not change the user-facing outcome. ### 5.6 Keep aggregate identity coherent When a product declares one domain object to be its authoritative aggregate, every subordinate capability MUST reference that aggregate's stable identity rather than minting a parallel identity for the same concept. Storage roots, repositories, remotes, user registries, applications, workflows, evidence, releases, and deployments MAY have their own identities and authorities, but MUST NOT become implicit substitutes for the aggregate. An initial storage or implementation profile MUST NOT permanently equate the aggregate with one incidental mechanism when future supported forms are already material to the architecture. The contract MUST state the current compatibility limit, preserve a migration boundary, and fail explicitly when the requested shape is unsupported. Moving, adding, replacing, or disconnecting a subordinate resource MUST NOT silently remint the aggregate. When two predecessor capabilities already claim the aggregate's identity, the reconciliation MUST define one authoritative successor, preserve completed history, detect conflicts rather than guessing, and provide a versioned, inspectable, recoverable migration path. Public command language and information architecture MUST express the accepted aggregate instead of retaining a superseded product or module solely for implementation convenience. ## 6. Information architecture as an operating contract Information architecture MUST communicate the operating model rather than merely expose stored fields, implementation structures, or every available control. Navigation, hierarchy, labels, disclosure, and action placement SHOULD help a person understand what is true, why it matters, what authority they are exercising, and what they can do next. Interfaces and agent responses SHOULD: - lead with the outcome, decision, or next useful action; - use progressive disclosure for supporting implementation and historical detail; - reveal consequential distinctions without exposing incidental machinery; - use direct manipulation when the object itself clearly expresses intent; - avoid duplicate controls and competing primary actions; - preserve exact identity when ambiguity would change the consequence; - communicate freshness, uncertainty, and unavailable evidence truthfully; and - keep historical lineage accessible without allowing it to dominate the normal experience. A presentation layer MUST NOT infer, mutate, or override canonical state unless that authority is explicitly part of its contract. Status, color, language, and placement MUST NOT imply a state or authority that the system does not preserve. ## 7. Agentic governance and human judgment ### 7.1 Govern routine work through the system Agents SHOULD receive enough responsibility and capability to accomplish coherent outcomes. Their authority MUST remain bounded by explicit permissions, inputs, contracts, state transitions, evidence requirements, and failure behavior. Routine governance SHOULD be enforced by the system. An agent MUST NOT add a human approval merely because human approval is a familiar control. Human involvement is required when the decision needs human authority, taste, consent, accountability, or judgment that the system cannot legitimately supply. The human MUST NOT be treated as the workflow engine for routine execution. When an agent can safely resolve a choice within the outcome and constraints, it SHOULD do so and document material reasoning. An agent MUST NOT fabricate human acceptance, consent, identity, policy approval, source provenance, or judgment. ### 7.2 Require authorization at consequential boundaries Routine, reversible, and clearly authorized work SHOULD proceed without additional ceremony. An agent MUST NOT request confirmation merely to reproduce a familiar process or transfer routine checking work to a person. Destructive, irreversible, externally consequential, or materially surprising actions MUST receive authorization from the person or system that owns the consequence. The architecture MUST preserve the difference between permission to prepare a change, permission to apply it, and acceptance of the resulting outcome. ## 8. Constraints, simplicity, and adoption ### 8.1 Treat constraints as architectural inputs The agent MUST identify material constraints beyond technical feasibility. Legal requirements, platform rules, policy, cost, access, time, distribution, adoption, and organizational capacity MAY change the correct system shape. When an expected design is blocked, the agent SHOULD restate the outcome and search for a constructive alternative that respects the constraint. It MUST NOT misrepresent a workaround as the original capability. Local, connected, centralized, distributed, synchronous, asynchronous, managed, and self-hosted designs are mechanisms. None is a governing principle without a problem-specific justification. ### 8.2 Make the simple path safe The primary path SHOULD allow a person to express the outcome without assembling avoidable implementation machinery. The architecture SHOULD absorb routine validation, isolation, evidence capture, recovery, and operational detail. It MUST NOT hide consequential targets, irreversible effects, authority changes, uncertainty, or failure. The system SHOULD hide ceremony while preserving substance, inspectability, recovery, and interoperability. ### 8.3 Preserve substance through abstraction An abstraction MAY hide implementation machinery, but it MUST preserve: - the meaning of the operation; - consequential authority boundaries; - evidence of what occurred; - recovery, reconstruction, or export when appropriate; and - deterministic failure when a required dependency or guarantee is unavailable. Implementation mechanisms MAY remain available for inspection, diagnostics, interoperability, and recovery without becoming the primary product language. An abstraction MUST NOT convert an unavailable dependency, partial result, or failed guarantee into apparent success. ### 8.4 Design adoption as part of the system The first useful experience MUST be understandable and valuable without requiring adoption of the final platform vision. Each platform layer SHOULD: - solve a real problem independently; - establish a stable identity, contract, or boundary; - avoid claiming capabilities reserved for later layers; and - make the next useful capability easier to adopt. A coherent product experience MAY span multiple repositories, runtimes, languages, licenses, or release cycles. Consolidation MUST NOT be used as a substitute for clear ownership and stable contracts. ## 9. Technology, legacy, and documentation ### 9.1 Select for system fit An architecturally significant technology choice MUST begin with the outcome, constraints, and responsibility being assigned. Familiarity MAY reduce delivery or operating risk, but MUST NOT be the sole justification. The agent MUST evaluate the factors that materially affect the choice. Depending on the problem, these may include: - capability and domain fit; - reliability and failure behavior; - security, privacy, policy, and compliance; - cost and resource requirements; - operability, observability, and recovery; - ecosystem maturity and available skills; - adoption and distribution; - interoperability, portability, and lock-in; and - upgrade, migration, and replacement paths. The evaluation SHOULD be proportional to consequence and reversibility. It MUST NOT become a generic scorecard in which irrelevant factors receive artificial weight. ### 9.2 Treat every accepted decision as legacy Once accepted, an architectural decision MUST be treated as an inherited dependency. The architecture SHOULD identify, when material: - ownership; - support and upgrade expectations; - compatibility boundaries; - operating and recovery obligations; - accepted risks and tradeoffs; and - conditions that would trigger reconsideration or replacement. A defensible decision need not remain correct under future conditions. It MUST be reasonable from the outcome, alternatives, constraints, evidence, risks, and tradeoffs available when it was made. ### 9.3 Make documentation part of completion It’s not done until it’s documented. An architecturally significant decision MUST produce or update a durable record containing the material parts of: - the outcome and context; - the decision and its owner; - the relevant constraints and factors; - alternatives considered and why they were rejected; - evidence supporting the choice; - assumptions, unknowns, risks, and tradeoffs; - operating and legacy obligations; and - conditions that should cause the decision to be revisited. The record SHOULD be as small as the decision permits. It MAY be embedded in an existing specification, plan, card, issue, or source document when that location is durable and discoverable. Agents MUST preserve this reasoning while the context is available. An unstructured transcript alone is not a sufficient decision record. ## 10. Evidence, change, and recovery ### 10.1 Make change inspectable, attributable, and recoverable Architecturally significant changes SHOULD be inspectable before execution, attributable afterward, and recoverable in proportion to their consequence. The system SHOULD provide: - a preview or clear description of consequential change; - target and scope validation; - a durable record of what changed; - attribution to the responsible person, agent, or system; - evidence appropriate to the claim being made; and - a correction, fallback, restoration, or containment path appropriate to the actual consequence. Automated tests, source inspection, browser or device verification, external observation, and human acceptance MUST be reported separately when they establish different claims. A failed attempt MUST NOT overwrite a previously accepted state merely to make the current system appear clean. History SHOULD remain available without overwhelming the current experience. ### 10.2 Define state mutation and recovery contracts A state-changing operation MUST resolve the exact target and validate relevant current state before mutation. It SHOULD be idempotent and atomic when practical. When either property is impractical, the operation MUST define how retries, concurrent change, partial application, and interruption are detected and contained. Partial failure MUST NOT silently corrupt adjacent state or imply that the complete outcome exists. The system MUST identify what changed, what did not change, and which recovery or containment action remains available. Recovery MUST be an operating capability rather than a future intention. Its depth SHOULD be proportional to consequence, but the documented path MUST be executable under the conditions in which it may be needed. When recovery depends on retained evidence, history, credentials, tools, or external services, the architecture MUST preserve or explicitly identify those dependencies. ### 10.3 Choose recovery rather than assuming rollback Recovery does not imply rollback. A design MUST select the smallest recovery mode that fits the state, consequence, and time sensitivity of the operation: 1. **Prevent activation:** validate a candidate before it becomes authoritative or receives traffic. A rejected candidate needs cleanup, not rollback. 2. **Contain and retry:** preserve the current accepted state, isolate partial work, and retry idempotently when the failure is transient or incomplete. 3. **Fix forward:** create a new immutable correction when the current result remains operable and the correction can arrive within the acceptable recovery window. This is the default for Foundry releases and deployments. 4. **Reactivate a retained known-good version:** when service impact requires faster recovery than a fix can provide, move the authoritative pointer or route to an already verified immutable version. This MUST NOT rebuild, reverse-mutate, or rewrite the historical release. 5. **Restore state:** use backup, replay, or reconstruction only when durable state was lost or corrupted and cannot be recovered by selection or a new corrective transition. Cards and contracts MUST NOT require every recovery mode. They MUST name the failure being contained, the maximum acceptable consequence, and the one recovery path justified by that consequence. Infrastructure transaction rollback MAY remain an internal provider safety mechanism when it prevents a failed apply from leaving partial resources; it MUST NOT become a product rollback feature merely because the provider supports it. ## 11. Outcomes and handoffs The preferred unit of progress is a coherent, evidence-bearing outcome rather than a transcript of activity. An architecturally significant handoff MUST communicate, as applicable: 1. **Outcome:** What now exists or was decided. 2. **Authority:** Which source or component owns the resulting truth. 3. **Constraints:** Which realities shaped the result. 4. **Decision record:** Where material reasoning and alternatives are preserved. 5. **Evidence:** What was verified and what each check establishes. 6. **Unknowns:** What remains unavailable, unverified, or undecided. 7. **Change safety:** How the result can be reversed, restored, or contained. 8. **Adoption:** How someone first encounters or benefits from it. 9. **Evolution:** Which boundary supports the next layer without claiming it already exists. 10. **Next responsibility:** Who or what owns the next meaningful decision or action. The handoff SHOULD omit categories that genuinely do not apply. It MUST NOT fill them with ceremonial text. When an authority map is required by section 5.1, the handoff MUST include the applicable map or a durable, accessible reference to it. The receiving actor MUST be able to identify its permitted next actions, required evidence, stopping conditions, and recovery responsibilities without reconstructing authority from an activity transcript. Source code MAY be part of the handoff. Source code alone is not sufficient when the next actor also needs intent, provenance, evidence, constraints, or operating context. ## 12. Required agent behavior ### Before work The agent MUST inspect applicable instructions, canonical sources, current state, existing boundaries, and relevant constraints. It MUST identify the intended outcome and avoid changing state outside the authorized scope. For architecturally significant work, the agent SHOULD make material assumptions, authority boundaries, and unresolved conflicts visible before implementation. It MUST NOT pause for questions that it can safely resolve within the established outcome and constraints. ### During work The agent MUST preserve unrelated work, maintain meaningful state distinctions, and prefer the smallest coherent change that satisfies the outcome. If evidence invalidates the selected design, the agent SHOULD revise the design rather than protect the original plan. It SHOULD preserve the failed assumption when that failure affects future understanding. The agent SHOULD put routine safeguards into code, contracts, tools, or validation instead of transferring avoidable checking work to the user. It MUST record architecturally significant decisions while their context remains available. ### At handoff The agent MUST lead with the outcome rather than an activity transcript. It MUST separate verified facts from inference, unknowns, and judgments that still require a person. The handoff MUST be executable by its intended recipient. When human validation remains, the agent MUST provide concrete starting state, actions, expected results, created state, and a safe cleanup or restoration path. ## 13. Prohibited shortcuts An agent MUST NOT: - choose a technology primarily because it is familiar, fashionable, or conventional; - treat a provider, framework, repository, runtime, or deployment mode as the product architecture; - allow a projection or generated view to become canonical by convenience; - resolve historical operations only through mutable current metadata when doing so could rewrite their meaning; - equate activity, execution completion, verification, acceptance, deployment, and operation; - add human process as a substitute for capability boundaries or state design; - expose implementation ceremony as the primary user model without a concrete reason; - hide unknown, stale, or unavailable evidence behind reassuring language; - fabricate consent, identity, provenance, policy approval, or acceptance; - delete or rewrite history merely to make the present state look clean; - claim future platform capability from an initial layer; - duplicate a domain model without examining shared ownership and contracts; - optimize technical scale while ignoring adoption or decision scale; - broaden scope because an implementation makes it convenient; - treat an inherited industry convention as a requirement without testing its purpose; or - defer material documentation as cleanup after completion. ## 14. Conformance review A proposal or result is conformant when the answers to the following questions are credible and proportional to the work: - Does it begin with a real outcome rather than a favored mechanism? - Are meaning and authority explicit? - Will the record still describe what was true when the operation occurred after its source data changes? - Do the interface and system state agree? - Does the information architecture communicate the operating model without creating competing actions or false authority? - Are consequential distinctions and unknowns preserved? - Do shared models or versioned contracts preserve meaning across surfaces and implementations? - Can agents act substantially within governed boundaries? - Is human judgment concentrated where it is actually required? - Do consequential actions require the correct authority without adding ceremony to routine reversible work? - Have all material constraints shaped the design? - Is this the smallest constructive solution that delivers useful value? - Is the first adoption step understandable? - Can the design grow through a stable boundary? - Were technologies selected for system fit rather than familiarity? - Are immediate legacy and operating obligations understood? - Can a future person reconstruct and challenge significant decisions? - Are changes inspectable, attributable, and recoverable? - Are state mutation, retry, partial failure, and recovery behavior explicit? - Do abstractions fail honestly when their dependencies or guarantees are unavailable? - Does the evidence support the claims being made? - Can the outcome become a trustworthy input to the next responsible actor? - Is the work documented well enough to be complete? A proposal is not conformant merely because it uses agents, automation, local execution, cloud infrastructure, microservices, events, or another architectural style. Conformance depends on the relationships among outcome, meaning, authority, constraints, adoption, governance, evidence, evolution, and recovery. ## 15. Exceptions and evolution An exception MAY be made when a project-specific need conflicts with this specification. The exception MUST record: - the affected requirement; - the concrete reason for the exception; - the risk introduced; - the containment or recovery approach; and - whether the exception is temporary or changes the governing architecture. The Bailey Postulate applies to this specification: if nothing changes, it never gets better. Revisions SHOULD incorporate demonstrated learning while preserving the distinction between enduring principles and tactics chosen for a particular constraint.