expflow-hooks 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paragon UX
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,147 @@
1
+ Metadata-Version: 2.4
2
+ Name: expflow-hooks
3
+ Version: 1.0.0
4
+ Summary: Expflow Python hook scaffold and read-only architecture schema discovery
5
+ Author-email: Paragon AI <work.jlines@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/paragon-ux/Expflow
8
+ Project-URL: Issues, https://github.com/paragon-ux/Expflow/issues
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Intended Audience :: Developers
12
+ Requires-Python: >=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Provides-Extra: dev
16
+ Requires-Dist: jsonschema>=4.23.0; extra == "dev"
17
+ Requires-Dist: pytest>=8.3.0; extra == "dev"
18
+ Requires-Dist: build>=1.2.0; extra == "dev"
19
+ Requires-Dist: twine>=6.1.0; extra == "dev"
20
+ Dynamic: license-file
21
+
22
+ [![CI](https://github.com/paragon-ux/Expflow/actions/workflows/phase-1-contract.yml/badge.svg)](https://github.com/paragon-ux/Expflow/actions/workflows/phase-1-contract.yml)
23
+
24
+ # Expflow
25
+
26
+ Expflow is a schema-governed, local-first workflow ownership and observability platform for projects where people, agents, and tools produce changing artifact trees.
27
+
28
+ Expflow records what changed, which evidence was trusted, which decisions remain durable, and which outputs can be inspected, regenerated, restored, or reused.
29
+
30
+ Current release: [`v1.0.0`](docs/release_notes/GITHUB_RELEASE_NOTE_V1_0_0.md).
31
+
32
+ ## What Expflow Tracks
33
+
34
+ Expflow separates five concerns that are often blurred in automated work:
35
+
36
+ - material files before and after workflow activity;
37
+ - accepted authority sources for the work;
38
+ - attributed claims, decisions, conflicts, and review requests;
39
+ - workflow inputs, outputs, projections, regeneration attempts, equivalence evaluations, and reuse evidence;
40
+ - local security, migration, package, and proof evidence.
41
+
42
+ Material output does not imply semantic acceptance, workflow completion, or reuse permission. Expflow keeps those records separate.
43
+
44
+ ## Release Scope
45
+
46
+ Expflow v1.0.0 covers the local core surfaces implemented in this repository:
47
+
48
+ - four ordinary commands: `expflow init`, `expflow sync`, `expflow status`, and `expflow restore`;
49
+ - local `.expflow/` material storage with immutable object, node-revision, tree-revision, receipt, validation, change, and material-head records;
50
+ - complete-tree sync, drift status, tree/node restore, scoped path selection, explicit identity directives, and digest-similarity proposals without silent identity preservation;
51
+ - project locks, operation-scoped staging, recoverable init/restore intents, stale-lock classification, causal tree/receipt head repair, restore recovery, and restored-tree digest verification;
52
+ - library runtimes for authority sources, semantic decisions, workflow boundaries, projections, regeneration/equivalence, structural reuse, security controls, migration evidence, and the native extension host;
53
+ - repository-contract checks for immutable architecture sources, schemas, examples, fixtures, registries, package boundaries, and end-to-end proof.
54
+
55
+ ## Quickstart
56
+
57
+ With the npm package available from the public registry:
58
+
59
+ ```bash
60
+ npm install -g expflow
61
+ expflow init
62
+ expflow status
63
+ ```
64
+
65
+ 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.
66
+
67
+ ## Installation
68
+
69
+ After verified registry publication, install the primary Expflow CLI and TypeScript package with:
70
+
71
+ ```bash
72
+ npm install -g expflow
73
+ ```
74
+
75
+ Install the Python hook scaffold separately with:
76
+
77
+ ```bash
78
+ pip install expflow-hooks
79
+ ```
80
+
81
+ `expflow-hooks` is not the primary Expflow CLI implementation. It exposes the limited Python hook/scaffold package and `expflow_hooks` import surface.
82
+
83
+ ## Workflow
84
+
85
+ 1. Run `expflow init` to create local Expflow state.
86
+ 2. Change files in the project tree.
87
+ 3. Run `expflow sync` to record a complete material tree revision.
88
+ 4. Run `expflow status` to inspect drift and recorded state.
89
+ 5. Run `expflow restore` when a recorded tree or node revision should be restored.
90
+
91
+ Gate C ownership/reproduction behavior and Gate D security/migration behavior are available through library runtimes rather than additional ordinary commands.
92
+
93
+ ## Commands
94
+
95
+ | Command | Purpose |
96
+ | ----------------- | ------------------------------------------------------------------- |
97
+ | `expflow init` | Initialize local Expflow project state. |
98
+ | `expflow sync` | Scan the working tree and commit a complete material tree revision. |
99
+ | `expflow status` | Report local drift and material project state. |
100
+ | `expflow restore` | Restore a recorded material tree or node revision. |
101
+
102
+ ## What Expflow Delegates
103
+
104
+ Expflow core intentionally does not implement every surrounding integration surface.
105
+
106
+ - **Adapter inspection and reconciliation:** belongs in separately versioned adapter packages.
107
+ - **External revision cursors and idempotency:** outside the core repository.
108
+ - **Guerilla hook dispatch:** compatibility reference only, not an Expflow core runtime.
109
+ - **Network services, databases, and brokers:** absent from the local core.
110
+ - **Archive extraction and generated-code execution:** blocked by the Gate D security posture.
111
+ - **Pilots and empirical evaluation:** future work outside the v1.0.0 core release.
112
+
113
+ ## Repository Map
114
+
115
+ - `docs/architecture/` contains immutable architecture sources.
116
+ - `docs/` contains mutable implementation evidence, completion reports, release notes, review summaries, and orientation.
117
+ - `schemas/` and `examples/` mirror the architecture schemas and examples for tooling.
118
+ - `src/` contains the TypeScript package, CLI, material runtime, Gate C library runtimes, Gate D security/migration runtimes, and contract tooling.
119
+ - `python/expflow_hooks/` contains the Python hook-package scaffold and repository-only schema discovery.
120
+ - `tests/` contains repository-contract, material-runtime, authority, Gate C ownership/reproduction, Gate D security/migration, package, and end-to-end proof tests.
121
+
122
+ For implementation status, see [docs/CURRENT_STATUS_MATRIX.md](docs/CURRENT_STATUS_MATRIX.md). For contributor setup and validation commands, see [README_DEV.md](README_DEV.md).
123
+
124
+ ## Validation
125
+
126
+ ```bash
127
+ npm ci
128
+ npm run validate
129
+ python -m pip install -e ".[dev]"
130
+ python -m pytest
131
+ python -m build --wheel
132
+ python tests/contracts/verify_python_wheel.py
133
+ ```
134
+
135
+ ## Documentation
136
+
137
+ - [v1.0.0 GitHub release note](docs/release_notes/GITHUB_RELEASE_NOTE_V1_0_0.md)
138
+ - [v1 compatibility promise](docs/V1_COMPATIBILITY.md)
139
+ - [Release publishing checklist](docs/RELEASE_PUBLISHING.md)
140
+ - [Current status matrix](docs/CURRENT_STATUS_MATRIX.md)
141
+ - [Developer guide](README_DEV.md)
142
+ - [Repository directory structure](docs/REPOSITORY_DIRECTORY_STRUCTURE.md)
143
+ - [Security policy](SECURITY.md)
144
+
145
+ ## License
146
+
147
+ Expflow is released under the [MIT License](LICENSE).
@@ -0,0 +1,126 @@
1
+ [![CI](https://github.com/paragon-ux/Expflow/actions/workflows/phase-1-contract.yml/badge.svg)](https://github.com/paragon-ux/Expflow/actions/workflows/phase-1-contract.yml)
2
+
3
+ # Expflow
4
+
5
+ Expflow is a schema-governed, local-first workflow ownership and observability platform for projects where people, agents, and tools produce changing artifact trees.
6
+
7
+ Expflow records what changed, which evidence was trusted, which decisions remain durable, and which outputs can be inspected, regenerated, restored, or reused.
8
+
9
+ Current release: [`v1.0.0`](docs/release_notes/GITHUB_RELEASE_NOTE_V1_0_0.md).
10
+
11
+ ## What Expflow Tracks
12
+
13
+ Expflow separates five concerns that are often blurred in automated work:
14
+
15
+ - material files before and after workflow activity;
16
+ - accepted authority sources for the work;
17
+ - attributed claims, decisions, conflicts, and review requests;
18
+ - workflow inputs, outputs, projections, regeneration attempts, equivalence evaluations, and reuse evidence;
19
+ - local security, migration, package, and proof evidence.
20
+
21
+ Material output does not imply semantic acceptance, workflow completion, or reuse permission. Expflow keeps those records separate.
22
+
23
+ ## Release Scope
24
+
25
+ Expflow v1.0.0 covers the local core surfaces implemented in this repository:
26
+
27
+ - four ordinary commands: `expflow init`, `expflow sync`, `expflow status`, and `expflow restore`;
28
+ - local `.expflow/` material storage with immutable object, node-revision, tree-revision, receipt, validation, change, and material-head records;
29
+ - complete-tree sync, drift status, tree/node restore, scoped path selection, explicit identity directives, and digest-similarity proposals without silent identity preservation;
30
+ - project locks, operation-scoped staging, recoverable init/restore intents, stale-lock classification, causal tree/receipt head repair, restore recovery, and restored-tree digest verification;
31
+ - library runtimes for authority sources, semantic decisions, workflow boundaries, projections, regeneration/equivalence, structural reuse, security controls, migration evidence, and the native extension host;
32
+ - repository-contract checks for immutable architecture sources, schemas, examples, fixtures, registries, package boundaries, and end-to-end proof.
33
+
34
+ ## Quickstart
35
+
36
+ With the npm package available from the public registry:
37
+
38
+ ```bash
39
+ npm install -g expflow
40
+ expflow init
41
+ expflow status
42
+ ```
43
+
44
+ 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.
45
+
46
+ ## Installation
47
+
48
+ After verified registry publication, install the primary Expflow CLI and TypeScript package with:
49
+
50
+ ```bash
51
+ npm install -g expflow
52
+ ```
53
+
54
+ Install the Python hook scaffold separately with:
55
+
56
+ ```bash
57
+ pip install expflow-hooks
58
+ ```
59
+
60
+ `expflow-hooks` is not the primary Expflow CLI implementation. It exposes the limited Python hook/scaffold package and `expflow_hooks` import surface.
61
+
62
+ ## Workflow
63
+
64
+ 1. Run `expflow init` to create local Expflow state.
65
+ 2. Change files in the project tree.
66
+ 3. Run `expflow sync` to record a complete material tree revision.
67
+ 4. Run `expflow status` to inspect drift and recorded state.
68
+ 5. Run `expflow restore` when a recorded tree or node revision should be restored.
69
+
70
+ Gate C ownership/reproduction behavior and Gate D security/migration behavior are available through library runtimes rather than additional ordinary commands.
71
+
72
+ ## Commands
73
+
74
+ | Command | Purpose |
75
+ | ----------------- | ------------------------------------------------------------------- |
76
+ | `expflow init` | Initialize local Expflow project state. |
77
+ | `expflow sync` | Scan the working tree and commit a complete material tree revision. |
78
+ | `expflow status` | Report local drift and material project state. |
79
+ | `expflow restore` | Restore a recorded material tree or node revision. |
80
+
81
+ ## What Expflow Delegates
82
+
83
+ Expflow core intentionally does not implement every surrounding integration surface.
84
+
85
+ - **Adapter inspection and reconciliation:** belongs in separately versioned adapter packages.
86
+ - **External revision cursors and idempotency:** outside the core repository.
87
+ - **Guerilla hook dispatch:** compatibility reference only, not an Expflow core runtime.
88
+ - **Network services, databases, and brokers:** absent from the local core.
89
+ - **Archive extraction and generated-code execution:** blocked by the Gate D security posture.
90
+ - **Pilots and empirical evaluation:** future work outside the v1.0.0 core release.
91
+
92
+ ## Repository Map
93
+
94
+ - `docs/architecture/` contains immutable architecture sources.
95
+ - `docs/` contains mutable implementation evidence, completion reports, release notes, review summaries, and orientation.
96
+ - `schemas/` and `examples/` mirror the architecture schemas and examples for tooling.
97
+ - `src/` contains the TypeScript package, CLI, material runtime, Gate C library runtimes, Gate D security/migration runtimes, and contract tooling.
98
+ - `python/expflow_hooks/` contains the Python hook-package scaffold and repository-only schema discovery.
99
+ - `tests/` contains repository-contract, material-runtime, authority, Gate C ownership/reproduction, Gate D security/migration, package, and end-to-end proof tests.
100
+
101
+ For implementation status, see [docs/CURRENT_STATUS_MATRIX.md](docs/CURRENT_STATUS_MATRIX.md). For contributor setup and validation commands, see [README_DEV.md](README_DEV.md).
102
+
103
+ ## Validation
104
+
105
+ ```bash
106
+ npm ci
107
+ npm run validate
108
+ python -m pip install -e ".[dev]"
109
+ python -m pytest
110
+ python -m build --wheel
111
+ python tests/contracts/verify_python_wheel.py
112
+ ```
113
+
114
+ ## Documentation
115
+
116
+ - [v1.0.0 GitHub release note](docs/release_notes/GITHUB_RELEASE_NOTE_V1_0_0.md)
117
+ - [v1 compatibility promise](docs/V1_COMPATIBILITY.md)
118
+ - [Release publishing checklist](docs/RELEASE_PUBLISHING.md)
119
+ - [Current status matrix](docs/CURRENT_STATUS_MATRIX.md)
120
+ - [Developer guide](README_DEV.md)
121
+ - [Repository directory structure](docs/REPOSITORY_DIRECTORY_STRUCTURE.md)
122
+ - [Security policy](SECURITY.md)
123
+
124
+ ## License
125
+
126
+ Expflow is released under the [MIT License](LICENSE).
@@ -0,0 +1,40 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77.0.3"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "expflow-hooks"
7
+ version = "1.0.0"
8
+ authors = [
9
+ { name="Paragon AI", email="work.jlines@gmail.com" },
10
+ ]
11
+ description = "Expflow Python hook scaffold and read-only architecture schema discovery"
12
+ requires-python = ">=3.11"
13
+ classifiers = [
14
+ "Programming Language :: Python :: 3",
15
+ "Operating System :: OS Independent",
16
+ "Intended Audience :: Developers",
17
+ ]
18
+ license = "MIT"
19
+ license-files = ["LICENSE"]
20
+ readme = "README.md"
21
+
22
+ [project.urls]
23
+ Repository = "https://github.com/paragon-ux/Expflow"
24
+ Issues = "https://github.com/paragon-ux/Expflow/issues"
25
+
26
+ [project.optional-dependencies]
27
+ dev = [
28
+ "jsonschema>=4.23.0",
29
+ "pytest>=8.3.0",
30
+ "build>=1.2.0",
31
+ "twine>=6.1.0",
32
+ ]
33
+
34
+ [tool.setuptools.packages.find]
35
+ where = ["python"]
36
+ include = ["expflow_hooks*"]
37
+
38
+ [tool.pytest.ini_options]
39
+ testpaths = ["python/tests"]
40
+ python_files = ["test_*.py"]
@@ -0,0 +1,8 @@
1
+ """
2
+ Expflow Python hook package - v1 scaffold.
3
+
4
+ This package contains no product runtime implementation.
5
+ No hook registration, dispatch, or execution exists in core.
6
+ """
7
+
8
+ __version__ = "1.0.0"
@@ -0,0 +1,54 @@
1
+ """Read-only discovery of architecture schema-source directory.
2
+
3
+ Phase 1 scaffold only. No product runtime behavior exists.
4
+
5
+ Architecture sources are repository-contract inputs and are not packaged into
6
+ the Python wheel. Installed wheels can import the package and report the
7
+ contract version, while architecture discovery is explicitly available only
8
+ from an editable repository checkout.
9
+ """
10
+
11
+ from pathlib import Path
12
+
13
+ _REPO_ROOT = Path(__file__).resolve().parent.parent.parent
14
+ ARCHITECTURE_DIR = _REPO_ROOT / "docs" / "architecture"
15
+ SCHEMAS_DIR = ARCHITECTURE_DIR / "schemas"
16
+ SOURCE_MANIFEST_PATH = ARCHITECTURE_DIR / "SOURCE_MANIFEST.json"
17
+ ARCHITECTURE_DISCOVERY_MODE = "editable-repository"
18
+
19
+
20
+ def architecture_sources_available() -> bool:
21
+ """Return whether repository architecture sources are available."""
22
+ return (
23
+ ARCHITECTURE_DIR.is_dir()
24
+ and SCHEMAS_DIR.is_dir()
25
+ and SOURCE_MANIFEST_PATH.is_file()
26
+ )
27
+
28
+
29
+ def require_repository_architecture() -> None:
30
+ """Require architecture sources from an editable repository checkout."""
31
+ if architecture_sources_available():
32
+ return
33
+
34
+ missing = [
35
+ path
36
+ for path in (ARCHITECTURE_DIR, SCHEMAS_DIR, SOURCE_MANIFEST_PATH)
37
+ if not path.exists()
38
+ ]
39
+ missing_text = ", ".join(str(path) for path in missing)
40
+ raise FileNotFoundError(
41
+ "Expflow Phase 1 Python architecture discovery is available only from "
42
+ "an editable repository checkout; installed wheels do not package "
43
+ f"docs/architecture. Missing: {missing_text}"
44
+ )
45
+
46
+
47
+ __all__ = [
48
+ "ARCHITECTURE_DIR",
49
+ "ARCHITECTURE_DISCOVERY_MODE",
50
+ "SCHEMAS_DIR",
51
+ "SOURCE_MANIFEST_PATH",
52
+ "architecture_sources_available",
53
+ "require_repository_architecture",
54
+ ]
@@ -0,0 +1,147 @@
1
+ Metadata-Version: 2.4
2
+ Name: expflow-hooks
3
+ Version: 1.0.0
4
+ Summary: Expflow Python hook scaffold and read-only architecture schema discovery
5
+ Author-email: Paragon AI <work.jlines@gmail.com>
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/paragon-ux/Expflow
8
+ Project-URL: Issues, https://github.com/paragon-ux/Expflow/issues
9
+ Classifier: Programming Language :: Python :: 3
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Intended Audience :: Developers
12
+ Requires-Python: >=3.11
13
+ Description-Content-Type: text/markdown
14
+ License-File: LICENSE
15
+ Provides-Extra: dev
16
+ Requires-Dist: jsonschema>=4.23.0; extra == "dev"
17
+ Requires-Dist: pytest>=8.3.0; extra == "dev"
18
+ Requires-Dist: build>=1.2.0; extra == "dev"
19
+ Requires-Dist: twine>=6.1.0; extra == "dev"
20
+ Dynamic: license-file
21
+
22
+ [![CI](https://github.com/paragon-ux/Expflow/actions/workflows/phase-1-contract.yml/badge.svg)](https://github.com/paragon-ux/Expflow/actions/workflows/phase-1-contract.yml)
23
+
24
+ # Expflow
25
+
26
+ Expflow is a schema-governed, local-first workflow ownership and observability platform for projects where people, agents, and tools produce changing artifact trees.
27
+
28
+ Expflow records what changed, which evidence was trusted, which decisions remain durable, and which outputs can be inspected, regenerated, restored, or reused.
29
+
30
+ Current release: [`v1.0.0`](docs/release_notes/GITHUB_RELEASE_NOTE_V1_0_0.md).
31
+
32
+ ## What Expflow Tracks
33
+
34
+ Expflow separates five concerns that are often blurred in automated work:
35
+
36
+ - material files before and after workflow activity;
37
+ - accepted authority sources for the work;
38
+ - attributed claims, decisions, conflicts, and review requests;
39
+ - workflow inputs, outputs, projections, regeneration attempts, equivalence evaluations, and reuse evidence;
40
+ - local security, migration, package, and proof evidence.
41
+
42
+ Material output does not imply semantic acceptance, workflow completion, or reuse permission. Expflow keeps those records separate.
43
+
44
+ ## Release Scope
45
+
46
+ Expflow v1.0.0 covers the local core surfaces implemented in this repository:
47
+
48
+ - four ordinary commands: `expflow init`, `expflow sync`, `expflow status`, and `expflow restore`;
49
+ - local `.expflow/` material storage with immutable object, node-revision, tree-revision, receipt, validation, change, and material-head records;
50
+ - complete-tree sync, drift status, tree/node restore, scoped path selection, explicit identity directives, and digest-similarity proposals without silent identity preservation;
51
+ - project locks, operation-scoped staging, recoverable init/restore intents, stale-lock classification, causal tree/receipt head repair, restore recovery, and restored-tree digest verification;
52
+ - library runtimes for authority sources, semantic decisions, workflow boundaries, projections, regeneration/equivalence, structural reuse, security controls, migration evidence, and the native extension host;
53
+ - repository-contract checks for immutable architecture sources, schemas, examples, fixtures, registries, package boundaries, and end-to-end proof.
54
+
55
+ ## Quickstart
56
+
57
+ With the npm package available from the public registry:
58
+
59
+ ```bash
60
+ npm install -g expflow
61
+ expflow init
62
+ expflow status
63
+ ```
64
+
65
+ 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.
66
+
67
+ ## Installation
68
+
69
+ After verified registry publication, install the primary Expflow CLI and TypeScript package with:
70
+
71
+ ```bash
72
+ npm install -g expflow
73
+ ```
74
+
75
+ Install the Python hook scaffold separately with:
76
+
77
+ ```bash
78
+ pip install expflow-hooks
79
+ ```
80
+
81
+ `expflow-hooks` is not the primary Expflow CLI implementation. It exposes the limited Python hook/scaffold package and `expflow_hooks` import surface.
82
+
83
+ ## Workflow
84
+
85
+ 1. Run `expflow init` to create local Expflow state.
86
+ 2. Change files in the project tree.
87
+ 3. Run `expflow sync` to record a complete material tree revision.
88
+ 4. Run `expflow status` to inspect drift and recorded state.
89
+ 5. Run `expflow restore` when a recorded tree or node revision should be restored.
90
+
91
+ Gate C ownership/reproduction behavior and Gate D security/migration behavior are available through library runtimes rather than additional ordinary commands.
92
+
93
+ ## Commands
94
+
95
+ | Command | Purpose |
96
+ | ----------------- | ------------------------------------------------------------------- |
97
+ | `expflow init` | Initialize local Expflow project state. |
98
+ | `expflow sync` | Scan the working tree and commit a complete material tree revision. |
99
+ | `expflow status` | Report local drift and material project state. |
100
+ | `expflow restore` | Restore a recorded material tree or node revision. |
101
+
102
+ ## What Expflow Delegates
103
+
104
+ Expflow core intentionally does not implement every surrounding integration surface.
105
+
106
+ - **Adapter inspection and reconciliation:** belongs in separately versioned adapter packages.
107
+ - **External revision cursors and idempotency:** outside the core repository.
108
+ - **Guerilla hook dispatch:** compatibility reference only, not an Expflow core runtime.
109
+ - **Network services, databases, and brokers:** absent from the local core.
110
+ - **Archive extraction and generated-code execution:** blocked by the Gate D security posture.
111
+ - **Pilots and empirical evaluation:** future work outside the v1.0.0 core release.
112
+
113
+ ## Repository Map
114
+
115
+ - `docs/architecture/` contains immutable architecture sources.
116
+ - `docs/` contains mutable implementation evidence, completion reports, release notes, review summaries, and orientation.
117
+ - `schemas/` and `examples/` mirror the architecture schemas and examples for tooling.
118
+ - `src/` contains the TypeScript package, CLI, material runtime, Gate C library runtimes, Gate D security/migration runtimes, and contract tooling.
119
+ - `python/expflow_hooks/` contains the Python hook-package scaffold and repository-only schema discovery.
120
+ - `tests/` contains repository-contract, material-runtime, authority, Gate C ownership/reproduction, Gate D security/migration, package, and end-to-end proof tests.
121
+
122
+ For implementation status, see [docs/CURRENT_STATUS_MATRIX.md](docs/CURRENT_STATUS_MATRIX.md). For contributor setup and validation commands, see [README_DEV.md](README_DEV.md).
123
+
124
+ ## Validation
125
+
126
+ ```bash
127
+ npm ci
128
+ npm run validate
129
+ python -m pip install -e ".[dev]"
130
+ python -m pytest
131
+ python -m build --wheel
132
+ python tests/contracts/verify_python_wheel.py
133
+ ```
134
+
135
+ ## Documentation
136
+
137
+ - [v1.0.0 GitHub release note](docs/release_notes/GITHUB_RELEASE_NOTE_V1_0_0.md)
138
+ - [v1 compatibility promise](docs/V1_COMPATIBILITY.md)
139
+ - [Release publishing checklist](docs/RELEASE_PUBLISHING.md)
140
+ - [Current status matrix](docs/CURRENT_STATUS_MATRIX.md)
141
+ - [Developer guide](README_DEV.md)
142
+ - [Repository directory structure](docs/REPOSITORY_DIRECTORY_STRUCTURE.md)
143
+ - [Security policy](SECURITY.md)
144
+
145
+ ## License
146
+
147
+ Expflow is released under the [MIT License](LICENSE).
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ python/expflow_hooks/__init__.py
5
+ python/expflow_hooks/discovery.py
6
+ python/expflow_hooks.egg-info/PKG-INFO
7
+ python/expflow_hooks.egg-info/SOURCES.txt
8
+ python/expflow_hooks.egg-info/dependency_links.txt
9
+ python/expflow_hooks.egg-info/requires.txt
10
+ python/expflow_hooks.egg-info/top_level.txt
@@ -0,0 +1,6 @@
1
+
2
+ [dev]
3
+ jsonschema>=4.23.0
4
+ pytest>=8.3.0
5
+ build>=1.2.0
6
+ twine>=6.1.0
@@ -0,0 +1 @@
1
+ expflow_hooks
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+