durable-goals 0.1.0__tar.gz

durable_goals-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 durable-goals contributors
+
+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.

durable_goals-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: durable-goals
+Version: 0.1.0
+Summary: A durable, evidence-backed goal protocol for long-running agents
+Author: durable-goals contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/tim-inzitari/durable-goals
+Project-URL: Repository, https://github.com/tim-inzitari/durable-goals
+Project-URL: Issues, https://github.com/tim-inzitari/durable-goals/issues
+Keywords: agents,ai,goals,workflow,dag
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Durable Goals
+
+Durable Goals helps AI agents keep working toward the same goal across long
+conversations, restarts, and multiple agent threads.
+
+Instead of relying on chat history, it stores the goal, changes to the goal,
+evidence, and completion rules in the repository. A small DAG can also expose
+several independent goals so different threads can safely pick up different
+work.
+
+It does **not** run agents or choose models. It gives Codex, Claude Code, local
+scripts, or another harness a shared answer to three questions:
+
+- What is the current goal?
+- What work is ready next?
+- What evidence proves the goal is complete?
+
+## Install
+
+Requires Python 3.11 or newer and has no runtime dependencies.
+
+```bash
+uv tool install durable-goals
+```
+
+Or install it with pip:
+
+```bash
+python -m pip install durable-goals
+```
+
+Then use the `dgoal` command anywhere:
+
+```bash
+dgoal --version
+dgoal init goals/my-goal \
+  --goal-id my-goal \
+  --objective "Describe what needs to be finished."
+```
+
+## Try the example
+
+From a clone of this repository:
+
+```bash
+python -m pip install -e .
+
+dgoal validate examples/model-refresh/gateway.json
+dgoal status examples/model-refresh/gateway.json
+dgoal resolve examples/model-refresh/gateway.json
+```
+
+The basic convention is simple: an agent reads the goal package's `GOAL.md`
+before acting. The repository remains the source of truth, even when the chat
+or process disappears.
+
+## What is included
+
+- Persistent, versioned goal contracts
+- Evidence-backed completion
+- Append-only goal amendments and activation records
+- DAG dependencies for multi-goal workflows
+- Atomic claims so concurrent threads choose different ready goals
+- A dependency-free Python CLI and test suite
+
+## Learn more
+
+Agents and maintainers should read [`AGENTS.md`](AGENTS.md) for the full
+protocol, authority rules, CLI examples, and implementation scope.
+
+- [CLI reference](docs/CLI.md)
+- [Authoritative entry-point convention](docs/AUTHORITATIVE_ENTRYPOINT.md)
+- [Distribution model](docs/DISTRIBUTION.md)
+- [Cross-agent compatibility](docs/SKILL_COMPATIBILITY.md)
+
+## Status
+
+This is an early `0.1` release intended for trusted repositories. SHA-256
+checks protect integrity, but they do not authenticate authors. Use signed
+commits or another trusted transport when writers do not share the same trust
+boundary.
+
+Licensed under the [MIT License](LICENSE).

durable_goals-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Durable Goals
+
+Durable Goals helps AI agents keep working toward the same goal across long
+conversations, restarts, and multiple agent threads.
+
+Instead of relying on chat history, it stores the goal, changes to the goal,
+evidence, and completion rules in the repository. A small DAG can also expose
+several independent goals so different threads can safely pick up different
+work.
+
+It does **not** run agents or choose models. It gives Codex, Claude Code, local
+scripts, or another harness a shared answer to three questions:
+
+- What is the current goal?
+- What work is ready next?
+- What evidence proves the goal is complete?
+
+## Install
+
+Requires Python 3.11 or newer and has no runtime dependencies.
+
+```bash
+uv tool install durable-goals
+```
+
+Or install it with pip:
+
+```bash
+python -m pip install durable-goals
+```
+
+Then use the `dgoal` command anywhere:
+
+```bash
+dgoal --version
+dgoal init goals/my-goal \
+  --goal-id my-goal \
+  --objective "Describe what needs to be finished."
+```
+
+## Try the example
+
+From a clone of this repository:
+
+```bash
+python -m pip install -e .
+
+dgoal validate examples/model-refresh/gateway.json
+dgoal status examples/model-refresh/gateway.json
+dgoal resolve examples/model-refresh/gateway.json
+```
+
+The basic convention is simple: an agent reads the goal package's `GOAL.md`
+before acting. The repository remains the source of truth, even when the chat
+or process disappears.
+
+## What is included
+
+- Persistent, versioned goal contracts
+- Evidence-backed completion
+- Append-only goal amendments and activation records
+- DAG dependencies for multi-goal workflows
+- Atomic claims so concurrent threads choose different ready goals
+- A dependency-free Python CLI and test suite
+
+## Learn more
+
+Agents and maintainers should read [`AGENTS.md`](AGENTS.md) for the full
+protocol, authority rules, CLI examples, and implementation scope.
+
+- [CLI reference](docs/CLI.md)
+- [Authoritative entry-point convention](docs/AUTHORITATIVE_ENTRYPOINT.md)
+- [Distribution model](docs/DISTRIBUTION.md)
+- [Cross-agent compatibility](docs/SKILL_COMPATIBILITY.md)
+
+## Status
+
+This is an early `0.1` release intended for trusted repositories. SHA-256
+checks protect integrity, but they do not authenticate authors. Use signed
+commits or another trusted transport when writers do not share the same trust
+boundary.
+
+Licensed under the [MIT License](LICENSE).

durable_goals-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "durable-goals"
+version = "0.1.0"
+description = "A durable, evidence-backed goal protocol for long-running agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "durable-goals contributors"}]
+keywords = ["agents", "ai", "goals", "workflow", "dag"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/tim-inzitari/durable-goals"
+Repository = "https://github.com/tim-inzitari/durable-goals"
+Issues = "https://github.com/tim-inzitari/durable-goals/issues"
+
+[project.scripts]
+dgoal = "durable_goals.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.data-files]
+"share/durable-goals/schemas" = ["schemas/*.json"]

durable_goals-0.1.0/schemas/activation.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Durable Goals Activation v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "goal_id", "amendment_revision", "activated_at"],
+  "properties": {
+    "schema": {"const": "durable-goals.activation/v1"},
+    "goal_id": {"type": "string", "minLength": 1},
+    "amendment_revision": {"type": "integer", "minimum": 2},
+    "activated_at": {"type": "string", "format": "date-time"},
+    "evidence": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "sha256"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
+        }
+      }
+    }
+  }
+}

durable_goals-0.1.0/schemas/amendment.schema.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Durable Goals Amendment v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "goal_id", "revision", "recorded_at", "authority", "operations", "activation_mode"],
+  "properties": {
+    "schema": {"const": "durable-goals.amendment/v1"},
+    "goal_id": {"type": "string", "minLength": 1},
+    "revision": {"type": "integer", "minimum": 2},
+    "recorded_at": {"type": "string", "format": "date-time"},
+    "authority": {"type": "string", "minLength": 1},
+    "reason": {"type": "string"},
+    "activation_mode": {"enum": ["manual", "immediate", "next_safe_boundary"]},
+    "activation_condition": {"$ref": "contract.schema.json#/$defs/predicate"},
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["op", "path"],
+        "properties": {
+          "op": {"enum": ["set", "remove"]},
+          "path": {"type": "string", "pattern": "^/"},
+          "value": {},
+          "expect": {}
+        },
+        "oneOf": [
+          {"properties": {"op": {"const": "set"}}, "required": ["value"]},
+          {
+            "properties": {"op": {"const": "remove"}},
+            "not": {"required": ["value"]}
+          }
+        ]
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {"properties": {"activation_mode": {"const": "next_safe_boundary"}}},
+      "then": {"required": ["activation_condition"]}
+    }
+  ]
+}

durable_goals-0.1.0/schemas/contract.schema.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Durable Goals Contract v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "goal_id", "revision", "objective", "invariants", "completion"],
+  "properties": {
+    "schema": {"const": "durable-goals.contract/v1"},
+    "goal_id": {"type": "string", "minLength": 1},
+    "revision": {"type": "integer", "minimum": 1},
+    "objective": {"type": "string", "minLength": 1},
+    "invariants": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "statement"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "statement": {"type": "string", "minLength": 1}
+        }
+      }
+    },
+    "completion": {"$ref": "#/$defs/predicate"},
+    "delegations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["goal_id", "owns"],
+        "properties": {
+          "goal_id": {"type": "string", "minLength": 1},
+          "owns": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}
+        }
+      }
+    },
+    "transitions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "goal_id", "goal_gateway", "after"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "goal_id": {"type": "string", "minLength": 1},
+          "goal_gateway": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
+          },
+          "after": {"const": "completion"}
+        }
+      }
+    }
+  },
+  "$defs": {
+    "predicate": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["literal"],
+          "properties": {"literal": {"type": "boolean"}}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["all"],
+          "properties": {"all": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/predicate"}}}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["any"],
+          "properties": {"any": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/predicate"}}}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["not"],
+          "properties": {"not": {"$ref": "#/$defs/predicate"}}
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["evidence", "field"],
+          "properties": {
+            "evidence": {"type": "string", "minLength": 1},
+            "field": {"type": "string", "pattern": "^(/.*)?$"},
+            "equals": {},
+            "gte": {"type": "number"},
+            "lte": {"type": "number"},
+            "exists": {"type": "boolean"}
+          },
+          "oneOf": [
+            {"required": ["equals"]},
+            {"required": ["gte"]},
+            {"required": ["lte"]},
+            {"required": ["exists"]}
+          ]
+        }
+      ]
+    }
+  }
+}

durable_goals-0.1.0/schemas/evidence-index.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Durable Goals Evidence Index v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "goal_id", "entries"],
+  "properties": {
+    "schema": {"const": "durable-goals.evidence-index/v1"},
+    "goal_id": {"type": "string", "minLength": 1},
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "path", "sha256"],
+        "properties": {
+          "id": {"type": "string", "minLength": 1},
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
+          },
+          "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"},
+          "contract_revision": {"type": "integer", "minimum": 1},
+          "recorded_at": {"type": "string", "format": "date-time"}
+        }
+      }
+    }
+  }
+}

durable_goals-0.1.0/schemas/gateway.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Durable Goals Gateway v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "goal_id", "current_revision", "contract", "amendments", "activations", "evidence_index"],
+  "properties": {
+    "schema": {"const": "durable-goals.gateway/v1"},
+    "goal_id": {"type": "string", "minLength": 1},
+    "current_revision": {"type": "integer", "minimum": 1},
+    "contract": {"$ref": "#/$defs/reference"},
+    "amendments": {"$ref": "#/$defs/reference"},
+    "activations": {"$ref": "#/$defs/reference"},
+    "evidence_index": {"$ref": "#/$defs/reference"},
+    "status": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "reference": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["path", "sha256"],
+      "properties": {
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
+        },
+        "sha256": {"type": "string", "pattern": "^sha256:[0-9a-f]{64}$"}
+      }
+    }
+  }
+}

durable_goals-0.1.0/schemas/workflow.schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Durable Goals Workflow v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "workflow_id", "revision", "nodes", "edges"],
+  "properties": {
+    "schema": {"const": "durable-goals.workflow/v1"},
+    "workflow_id": {"$ref": "#/$defs/id"},
+    "revision": {"type": "integer", "minimum": 1},
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "goal_id", "gateway"],
+        "properties": {
+          "id": {"$ref": "#/$defs/id"},
+          "goal_id": {"type": "string", "minLength": 1},
+          "gateway": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^(?!/)(?![A-Za-z]:[\\\\/]).+"
+          }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "from", "to"],
+        "properties": {
+          "id": {"$ref": "#/$defs/id"},
+          "from": {"$ref": "#/$defs/id"},
+          "to": {"$ref": "#/$defs/id"}
+        }
+      }
+    }
+  },
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$"
+    }
+  }
+}

durable_goals-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

durable_goals-0.1.0/src/durable_goals/__init__.py

@@ -0,0 +1,51 @@
+"""Public API for the durable-goals protocol resolver."""
+
+from .errors import GoalError, IntegrityError, ResolutionError, ValidationError
+from .resolve import Resolution, resolve_gateway
+from .writer import (
+    activate_amendment,
+    chain_goal,
+    initialize_goal_package,
+    materialize_status,
+    record_amendment,
+    record_evidence,
+)
+from .workflow import (
+    WorkflowResolution,
+    add_dependency,
+    add_goal_node,
+    claim_next_prompt,
+    initialize_workflow,
+    next_prompts,
+    remove_dependency,
+    remove_goal_node,
+    release_claim,
+    resolve_workflow,
+)
+
+__all__ = [
+    "GoalError",
+    "IntegrityError",
+    "Resolution",
+    "ResolutionError",
+    "ValidationError",
+    "WorkflowResolution",
+    "add_dependency",
+    "add_goal_node",
+    "claim_next_prompt",
+    "activate_amendment",
+    "chain_goal",
+    "initialize_goal_package",
+    "initialize_workflow",
+    "materialize_status",
+    "record_amendment",
+    "record_evidence",
+    "remove_dependency",
+    "remove_goal_node",
+    "release_claim",
+    "resolve_gateway",
+    "resolve_workflow",
+    "next_prompts",
+]
+
+__version__ = "0.1.0"