diff --git a/kits/profile-dev-kit/README.md b/kits/profile-dev-kit/README.md index 5ef7028..169d281 100644 --- a/kits/profile-dev-kit/README.md +++ b/kits/profile-dev-kit/README.md @@ -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//stage-outcomes/.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 +``` diff --git a/kits/profile-dev-kit/kit.yaml b/kits/profile-dev-kit/kit.yaml index 65ff2c1..28d4f82 100644 --- a/kits/profile-dev-kit/kit.yaml +++ b/kits/profile-dev-kit/kit.yaml @@ -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 @@ -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: @@ -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: > diff --git a/kits/profile-dev-kit/python/beddel_profile_dev/_errors.py b/kits/profile-dev-kit/python/beddel_profile_dev/_errors.py index 32cbaab..accf9e9 100644 --- a/kits/profile-dev-kit/python/beddel_profile_dev/_errors.py +++ b/kits/profile-dev-kit/python/beddel_profile_dev/_errors.py @@ -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", ] @@ -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).""" diff --git a/kits/profile-dev-kit/python/beddel_profile_dev/_io.py b/kits/profile-dev-kit/python/beddel_profile_dev/_io.py index e7c6f47..495cbeb 100644 --- a/kits/profile-dev-kit/python/beddel_profile_dev/_io.py +++ b/kits/profile-dev-kit/python/beddel_profile_dev/_io.py @@ -23,6 +23,7 @@ __all__ = [ "blob_at", "canonical_json", + "changed_paths", "confined", "diff_text", "footprint", @@ -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)) diff --git a/kits/profile-dev-kit/python/beddel_profile_dev/plan.py b/kits/profile-dev-kit/python/beddel_profile_dev/plan.py new file mode 100644 index 0000000..247834d --- /dev/null +++ b/kits/profile-dev-kit/python/beddel_profile_dev/plan.py @@ -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 + ) diff --git a/kits/profile-dev-kit/python/beddel_profile_dev/tools/plan.py b/kits/profile-dev-kit/python/beddel_profile_dev/tools/plan.py new file mode 100644 index 0000000..9daea7b --- /dev/null +++ b/kits/profile-dev-kit/python/beddel_profile_dev/tools/plan.py @@ -0,0 +1,387 @@ +"""Plan-stage reconciliation and settlement tools.""" + +from __future__ import annotations + +import hashlib +import os +from collections.abc import Mapping +from pathlib import Path +from typing import Any + +from beddel.tools import beddel_tool + +from beddel_profile_dev._errors import ( + PROFILE_PLAN_REFUSED, + PROFILE_REPOSITORY_INVALID, + ProfileError, +) +from beddel_profile_dev._io import ( + changed_paths, + confined, + real_repo_root, + resolve_revision, +) +from beddel_profile_dev.plan import ( + STORY_KEY, + front_matter, + relative_path, + spec_complete, +) + +__all__ = ["profile_plan_reconcile", "profile_plan_settle"] + + +def _refuse(reason: str) -> ProfileError: + return ProfileError( + PROFILE_PLAN_REFUSED, + f"plan refused: {reason}", + {"reason": reason}, + ) + + +def _valid_story_key(value: object) -> bool: + return isinstance(value, str) and STORY_KEY.fullmatch(value) is not None + + +def _validate_inputs( + story_key: object, story_path: object, guide_path: object, spec_path: object +) -> tuple[str, str, str, str]: + if not _valid_story_key(story_key): + raise _refuse("story_key.invalid") + if ( + not all( + isinstance(value, str) and relative_path(value) + for value in (story_path, guide_path, spec_path) + ) + or not isinstance(spec_path, str) + or len(spec_path) > 512 + ): + raise _refuse("path.invalid") + assert isinstance(story_key, str) + assert isinstance(story_path, str) + assert isinstance(guide_path, str) + assert isinstance(spec_path, str) + return story_key, story_path, guide_path, spec_path + + +def _read_required(repo: Path, relative: str, reason: str) -> None: + try: + path = confined(repo, relative) + if not path.is_file(): + raise _refuse(reason) + path.read_bytes() + except ProfileError as error: + if error.code == PROFILE_REPOSITORY_INVALID: + raise _refuse("path.invalid") from error + raise + except (OSError, RuntimeError, ValueError) as error: + raise _refuse(reason) from error + + +def _duplicate_reason(repo: Path, spec_path: str, story_key: str) -> str | None: + parent = confined(repo, str(Path(spec_path).parent).replace("\\", "/")) + try: + if not parent.is_dir(): + return "spec_dir.absent" + entries = list(parent.iterdir()) + if len(entries) > 10000: + return "spec.unreadable" + target = confined(repo, spec_path) + for entry in entries: + if ( + entry == target + or entry.suffix != ".md" + or entry.is_symlink() + or not entry.is_file() + ): + continue + try: + data = entry.read_bytes() + except (OSError, RuntimeError, ValueError): + return "spec.unreadable" + metadata = front_matter(data) + if metadata is not None and metadata.get("story_key") == story_key: + return "spec.duplicate" + except (OSError, RuntimeError, ValueError) as error: + raise _refuse("spec.unreadable") from error + return None + + +def _state( + repo_path: str, + story_key: object, + story_path: object, + guide_path: object, + spec_path: object, +) -> dict[str, Any]: + story, source, guide, spec = _validate_inputs( + story_key, story_path, guide_path, spec_path + ) + repo = real_repo_root(repo_path) + _read_required(repo, source, "story.absent") + _read_required(repo, guide, "guide.absent") + try: + spec_file = confined(repo, spec) + spec_dir = spec_file.parent + if not spec_dir.is_dir(): + raise _refuse("spec_dir.absent") + except ProfileError as error: + if error.code == PROFILE_REPOSITORY_INVALID: + raise _refuse("path.invalid") from error + raise + except OSError as error: + raise _refuse("spec.unreadable") from error + if Path(os.path.realpath(os.getcwd())) != repo: + raise _refuse("cwd.mismatch") + dirty = changed_paths(repo) + if any(path != spec for path in dirty): + raise _refuse("worktree.dirty") + + try: + if not spec_file.exists(): + data: bytes | None = None + elif not spec_file.is_file(): + raise _refuse("spec.unreadable") + else: + data = spec_file.read_bytes() + except OSError as error: + raise _refuse("spec.unreadable") from error + if data is not None: + metadata = front_matter(data) + if metadata is not None and metadata.get("story_key") not in (None, story): + raise _refuse("spec.foreign") + duplicate = _duplicate_reason(repo, spec, story) + if duplicate is not None: + raise _refuse(duplicate) + head = resolve_revision(repo, "HEAD") + complete = data is not None and spec_complete(data, story) + return { + "story_key": story, + "spec_path": spec, + "head": head, + "state": "complete" + if complete + else ("incomplete" if data is not None else "absent"), + "spec_sha256": hashlib.sha256(data).hexdigest() if data is not None else None, + "author": not complete, + } + + +def _refs( + spec_path: str | None, + spec_sha256: str | None, + revision: str | None, + out_of_scope: int = 0, +) -> dict[str, Any]: + return { + "spec_path": spec_path, + "spec_sha256": spec_sha256, + "revision": revision, + "out_of_scope": out_of_scope, + } + + +def _result( + story_key: str | None, + outcome: str, + reason: str, + *, + spec_path: str | None, + spec_sha256: str | None, + revision: str | None, + out_of_scope: int = 0, +) -> dict[str, Any]: + return { + "stage": "plan", + "story_key": story_key, + "outcome": outcome, + "reason": reason, + "refs": _refs(spec_path, spec_sha256, revision, out_of_scope), + } + + +@beddel_tool( + name="profile_plan_reconcile", + description="Reconcile one selected story with exactly one implementation spec", + category="profile", +) +def profile_plan_reconcile( + repo_path: str, + story_key: str, + story_path: str, + guide_path: str, + spec_path: str, +) -> dict[str, Any]: + """Validate plan inputs and report whether the Coding agent must author.""" + return _state(repo_path, story_key, story_path, guide_path, spec_path) + + +def _mapping_matches( + reconcile: Mapping[str, Any], + story_key: str, + spec_path: str, +) -> bool: + return ( + reconcile.get("story_key") == story_key + and reconcile.get("spec_path") == spec_path + and isinstance(reconcile.get("head"), str) + and reconcile.get("state") in {"absent", "incomplete", "complete"} + and ( + isinstance(reconcile.get("spec_sha256"), str) + or reconcile.get("spec_sha256") is None + ) + and reconcile.get("author") is (reconcile.get("state") != "complete") + ) + + +def _settle_current( + repo: Path, story_key: str, spec_path: str +) -> tuple[str, bytes | None, int]: + current = changed_paths(repo) + extras = current - {spec_path} + if extras: + return "scope.exceeded", None, len(extras) + try: + spec_file = confined(repo, spec_path) + if not spec_file.is_file(): + return "spec.incomplete", None, 0 + data = spec_file.read_bytes() + except (OSError, ProfileError, RuntimeError, ValueError): + return "spec.incomplete", None, 0 + try: + duplicate = _duplicate_reason(repo, spec_path, story_key) + except ProfileError as error: + # After the agent ran, an unreadable scan is a failure, not a refusal. + duplicate = str(error.details.get("reason", "spec.unreadable")) + if duplicate is not None: + return duplicate, data, 0 + if not spec_complete(data, story_key): + return "spec.incomplete", data, 0 + return "ok", data, 0 + + +@beddel_tool( + name="profile_plan_settle", + description="Settle a plan stage without writing or committing the spec", + category="profile", +) +def profile_plan_settle( + repo_path: str, + story_key: str, + story_path: str, + guide_path: str, + spec_path: str, + reconcile: Mapping[str, Any] | None, +) -> dict[str, Any]: + """Derive a success, refusal, or failure outcome from the settled work tree.""" + valid_story = story_key if _valid_story_key(story_key) else None + valid_spec = ( + spec_path + if isinstance(spec_path, str) + and len(spec_path) <= 512 + and relative_path(spec_path) + else None + ) + try: + story, _source, _guide, spec = _validate_inputs( + story_key, story_path, guide_path, spec_path + ) + repo = real_repo_root(repo_path) + current_head = resolve_revision(repo, "HEAD") + if reconcile is None: + try: + state = _state(repo_path, story, story_path, guide_path, spec) + except ProfileError as error: + reason = str(error.details.get("reason", "reconcile.failed")) + return _result( + valid_story, + "refused", + reason, + spec_path=valid_spec, + spec_sha256=None, + revision=current_head, + ) + return _result( + story, + "failed", + "reconcile.failed", + spec_path=spec, + spec_sha256=state["spec_sha256"], + revision=state["head"], + ) + if not isinstance(reconcile, Mapping) or not _mapping_matches( + reconcile, story, spec + ): + return _result( + valid_story, + "failed", + "reconcile.mismatch", + spec_path=valid_spec, + spec_sha256=None, + revision=current_head, + ) + if current_head != reconcile.get("head"): + return _result( + story, + "failed", + "head.moved", + spec_path=spec, + spec_sha256=None, + revision=current_head, + ) + initial_sha = reconcile.get("spec_sha256") + settle_state, data, out_of_scope = _settle_current(repo, story, spec) + if settle_state == "scope.exceeded": + return _result( + story, + "failed", + settle_state, + spec_path=spec, + spec_sha256=None, + revision=current_head, + out_of_scope=out_of_scope, + ) + if settle_state != "ok": + return _result( + story, + "failed", + settle_state, + spec_path=spec, + spec_sha256=hashlib.sha256(data).hexdigest() + if data is not None + else None, + revision=current_head, + ) + assert data is not None + digest = hashlib.sha256(data).hexdigest() + if reconcile.get("state") == "complete" and digest != initial_sha: + return _result( + story, + "failed", + "spec.changed", + spec_path=spec, + spec_sha256=digest, + revision=current_head, + ) + return _result( + story, + "succeeded", + { + "absent": "spec.created", + "incomplete": "spec.reconciled", + "complete": "spec.reused", + }[str(reconcile["state"])], + spec_path=spec, + spec_sha256=digest, + revision=current_head, + ) + except ProfileError as error: + reason = str(error.details.get("reason", "reconcile.failed")) + return _result( + valid_story, + "refused" if error.code == PROFILE_PLAN_REFUSED else "failed", + reason, + spec_path=valid_spec, + spec_sha256=None, + revision=None, + ) diff --git a/kits/profile-dev-kit/python/beddel_profile_dev/tools/stage_outcome.py b/kits/profile-dev-kit/python/beddel_profile_dev/tools/stage_outcome.py new file mode 100644 index 0000000..a83bec3 --- /dev/null +++ b/kits/profile-dev-kit/python/beddel_profile_dev/tools/stage_outcome.py @@ -0,0 +1,160 @@ +"""Append-only Stage outcome records for profile Delivery stages.""" + +from __future__ import annotations + +import re +from datetime import UTC, datetime +from pathlib import Path +from typing import Any + +from beddel.tools import beddel_tool + +from beddel_profile_dev._errors import ( + PROFILE_REPOSITORY_INVALID, + PROFILE_STAGE_OUTCOME_REFUSED, + ProfileError, +) +from beddel_profile_dev._io import ( + canonical_json, + confined, + real_repo_root, + records_root, + write_create_only, +) +from beddel_profile_dev.config import load_config +from beddel_profile_dev.plan import STORY_KEY +from beddel_profile_dev.tools.ratify import TIMESTAMP_FORMAT + +__all__ = ["OUTCOMES", "STAGE_OUTCOME_SCHEMA", "profile_record_stage_outcome"] + +STAGE_OUTCOME_SCHEMA = "profile-dev/stage-outcome/1" +OUTCOMES = ("succeeded", "refused", "failed", "stopped") +_STAGE = re.compile(r"[a-z][a-z0-9-]{0,31}") +_REASON = re.compile(r"[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*") +_TOKEN = re.compile(r"(?:gh[pousr]_\w{10,}|github_pat_\w{10,})") +_REF_KEY = re.compile(r"[a-z][a-z0-9_]{0,31}") + + +def _refuse(reason: str) -> ProfileError: + return ProfileError( + PROFILE_STAGE_OUTCOME_REFUSED, + "stage outcome refused", + {"reason": reason}, + ) + + +def _has_control(value: str) -> bool: + return any(ord(char) < 32 or ord(char) == 127 for char in value) + + +def _valid_refs(refs: object) -> bool: + if not isinstance(refs, dict) or len(refs) > 16: + return False + for key, value in refs.items(): + if not isinstance(key, str) or _REF_KEY.fullmatch(key) is None: + return False + if value is None or isinstance(value, bool): + continue + if isinstance(value, int): + if not 0 <= value <= 10**9: + return False + continue + if ( + not isinstance(value, str) + or len(value) > 512 + or _has_control(value) + or _TOKEN.search(value) is not None + ): + return False + return True + + +def _next_ordinal(records: Path) -> int: + directory = confined(records, "stage-outcomes") + if not directory.exists(): + return 1 + if not directory.is_dir(): + raise ProfileError(PROFILE_REPOSITORY_INVALID, "repository or revision invalid") + values = [ + int(match.group(1)) + for entry in directory.iterdir() + if (match := re.fullmatch(r"([1-9][0-9]*)\.json", entry.name)) is not None + ] + return max(values, default=0) + 1 + + +def _validate_fields( + story_key: object, + stage: object, + outcome: object, + reason: object, + refs: object, +) -> None: + if not isinstance(stage, str) or _STAGE.fullmatch(stage) is None: + raise _refuse("stage.invalid") + if outcome not in OUTCOMES: + raise _refuse("outcome.invalid") + if ( + not isinstance(reason, str) + or len(reason) > 64 + or _REASON.fullmatch(reason) is None + ): + raise _refuse("reason.invalid") + if story_key is not None and ( + not isinstance(story_key, str) or STORY_KEY.fullmatch(story_key) is None + ): + raise _refuse("story_key.invalid") + if story_key is None and outcome != "refused": + raise _refuse("story_key.required") + if not _valid_refs(refs): + raise _refuse("refs.invalid") + + +@beddel_tool( + name="profile_record_stage_outcome", + description="Append one create-only Stage outcome record outside the repository", + category="profile", +) +def profile_record_stage_outcome( + repo_path: str, + story_key: str | None, + stage: str, + outcome: str, + reason: str, + refs: dict[str, Any], +) -> dict[str, Any]: + """Validate and append one Stage outcome record.""" + _validate_fields(story_key, stage, outcome, reason, refs) + repo = real_repo_root(repo_path) + records = records_root(repo, load_config().records_dir) + ordinal = _next_ordinal(records) + record = { + "schema": STAGE_OUTCOME_SCHEMA, + "record": ordinal, + "stage": stage, + "story_key": story_key, + "outcome": outcome, + "reason": reason, + "refs": refs, + "recorded_at": datetime.now(UTC).strftime(TIMESTAMP_FORMAT), + } + for _ in range(100): + try: + created = write_create_only( + records, f"stage-outcomes/{ordinal}.json", canonical_json(record) + ) + except FileExistsError: + created = False + if created: + return { + "ok": True, + "record": ordinal, + "path": f"stage-outcomes/{ordinal}.json", + "stage": stage, + "story_key": story_key, + "outcome": outcome, + "reason": reason, + } + ordinal += 1 + record["record"] = ordinal + raise ProfileError(PROFILE_REPOSITORY_INVALID, "repository or revision invalid") diff --git a/kits/profile-dev-kit/tests/test_manifest.py b/kits/profile-dev-kit/tests/test_manifest.py index f4ccaea..79aa452 100644 --- a/kits/profile-dev-kit/tests/test_manifest.py +++ b/kits/profile-dev-kit/tests/test_manifest.py @@ -30,6 +30,9 @@ "profile_approve_change", "profile_record_approval_decision", "profile_read_approval", + "profile_plan_reconcile", + "profile_plan_settle", + "profile_record_stage_outcome", ] @@ -103,9 +106,11 @@ def test_manifest_declares_all_workflows_and_python_targets() -> None: "approve-change", "record-approval-decision", "read-approval", + "plan-story", ] declared = {t["name"] for t in manifest["tools"]} targeted = {t["name"] for t in manifest["targets"]["python"]["tools"]} + assert manifest["targets"]["python"]["dependencies"] == [] assert declared == targeted == set(_TOOLS) diff --git a/kits/profile-dev-kit/tests/test_plan.py b/kits/profile-dev-kit/tests/test_plan.py new file mode 100644 index 0000000..04709dc --- /dev/null +++ b/kits/profile-dev-kit/tests/test_plan.py @@ -0,0 +1,324 @@ +"""Plan contract, reconciliation and settlement coverage.""" + +from __future__ import annotations + +import hashlib +import os +from pathlib import Path + +import pytest +from beddel_profile_dev._errors import PROFILE_PLAN_REFUSED, ProfileError +from beddel_profile_dev._io import changed_paths +from beddel_profile_dev.plan import front_matter, relative_path, spec_complete +from beddel_profile_dev.tools import plan as plan_tools +from beddel_profile_dev.tools.plan import profile_plan_reconcile, profile_plan_settle + +from ._helpers import commit_all, git, init_repo + +STORY = "7-3-plan-workflow-turns-one-story-into-one-spec" +STORY_PATH = "stories/story.md" +GUIDE_PATH = "guides/guide.md" +SPEC_PATH = "specs/7-3.md" + + +def complete_spec(story_key: str = STORY) -> bytes: + return ( + f"---\nstory_key: {story_key}\nrequirements: [FR-13]\n" + "repositories: [kits/profile-dev-kit]\ndependencies: []\n" + "size_cap_bytes: 64000\n---\n\n# Implementation\n" + ).encode() + + +def prepared_repo(tmp_path: Path) -> Path: + repo = init_repo(tmp_path / "repo") + (repo / "stories").mkdir() + (repo / STORY_PATH).write_text("selected story") + (repo / "guides").mkdir() + (repo / GUIDE_PATH).write_text("guide") + commit_all(repo) + return repo + + +def call_reconcile(repo: Path, **kwargs: str) -> dict[str, object]: + values = { + "repo_path": str(repo), + "story_key": STORY, + "story_path": STORY_PATH, + "guide_path": GUIDE_PATH, + "spec_path": SPEC_PATH, + } + values.update(kwargs) + return profile_plan_reconcile(**values) + + +def test_long_spec_path_is_refused_without_echoing_it( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + long_path = "specs/" + "a" * 600 + ".md" + with pytest.raises(ProfileError) as exc_info: + call_reconcile(repo, spec_path=long_path) + assert exc_info.value.details["reason"] == "path.invalid" + settled = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, long_path, None + ) + assert settled["reason"] == "path.invalid" + assert settled["refs"]["spec_path"] is None + + +def test_recursion_in_spec_is_incomplete_and_settles_as_failure( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + reconcile = call_reconcile(repo) + malformed = b"---\nx: " + b"[" * 3000 + b"\n---\nbody\n" + (repo / SPEC_PATH).write_bytes(malformed) + assert call_reconcile(repo)["state"] == "incomplete" + settled = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, reconcile + ) + assert settled["outcome"] == "failed" + assert settled["reason"] == "spec.incomplete" + + +def test_escaping_story_symlink_is_path_invalid( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + os.symlink("/etc/hostname", repo / "story-link") + monkeypatch.chdir(repo) + with pytest.raises(ProfileError) as exc_info: + call_reconcile(repo, story_path="story-link") + assert exc_info.value.details["reason"] == "path.invalid" + + +def test_duplicate_scan_unreadable_is_a_settle_failure( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + reconcile = call_reconcile(repo) + (repo / SPEC_PATH).write_bytes(complete_spec()) + monkeypatch.setattr( + plan_tools, "_duplicate_reason", lambda *args: "spec.unreadable" + ) + settled = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, reconcile + ) + assert settled["outcome"] == "failed" + assert settled["reason"] == "spec.unreadable" + + +def test_duplicate_scan_refusal_after_the_agent_ran_is_a_failure( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + reconcile = call_reconcile(repo) + (repo / SPEC_PATH).write_bytes(complete_spec()) + + def unreadable(*args: object) -> str: + raise ProfileError( + PROFILE_PLAN_REFUSED, "plan refused", {"reason": "spec.unreadable"} + ) + + monkeypatch.setattr(plan_tools, "_duplicate_reason", unreadable) + settled = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, reconcile + ) + assert settled["outcome"] == "failed" + assert settled["reason"] == "spec.unreadable" + + +def test_spec_replaced_by_an_escaping_symlink_is_spec_incomplete( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + reconcile = call_reconcile(repo) + os.symlink("/etc/hostname", repo / SPEC_PATH) + settled = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, reconcile + ) + assert settled["outcome"] == "failed" + assert settled["reason"] == "spec.incomplete" + + +def test_changed_paths_reports_both_rename_paths(tmp_path: Path) -> None: + repo = init_repo(tmp_path / "rename") + (repo / "a.txt").write_text("a") + commit_all(repo) + git(repo, "mv", "a.txt", "b.txt") + assert changed_paths(repo) == {"a.txt", "b.txt"} + + +def test_pure_contract() -> None: + data = complete_spec() + assert front_matter(data)["story_key"] == STORY + assert spec_complete(data, STORY) + assert not spec_complete( + data.replace(b"size_cap_bytes: 64000", b"size_cap_bytes: 0"), STORY + ) + assert relative_path(".", allow_dot=True) + assert not relative_path(".") + assert not relative_path("../outside") + assert not relative_path("a\\b") + + +@pytest.mark.parametrize( + ("field", "value", "reason"), + [ + ("story_key", "BAD KEY", "story_key.invalid"), + ("story_path", "../story.md", "path.invalid"), + ("guide_path", "../guide.md", "path.invalid"), + ("spec_path", "../spec.md", "path.invalid"), + ], +) +def test_invalid_inputs_refuse( + tmp_path: Path, field: str, value: str, reason: str +) -> None: + repo = prepared_repo(tmp_path) + with pytest.raises(ProfileError) as exc_info: + call_reconcile(repo, **{field: value}) + assert exc_info.value.code == PROFILE_PLAN_REFUSED + assert exc_info.value.details["reason"] == reason + + +@pytest.mark.parametrize( + ("kind", "reason"), + [ + ("story_absent", "story.absent"), + ("guide_absent", "guide.absent"), + ("spec_dir_absent", "spec_dir.absent"), + ("cwd_mismatch", "cwd.mismatch"), + ("worktree_dirty", "worktree.dirty"), + ("spec_unreadable", "spec.unreadable"), + ("spec_foreign", "spec.foreign"), + ("spec_duplicate", "spec.duplicate"), + ], +) +def test_refusal_matrix( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch, kind: str, reason: str +) -> None: + root = prepared_repo(tmp_path) + monkeypatch.chdir(root) + if kind == "story_absent": + (root / STORY_PATH).unlink() + elif kind == "guide_absent": + (root / GUIDE_PATH).unlink() + elif kind == "spec_dir_absent": + pass + elif kind == "cwd_mismatch": + (root / "specs").mkdir() + monkeypatch.chdir(tmp_path) + elif kind == "worktree_dirty": + (root / "specs").mkdir() + (root / "other.txt").write_text("outside spec") + elif kind == "spec_unreadable": + (root / "specs").mkdir() + (root / SPEC_PATH).mkdir() + elif kind == "spec_foreign": + (root / "specs").mkdir() + (root / SPEC_PATH).write_bytes(complete_spec("other-story")) + elif kind == "spec_duplicate": + (root / "specs").mkdir() + (root / SPEC_PATH).write_bytes(complete_spec()) + (root / "specs" / "other.md").write_bytes(complete_spec()) + commit_all(root) + with pytest.raises(ProfileError) as exc_info: + call_reconcile(root) + assert exc_info.value.code == PROFILE_PLAN_REFUSED + assert exc_info.value.details["reason"] == reason + + +def test_create_reconcile_reuse_and_settle_outcomes( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + + absent = call_reconcile(repo) + assert absent["state"] == "absent" + assert absent["author"] is True + (repo / SPEC_PATH).write_bytes(complete_spec()) + created = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, absent + ) + assert created["outcome"] == "succeeded" + assert created["reason"] == "spec.created" + assert created["refs"]["spec_sha256"] == hashlib.sha256(complete_spec()).hexdigest() + + incomplete_bytes = b"---\nstory_key: " + STORY.encode() + b"\n---\nunfinished\n" + (repo / SPEC_PATH).write_bytes(incomplete_bytes) + incomplete = call_reconcile(repo) + assert incomplete["state"] == "incomplete" + (repo / SPEC_PATH).write_bytes(complete_spec()) + reconciled = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, incomplete + ) + assert reconciled["reason"] == "spec.reconciled" + + reused_before = (repo / SPEC_PATH).read_bytes() + reused = call_reconcile(repo) + reused_result = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, reused + ) + assert reused_result["reason"] == "spec.reused" + assert (repo / SPEC_PATH).read_bytes() == reused_before + + +def test_settle_scope_commit_changed_and_agent_failure_states( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + (repo / "specs").mkdir() + monkeypatch.chdir(repo) + absent = call_reconcile(repo) + (repo / SPEC_PATH).write_bytes(complete_spec()) + (repo / "extra.txt").write_text("scope") + scope = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, absent + ) + assert scope["reason"] == "scope.exceeded" + assert scope["refs"]["out_of_scope"] == 1 + + (repo / "extra.txt").unlink() + commit_all(repo, "agent commit") + moved = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, absent + ) + assert moved["reason"] == "head.moved" + + repo2 = prepared_repo(tmp_path / "second") + (repo2 / "specs").mkdir() + (repo2 / SPEC_PATH).write_bytes(complete_spec()) + monkeypatch.chdir(repo2) + complete = call_reconcile(repo2) + (repo2 / SPEC_PATH).write_bytes( + complete_spec().replace(b"# Implementation", b"# Changed") + ) + changed = profile_plan_settle( + str(repo2), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, complete + ) + assert changed["reason"] == "spec.changed" + + +def test_settle_without_reconcile_refuses_and_records_reason( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = prepared_repo(tmp_path) + monkeypatch.chdir(repo) + result = profile_plan_settle( + str(repo), STORY, STORY_PATH, GUIDE_PATH, SPEC_PATH, None + ) + assert result["outcome"] == "refused" + assert result["reason"] == "spec_dir.absent" diff --git a/kits/profile-dev-kit/tests/test_plan_workflow.py b/kits/profile-dev-kit/tests/test_plan_workflow.py new file mode 100644 index 0000000..4f44551 --- /dev/null +++ b/kits/profile-dev-kit/tests/test_plan_workflow.py @@ -0,0 +1,288 @@ +"""In-process plan workflow coverage with a fake Coding agent.""" + +from __future__ import annotations + +import asyncio +import json +import subprocess +from pathlib import Path +from typing import Any + +import pytest +import yaml +from beddel.domain.errors import AgentError +from beddel.domain.executor import WorkflowExecutor +from beddel.domain.kit import parse_kit_manifest +from beddel.domain.models import AgentResult, DefaultDependencies +from beddel.domain.parser import WorkflowParser +from beddel.domain.registry import PrimitiveRegistry +from beddel.error_codes import AGENT_EXECUTION_FAILED +from beddel.primitives import register_builtins +from beddel.tools.kits import load_kit +from beddel_profile_dev._io import records_root +from beddel_profile_dev.tools.plan import profile_plan_settle +from beddel_profile_dev.tools.stage_outcome import profile_record_stage_outcome + +from ._helpers import commit_all, init_repo + +KIT_ROOT = Path(__file__).resolve().parents[1] +WORKFLOW_PATH = KIT_ROOT / "workflows" / "plan-story.yaml" +STORY = "7-3-plan-workflow-turns-one-story-into-one-spec" + + +def complete_spec() -> bytes: + return ( + f"---\nstory_key: {STORY}\nrequirements: [FR-13]\n" + "repositories: [kits/profile-dev-kit]\ndependencies: []\n" + "size_cap_bytes: 64000\n---\n\n# Plan\n" + ).encode() + + +class FakeAgent: + def __init__(self, repo: Path, mode: str) -> None: + self.repo = repo + self.mode = mode + self.calls = 0 + + async def execute( + self, + prompt: str, + *, + model: str | None = None, + sandbox: str = "read-only", + tools: list[str] | None = None, + output_schema: dict[str, Any] | None = None, + ) -> AgentResult: + self.calls += 1 + spec = self.repo / "specs" / "story.md" + spec.parent.mkdir(exist_ok=True) + if self.mode == "error": + raise AgentError(code=AGENT_EXECUTION_FAILED, message="fake agent failed") + if self.mode == "incomplete": + spec.write_text("unfinished") + else: + spec.write_bytes(complete_spec()) + if self.mode == "extra": + (self.repo / "extra.txt").write_text("out of scope") + if self.mode == "commit": + await asyncio.to_thread( + subprocess.run, + ["git", "-C", str(self.repo), "add", "-A"], + check=True, + ) + await asyncio.to_thread( + subprocess.run, + [ + "git", + "-C", + str(self.repo), + "-c", + "user.name=Fixture", + "-c", + "user.email=fixture@example.invalid", + "commit", + "-qm", + "agent", + ], + check=True, + ) + return AgentResult( + exit_code=0, + output="", + events=[], + files_changed=[], + usage={}, + agent_id="fake", + ) + + +def _repo(tmp_path: Path) -> Path: + repo = init_repo(tmp_path / "repo") + (repo / "story.md").write_text("story") + (repo / "guide.md").write_text("guide") + (repo / "specs").mkdir() + commit_all(repo) + return repo + + +def _run( + repo: Path, + fake: FakeAgent, + monkeypatch: pytest.MonkeyPatch, + story_key: str = STORY, +) -> dict[str, Any]: + workflow = WorkflowParser.parse(WORKFLOW_PATH.read_text()) + registry = PrimitiveRegistry() + register_builtins(registry) + tools = load_kit(parse_kit_manifest(KIT_ROOT / "kit.yaml")) + executor = WorkflowExecutor( + registry, + deps=DefaultDependencies( + agent_registry={"kiro-cli": fake}, tool_registry=tools + ), + ) + import asyncio + + return asyncio.run( + executor.execute( + workflow, + { + "repo_path": str(repo), + "story_key": story_key, + "story_path": "story.md", + "guide_path": "guide.md", + "spec_path": "specs/story.md", + }, + ) + ) + + +def test_workflow_shape() -> None: + document = yaml.safe_load(WORKFLOW_PATH.read_text()) + assert document["id"] == "plan-story" + assert document["requires_kits"] == ["profile-dev-kit", "agent-kiro-kit"] + assert document["inputs"] == [ + "repo_path", + "story_key", + "story_path", + "guide_path", + "spec_path", + ] + assert document["allowed_tools"] == [ + "profile_plan_reconcile", + "profile_plan_settle", + "profile_record_stage_outcome", + ] + assert "Coding agent" in document["description"] + assert {step["id"] for step in document["steps"]} == { + "reconcile", + "author", + "settle", + "record", + } + author = next(step for step in document["steps"] if step["id"] == "author") + assert author["execution_strategy"]["type"] == "skip" + assert author["config"]["adapter"] == "kiro-cli" + assert author["config"]["sandbox"] == "workspace-write" + assert author["timeout"] <= 600 + assert "verify" not in document["allowed_tools"] + workflow = WorkflowParser.parse(WORKFLOW_PATH.read_text()) + steps = {step.id: step for step in workflow.steps} + assert steps["reconcile"].execution_strategy.type.value == "skip" + assert steps["author"].if_condition == "$stepResult.reconcile.result.author == true" + assert steps["settle"].execution_strategy.type.value == "fail" + assert steps["record"].execution_strategy.type.value == "fail" + + +@pytest.mark.parametrize( + ("mode", "expected", "reason", "calls"), + [ + ("complete", "succeeded", "spec.created", 1), + ("incomplete", "failed", "spec.incomplete", 1), + ("extra", "failed", "scope.exceeded", 1), + ("commit", "failed", "head.moved", 1), + ("error", "failed", "spec.incomplete", 1), + ], +) +def test_workflow_settles_agent_modes( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + mode: str, + expected: str, + reason: str, + calls: int, +) -> None: + repo = _repo(tmp_path) + monkeypatch.chdir(repo) + monkeypatch.setenv("HOME", str(tmp_path / "home")) + fake = FakeAgent(repo, mode) + result = _run(repo, fake, monkeypatch) + assert result["step_results"]["settle"]["result"]["outcome"] == expected + assert result["step_results"]["settle"]["result"]["reason"] == reason + assert fake.calls == calls + records = records_root(repo, "records/profile-dev") / "stage-outcomes" + stored = json.loads((records / "1.json").read_text()) + assert stored["reason"] == reason + + +def test_reuse_and_refusal_skip_agent_and_still_record( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = _repo(tmp_path) + (repo / "specs" / "story.md").write_bytes(complete_spec()) + monkeypatch.chdir(repo) + monkeypatch.setenv("HOME", str(tmp_path / "home")) + fake = FakeAgent(repo, "error") + records = records_root(repo, "records/profile-dev") / "stage-outcomes" + result = _run(repo, fake, monkeypatch) + assert result["step_results"]["settle"]["result"]["reason"] == "spec.reused" + first_record = json.loads((records / "1.json").read_text()) + assert first_record["story_key"] == STORY + result_again = _run(repo, fake, monkeypatch) + assert result_again["step_results"]["settle"]["result"]["reason"] == "spec.reused" + assert fake.calls == 0 + second_record = json.loads((records / "2.json").read_text()) + assert second_record["record"] == 2 + assert second_record["reason"] == "spec.reused" + + repo2 = _repo(tmp_path / "refusal") + (repo2 / "specs").rmdir() + monkeypatch.chdir(repo2) + fake2 = FakeAgent(repo2, "error") + result2 = _run(repo2, fake2, monkeypatch, story_key="BAD KEY") + assert result2["step_results"]["settle"]["result"]["reason"] == "story_key.invalid" + assert result2["step_results"]["settle"]["result"]["outcome"] == "refused" + assert fake2.calls == 0 + refusal_record = json.loads( + ( + records_root(repo2, "records/profile-dev") / "stage-outcomes/1.json" + ).read_text() + ) + assert refusal_record["story_key"] is None + + +def test_mismatch_and_invalid_path_records_are_written( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = _repo(tmp_path / "mismatch") + monkeypatch.chdir(repo) + monkeypatch.setenv("HOME", str(tmp_path / "home")) + mismatch = profile_plan_settle( + str(repo), STORY, "story.md", "guide.md", "specs/story.md", {"wrong": True} + ) + assert mismatch["reason"] == "reconcile.mismatch" + profile_record_stage_outcome( + str(repo), + mismatch["story_key"], + mismatch["stage"], + mismatch["outcome"], + mismatch["reason"], + mismatch["refs"], + ) + mismatch_record = json.loads( + ( + records_root(repo, "records/profile-dev") / "stage-outcomes/1.json" + ).read_text() + ) + assert mismatch_record["reason"] == "reconcile.mismatch" + + repo2 = _repo(tmp_path / "invalid-path") + monkeypatch.chdir(repo2) + invalid = profile_plan_settle( + str(repo2), STORY, "story.md", "guide.md", "specs/a\nb.md", None + ) + assert invalid["reason"] == "path.invalid" + profile_record_stage_outcome( + str(repo2), + invalid["story_key"], + invalid["stage"], + invalid["outcome"], + invalid["reason"], + invalid["refs"], + ) + invalid_record = json.loads( + ( + records_root(repo2, "records/profile-dev") / "stage-outcomes/1.json" + ).read_text() + ) + assert invalid_record["refs"]["spec_path"] is None diff --git a/kits/profile-dev-kit/tests/test_stage_outcome.py b/kits/profile-dev-kit/tests/test_stage_outcome.py new file mode 100644 index 0000000..235b258 --- /dev/null +++ b/kits/profile-dev-kit/tests/test_stage_outcome.py @@ -0,0 +1,194 @@ +"""Append-only Stage outcome record validation and persistence.""" + +from __future__ import annotations + +import json +from pathlib import Path + +import pytest +from beddel_profile_dev._errors import ( + PROFILE_REPOSITORY_INVALID, + PROFILE_STAGE_OUTCOME_REFUSED, + ProfileError, +) +from beddel_profile_dev._io import records_root +from beddel_profile_dev.tools import stage_outcome +from beddel_profile_dev.tools.stage_outcome import profile_record_stage_outcome + +from ._helpers import commit_all, init_repo + + +def repo_fixture(tmp_path: Path) -> Path: + repo = init_repo(tmp_path / "repo") + (repo / "story.md").write_text("story") + commit_all(repo) + return repo + + +def record_root(tmp_path: Path, repo: Path, monkeypatch: pytest.MonkeyPatch) -> Path: + monkeypatch.setenv("HOME", str(tmp_path / "home")) + return records_root(repo, "records/profile-dev") + + +def test_ordinals_are_append_only_and_outside_repo( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = repo_fixture(tmp_path) + root = record_root(tmp_path, repo, monkeypatch) + first = profile_record_stage_outcome( + str(repo), "story-1", "plan", "succeeded", "spec.created", {"out_of_scope": 0} + ) + second = profile_record_stage_outcome( + str(repo), "story-1", "plan", "succeeded", "spec.reused", {"out_of_scope": 0} + ) + first_path = root / str(first["path"]) + assert first_path.exists() + assert second["record"] == 2 + assert root / "stage-outcomes" == root / Path(str(first["path"])).parent + assert (root / "stage-outcomes").is_relative_to(tmp_path / "home") + assert not (repo / "stage-outcomes").exists() + assert not list(repo.glob("stage-outcomes/*")) + stored = json.loads((root / "stage-outcomes/2.json").read_text()) + assert stored["schema"] == "profile-dev/stage-outcome/1" + assert stored["recorded_at"].endswith("Z") + + +def test_preexisting_and_racing_files_stay_byte_identical( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = repo_fixture(tmp_path) + root = record_root(tmp_path, repo, monkeypatch) + directory = root / "stage-outcomes" + directory.mkdir(parents=True) + existing = b"existing\n" + (directory / "1.json").write_bytes(existing) + result = profile_record_stage_outcome( + str(repo), "story-1", "plan", "succeeded", "spec.created", {} + ) + assert result["record"] == 2 + assert (directory / "1.json").read_bytes() == existing + + original = stage_outcome.write_create_only + calls = 0 + + def racing(root_path: Path, relative: str, data: bytes) -> bool: + nonlocal calls + calls += 1 + if calls == 1: + path = root_path / relative + path.parent.mkdir(parents=True, exist_ok=True) + path.write_bytes(b"racer\n") + return original(root_path, relative, data) + + monkeypatch.setattr(stage_outcome, "write_create_only", racing) + third = profile_record_stage_outcome( + str(repo), "story-1", "plan", "succeeded", "spec.created", {} + ) + assert third["record"] == 4 + assert (directory / "3.json").read_bytes() == b"racer\n" + + +@pytest.mark.parametrize( + ("kwargs", "reason"), + [ + ({"stage": "Bad Stage"}, "stage.invalid"), + ({"outcome": "unknown"}, "outcome.invalid"), + ({"reason": "Bad reason"}, "reason.invalid"), + ({"story_key": "BAD"}, "story_key.invalid"), + ({"story_key": None, "outcome": "failed"}, "story_key.required"), + ({"refs": {"Bad": 1}}, "refs.invalid"), + ({"refs": {"count": -1}}, "refs.invalid"), + ({"refs": {f"key-{index}": index for index in range(17)}}, "refs.invalid"), + ({"refs": {"value": "x" * 513}}, "refs.invalid"), + ], +) +def test_bad_fields_write_nothing( + tmp_path: Path, + monkeypatch: pytest.MonkeyPatch, + kwargs: dict[str, object], + reason: str, +) -> None: + repo = repo_fixture(tmp_path) + root = record_root(tmp_path, repo, monkeypatch) + values: dict[str, object] = { + "repo_path": str(repo), + "story_key": "story-1", + "stage": "plan", + "outcome": "succeeded", + "reason": "spec.created", + "refs": {}, + } + values.update(kwargs) + with pytest.raises(ProfileError) as exc_info: + profile_record_stage_outcome(**values) + assert exc_info.value.code == PROFILE_STAGE_OUTCOME_REFUSED + assert exc_info.value.details["reason"] == reason + assert not (root / "stage-outcomes").exists() + + +def test_token_and_control_values_are_rejected_without_echoing( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = repo_fixture(tmp_path) + root = record_root(tmp_path, repo, monkeypatch) + token = "gh" + "p_" + "A" * 36 + for value in (token, "safe\nvalue"): + with pytest.raises(ProfileError) as exc_info: + profile_record_stage_outcome( + str(repo), + "story-1", + "plan", + "succeeded", + "spec.created", + {"ref": value}, + ) + assert exc_info.value.code == PROFILE_STAGE_OUTCOME_REFUSED + assert not (root / "stage-outcomes").exists() + + +def test_invalid_repository_does_not_create_a_record( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + root = tmp_path / "home" + monkeypatch.setenv("HOME", str(root)) + with pytest.raises(ProfileError): + profile_record_stage_outcome( + str(tmp_path / "missing"), + "story-1", + "plan", + "succeeded", + "spec.created", + {}, + ) + assert not (root / ".config").exists() + + +def test_exhausted_create_only_attempts_raise_repository_invalid( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +) -> None: + repo = repo_fixture(tmp_path) + record_root(tmp_path, repo, monkeypatch) + calls = 0 + + def always_exists(*args: object, **kwargs: object) -> bool: + nonlocal calls + calls += 1 + raise FileExistsError + + monkeypatch.setattr(stage_outcome, "write_create_only", always_exists) + with pytest.raises(ProfileError) as exc_info: + profile_record_stage_outcome( + str(repo), "story-1", "plan", "succeeded", "spec.created", {} + ) + assert exc_info.value.code == PROFILE_REPOSITORY_INVALID + assert calls == 100 + + +def test_stage_outcomes_term_is_isolated_to_its_tool() -> None: + module_root = Path(__file__).resolve().parents[1] / "python" / "beddel_profile_dev" + matches = { + path.name + for path in module_root.rglob("*.py") + if "stage-outcomes" in path.read_text() + } + assert matches == {"stage_outcome.py"} diff --git a/kits/profile-dev-kit/tests/test_workflow.py b/kits/profile-dev-kit/tests/test_workflow.py index e164fec..58e0942 100644 --- a/kits/profile-dev-kit/tests/test_workflow.py +++ b/kits/profile-dev-kit/tests/test_workflow.py @@ -113,7 +113,7 @@ def test_allowlist_equals_the_tools_the_steps_name() -> None: "profile_capture_evidence", "profile_record_report", ] - assert len(list(WORKFLOWS_DIR.glob("*.yaml"))) == 8 + assert len(list(WORKFLOWS_DIR.glob("*.yaml"))) == 9 def test_review_step_outlives_the_largest_accepted_review_budget() -> None: diff --git a/kits/profile-dev-kit/workflows/plan-story.yaml b/kits/profile-dev-kit/workflows/plan-story.yaml new file mode 100644 index 0000000..5474473 --- /dev/null +++ b/kits/profile-dev-kit/workflows/plan-story.yaml @@ -0,0 +1,73 @@ +id: plan-story +name: Plan Story +description: Entry plan stage that turns one selected story into one implementation spec written by a Coding agent through agent-exec; it never implements, verifies or commits. +version: "1.0" +requires_kits: + - profile-dev-kit + - agent-kiro-kit +allowed_tools: + - profile_plan_reconcile + - profile_plan_settle + - profile_record_stage_outcome +inputs: + - repo_path + - story_key + - story_path + - guide_path + - spec_path +steps: + - id: reconcile + primitive: tool + execution_strategy: + type: skip + config: + tool: profile_plan_reconcile + arguments: + repo_path: "$input.repo_path" + story_key: "$input.story_key" + story_path: "$input.story_path" + guide_path: "$input.guide_path" + spec_path: "$input.spec_path" + - id: author + primitive: agent-exec + if: "$stepResult.reconcile.result.author == true" + execution_strategy: + type: skip + timeout: 600 + config: + adapter: kiro-cli + sandbox: workspace-write + prompt: >- + You are the Coding agent for one plan stage. Read the selected story source at + $input.story_path and the planning guide at $input.guide_path and write exactly one + complete implementation spec to $input.spec_path and ensure its YAML front matter + contains story_key, requirements, repositories, dependencies and size_cap_bytes; + set story_key to $input.story_key and size_cap_bytes to 64000. Keep the spec + within the 64000-byte cap. Change no other file. Do not implement, test, verify, + commit or push. + - id: settle + primitive: tool + execution_strategy: + type: fail + config: + tool: profile_plan_settle + arguments: + repo_path: "$input.repo_path" + story_key: "$input.story_key" + story_path: "$input.story_path" + guide_path: "$input.guide_path" + spec_path: "$input.spec_path" + reconcile: "$stepResult.reconcile.result" + - id: record + primitive: tool + execution_strategy: + type: fail + config: + tool: profile_record_stage_outcome + arguments: + repo_path: "$input.repo_path" + story_key: "$stepResult.settle.result.story_key" + stage: plan + outcome: "$stepResult.settle.result.outcome" + reason: "$stepResult.settle.result.reason" + refs: "$stepResult.settle.result.refs"