Expflow

Expflow is a schema-governed, local-first workflow ownership and observability platform for projects where people, agents, and tools produce changing artifact trees.

Expflow records what changed, which evidence was trusted, which decisions remain durable, and which outputs can be inspected, regenerated, restored, or reused.

Current release candidate: v1.1.0.

What Expflow Tracks

Expflow separates five concerns that are often blurred in automated work:

• material files before and after workflow activity;
• accepted authority sources for the work;
• attributed claims, decisions, conflicts, and review requests;
• workflow inputs, outputs, projections, regeneration attempts, equivalence evaluations, and reuse evidence;
• local security, migration, package, and proof evidence.

Material output does not imply semantic acceptance, workflow completion, or reuse permission. Expflow keeps those records separate.

Release Scope

Expflow v1.1.0 covers the local core surfaces implemented in this repository:

• four ordinary commands: expflow init, expflow sync, expflow status, and expflow restore;
• local .expflow/ material storage with immutable object, node-revision, tree-revision, receipt, validation, change, and material-head records;
• complete-tree sync, drift status, tree/node restore, scoped path selection, explicit identity directives, and digest-similarity proposals without silent identity preservation;
• project locks, operation-scoped staging, recoverable init/restore intents, stale-lock classification, causal tree/receipt head repair, restore recovery, and restored-tree digest verification;
• library runtimes for authority sources, semantic decisions, workflow boundaries, projections, regeneration/equivalence, structural reuse, security controls, migration evidence, and the native extension host;
• stable, bounded, versioned read models over advanced authority, semantic, workflow, projection, reproduction, and material linkage records;
• attributed evidence intake, quarantine, duplicate detection, source proposals, correspondence, conflict, artifact-candidate, and decision helpers through the TypeScript library;
• deterministic portable workflow package export, offline validation, import planning, collision-safe import, and resume-state reporting through the TypeScript library;
• repository-contract checks for immutable architecture sources, schemas, examples, fixtures, registries, package boundaries, and end-to-end proof.

Quickstart

With the npm package available from the public registry:

npm install -g expflow
expflow init
expflow status

The npm package exposes the expflow CLI and TypeScript library exports. The Python package is a separate hook scaffold with read-only repository architecture discovery; it does not dispatch or execute hooks.

Installation

After verified registry publication, install the primary Expflow CLI and TypeScript package with:

npm install -g expflow

Install the Python hook scaffold separately with:

pip install expflow-hooks

expflow-hooks is not the primary Expflow CLI implementation. It exposes the limited Python hook/scaffold package and expflow_hooks import surface.

Workflow

1. Run expflow init to create local Expflow state.
2. Change files in the project tree.
3. Run expflow status or expflow sync --dry-run to preview pending changes.
4. Run expflow sync to record a complete material tree revision.
5. Run expflow status --history or expflow status --node-history <path> to find restore references.
6. Run expflow restore <reference> --dry-run before restoring a recorded tree or node revision.

Gate C ownership/reproduction behavior, Phase 4 evidence intake/reconciliation behavior, Phase 5 portable workflow package behavior, and Gate D security/migration behavior are available through library runtimes rather than additional ordinary commands.

Commands

Useful Phase 1 options:

• expflow sync --dry-run previews path-level changes without committing.
• expflow status --history lists recent tree restore references.
• expflow status --node-history <path> lists node restore references for a tracked path.
• expflow restore <reference> --dry-run previews affected paths and conflicting drift.
• expflow restore <reference> --force explicitly overwrites conflicting unrecorded drift.

What Expflow Delegates

Expflow core intentionally does not implement every surrounding integration surface.

• Adapter inspection and reconciliation: belongs in separately versioned adapter packages.
• External revision cursors and idempotency: outside the core repository.
• Guerilla hook dispatch: compatibility reference only, not an Expflow core runtime.
• Network services, databases, and brokers: absent from the local core.
• Archive extraction and generated-code execution: blocked by the Gate D security posture.
• Pilots and empirical evaluation: one repository-owned pilot completed in Phase 7. Broader external pilots, comparative evaluation, multi-user evidence, and adoption evidence remain future work.

Repository Map

• docs/architecture/ contains immutable architecture sources.
• docs/internal/ contains current Build Week governance, status, prompts, and activation records.
• docs/external/ contains current product overviews and narratives.
• docs/releases/v1.1.0/ contains the frozen v1.1.0 release documentation record.
• apps/gui/ contains the local Expflow GUI client and server.
• schemas/ and examples/ mirror the architecture schemas and examples for tooling.
• src/ contains the TypeScript package, CLI, GUI bridge, read-model runtime, evidence runtime, portable package runtime, material runtime, Gate C library runtimes, Gate D security/migration runtimes, and contract tooling.
• python/expflow_hooks/ contains the Python hook-package scaffold and repository-only schema discovery.
• tests/ contains repository-contract, material-runtime, evidence-intake, authority, Gate C ownership/reproduction, Gate D security/migration, package, and end-to-end proof tests.

For implementation status, see docs/internal/CURRENT_STATUS_MATRIX.md. For contributor setup and validation commands, see README_DEV.md.

Validation

npm ci
npm run validate
python -m pip install -e ".[dev]"
python -m pytest
python -m build --wheel
python tests/contracts/verify_python_wheel.py

Documentation

• v1.1.0 GitHub release note
• v1 compatibility promise
• Release publishing policy
• Current status matrix
• Developer guide
• Security policy

License

Expflow is released under the MIT License.