@really-knows-ai/foundry 2.3.2 → 3.0.0

package/dist/README.md

@@ -0,0 +1,278 @@
+# Foundry
+
+> Engineered confidence for AI-generated work. Define what good looks like.
+
+[![npm version](https://img.shields.io/npm/v/@really-knows-ai/foundry.svg)](https://www.npmjs.com/package/@really-knows-ai/foundry)
+[![Tests](https://github.com/really-knows-ai/foundry/actions/workflows/test.yml/badge.svg)](https://github.com/really-knows-ai/foundry/actions/workflows/test.yml)
+[![license](https://img.shields.io/npm/l/@really-knows-ai/foundry.svg)](LICENSE)
+
+---
+
+## Engineering confidence
+
+### Confidence is engineered
+
+Generation is cheap; trust is expensive. An agent can produce output quickly, skip
+validation, or lose feedback between iterations. The work arrives fast, but the
+evidence is incomplete and trust is fragile. Nobody can see the path from prompt to
+finish. Nobody knows how many times the agent tried, what it fixed, or why it
+stopped.
+
+Foundry is the system around the prompt: explicit standards, repeatable checks, and
+recorded sign-off applied to every artefact your AI produces. It transforms "ask an
+agent and hope" into a staged system where the checks are structural and mandatory.
+If an artefact should be validated, it is validated. If feedback must be resolved,
+that state is recorded. If a stage writes outside its lane, the cycle stops. The
+framework is deterministic; the LLM is not. Your laws are.
+
+Variability helps where creativity matters; control enforces discipline where
+reliability does. You choose what gates each stage passes through, what laws your
+artefacts must satisfy, and which models you trust for each decision. Foundry runs
+the loop and records every step in git, so the path from draft to approved artefact
+is auditable, repeatable, and defensible to auditors and stakeholders. You can show
+exactly how the output was made. Confidence is engineered; it is not hoped for.
+
+### The operating model: assay, then forge → quench → appraise
+
+A codebase-aware cycle can begin with **assay**: a deterministic pre-forge stage
+that runs project-authored extractor scripts, parses the strict JSONL facts they
+emit, and writes typed facts into flow memory. In the foundry metaphor, an assay
+establishes composition before work begins. In Foundry, assay gives forge a
+measured map of the project before it creates an artefact. Cycles without memory
+configuration skip this stage.
+
+After assay, one draft enters a short loop and leaves only when it passes quality
+gates. Each loop has four distinct roles that turn a candidate into a verified output:
+
+- **Forge** produces or revises the artefact. The stage that creates and reshapes
+  work, responding to feedback from appraisers or building on prior drafts.
+
+- **Quench** runs deterministic checks that harden or reject the work. Validation is
+  fast and non-negotiable, catching errors before they reach appraisers.
+
+- **Appraise** judges quality against written laws. Independent evaluators inspect
+  whether the work meets the subjective standards you define.
+
+- **Human-appraise** provides direct judgement when the stakes require it or the loop
+  deadlocks. Offers human oversight at critical decision points.
+
+Every stage commits separately, so every step leaves a record. Every decision is
+timestamped. A single loop produces an **output** — a verified draft. A flow
+composes one or more such loops to produce an **outcome** — the final artefact that
+reaches your codebase or customers.
+
+### What you describe, what Foundry enforces
+
+You write the laws — the criteria that define acceptable. You describe the artefact
+types you want produced and what files they generate. You choose which stages each
+cycle passes through and what models to use at each step. You control the operating
+model entirely. Your configuration is law.
+
+Foundry runs the loop, gates writes per stage so only the right mutation happens at
+the right time, records every decision in git, and stops when there is nothing left
+to fix. Each stage holds a token that authorises its mutations. Stages cannot write
+outside their assigned lane. Feedback state moves through a state machine that
+prevents invalid transitions. The framework owns the process and enforces the rules;
+the LLM performs the creative and evaluative work inside each stage. You define the
+machine; Foundry runs it. Confidence is the difference.
+
+---
+
+## Compatibility
+
+Foundry works primarily with OpenCode. The skills and tools are portable to other
+skill-aware AI systems. Multi-model stage routing is OpenCode-specific today.
+
+- **OpenCode** — full support. Multi-model routing via file-based `foundry-*` agents.
+  This is the primary target platform.
+
+- **Other skill-aware AI tools** — the skills and tools are portable to any
+  skill-aware AI system. Multi-model stage routing is OpenCode-specific today
+  because it relies on `.opencode/agents/` files.
+
+---
+
+## Install
+
+Add the plugin to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
+}
+```
+
+Restart OpenCode so the plugin registers its tools and skills. You will see new
+tools and skills become available in OpenCode's command palette once the restart
+completes. The `init-foundry` skill and flow-management tools are now ready to use.
+
+---
+
+## Upgrade
+
+Run the `upgrade-foundry` skill from a clean project state when moving an existing project to the installed Foundry version. The skill preserves the existing `foundry/` directory, initialises a fresh current-version configuration, analyses the preserved configuration as source material, and recreates supported concepts through current tools.
+
+The upgrade process asks clarifying questions for ambiguous routing, input contracts, validation behaviour, memory settings, and deprecated concepts. It leaves the preserved source directory in place until you explicitly approve cleanup.
+
+---
+
+## Quick start
+
+### Phase 1 — Install
+
+Add the plugin to `opencode.json` (see Install section above):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@really-knows-ai/foundry"]
+}
+```
+
+Then restart OpenCode so the plugin registers its tools and skills. You will see new
+tools and skills become available in OpenCode's command palette once the restart
+completes. The `init-foundry` skill and flow-management tools are now ready to use.
+
+### Phase 2 — Initialise
+
+Open OpenCode in your project repo and say:
+
+```
+> run init-foundry
+```
+
+Foundry scaffolds a `foundry/` directory, generates one `foundry-<model>` agent file
+per model available in your session, commits the structure, and then asks you to
+restart. All the foundational configuration directories are created; you will
+populate them next.
+
+Restart OpenCode so the new `foundry-<model>` agents register — multi-model dispatch cannot route to agents it cannot discover.
+
+### Phase 3 — Build a flow without writing one
+
+Ask Foundry to set up a flow:
+
+```
+> set up a flow that writes haikus
+```
+
+Foundry will ask clarifying questions about the flow's purpose, constraints, and
+entry points. It will then scaffold a haiku artefact type with a syllable-count
+validator, laws for form / imagery / mood, two appraisers with different
+sensibilities and bias profiles, a cycle that connects them in sequence, and a flow
+that ties it all together. Everything is scaffolded; you do not write any
+configuration by hand. This demonstrates the full system in action.
+
+Now run it:
+
+```
+> write me a haiku about autumn
+```
+
+Here is what the loop produces:
+
+```
+forge     → drafts a haiku                          [commit]
+quench    → 7/7/5 — fails syllable check            [commit]
+forge     → revises                                 [commit]
+quench    → 5/7/5 — passes                          [commit]
+appraise  → 2 appraisers, one flags weak imagery    [commit]
+forge     → revises                                 [commit]
+appraise  → clean                                   [commit]
+done      → squash-merged to main with attestation
+```
+
+Every stage commits. Every decision is recorded. Every piece of feedback and every
+revision leaves a trace in the work branch. The final artefact on `main` carries a
+signed attestation showing exactly how that output was produced, which models
+contributed, and when each appraiser signed off.
+
+This trace is the proof. You can play it back, audit it, replay it under a different
+model, or use it to argue that the AI output is trustworthy. Every step is visible.
+Nothing is hidden.
+
+For codebase-aware flows, add flow memory after the first run: initialise memory,
+declare the entity and edge vocabulary, add extractors, and opt a cycle into
+`assay.extractors`. See [Optional: flow memory](docs/getting-started.md#optional-flow-memory)
+and [Assay](docs/concepts.md#assay) for the configuration path.
+
+> **Note (3.0.0):** flow memory currently persists to `cozo-node`, which is
+> unmaintained upstream. Installation produces six cosmetic deprecation warnings
+> from transitive dependencies (`pnpm audit` is clean). Foundry will migrate to
+> a maintained backend in a future release; the public `foundry_memory_*` tools
+> and on-disk vocabulary/NDJSON format are designed to survive that migration.
+> See `CHANGELOG.md` and [docs/memory-maintenance.md](docs/memory-maintenance.md#backend-status-as-of-300).
+
+---
+
+## What you can show your team
+
+After the quick start completes, you have five concrete artefacts to point at to
+demonstrate engineered confidence:
+
+- **The artefact itself** — `haikus/autumn.md` on `main`. The final, approved output
+  ready for use or deployment.
+
+- **The laws it satisfied** — `foundry/artefacts/haiku/laws.md`. The criteria it was
+  measured against, written in markdown and version-controlled.
+
+- **The feedback ledger** — `WORK.feedback.yaml` on the archived work branch. Every
+  issue raised, by whom, and how it was resolved during the loop.
+
+- **The per-stage commit history** — the raw commits on `archive/work/<flow>-<...>`.
+  A micro-commit per stage showing exactly what changed and why at each step.
+
+- **The signed attestation on main** — the squash commit with the Foundry attestation
+  block embedded in its message. Proof of approval, signed and timestamped.
+
+This is what makes "engineered confidence" concrete. You can show your team exactly
+how that AI output was produced, what it passed through, why you trust it, and who
+signed off. Every step is auditable. Every decision is recorded. The loop is
+reproducible.
+
+---
+
+## What's in the box
+
+- **Deterministic governance** — routing, commits, write boundaries, and feedback
+  state live in tested plugin code, outside LLM control.
+
+- **Written quality criteria** — laws are markdown files; an appraiser panel scores
+  each artefact against them, so quality is objective.
+
+- **Multi-model diversity** — forge on one model, appraise on another, every
+  appraiser on a different model if you want. Different models catch different
+  mistakes.
+
+- **Full git audit trail** — one commit per stage with `WORK.md`,
+  `WORK.feedback.yaml`, and `WORK.history.yaml`. Every iteration is recorded.
+
+- **Signed attestation on main** — every flow finishes with a squash commit carrying
+  a canonical Foundry attestation block that proves the artefact was processed.
+
+- **Archived forensic branch** — the raw work branch is retained for auditors as
+  `archive/work/<flow>-<desc>-<hash>`. The full micro-history is never lost.
+
+- **Bring your own pipeline** — artefact types, laws, and stages are yours; works
+  for code, specs, docs, data, and anything else you can describe as files with
+  pass/fail criteria.
+
+- **Assay preflight** — deterministic extractor stage that measures the project
+  before forge starts, so codebase-aware flows can begin from structured facts.
+
+- **Flow memory** — typed graph store with scoped tools, semantic search when
+  enabled, and committed NDJSON rows for cross-cycle reuse.
+
+---
+
+## Further reading
+
+The full reference set lives in [docs/](docs/) — start at [docs/README.md](docs/README.md)
+for a guided index of every document and when to read it.
+
+---
+
+## License
+
+MIT.

package/dist/docs/README.md

@@ -0,0 +1,59 @@
+# Foundry docs
+
+This directory contains the reference set behind the project README. Every document here serves a single purpose; use this index to find what you need.
+
+**How to navigate:** Work through the sections in order: **Start here** establishes conceptual foundations, **Reference** provides detailed specifications for implementation, and **Contributors** covers subsystem maintenance and extensions.
+
+## Start here
+
+Getting oriented with Foundry means understanding both the concepts it uses and how to work within it practically. These documents establish the mental model and hands-on practice you need before authoring configuration or working with flows.
+
+**Reading order:** Work through them in order; [getting-started.md](getting-started.md) builds hands-on confidence, and [concepts.md](concepts.md) provides reference depth. Most implementers spend 1–2 hours on getting-started before moving to Reference materials.
+
+- **getting-started.md** — Complete end-to-end installation, bootstrap (`init-foundry`), and first flow walkthrough. Read this immediately after installing the plugin and before authoring any of your own configuration. 
+
+  It establishes the operating model, directory structure, and practical confidence in one pass. Includes hands-on guidance on authoring the five foundational concepts (artefact types, laws, appraisers, cycles, flows) with worked examples you can run against real code. Also covers the optional flow-memory path: initialise memory, declare vocabulary, add extractors, and opt a cycle into assay for codebase-aware flows.
+
+  Implementers must follow every step and complete the bootstrap; architects typically skim for structure before moving to [concepts.md](concepts.md) and [architecture.md](architecture.md) to reason about their designs.
+
+- **concepts.md** — The glossary and conceptual foundation for Foundry's key terms and ideas, arranged top-down from flows through cycles, stages, artefacts, and feedback loops. 
+
+  Reach for this when you encounter terminology you need to understand, or as a reference map before diving into [work-spec.md](work-spec.md) or [architecture.md](architecture.md). Defines each concept affirmatively with concrete examples and links outward to spec documents that elaborate them in detail. Defines `Assay`, `Flow memory`, `Extractor`, and the read/write permission model that scopes memory tools per cycle.
+
+  Architects especially need this to reason about system boundaries, design decisions, and invariants; implementers reference it iteratively as they build configuration, debug unexpected behaviour, and reason about state transitions.
+
+## Reference
+
+These documents specify formats, tools, and design principles. Use them when implementing tooling, understanding the work-file lifecycle, debugging state transitions, or reasoning about Foundry's guarantees and safety properties.
+
+**Key property:** These are sources of truth and normative references. Changes to Foundry flow formats or tool behaviour must be reflected here first. Use them together—cross-references appear throughout.
+
+- **work-spec.md** — Complete specification of the `WORK.md`, `WORK.feedback.yaml`, and `WORK.history.yaml` file formats, including frontmatter fields, the artefact registry, and the full feedback state machine with all valid transitions and guards. 
+
+  Use this when implementing tooling around work files, validating state transitions, or understanding what metadata flows carry through an execution. It is the authoritative source of truth for all transient work-branch structures, format validation rules, and field semantics. 
+
+  Implementers and tool builders rely on this heavily; keep it updated immediately as formats evolve or new fields are added.
+
+- **tools.md** — Categorical index and reference documentation for all custom tools, organised by family (lifecycle, artefacts, feedback, config, memory, etc.) with complete signatures and permissions. 
+
+  Consult this when you need to understand what a specific tool does, its branch requirements, what stage locks apply, what arguments it accepts, and how it integrates with the overall system. Covers calling conventions, enforcement invariants, and the permission model for memory access. References `foundry_assay_run`, `foundry_extractor_create`, and memory data and admin tools.
+
+  Tool authors and system integrators use this constantly; it is the comprehensive reference for all custom tools in the Foundry ecosystem.
+
+- **architecture.md** — The design and enforcement model covering token lifecycle, stage-locked mutations, write invariants, branch namespaces, multi-model routing, and core design principles. 
+
+  Read this when you need to understand how Foundry maintains safety (how tokens prevent replay, why stages lock mutations, how writes are validated), what guarantees it makes and where they live in the code, or why it is structured the way it is. Explains the memory layout, assay write boundary, and failed-flow behaviour that keep extractor-populated memory auditable.
+
+  Architects and contributors working on core systems need this to reason about changes and implications; see also concepts.md for the high-level flow model context and work-spec.md for specifics on format validation and state machines.
+
+## Contributors
+
+Documentation for those extending Foundry's internals or maintaining subsystems. These documents go deeper into implementation detail and capture learning from production experience.
+
+**When to use:** Start here if you are modifying core functionality, debugging subsystem behaviour, or maintaining systems beyond the public API.
+
+- **memory-maintenance.md** — Cozo 0.7 adaptations, memory session lifecycle notes, and derived implementation wisdom for contributors working on the memory subsystem. 
+
+  Start here if you are maintaining or extending memory-related functionality; it documents known footguns (string literal syntax, HNSW index pseudo-relations), session-lifecycle edge cases, tracing techniques, and runtime extractor population in precise detail.
+
+  Captures learning from actual bugs and debugging sessions so the next maintainer does not have to discover them again through repeated debugging. Core contributors should read this before touching memory code; it explains why certain patterns are necessary, which changes cascade across the system, and common pitfalls to avoid.