diff --git a/README.md b/README.md index 8976365..a72388a 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **A prompt+code system for producing tested, portable agent packages — with deterministic enforcement and lighter, conversation-first prompts.** -Method Factory is the successor to [Process Engine](https://github.com/RedEyeNinja-BKK/Process-Engine). Process Engine proved the pipeline works through prompt-only experimentation and a successful end-to-end case study. Method Factory takes that proven design and adds a code layer: the state machine, gate enforcement, and manifest integrity are deterministic. The prompts are lighter, focused on conversation and content generation — not on enforcing their own rules. +Method Factory is the successor to [Process Engine](https://github.com/RedEyeNinja-BKK/Process-Engine). Process Engine proved the pipeline works through prompt-only experimentation and a successful end-to-end case study. Method Factory takes that proven design and adds a code layer: the state machine, gate enforcement, manifest integrity, and persistence are deterministic. The prompts are lighter, focused on conversation and content generation — not on enforcing their own rules. > **Process Engine** remains the Turnstone-native, prompts-only reference implementation — active, not abandoned. It is the philosophical anchor. This repo builds outward from it. @@ -12,14 +12,91 @@ Method Factory is the successor to [Process Engine](https://github.com/RedEyeNin Tell it what you want to build, share any material you have, and it produces a complete agent package — persona, skills, templates, and evaluation cases — through a gated pipeline: +```mermaid +flowchart TD + A[Intent] --> B[Collect] + B --> C[Clarify] + C --> D[Objective] + D --> E[Summary Gate] + E --> F[Pattern Author] + F --> G[Review] + G --> H[Trial] + H --> I[Ship] + I --> J[Triage] ``` -Intent → Collect → Clarify → Objective → Summary Gate → Pattern Author → Review → Trial → Ship → Triage -``` + +The spine is human-gated at every stage: the operator is the only authority for summary confirmation and shipping. Code owns deterministic state, gates, and persistence; prompts own conversation, clarification, and content generation. The model proposes; code validates, authorizes, persists, and verifies. The pipeline was discovered through prompt-only experimentation (Process Engine v1.0–v1.6.0) and validated in a real end-to-end case study. Method Factory hardens the gatekeeping logic into code while keeping the prompts conversation-first. --- +## What is RC1 (`v2.0.0-rc.1`)? + +RC1 is the first release candidate of the SQLite persistence reset. It is a **pre-release** for product trials, not final `2.0.0`. + +**Implemented and verified:** + +- **SQLite canonical transactional store** — append-only event/history model with deterministic replay validation. +- **Immutable content-addressed artifact storage** — blobs verified by SHA-256, never overwritten. +- **v0.1.2 JSONL migration** — `mf migrate-store` migrates a public v0.1.2 store to SQLite with a durable receipt and no-clobber atomic publication. +- **Deterministic event exports** — `mf export` with two formats: + - `method-factory-events-v1` (supported current export); + - `legacy-v012-jsonl` (v0.1.2-shaped evidence export that revalidates under the frozen legacy reader). +- **Minimal supported CLI** — intentionally only: + - `mf migrate-store`; + - `mf export`. +- **Python 3.11 and 3.12** supported and CI-tested. +- **JSON Action Envelope** remains the state-changing protocol; prose is never a state transition. + +**Intentionally NOT in RC1:** + +- generic import; +- backup/restore; +- garbage collection; +- lifecycle commands (`create`, `apply`, `status`, `summary`, `review`, `trial`, `ship`, `triage` are not exposed); +- final `2.0.0` release. + +**Important non-claim:** the event hash chain is *internal consistency evidence*, not cryptographic authenticity. An attacker who replaces and rehashes the whole database would not be detected by the chain alone. + +--- + +## Validation + +Method Factory reached RC1 through a sequence of bounded, operator-gated phases (foundation → corrections → invariant closure → migration/export → evidence closure → integration → release) and **seven mandatory code-review passes** over the migration/export surface (bug / security / performance / quality → verify → dedupe → sanity), finishing with **0 critical / 0 major** findings. + +- **420 tests** green on Python 3.11 and 3.12. +- Fault-injection matrix over atomic publication; deterministic-export goldens; clean wheel build; isolated-install provenance; packaged migration/export smoke — all proven in CI on the exact released commit. +- Release identity: `v2.0.0-rc.1` (tagged `c30332ba…`); package version `2.0.0rc1`. + +--- + +## Getting started + +```bash +pip install methodfactory-2.0.0rc1-py3-none-any.whl # or: pip install -e ".[test]" +mf --version # methodfactory 2.0.0rc1 +``` + +**Migrate an old v0.1.2 store:** + +```bash +mf migrate-store --source [--dest ] +``` + +The destination defaults to `/methodfactory.sqlite3`; migration refuses to overwrite an existing destination and never mutates the legacy source. + +**Export evidence:** + +```bash +mf export --store --output events.jsonl --format method-factory-events-v1 +mf export --store --output legacy.jsonl --format legacy-v012-jsonl +``` + +Both exports are deterministic and read-only. + +--- + ## How it differs from Process Engine | | Process Engine | Method Factory | @@ -29,33 +106,30 @@ The pipeline was discovered through prompt-only experimentation (Process Engine | **Prompts** | Include enforcement rules | Conversation + content only | | **State machine** | Prompts describe it | Code enforces it | | **Manifest** | LLM reads/writes TOML | Validated schema + code I/O | +| **Persistence** | JSONL experiments | SQLite canonical store | | **Trials** | Prompt-described | Code-driven harness | -| **Status** | Active reference | Under development | +| **Status** | Active reference | RC1 release candidate | --- ## Architecture ``` -Code owns: state machine, gate enforcement, manifest I/O, trial harness +Code owns: state machine, gate enforcement, manifest I/O, persistence, exports Prompts own: conversation, clarifying questions, content generation, tone ``` Design principle: the model should not be responsible for enforcing its own constraints. Code enforces the rules; prompts guide the work. +For developers: [Architecture reset status](docs/architecture-reset-status.md) (current state + full gate history), [Public surface & error contract](docs/public-surface.md), [ADR-0012 persistence architecture](docs/adr/ADR-0012-persistence-architecture.md). + --- ## Origin Method Factory is built from the domain knowledge captured in [Process Engine](https://github.com/RedEyeNinja-BKK/Process-Engine) — specifically the pipeline design (Intent → Collect → Clarify → Objective → Summary Gate → Pattern → Review → Trial → Ship → Triage) that emerged from hundreds of prompt-only experiments and was validated in a [real end-to-end run](https://github.com/RedEyeNinja-BKK/Process-Engine/blob/main/evals/case-study-first-run.md). -The prompt-only phase was not a shortcut — it was the discovery method. We didn't guess the architecture. We ran real interactions until the lifecycle proved itself. Now we're hardening the guarantees into code. - ---- - -## Status - -**Under active development.** This repo contains migrated content from Process Engine v1.9.1 and is being restructured around the prompt+code architecture. The initial code layer (state machine, manifest validation, gate enforcement) is under construction. +The prompt-only phase was not a shortcut — it was the discovery method. We didn't guess the architecture. We ran real interactions until the lifecycle proved itself. Now the guarantees are hardened into code. --- @@ -67,7 +141,9 @@ MIT — see [LICENSE](LICENSE). ## Docs -- [Architecture](docs/architecture.md) -- [Migration from Process Engine](docs/migration-from-process-engine.md) -- [Spec compliance](docs/spec-compliance.md) -- [Case study: first live run](evals/case-study-first-run.md) +- [Architecture reset status — current state + gate history](docs/architecture-reset-status.md) +- [Public surface and stable error contract](docs/public-surface.md) +- [ADR-0012 — persistence architecture](docs/adr/ADR-0012-persistence-architecture.md) +- [Action Envelope — prompt/code protocol](docs/action-envelope.md) +- [Manifest contract v0.1](docs/manifest-contract-v0.1.md) +- [Migration from Process Engine (historical)](docs/migration-from-process-engine.md) diff --git a/docs/adr/ADR-0012-persistence-architecture.md b/docs/adr/ADR-0012-persistence-architecture.md index 8dd1555..4c7e27c 100644 --- a/docs/adr/ADR-0012-persistence-architecture.md +++ b/docs/adr/ADR-0012-persistence-architecture.md @@ -1,6 +1,6 @@ # ADR-0012 — Persistence architecture reset: SQLite canonical store -**Status:** Accepted in principle (2026-08-07 senior-review direction; operator-authorized controlled publication). Implementation pending ADR review from the pushed branch. +**Status:** Accepted; implemented and released as `v2.0.0-rc.1` (2026-08-08). This ADR remains authoritative for persistence. **Supersedes:** the JSONL journal-first canonical-store decision in ADR-0008 (and the review-held `8a7e916` remediation branch). **Applies to:** Method Factory persistence layer, post-v0.1.x overhaul. diff --git a/docs/architecture.md b/docs/architecture.md index 4e06eea..6126509 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,5 +1,7 @@ # Architecture +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + Process Engine is an agent-skill framework: a persona, six skills, seven references, and six session templates that drive a gated authoring pipeline. It is **runtime-aware**: the same core content deploys three ways. diff --git a/docs/evaluator-freeze-policy.md b/docs/evaluator-freeze-policy.md index 95049bb..5fc826a 100644 --- a/docs/evaluator-freeze-policy.md +++ b/docs/evaluator-freeze-policy.md @@ -1,5 +1,7 @@ # First-Response Evaluator — FROZEN v1.9.1 +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + **Purpose:** Detect regressions in prompt binding, domain routing, operator control, non-authoring, non-deployment and critical workflow entry. diff --git a/docs/governance-usage.md b/docs/governance-usage.md index 3a1c765..c6d8682 100644 --- a/docs/governance-usage.md +++ b/docs/governance-usage.md @@ -1,5 +1,7 @@ # Governance Usage — Process Engine × Turnstone's Governance Surface +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + > **Status:** PARTIALLY DEPLOYED (2026-08-01). Live: prompt policy > `process-engine-context` (content-only, priority 1) + heuristic rule > `process-engine-authoring` (advisory, review, low risk) + judge surface diff --git a/docs/migration-from-process-engine.md b/docs/migration-from-process-engine.md index 08d82ba..10fc439 100644 --- a/docs/migration-from-process-engine.md +++ b/docs/migration-from-process-engine.md @@ -1,5 +1,7 @@ # Migration from Process Engine +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + **Date:** 2026-08-03 **Source:** [Process Engine](https://github.com/RedEyeNinja-BKK/Process-Engine) at tag `v1.9.1` — commit `240520e` **Split point:** Process Engine at commit `69de7bc` — the version behind the [Etsy store case study](https://github.com/RedEyeNinja-BKK/Process-Engine/blob/main/evals/case-study-first-run.md) diff --git a/docs/package-manifest-schema.md b/docs/package-manifest-schema.md index a2aba3f..5e166ee 100644 --- a/docs/package-manifest-schema.md +++ b/docs/package-manifest-schema.md @@ -1,5 +1,7 @@ # Package Manifest Schema +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + > The durable state record that connects every pipeline stage. Every package > generated by Process Engine carries a manifest from intent through deployment. diff --git a/docs/portability-test-hermes-openclaw-20260802.md b/docs/portability-test-hermes-openclaw-20260802.md index dbc2385..fe63bc4 100644 --- a/docs/portability-test-hermes-openclaw-20260802.md +++ b/docs/portability-test-hermes-openclaw-20260802.md @@ -1,5 +1,7 @@ # Portability test — Hermes + OpenClaw (executed 2026-08-02) +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + **Status: EXECUTED — behavioral portability demonstrated on Hermes and OpenClaw.** This replaces the prior "provisioned, not executed" state. The six diff --git a/docs/portable-install-test-20260801.md b/docs/portable-install-test-20260801.md index 76bd531..510ad47 100644 --- a/docs/portable-install-test-20260801.md +++ b/docs/portable-install-test-20260801.md @@ -1,5 +1,7 @@ # Portable install test — 20260801 +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + **Status:** provisioned, not executed (operator deferred external-client testing 2026-08-01). ## Target diff --git a/docs/provenance-schema.md b/docs/provenance-schema.md index 6842966..79c04cd 100644 --- a/docs/provenance-schema.md +++ b/docs/provenance-schema.md @@ -1,5 +1,7 @@ # Canonical Provenance Schema +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + **Version:** 1.9.0 This document defines the single authoritative provenance contract for an diff --git a/docs/public-surface.md b/docs/public-surface.md index aacc040..2382b4b 100644 --- a/docs/public-surface.md +++ b/docs/public-surface.md @@ -1,8 +1,7 @@ # Public Surface and Stable Error Contract -Phase 2 foundation closure (review 4879440857, Finding 4). This table is the -authoritative public error boundary for the currently supported package and -storage APIs. +This table is the authoritative public error boundary for the currently +supported package and storage APIs (RC1, package identity `2.0.0rc1`). **Boundary rule:** every supported public operation surfaces **only** `methodfactory.domain.errors.MethodFactoryError` subclasses (stable @@ -38,9 +37,10 @@ exception contract and are not part of the supported surface. > with an explicitly DIFFERENT instant is `PACKAGE_EXISTS`; a retry that omits > `created_at` replays using the stored creation time. This is a deliberate > pre-release breaking change to the SQLite store format (revision-0 -> `action_json` payload now carries `created_at`); no released stores exist -> (PR #1 Draft, v2.0.0a1), so no migration is required — any pre-A1 test store -> must be recreated. The authoritative chain validator binds +> `action_json` payload now carries `created_at`); no stores were released +> under the earlier alpha format (the first release is `v2.0.0-rc.1`), so no +> migration is required — any pre-A1 test store must be recreated. The +> authoritative chain validator binds > `payload.created_at` to the indexed row `created_at`. | `SqliteManifestStore.apply(envelope)` | `dict` (parsed Action Envelope) | complete resulting manifest `dict` | `InvalidEnvelopeError` (`INVALID_ENVELOPE`), `InvalidPayloadError` (`INVALID_PAYLOAD`), `PackageNotFoundError` (`PACKAGE_NOT_FOUND`), `StaleActionError` (`STALE_ACTION`), `IllegalTransitionError` (`ILLEGAL_TRANSITION`), `GateUnsatisfiedError` (`GATE_UNSATISFIED`), `ActionIdConflictError` (`ACTION_ID_CONFLICT`), `SerializationError` (`SERIALIZATION`), `ArtifactVerificationError` (`ARTIFACT_VERIFICATION`), `ManifestInvalidError` (`MANIFEST_INVALID`), `ConcurrencyError` (`CONCURRENCY`), `StorageError` (`STORAGE_ERROR`) | `TypeError`/`ValueError`/`UnicodeError`/`RecursionError`, `OSError`, `sqlite3.Error` (incl. locked -> `CONCURRENCY`) | | `SqliteManifestStore.load(package_id)` | str | complete current manifest `dict` | `PackageNotFoundError` (`PACKAGE_NOT_FOUND`), `ManifestInvalidError` (`MANIFEST_INVALID`), `StorageError` (`STORAGE_ERROR`) | `TypeError`/`ValueError`/`UnicodeError`/`RecursionError`, `sqlite3.Error` | diff --git a/docs/spec-compliance.md b/docs/spec-compliance.md index 62dc1b8..d114928 100644 --- a/docs/spec-compliance.md +++ b/docs/spec-compliance.md @@ -1,5 +1,7 @@ # Spec compliance +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + Every skill this engine generates complies with the [Agent Skills open format standard](https://github.com/agentskills/agentskills) (originally developed by Anthropic; code Apache-2.0, docs CC-BY-4.0). diff --git a/docs/standards.md b/docs/standards.md index fcfe9c1..1bb7655 100644 --- a/docs/standards.md +++ b/docs/standards.md @@ -1,5 +1,7 @@ # Process Engine standards +> **Historical / superseded.** This document describes the Process Engine era. Current Method Factory architecture and release state: see [architecture-reset-status.md](architecture-reset-status.md) and [ADR-0012](adr/ADR-0012-persistence-architecture.md). + This document summarizes the release-facing standards checklist. The canonical skill reference is [`../references/standards.md`](../references/standards.md).