ww-agentic-workflows 1.0.0.dev3__py3-none-any.whl

ww/artifacts.py

@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Rendering for durable agent-produced workflow step artifacts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+RuleStatus = Literal[
+    "passed", "failed", "not applicable", "self-declared", "verified pass"
+]
+
+
+@dataclass(frozen=True)
+class RuleOutcome:
+    """One rule or check of a completed step, as its artifact reports it.
+
+    ``detail`` names what decided a rule without a command of its own: the
+    derived check that ran, or the verification item that gave the verdict.
+    """
+
+    id: str
+    status: RuleStatus
+    hook: bool = False
+    detail: str | None = None
+
+
+@dataclass(frozen=True)
+class RulesSummary:
+    """The ``## Rules`` section of a step artifact.
+
+    ``waived`` names the checks the step completed without, each with the
+    operator's reason; ``fix_attempts`` counts the completions ww rejected
+    before.
+    """
+
+    outcomes: tuple[RuleOutcome, ...]
+    fix_attempts: int = 0
+    waived: tuple[tuple[str, str], ...] = ()
+
+
+def render_step_artifact(
+    *,
+    task_id: str,
+    workflow: str,
+    step: str,
+    step_number: int,
+    step_total: int,
+    skill: str,
+    result: str,
+    rules: RulesSummary | None = None,
+) -> str:
+    """Wrap an agent result in the built-in, stable Markdown artifact format."""
+    body = _normalize_result(result).rstrip()
+    return (
+        f"# {task_id} — {step}\n\n"
+        "## Workflow context\n\n"
+        f"- Workflow: {workflow}\n"
+        f"- Step: {step_number} of {step_total}\n"
+        f"- Skill: {skill}\n\n"
+        "## Result\n\n"
+        f"{body}\n" + (_rules_section(rules) if rules is not None else "")
+    )
+
+
+def _rules_section(rules: RulesSummary) -> str:
+    lines = ["", "## Rules", ""]
+    lines.extend(
+        f"- `{outcome.id}`{' (hook)' if outcome.hook else ''}: {outcome.status}"
+        + (f" ({outcome.detail})" if outcome.detail else "")
+        for outcome in rules.outcomes
+    )
+    lines.append("")
+    reasons: dict[str, list[str]] = {}
+    for check_id, reason in rules.waived:
+        reasons.setdefault(reason, []).append(check_id)
+    for reason, waived in reasons.items():
+        names = ", ".join(f"`{check_id}`" for check_id in waived)
+        lines.append(f"Checks waived by the operator ({names}): {reason}")
+    attempts = rules.fix_attempts
+    lines.append(
+        f"Completions rejected before this one: {attempts}."
+        if attempts
+        else "No completion was rejected."
+    )
+    return "\n".join(lines) + "\n"
+
+
+def _normalize_result(result: str) -> str:
+    """Restore line endings when Markdown arrived as one escaped CLI argument."""
+    if "\n" in result or "\r" in result:
+        return result
+    return result.replace("\\r\\n", "\n").replace("\\n", "\n").replace("\\r", "\n")

ww/assessments.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""The outcomes of an ``assess`` step, and when one is waiting to be chosen.
+
+An assessment is completed like any agent step; its answer is then given to
+``next --outcome``. The transition that applies the answer and the pages that
+ask for it both read the choice from here, so they cannot disagree about which
+answers exist or what each one does.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ww.errors import StateError
+from ww.execution_models import ExecutionState
+from ww.plan import PlanItem, WorkflowPlan
+
+# The answers every assessment with declared outcomes accepts. One it does not
+# declare runs nothing and continues after the assessment, so a gate declares
+# only the outcome that has work. The compact form keeps its own rule:
+# positive continues, negative ends the workflow.
+STANDARD_OUTCOMES = ("positive", "negative", "mixed")
+
+
+@dataclass(frozen=True)
+class AssessmentOutcome:
+    """One answer: the step it runs first, or that it ends the workflow."""
+
+    label: str
+    stops: bool = False
+    first_step: str | None = None
+    # A standard answer the assessment does not declare: it skips every
+    # outcome's work and continues after the assessment.
+    declared: bool = True
+
+
+@dataclass(frozen=True)
+class PendingAssessment:
+    """A completed assessment whose outcome ``next`` must be given."""
+
+    index: int
+    question: str
+    outcomes: tuple[AssessmentOutcome, ...]
+    # Declared outcomes, as opposed to the compact form.
+    declared: bool
+
+    @property
+    def labels(self) -> tuple[str, ...]:
+        return tuple(outcome.label for outcome in self.outcomes)
+
+    def outcome(self, label: str) -> AssessmentOutcome | None:
+        return next((item for item in self.outcomes if item.label == label), None)
+
+
+def assessment_outcomes(
+    plan: WorkflowPlan, index: int
+) -> tuple[AssessmentOutcome, ...]:
+    """What each answer to the assessment at ``index`` does."""
+    item = plan.items[index]
+    if not item.assessment_outcomes:
+        following = plan.items[index + 1].name if index + 1 < len(plan.items) else None
+        return (
+            AssessmentOutcome("positive", first_step=following),
+            AssessmentOutcome("negative", stops=True),
+        )
+    region = outcome_region(plan, index)
+    after = max(region, default=index) + 1
+    declared = tuple(
+        AssessmentOutcome(
+            label,
+            stops=label in item.assessment_stops,
+            first_step=next(
+                (
+                    plan.items[position].name
+                    for position in region
+                    if plan.items[position].assessment_outcome == label
+                ),
+                None,
+            ),
+        )
+        for label in item.assessment_outcomes
+    )
+    implied = tuple(
+        AssessmentOutcome(
+            label,
+            first_step=plan.items[after].name if after < len(plan.items) else None,
+            declared=False,
+        )
+        for label in STANDARD_OUTCOMES
+        if label not in item.assessment_outcomes
+    )
+    return (*declared, *implied)
+
+
+def outcome_region(plan: WorkflowPlan, index: int) -> tuple[int, ...]:
+    """The plan positions of every declared outcome's work, in order."""
+    step = plan.items[index].step
+    return tuple(
+        position
+        for position, candidate in enumerate(plan.items)
+        if _assessment_parent(candidate) == step
+    )
+
+
+def pending_assessment(
+    state: ExecutionState, plan: WorkflowPlan
+) -> PendingAssessment | None:
+    """The assessment just completed whose outcome is still to be chosen.
+
+    Its outcome items, or for the compact form the step after it, are still
+    pending at the cursor until an outcome is chosen; the choice is recorded
+    on the assessment's record and the cursor moves into its work.
+    """
+    if not 0 < state.cursor < len(plan.items):
+        return None
+    if state.item_executions[state.cursor].status != "pending":
+        return None
+    item = plan.items[state.cursor]
+    parent = _assessment_parent(item)
+    if parent is not None:
+        group = [
+            index
+            for index, candidate in enumerate(plan.items)
+            if _assessment_parent(candidate) == parent
+        ]
+        if state.cursor != min(group):
+            return None
+        index = next(
+            (
+                index
+                for index, candidate in enumerate(plan.items)
+                if candidate.step == parent
+                and candidate.assessment_question is not None
+            ),
+            None,
+        )
+        if index is None:
+            raise StateError(f"assessment outcome has no parent assessment: {parent}")
+        return _unanswered(state, plan, index, declared=True)
+    previous = plan.items[state.cursor - 1]
+    if previous.assessment_question is not None and not previous.assessment_outcomes:
+        return _unanswered(state, plan, state.cursor - 1, declared=False)
+    return None
+
+
+def _unanswered(
+    state: ExecutionState, plan: WorkflowPlan, index: int, *, declared: bool
+) -> PendingAssessment | None:
+    """The assessment at ``index``, unless its outcome is already chosen.
+
+    A chosen outcome is kept on the assessment's record, so a stop between
+    the answer and the next step, such as a pass gate, never asks again.
+    """
+    if state.item_executions[index].assessment_outcome is not None:
+        return None
+    return _pending(plan, index, declared=declared)
+
+
+def _pending(plan: WorkflowPlan, index: int, *, declared: bool) -> PendingAssessment:
+    question = plan.items[index].assessment_question
+    assert question is not None  # pragma: no cover - callers check it
+    return PendingAssessment(
+        index, question, assessment_outcomes(plan, index), declared
+    )
+
+
+def _assessment_parent(item: PlanItem) -> str | None:
+    """Resolve template paths retained by previously materialized snapshots.
+
+    Keep the persisted plan unchanged so its digest and completed work remain
+    valid. Concrete paths bind each outcome to its own item or child.
+    """
+    parent = item.assessment_parent
+    if parent is None:
+        return None
+    parts = parent.split("/")
+    step_parts = item.step.split("/")
+    for index, part in enumerate(parts):
+        if part in {"{item}", "{child}"} and index < len(step_parts):
+            parts[index] = step_parts[index]
+    return "/".join(parts)

ww/assets/__init__.py

@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""Package data used when initializing a project."""

ww/assets/agent_instructions.md

@@ -0,0 +1,49 @@
+# Working with ww
+
+ww saves progress, runs handlers, and names the next role; it is only for
+development. Where ww is used by default, every file change goes through ww
+unless the user asks you not to. Reviews, questions, investigations and other
+read-only work never use ww, its skill or a task. When no workflow fits a change, run
+`./ww lookup [<task>] --agent <agent>` and follow it; it never creates a task without operator confirmation.
+
+## Start here
+
+Before starting new work, run:
+
+```console
+./ww discover
+```
+
+It lists the project's workflows, modes, the start command, resume commands, and
+whether to use ww unasked. If disabled, stop; if used only on request, use it only when
+the user asks for ww. Choose the matching workflow and keep its default modes
+unless the request matches another mode; ask only when the choice would
+materially change the work.
+
+When a request names an external ticket, use that as the task ID. Omit the ID
+only when none is named or the workflow obtains it in its first step.
+
+To continue an existing task, run `./ww instruction <task-id> --role manager`;
+a worker resuming its assignment uses `--role worker`. Check status with
+`./ww status <task-id>`.
+
+## Rules
+- Follow each authoritative ww page: replace placeholders and supply requested
+  values until completion, error, or assignment end. One completion rarely ends a task.
+- Perform only agent-owned work. Never run or bypass a ww handler, edit ww state, or read `ww.yaml` or ww source to infer the next step.
+- For handler repair, fix the cause and complete with an artifact; ww retries it. In `auto`, the manager dispatches repairs with `next`.
+- On an `interactive: true` step, converse in the operator session and finish
+  on clear contextual intent; ask if it is ambiguous. "Done for today" means
+  pause. Record both sides and end the interaction before completing it.
+- Use a host choice tool when available, following its contract; otherwise use
+  a numbered chat list. Keep async choices pending until an answer arrives;
+  timeout, dismissal, and preselection are not answers.
+- On nonzero exit, read the full response. For "Fix required", repair and complete again
+  (`./ww check <task-id>` previews checks) or `./ww dispute`; record impossible work
+  with `./ww fail` and the page's role/assignment. On `awaiting_operator`, stop and
+  report the reason and exact error; run only the operator's chosen recovery option;
+  never reset unasked. A standing operator authorization for routine repairs (dependency
+  installation, formatting, retries) covers such stops: apply it, asking only for a
+  material decision or an action outside it.
+- Relay feedback-deduction suggestions after completion; use its skill and ww
+  commands. Rule approval and pruning are separate follow-ups.