gooseloop 0.1.0__tar.gz

gooseloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Storm Developments
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gooseloop-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: gooseloop
+Version: 0.1.0
+Summary: Execution shell for goose-recipe pipelines
+Author: Storm Developments
+License: MIT License
+        
+        Copyright (c) 2026 Storm Developments
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Source, https://gitforge.ca/storm/gooseloop
+Keywords: goose,llm,pipeline,agent,automation
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: minijinja>=2; extra == "dev"
+Dynamic: license-file
+
+# gooseloop
+
+An execution shell for [goose](https://block.github.io/goose/) recipe pipelines.
+
+`gooseloop` runs an **Engine** against an **Environment**, driving a `Pipeline`
+of `review -> body -> summary` through goose, with retry, rate-limit handling,
+session bookkeeping, recipe overlay merging, and a typed session ledger.
+
+It is generic. The framework knows nothing about your domain. Engines plug in.
+
+## Install
+
+```
+pip install gooseloop
+```
+
+Or, from a checkout:
+
+```
+pip install -e .
+```
+
+Requires Python 3.11+, the `goose` CLI on `$PATH`, and a YAML recipe directory.
+
+## The shape
+
+Three primitives:
+
+- **Engine** (verbs). Returns a `Pipeline(review, body, summary)`. Owns
+  branching, recipes, scoring, retry rules.
+- **Environment** (nouns). One abstract method (`env_vars()`). Subclasses or
+  contrib mixins (`gooseloop.contrib.CustomerPipelineEnvironment`,
+  `gooseloop.contrib.ClaudeHandoffEnvironment`) add shape-specific contracts.
+- **Pipeline** (the bookend). Review runs first and emits structured routing.
+  Body phases run in queue order (cadence phases + review-spawned branches).
+  Summary runs last and reads the final ledger.
+
+The contract is documented in [`PROTOCOL.md`](PROTOCOL.md).
+The design history lives in [`docs/adr/`](docs/adr/).
+
+## Five minute tour
+
+```python
+from gooseloop import GooseLooper, Engine, Environment, Phase, Pipeline
+
+class HelloEnvironment(Environment):
+    def env_vars(self) -> dict[str, str]:
+        return {"GREETING": "hello"}
+
+class HelloEngine(Engine):
+    name = "hello-world"
+
+    def pipeline(self, ctx) -> Pipeline:
+        return Pipeline(
+            review=Phase(name="review", recipe_path="recipes/review.yaml"),
+            body=[Phase(name="greet", recipe_path="recipes/greet.yaml")],
+            summary=Phase(name="summary", recipe_path="recipes/summary.yaml"),
+        )
+
+GooseLooper(engine=HelloEngine(), environment=HelloEnvironment()).begin_loop()
+```
+
+The framework ships a working version of this engine under `engines/hello_world/`.
+
+## Built-in engines
+
+Three reference engines ship in `engines/`. They live alongside the framework,
+not inside the installed wheel, so run them **from a checkout** (the repo root,
+where `engines/` is importable) and select one with `-e <module>`:
+
+| Engine | What it does | Run (from the repo root) |
+|--------|--------------|--------------------------|
+| `hello_world` | The minimal reference engine (the tour above). | `python3 -m gooseloop run -e engines.hello_world` |
+| `git_recap` | Summarises your recent commits across configured repos into a changelog. Configure `[git_recap]` in `gooseloop.toml`. | `python3 -m gooseloop run -e engines.git_recap` |
+| `doc_drift` | Finds derived docs/pages that fell behind their canonical source and drafts a patch to seal. Configure `[doc_drift]`, then `cp doc-map.example.toml doc-map.toml` and edit. | `python3 -m gooseloop run -e engines.doc_drift` |
+
+Drop `-e` to run whatever `[gooseloop] engine_module` points at (`hello_world`
+by default). The installed `gooseloop` console script is equivalent to
+`python3 -m gooseloop`, but the built-in engines above still need a checkout on
+the path. Add `--review-only` to any of them to stop after the review phase.
+
+## Recipe overlay merge
+
+Recipes compose docker-compose style. The looper resolves layers in this order:
+
+1. Base recipe (declared in `gooseloop.toml`).
+2. `<name>.local.yaml` (gitignored; per-machine).
+3. `--review-overlay X.yaml` / `--summary-overlay X.yaml` (ad-hoc).
+
+Inspect the merged result with `gooseloop recipe --resolve <name>`.
+
+Merge rules table is in [PROTOCOL.md §6](PROTOCOL.md).
+
+## Contrib mixins
+
+Domain-shaped Environment ABCs ship under `gooseloop.contrib`:
+
+- `CustomerPipelineEnvironment`: customer-acquisition pipelines
+  (`build_digest()`, `journal_text()`, `lifecycle_dirs()`, ...).
+- `ClaudeHandoffEnvironment`: Claude design-handoff engines
+  (`handoff_dir()`, `target_repo()`, `dev_up_probe()`, ...).
+
+An engine with no fit subclasses bare `Environment` and writes one method.
+
+## CLI
+
+```
+gooseloop run                      # run the configured engine, one pass
+gooseloop run --review-only        # stop after review
+gooseloop run --review-overlay x.yaml --summary-overlay y.yaml
+gooseloop recipe --resolve review  # print fully-merged recipe
+gooseloop engines                  # list known engines from gooseloop.toml
+```
+
+`gooseloop.toml` at the project root configures which engine, which recipes,
+retry tuning, sessions dir.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Provenance
+
+`gooseloop` was extracted from Storm Developments' customer-acquisition pipeline
+in June 2026. Storm's customer engine remains the reference consumer; the
+framework is independent and OSS-first.

gooseloop-0.1.0/README.md

@@ -0,0 +1,126 @@
+# gooseloop
+
+An execution shell for [goose](https://block.github.io/goose/) recipe pipelines.
+
+`gooseloop` runs an **Engine** against an **Environment**, driving a `Pipeline`
+of `review -> body -> summary` through goose, with retry, rate-limit handling,
+session bookkeeping, recipe overlay merging, and a typed session ledger.
+
+It is generic. The framework knows nothing about your domain. Engines plug in.
+
+## Install
+
+```
+pip install gooseloop
+```
+
+Or, from a checkout:
+
+```
+pip install -e .
+```
+
+Requires Python 3.11+, the `goose` CLI on `$PATH`, and a YAML recipe directory.
+
+## The shape
+
+Three primitives:
+
+- **Engine** (verbs). Returns a `Pipeline(review, body, summary)`. Owns
+  branching, recipes, scoring, retry rules.
+- **Environment** (nouns). One abstract method (`env_vars()`). Subclasses or
+  contrib mixins (`gooseloop.contrib.CustomerPipelineEnvironment`,
+  `gooseloop.contrib.ClaudeHandoffEnvironment`) add shape-specific contracts.
+- **Pipeline** (the bookend). Review runs first and emits structured routing.
+  Body phases run in queue order (cadence phases + review-spawned branches).
+  Summary runs last and reads the final ledger.
+
+The contract is documented in [`PROTOCOL.md`](PROTOCOL.md).
+The design history lives in [`docs/adr/`](docs/adr/).
+
+## Five minute tour
+
+```python
+from gooseloop import GooseLooper, Engine, Environment, Phase, Pipeline
+
+class HelloEnvironment(Environment):
+    def env_vars(self) -> dict[str, str]:
+        return {"GREETING": "hello"}
+
+class HelloEngine(Engine):
+    name = "hello-world"
+
+    def pipeline(self, ctx) -> Pipeline:
+        return Pipeline(
+            review=Phase(name="review", recipe_path="recipes/review.yaml"),
+            body=[Phase(name="greet", recipe_path="recipes/greet.yaml")],
+            summary=Phase(name="summary", recipe_path="recipes/summary.yaml"),
+        )
+
+GooseLooper(engine=HelloEngine(), environment=HelloEnvironment()).begin_loop()
+```
+
+The framework ships a working version of this engine under `engines/hello_world/`.
+
+## Built-in engines
+
+Three reference engines ship in `engines/`. They live alongside the framework,
+not inside the installed wheel, so run them **from a checkout** (the repo root,
+where `engines/` is importable) and select one with `-e <module>`:
+
+| Engine | What it does | Run (from the repo root) |
+|--------|--------------|--------------------------|
+| `hello_world` | The minimal reference engine (the tour above). | `python3 -m gooseloop run -e engines.hello_world` |
+| `git_recap` | Summarises your recent commits across configured repos into a changelog. Configure `[git_recap]` in `gooseloop.toml`. | `python3 -m gooseloop run -e engines.git_recap` |
+| `doc_drift` | Finds derived docs/pages that fell behind their canonical source and drafts a patch to seal. Configure `[doc_drift]`, then `cp doc-map.example.toml doc-map.toml` and edit. | `python3 -m gooseloop run -e engines.doc_drift` |
+
+Drop `-e` to run whatever `[gooseloop] engine_module` points at (`hello_world`
+by default). The installed `gooseloop` console script is equivalent to
+`python3 -m gooseloop`, but the built-in engines above still need a checkout on
+the path. Add `--review-only` to any of them to stop after the review phase.
+
+## Recipe overlay merge
+
+Recipes compose docker-compose style. The looper resolves layers in this order:
+
+1. Base recipe (declared in `gooseloop.toml`).
+2. `<name>.local.yaml` (gitignored; per-machine).
+3. `--review-overlay X.yaml` / `--summary-overlay X.yaml` (ad-hoc).
+
+Inspect the merged result with `gooseloop recipe --resolve <name>`.
+
+Merge rules table is in [PROTOCOL.md §6](PROTOCOL.md).
+
+## Contrib mixins
+
+Domain-shaped Environment ABCs ship under `gooseloop.contrib`:
+
+- `CustomerPipelineEnvironment`: customer-acquisition pipelines
+  (`build_digest()`, `journal_text()`, `lifecycle_dirs()`, ...).
+- `ClaudeHandoffEnvironment`: Claude design-handoff engines
+  (`handoff_dir()`, `target_repo()`, `dev_up_probe()`, ...).
+
+An engine with no fit subclasses bare `Environment` and writes one method.
+
+## CLI
+
+```
+gooseloop run                      # run the configured engine, one pass
+gooseloop run --review-only        # stop after review
+gooseloop run --review-overlay x.yaml --summary-overlay y.yaml
+gooseloop recipe --resolve review  # print fully-merged recipe
+gooseloop engines                  # list known engines from gooseloop.toml
+```
+
+`gooseloop.toml` at the project root configures which engine, which recipes,
+retry tuning, sessions dir.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).
+
+## Provenance
+
+`gooseloop` was extracted from Storm Developments' customer-acquisition pipeline
+in June 2026. Storm's customer engine remains the reference consumer; the
+framework is independent and OSS-first.

gooseloop-0.1.0/gooseloop/__init__.py

@@ -0,0 +1,42 @@
+"""gooseloop — an execution shell for goose-recipe pipelines.
+
+Public surface:
+
+    GooseLooper        - the execution shell
+    Engine             - abstract base for engines
+    Environment        - abstract base for environments (just env_vars)
+    Phase              - one recipe invocation in a Pipeline
+    Pipeline           - named-slot dataclass: review + body + summary
+    Context            - passed to phase callables; typed ledger methods
+    BranchPolicy       - per-recipe rules for routing[] -> Phase building
+    LooperConfig       - resolved gooseloop.toml as a value object
+    predicates         - success_predicate factories
+    protocol           - ReviewOutput / OperatorAction / RoutingEntry types
+    toolkit            - stdlib-only engine helpers (Source, fetch_url, state io)
+    artifact           - versioned artifact contracts for engine composition
+"""
+
+from . import artifact, predicates, protocol, toolkit
+from .branch_policy import BranchPolicy
+from .config import LooperConfig
+from .engine import Engine
+from .environment import Environment
+from .looper import GooseLooper
+from .phase import Context, Phase, Pipeline
+
+__all__ = [
+    "BranchPolicy",
+    "Context",
+    "Engine",
+    "Environment",
+    "GooseLooper",
+    "LooperConfig",
+    "Phase",
+    "Pipeline",
+    "artifact",
+    "predicates",
+    "protocol",
+    "toolkit",
+]
+
+__version__ = "0.1.0"

gooseloop-0.1.0/gooseloop/__main__.py

@@ -0,0 +1,181 @@
+"""`gooseloop` CLI entry point.
+
+Subcommands:
+    run                          Run the configured engine, one pass.
+        --review-only            Stop after the review phase.
+        --review-overlay PATH    Stack a review-recipe overlay (repeatable).
+        --summary-overlay PATH   Stack a summary-recipe overlay (repeatable).
+        --no-save                Don't write a session folder.
+        --no-validate            Skip engine.precheck().
+        --model NAME             Override the configured model.
+
+    recipe --resolve NAME        Print the fully-merged recipe NAME.
+
+    engines                      Print the configured engine module.
+
+Engine discovery: gooseloop.toml's [gooseloop] engine_module = "..." is
+imported and its module-level `engine` attribute is instantiated. Engines
+expose their class as a module-level callable in their __init__.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+from pathlib import Path
+
+from .config import LooperConfig
+from .engine import Engine
+from .environment import Environment
+from .looper import GooseLooper
+from .recipe_merge import load_layered_recipe, resolved_recipe_yaml
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="gooseloop")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    run = sub.add_parser("run", help="run the configured engine, one pass")
+    run.add_argument("-e", "--engine", default=None, metavar="MODULE",
+                     help="override the engine module (default: from gooseloop.toml)")
+    run.add_argument("--review-only", action="store_true",
+                     help="stop after the review phase")
+    run.add_argument("--review-overlay", action="append", default=[],
+                     metavar="PATH", help="stack a review-recipe overlay")
+    run.add_argument("--summary-overlay", action="append", default=[],
+                     metavar="PATH", help="stack a summary-recipe overlay")
+    run.add_argument("--no-save", action="store_true",
+                     help="do not write a session folder")
+    run.add_argument("--no-validate", action="store_true",
+                     help="skip engine.precheck()")
+    run.add_argument("--model", default=None, help="override the configured model")
+
+    rec = sub.add_parser("recipe", help="recipe utilities")
+    rec.add_argument("--resolve", metavar="NAME",
+                     help="print the fully-merged recipe NAME")
+    rec.add_argument("--overlay", action="append", default=[], metavar="PATH",
+                     help="extra overlay path to include in the merge")
+
+    sub.add_parser("engines", help="show the configured engine module")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "run":
+        return _cmd_run(args)
+    if args.cmd == "recipe":
+        return _cmd_recipe(args)
+    if args.cmd == "engines":
+        return _cmd_engines(args)
+    parser.error(f"unknown command: {args.cmd}")
+    return 2  # unreachable
+
+
+def _cmd_run(args: argparse.Namespace) -> int:
+    config = LooperConfig.load()
+    engine, environment = _load_engine_and_environment(config, engine_override=args.engine)
+    looper = GooseLooper(
+        engine=engine,
+        environment=environment,
+        config=config,
+        model=args.model,
+        save=not args.no_save,
+        validate=not args.no_validate,
+        review_only=args.review_only,
+        review_overlays=[Path(p) for p in args.review_overlay],
+        summary_overlays=[Path(p) for p in args.summary_overlay],
+    )
+    result = looper.begin_loop()
+    return 0 if result.get("review_status") != "error" else 1
+
+
+def _cmd_recipe(args: argparse.Namespace) -> int:
+    if not args.resolve:
+        print("usage: gooseloop recipe --resolve NAME [--overlay PATH ...]",
+              file=sys.stderr)
+        return 2
+    config = LooperConfig.load()
+    base_path = (config.anchor / args.resolve).resolve()
+    if not base_path.exists():
+        # Try with .yaml suffix if user passed a bare name.
+        candidate = base_path.with_suffix(".yaml")
+        if candidate.exists():
+            base_path = candidate
+        else:
+            print(f"recipe not found: {base_path}", file=sys.stderr)
+            return 1
+    local = base_path.with_suffix("").with_name(base_path.stem + ".local").with_suffix(".yaml")
+    overlay_paths = [Path(p) for p in args.overlay]
+    merged = load_layered_recipe(
+        base_path,
+        local_path=local if local.exists() else None,
+        overlay_paths=overlay_paths,
+    )
+    print(resolved_recipe_yaml(merged))
+    return 0
+
+
+def _cmd_engines(args: argparse.Namespace) -> int:
+    config = LooperConfig.load()
+    print(f"engine_module: {config.engine_module}")
+    try:
+        mod = importlib.import_module(config.engine_module)
+        engine_cls = getattr(mod, "engine", None)
+        if engine_cls is None:
+            print("  (module has no `engine` attribute)", file=sys.stderr)
+            return 1
+        print(f"engine class:  {engine_cls.__module__}.{engine_cls.__name__}")
+    except ImportError as e:
+        print(f"  import failed: {e}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def _load_engine_and_environment(
+    config: LooperConfig,
+    *,
+    engine_override: str | None = None,
+) -> tuple[Engine, Environment | None]:
+    """Import the engine module; instantiate its `engine` attribute.
+
+    Convention: an engine package exposes a module-level `engine`
+    callable (often the class itself) and optionally an `environment`
+    callable. Both are instantiated with no arguments by default.
+    Engines requiring constructor arguments should ship factory
+    callables in those slots.
+
+    `engine_override` (from `-e`/`--engine`) supersedes
+    `config.engine_module` when provided.
+    """
+    module_name = engine_override or config.engine_module
+    sys.path.insert(0, str(config.anchor))
+    try:
+        mod = importlib.import_module(module_name)
+    except ImportError as e:
+        raise SystemExit(
+            f"gooseloop: cannot import engine module {module_name!r}: {e}"
+        )
+    engine_obj = getattr(mod, "engine", None)
+    if engine_obj is None:
+        raise SystemExit(
+            f"gooseloop: engine module {module_name!r} has no `engine` attribute"
+        )
+    engine = engine_obj() if callable(engine_obj) and not isinstance(engine_obj, Engine) else engine_obj
+    if not isinstance(engine, Engine):
+        raise SystemExit(
+            f"gooseloop: {module_name}.engine did not yield an Engine instance"
+        )
+
+    env_obj = getattr(mod, "environment", None)
+    environment: Environment | None = None
+    if env_obj is not None:
+        environment = env_obj() if callable(env_obj) and not isinstance(env_obj, Environment) else env_obj
+        if not isinstance(environment, Environment):
+            raise SystemExit(
+                f"gooseloop: {module_name}.environment did not yield an Environment instance"
+            )
+    return engine, environment
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gooseloop-0.1.0/gooseloop/artifact.py

@@ -0,0 +1,82 @@
+"""Versioned artifact contracts: how engines compose without knowing each other.
+
+Per PROTOCOL.md §12. When one engine's output is another engine's input, the
+artifact file is the interface between them, and an interface needs a version.
+The producing engine stamps a `schema_version` key into the artifact; the
+consuming engine checks it at read time with check_artifact_version().
+
+The semantics deliberately mirror the review protocol_version check in
+protocol.py, because it is the same problem one level up:
+
+    - Same major, any minor: compatible. Additive schema changes (a new
+      optional field, a new enum value the reader ignores) bump the minor.
+    - Different major, or an unparseable version: refused loudly with
+      ArtifactVersionError. A major mismatch means the reader may
+      misinterpret every entry; limping along is the silent time bomb.
+    - Missing version: the artifact is still read, and a problem string is
+      returned nudging the operator to stamp the file. Fail-safe runs in the
+      KEEP direction: data we cannot positively classify is kept and named
+      out loud, never refused on a technicality. (Pre-versioning artifacts
+      sealed by hand exist; they should not stop working the day the
+      contract gains a version key.)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class ArtifactVersionError(Exception):
+    """The artifact declares a schema version this reader cannot honour."""
+
+
+def check_artifact_version(
+    data: dict[str, Any],
+    supported: str,
+    *,
+    key: str = "schema_version",
+    what: str = "artifact",
+) -> list[str]:
+    """Check a parsed artifact's declared schema version against `supported`.
+
+    Returns a list of problem strings (empty when the version is present and
+    compatible). Raises ArtifactVersionError on a major mismatch or an
+    unparseable declared version.
+
+    Parameters:
+        data: the parsed artifact (the top-level mapping).
+        supported: the version this reader ships, e.g. "1.0".
+        key: the version key inside the artifact.
+        what: human name for the artifact, used in messages.
+    """
+    supported_major = _major(supported, what=f"supported version for {what}")
+
+    declared = data.get(key)
+    if declared is None or str(declared).strip() == "":
+        return [
+            f"{what} has no {key}; assuming {supported} - "
+            f'add `{key} = "{supported}"` to the file'
+        ]
+
+    declared = str(declared).strip()
+    try:
+        declared_major = _major(declared, what=what)
+    except ArtifactVersionError:
+        raise ArtifactVersionError(
+            f"{what} declares {key} {declared!r}, which is not parseable; "
+            f"this reader supports major {supported_major}"
+        ) from None
+
+    if declared_major != supported_major:
+        raise ArtifactVersionError(
+            f"{what} declares {key} {declared!r} (major {declared_major}); "
+            f"this reader supports major {supported_major} only"
+        )
+    return []
+
+
+def _major(version: str, *, what: str) -> int:
+    try:
+        return int(str(version).split(".", 1)[0])
+    except (ValueError, IndexError):
+        raise ArtifactVersionError(f"{what}: version {version!r} is not parseable")

gooseloop-0.1.0/gooseloop/branch_policy.py

@@ -0,0 +1,49 @@
+"""BranchPolicy — per-recipe rules the framework applies when building body Phases.
+
+Per ADR 0007 and PROTOCOL.md §5. The framework consults the engine's
+branch_policies dict for each routing[] entry the review emitted, looking
+up by recipe name. Recipes with no entry get BranchPolicy() defaults
+(no skip, no path tracking, no extra predicate, intent unchecked).
+
+Authors of an engine register policies like:
+
+    class MyEngine(Engine):
+        branch_policies = {
+            "to-outreach": BranchPolicy(
+                skip_when=lambda p: (outreach_dir / f"{p['slug']}.md").exists(),
+                output_path=lambda p: outreach_dir / f"{p['slug']}.md",
+                intent="produce",
+            ),
+        }
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Literal, Optional
+
+
+Intent = Literal["produce", "edit", "edit-or-produce"]
+
+
+@dataclass
+class BranchPolicy:
+    """Per-recipe rules. All fields optional; the default is the no-op policy.
+
+    skip_when: called with the routing entry's params dict.
+        Truthy return skips the phase. A str return is used as the
+        skip reason in the session log.
+    output_path: called with the params dict to compute the deterministic
+        file path the recipe is expected to write. The framework uses this
+        to derive a default success predicate (file_nonempty) and to log
+        the path on success.
+    predicate: explicit success predicate override. Takes the recipe's
+        stdout. If unset and output_path is set, the framework derives a
+        file_nonempty predicate from output_path.
+    intent: declarative tag for the recipe's intent against output_path.
+        Currently informational; reserved for future intent-reconciliation
+        checks. None = unchecked.
+    """
+    skip_when: Optional[Callable[[dict[str, Any]], "bool | str | None"]] = None
+    output_path: Optional[Callable[[dict[str, Any]], Optional[Path]]] = None
+    predicate: Optional[Callable[[str], bool]] = None
+    intent: Optional[Intent] = None