Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions kits/profile-dev-kit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -426,3 +426,31 @@ replaces those placeholders, adds any literal arguments and the matching
qualified `allowed_tools` entry. Consent is obtained outside a run with
`python -m beddel_protocol_mcp.authorize`. Nothing returned by the copy is
read back or stored.

## Delivery: plan stage

The `plan-story` entry workflow accepts `repo_path`, `story_key`, `story_path`,
`guide_path` and `spec_path`. It reconciles one repository-relative spec, asks a
Coding agent through `agent-exec` to write it only when needed, settles the
work-tree result, and records the Stage outcome. The stage never implements,
tests, verifies or commits the story.

A complete spec is UTF-8, at most 262144 bytes, has YAML front matter with
`story_key`, non-empty `requirements`, non-empty `repositories`, `dependencies`
and `size_cap_bytes` from 1 through 64000, and has a non-blank body. The
`story_key` and the five front-matter fields are the only contract fields read
by the kit; other fields remain available to the authoring process.

Stage outcomes use fixed outcomes (`succeeded`, `refused`, `failed`, `stopped`)
and reason codes. Each record is canonical JSON under
`~/.config/beddel/records/profile-dev/<repository-key>/stage-outcomes/<n>.json`
with `schema`, `record`, `stage`, `story_key`, `outcome`, `reason`, `refs` and
`recorded_at`. Records are append-only and create-only, remain outside the
work tree, and are never committed, never Evidence, a Finding, a Verdict or
an Approval input.

Run the workflow from the repository root, for example:

```text
beddel run -i ... workflows/plan-story.yaml
```
21 changes: 21 additions & 0 deletions kits/profile-dev-kit/kit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,18 @@ tools:
target: "beddel_profile_dev.tools.approval:profile_read_approval"
description: "Read the stored Change Approval without writing records"
category: profile
- name: profile_plan_reconcile
target: "beddel_profile_dev.tools.plan:profile_plan_reconcile"
description: "Reconcile one story with one implementation spec"
category: profile
- name: profile_plan_settle
target: "beddel_profile_dev.tools.plan:profile_plan_settle"
description: "Settle a plan stage without writing or committing the spec"
category: profile
- name: profile_record_stage_outcome
target: "beddel_profile_dev.tools.stage_outcome:profile_record_stage_outcome"
description: "Append one create-only Stage outcome record outside the repository"
category: profile

workflows:
- name: verify-change
Expand All @@ -123,6 +135,9 @@ workflows:
- name: read-approval
path: workflows/read-approval.yaml
description: Reads the stored Change Approval without writing records.
- name: plan-story
path: workflows/plan-story.yaml
description: Plans one selected story into one implementation spec through a Coding agent; never implements, verifies or commits.

targets:
python:
Expand Down Expand Up @@ -162,6 +177,12 @@ targets:
target: "beddel_profile_dev.tools.approval_decision:profile_record_approval_decision"
- name: profile_read_approval
target: "beddel_profile_dev.tools.approval:profile_read_approval"
- name: profile_plan_reconcile
target: "beddel_profile_dev.tools.plan:profile_plan_reconcile"
- name: profile_plan_settle
target: "beddel_profile_dev.tools.plan:profile_plan_settle"
- name: profile_record_stage_outcome
target: "beddel_profile_dev.tools.stage_outcome:profile_record_stage_outcome"
typescript:
status: unavailable
unavailable_reason: >
Expand Down
8 changes: 8 additions & 0 deletions kits/profile-dev-kit/python/beddel_profile_dev/_errors.py
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,13 @@
"PROFILE_INVENTORY_BINDING_CONFLICT",
"PROFILE_INVENTORY_INTEGRITY_BLOCK",
"PROFILE_INVENTORY_UNRATIFIED",
"PROFILE_PLAN_REFUSED",
"PROFILE_PREFLIGHT_FAILED",
"PROFILE_PUBLICATION_REFUSED",
"PROFILE_RATIFICATION_REFUSED",
"PROFILE_REPOSITORY_INVALID",
"PROFILE_REVIEW_UNSCOPED",
"PROFILE_STAGE_OUTCOME_REFUSED",
"ProfileError",
]

Expand All @@ -48,6 +50,12 @@
PROFILE_PREFLIGHT_FAILED = "PROFILE_PREFLIGHT_FAILED"
"""Raised when one or more preflight checks fail."""

PROFILE_PLAN_REFUSED = "PROFILE_PLAN_REFUSED"
"""Raised when a plan stage cannot safely reconcile its spec input."""

PROFILE_STAGE_OUTCOME_REFUSED = "PROFILE_STAGE_OUTCOME_REFUSED"
"""Raised when a Stage outcome record fails validation before writing."""

PROFILE_PUBLICATION_REFUSED = "PROFILE_PUBLICATION_REFUSED"
"""Raised when no recorded Re-verification can be read for publication (nothing is written)."""

Expand Down
34 changes: 34 additions & 0 deletions kits/profile-dev-kit/python/beddel_profile_dev/_io.py
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
__all__ = [
"blob_at",
"canonical_json",
"changed_paths",
"confined",
"diff_text",
"footprint",
Expand Down Expand Up @@ -508,6 +509,39 @@ def work_tree_at(repo: Path, sha: str) -> bool:
return True


def changed_paths(repo: Path) -> set[str]:
"""Return every work-tree path changed from the index or HEAD."""
result = _git(
repo,
"--no-optional-locks",
"status",
"--porcelain=v1",
"-z",
"--untracked-files=all",
"--ignore-submodules=none",
)
if result is None or result.returncode != 0:
raise _repo_error()
tokens = result.stdout.decode("utf-8", "surrogateescape").split("\0")
paths: set[str] = set()
index = 0
while index < len(tokens):
token = tokens[index]
index += 1
if not token:
continue
if len(token) < 4:
raise _repo_error()
status = token[:2]
paths.add(token[3:])
if "R" in status or "C" in status:
if index >= len(tokens) or not tokens[index]:
raise _repo_error()
paths.add(tokens[index])
index += 1
return paths


def confined(root: Path, relative: str) -> Path:
"""Return ``root/relative`` if its real path stays inside ``root``."""
target = Path(os.path.realpath(root / relative))
Expand Down
102 changes: 102 additions & 0 deletions kits/profile-dev-kit/python/beddel_profile_dev/plan.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,102 @@
"""Pure validation helpers for the profile plan stage."""

from __future__ import annotations

import re
from collections.abc import Mapping
from typing import Any

import yaml

__all__ = [
"MAX_SIZE_CAP_BYTES",
"MAX_SPEC_BYTES",
"STORY_KEY",
"front_matter",
"relative_path",
"spec_complete",
]

STORY_KEY = re.compile(r"[a-z0-9][a-z0-9._-]{0,127}")
_REQUIREMENT_ID = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,63}")
MAX_SIZE_CAP_BYTES = 64000
MAX_SPEC_BYTES = 262144


def front_matter(data: bytes) -> dict[str, Any] | None:
"""Parse the kit-owned YAML front matter contract, or return ``None``."""
if not data.startswith(b"---\n"):
return None
closing = data.find(b"\n---\n", 4)
if closing < 0:
return None
try:
text = data[4:closing].decode("utf-8")
value = yaml.safe_load(text)
except (UnicodeDecodeError, TypeError, ValueError, RecursionError, yaml.YAMLError):
return None
return dict(value) if isinstance(value, Mapping) else None


def relative_path(value: object, *, allow_dot: bool = False) -> bool:
"""Return whether ``value`` is a normalized repository-relative POSIX path."""
if not isinstance(value, str) or not value or "\\" in value:
return False
if value == ".":
return allow_dot
if value.startswith("/") or any(
ord(char) < 32 or ord(char) == 127 for char in value
):
return False
return not any(segment in ("", ".", "..") for segment in value.split("/"))


def _valid_story_key(value: object) -> bool:
return isinstance(value, str) and STORY_KEY.fullmatch(value) is not None


def spec_complete(data: bytes, story_key: str) -> bool:
"""Return whether bytes satisfy the complete implementation-spec contract."""
if len(data) > MAX_SPEC_BYTES or not isinstance(story_key, str):
return False
metadata = front_matter(data)
if metadata is None or metadata.get("story_key") != story_key:
return False
closing = data.find(b"\n---\n", 4)
if closing < 0 or not data[closing + len(b"\n---\n") :].strip():
return False

requirements = metadata.get("requirements")
if (
not isinstance(requirements, list)
or not requirements
or not all(
isinstance(item, str) and _REQUIREMENT_ID.fullmatch(item) is not None
for item in requirements
)
):
return False

repositories = metadata.get("repositories")
if (
not isinstance(repositories, list)
or not repositories
or not all(
isinstance(item, str) and relative_path(item, allow_dot=True)
for item in repositories
)
):
return False

dependencies = metadata.get("dependencies")
if not isinstance(dependencies, list) or not all(
_valid_story_key(item) for item in dependencies
):
return False

size_cap = metadata.get("size_cap_bytes")
return (
isinstance(size_cap, int)
and not isinstance(size_cap, bool)
and 1 <= size_cap <= MAX_SIZE_CAP_BYTES
)
Loading
Loading