ww-agentic-workflows 1.0.0.dev3__tar.gz → 1.0.0.dev5__tar.gz

ww_agentic_workflows-1.0.0.dev5/.claude/skills/noww/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: noww
+description: Work without ww. Use only when the user invokes /noww or asks not to use ww.
+---
+
+# Work without ww
+
+Do not use ww for the rest of this conversation, unless the user asks for it
+again: do not run `./ww discover`, `./ww lookup` or `./ww record`, and do not
+start, continue, or complete a ww task. Carry out requests directly, as in a
+project without ww. A ww task already in progress stays as it is; do not reset
+or fail it.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev5}/.claude/skills/ww/SKILL.md

@@ -17,17 +17,29 @@ change, start from step 1 then.
    carry out the request without ww and do not ask.
 2. To continue an existing task, run
    `./ww instruction <task-id> --role manager` instead of starting a new one.
-3. Otherwise choose the workflow that matches the request, keep its default
-   modes unless the user's wording matches another mode, and start the task
-   with the start command `discover` shows. Pass the user's requirements,
-   normalized, as `--requirements`. When the request names an external
-   ticket, such as a Jira key, use that key as the task ID; omit the ID only
-   when there is none or the workflow obtains its own.
-   When no workflow fits and you are about to change files, do not start
-   `catchall` directly: run `./ww lookup [<task>] --agent <agent>` with the
-   task the conversation works on or the request names, as written, and
-   follow its answer, then do the work as you would without ww. Read-only work
-   needs no task.
+3. Otherwise decide how the request is carried out, in this order:
+   a. It names a ticket or clearly matches a configured workflow's
+      description, and is more than a small change: propose that workflow, and
+      offer the alternative in the same choice, "run `<workflow>`" / "just do
+      it, register afterwards". A workflow the user named is started without
+      asking. When one is chosen, keep its default
+      modes unless the user's wording matches another mode, and start the task
+      with the start command `discover` shows. Pass the user's requirements,
+      normalized, as `--requirements`. When the request names an external
+      ticket, such as a Jira key, use that key as the task ID; omit the ID
+      only when there is none or the workflow obtains its own.
+   b. Otherwise it is direct work: do it as you would in a plain conversation,
+      with no question asked, then run
+      `./ww record <task> --summary "..."`. `./ww lookup [<task>] --agent
+      <agent>` names the task and the command; pass the task the conversation
+      works on or the request names, as written. Read-only work needs no task.
+   c. Judge each prompt on its own. A series of small requests stays a series
+      of direct-work entries; never promote them into a workflow because they
+      add up.
+   d. Ask only when it is genuinely ambiguous, and never again on the same
+      task once the operator chose direct work.
+   e. If `record` fails or is forgotten, ww records the commits it had not
+      seen on the next run; say so, and do not retry it endlessly.
    When the first page of `start` says rules have no check
    yet, tell the user once and carry on: it never blocks the task, and the
    `ww-scriptize` skill builds those checks when they want it.

ww_agentic_workflows-1.0.0.dev5/.codex/skills/noww/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: noww
+description: Work without ww. Use only when the user invokes /noww or asks not to use ww.
+---
+
+# Work without ww
+
+Do not use ww for the rest of this conversation, unless the user asks for it
+again: do not run `./ww discover`, `./ww lookup` or `./ww record`, and do not
+start, continue, or complete a ww task. Carry out requests directly, as in a
+project without ww. A ww task already in progress stays as it is; do not reset
+or fail it.

ww_agentic_workflows-1.0.0.dev5/.codex/skills/ww/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: ww
+description: Carry out a development request through ww, this project's workflow tool. Use only when the request changes something (implement, fix, refactor, merge, edit documentation) or the user explicitly asks to work via ww, to start or continue a ww task, or to run a ww workflow; where `./ww discover` says ww is used by default, use it before changing files for any request, since every change then goes through ww. Never use it for reviews, questions, explanations, investigations, status checks or other read-only work, even when they concern ww or a ww task.
+---
+
+# Work through ww
+
+ww is for development: requests that change files. A review, question,
+explanation, investigation, status check or other read-only request never
+goes through ww; answer it directly, without these steps and without a task,
+even where ww is used by default. When a read-only conversation turns into a
+change, start from step 1 then.
+
+1. Run `./ww discover` and read all of it. If it says ww is disabled, stop:
+   do not use ww, and tell the user. If it says ww is used only on request
+   and the user did not explicitly ask for ww (invoking this skill counts),
+   carry out the request without ww and do not ask.
+2. To continue an existing task, run
+   `./ww instruction <task-id> --role manager` instead of starting a new one.
+3. Otherwise decide how the request is carried out, in this order:
+   a. It names a ticket or clearly matches a configured workflow's
+      description, and is more than a small change: propose that workflow, and
+      offer the alternative in the same choice, "run `<workflow>`" / "just do
+      it, register afterwards". A workflow the user named is started without
+      asking. When one is chosen, keep its default
+      modes unless the user's wording matches another mode, and start the task
+      with the start command `discover` shows. Pass the user's requirements,
+      normalized, as `--requirements`. When the request names an external
+      ticket, such as a Jira key, use that key as the task ID; omit the ID
+      only when there is none or the workflow obtains its own.
+   b. Otherwise it is direct work: do it as you would in a plain conversation,
+      with no question asked, then run
+      `./ww record <task> --summary "..."`. `./ww lookup [<task>] --agent
+      <agent>` names the task and the command; pass the task the conversation
+      works on or the request names, as written. Read-only work needs no task.
+   c. Judge each prompt on its own. A series of small requests stays a series
+      of direct-work entries; never promote them into a workflow because they
+      add up.
+   d. Ask only when it is genuinely ambiguous, and never again on the same
+      task once the operator chose direct work.
+   e. If `record` fails or is forgotten, ww records the commits it had not
+      seen on the next run; say so, and do not retry it endlessly.
+   When the first page of `start` says rules have no check
+   yet, tell the user once and carry on: it never blocks the task, and the
+   `ww-scriptize` skill builds those checks when they want it.
+4. Follow every ww response exactly: run each displayed command with all
+   placeholders replaced, and keep going until ww reports that the workflow
+   is complete or reports an error. On `interactive: true` steps, converse
+   naturally until intent to finish is clear, ask if ambiguous, and treat
+   "done for today" as a pause. Record and end the interaction before
+   completing it. Use the host choice tool when available; keep asynchronous
+   choices pending until an answer arrives, and do not treat timeouts or
+   preselection as answers. After completion, relay any optional
+   `ww-deduce-feedback` suggestion; do not insert learning into the plan.
+   Deduction uses ww commands and explicit existing point IDs; rule review
+   and pruning are separate, and rules require operator approval.
+5. Never run a ww-owned handler yourself, edit ww state, or read
+   `ww.yaml` or ww's source to work out what to do next. For a handler repair
+   assignment, fix the cause and complete with an artifact; ww retries the
+   command. In `auto`, the manager dispatches the repair with `next`. When
+   ww reports `awaiting_operator` (a failed handler or work, an interrupted
+   command, a loop at its iteration limit, a changed workflow), stop and report the task, its
+   `operator_reason` and the exact error to the user (unless they gave a
+   standing authorization for routine repairs such as dependency installation,
+   formatting or retries: apply it to a stop of that kind without asking again,
+   and ask only for a material decision or an action outside it); when they
+   decide, run the recovery command ww showed, `./ww next <task-id> --retry` to run the
+   handler again, `--force --reason` to skip it or leave the loop, or
+   `--replan` / `--keep-plan` for a changed workflow. A `pass_incomplete`
+   stop is cleared by recording what it names with `./ww update-item`, then
+   `./ww next <task-id> --retry`; `--force` is refused there.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev5}/CHANGELOG.md

@@ -11,6 +11,60 @@ yet, is in [documentation/limitations.md](documentation/limitations.md).
 
 ## 2026-10-05
 
+- Removed: the session-start task list, stop reminders, interruption records and transcript recovery, and the
+  `interrupted` command. Hooks, events and `agent_hooks` keys stay accepted. `5414a34`
+- Added: `add-child` is accepted while a per-child stage of a roadmap-style parent is active, not only while the
+  collecting step is. The new child is appended after the last planned child with its own expanded lifecycle;
+  once the last child's stages have finished the command is refused. `00338d9`
+- Added: `ww handoff <task> [--run ID] [--assignment TOKEN] [--json]` prints the handoff block of an ended assignment
+  again, for a worker whose output was cut short; the completion page and the `auto` runtime instruction name it.
+  The change set is reproduced only while the assignment is the latest one, otherwise the block says so. `aae3ed2`
+- Fixed: when a child task's run has completed, its handoff block names the parent task's `next` command
+  ("Manager: continue with the parent task: ...") instead of a command that fails because the child is completed;
+  a child partway through its run keeps its own. The handoff JSON carries `continuation_task_id`. `6b6669c`
+- Fixed: a child task's `ww/git` worktree is named like its branch, the parent's rendered `worktree_name_format`
+  plus `-<child id>` (`ww-worktrees/TASK-51-A`), so it no longer lands inside the parent's checkout as untracked
+  content; any other rendered name holding a `/` has each one replaced with `-`. Worktrees already created inside
+  a parent's are not migrated. `6b6669c`
+- Fixed: the continuation line of a requested-worker page names the flags (`--selected-agent`, `--model`,
+  `--reasoning`) whose values follow the request. `6b6669c`
+- Changed: ww's own roadmap workflow's `fix` step tells the worker to prefix its commits with the child ID, as the
+  child's own commits are. `6b6669c`
+
+- Added: direct work replaces the `catchall` workflow. A change no workflow fits is made as in a plain
+  conversation and registered afterwards with `record <task> --summary "<text>"`, which appends an entry to
+  the task's `direct-work.json` with the commits ww finds itself (the task's recorded branch since its base,
+  minus the commits ww already knows; without a recorded branch, the current branch's commits that name the task
+  ID). A task needs no run, and `lookup` no longer asks before a task ww has not seen. When the manager asks for
+  a task's page with `instruction --role manager`, ww records any commits it had not seen as a `reconciled` entry
+  and prints one line at the top of the page, so a forgotten or failed `record` is made up for. `status` lists the
+  entries and short SHAs. The agent instructions, the `ww` and `noww` skills and `discover` now say: propose a
+  matching workflow with "just do it, register afterwards" as the alternative, otherwise work directly and ask
+  nothing, judge each prompt on its own, and never ask again on a task once direct work was chosen. Existing
+  projects keep their installed skills; `init --force` or copying the bundled ones picks up the new wording.
+- Removed: the `catchall` workflow, its `discover` section (`catchall` is gone from the JSON, `direct_work`
+  replaces it) and the `lookup` menu. A `catchall` entry under `workflows` in `ww.json` is ignored and `lint`
+  warns about it, instead of failing.
+- The repair page for a failed automatic handler now says what to do when the cause is the environment rather than
+  the work (a sandbox or permission denial, a network or package-install error, a held lock): change no project
+  files, fix the environment or ask the operator, and say in the completion that the cause was environmental.
+- A rule file can narrow a rule to files by content with `contains`, a list of plain, case-sensitive strings (no
+  regular expressions) in its frontmatter: a file must match a `paths` glob, if any, and contain one of the
+  strings. A check whose strings are in no changed file is not applicable, a converted check covering several
+  rules takes the union of their strings, and the step page prints the strings beside the globs. `rules add` and
+  `rules edit` take `--contains <text>...` and report how many project files hold each string. Rules written in a
+  step's own `rules` list still take no `paths` or `contains`.
+- `complete` and `loop` take `--adjustments "<text>"` for the changes the operator asked for during a step. ww
+  stores it on the step record, shows it in `status`, beside the summary on the next step's page and on the
+  verifier's page, and hands it to feedback deduction as a labelled `adjustments` field; a repair completion
+  refuses it. Every worker step page now asks the worker to record such requests in the artifact and in the flag.
+- A workflow can set `manual: true`: `discover` and `lookup` leave it out, `start` still accepts it, and `inherit`
+  does not copy the setting. A workflow named `manual` in the `- name: description` shorthand must now use the
+  `name:` key.
+- A handoff now gives the new run the target workflow's declared `runtime`, and replaces the run-level `model` and
+  `reasoning` with the target's declared values, keeping the source run's values for what the target does not
+  declare.
+- The specification and features now describe how a child gets its external ID.
 - The `ww` skill and agent instructions now say ww is only for development: reviews, questions, investigations,
   status checks and other read-only requests never invoke the skill or start a task. Existing projects keep their
   installed skill; `init --force` or copying the bundled one picks up the new wording.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ww-agentic-workflows
-Version: 1.0.0.dev3
+Version: 1.0.0.dev5
 Summary: A local-first, resumable workflow CLI for people and AI agents.
 Project-URL: Homepage, https://agenticworkflows.dev
 Project-URL: Documentation, https://github.com/from-developers-for-developers/agentic-workflows/tree/main/documentation
@@ -323,14 +323,14 @@ one:
 - `--role manager` is the role driving the task; a worker performing a single
   assignment uses `--role worker`.
 
-A request no workflow fits still goes through ww once it changes files. The
-agent records it with `catchall`, a one-step workflow ww provides to every
-project, and otherwise works exactly as it would without ww. Questions and
-other read-only work never start a task. The agent first runs `./ww lookup`
-with the task you named, however you wrote it (`12345` finds `FOOBAR-12345`),
-and a task ww has never seen is only created after you confirm it in the
-agent's choice menu. Say `/noww` when you want the
-agent to leave ww out.
+A request no workflow fits is direct work: the agent does it exactly as it
+would without ww, then registers it with `./ww record <task> --summary "..."`,
+and ww keeps the summary and the commits it finds for it. Questions and other
+read-only work never start a task. The agent first runs `./ww lookup` with the
+task you named, however you wrote it (`12345` finds `FOOBAR-12345`), and asks
+you nothing unless the request clearly matches a workflow, in which case it
+offers that workflow or "just do it, register afterwards". Say `/noww` when
+you want the agent to leave ww out.
 
 If you would rather open the task yourself — to pin an external ticket key, or
 to hand a prepared task to an agent — the same command works typed in.
@@ -649,7 +649,7 @@ ww-agentic-workflows complete TASK-123 --role worker \
 - [architecture.md](documentation/architecture.md) describes internals, boundaries, state, and
   design decisions.
 - [agent-hooks.md](documentation/agent-hooks.md) covers the agent's own hooks
-  (session-start, stop, interrupt): what they do, per-agent support, and
+  (the session-start line): what it does, per-agent support, and
   install/uninstall/show.
 - [examples.md](documentation/examples.md) is a set of complete, tested
   `ww.yaml` examples, one per control or behaviour.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev5}/README.md

@@ -285,14 +285,14 @@ one:
 - `--role manager` is the role driving the task; a worker performing a single
   assignment uses `--role worker`.
 
-A request no workflow fits still goes through ww once it changes files. The
-agent records it with `catchall`, a one-step workflow ww provides to every
-project, and otherwise works exactly as it would without ww. Questions and
-other read-only work never start a task. The agent first runs `./ww lookup`
-with the task you named, however you wrote it (`12345` finds `FOOBAR-12345`),
-and a task ww has never seen is only created after you confirm it in the
-agent's choice menu. Say `/noww` when you want the
-agent to leave ww out.
+A request no workflow fits is direct work: the agent does it exactly as it
+would without ww, then registers it with `./ww record <task> --summary "..."`,
+and ww keeps the summary and the commits it finds for it. Questions and other
+read-only work never start a task. The agent first runs `./ww lookup` with the
+task you named, however you wrote it (`12345` finds `FOOBAR-12345`), and asks
+you nothing unless the request clearly matches a workflow, in which case it
+offers that workflow or "just do it, register afterwards". Say `/noww` when
+you want the agent to leave ww out.
 
 If you would rather open the task yourself — to pin an external ticket key, or
 to hand a prepared task to an agent — the same command works typed in.
@@ -611,7 +611,7 @@ ww-agentic-workflows complete TASK-123 --role worker \
 - [architecture.md](documentation/architecture.md) describes internals, boundaries, state, and
   design decisions.
 - [agent-hooks.md](documentation/agent-hooks.md) covers the agent's own hooks
-  (session-start, stop, interrupt): what they do, per-agent support, and
+  (the session-start line): what it does, per-agent support, and
   install/uninstall/show.
 - [examples.md](documentation/examples.md) is a set of complete, tested
   `ww.yaml` examples, one per control or behaviour.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev5}/WW_AGENT_INSTRUCTIONS.md

@@ -3,8 +3,7 @@
 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.
+read-only work never use ww, its skill or a task.
 
 ## Start here
 
@@ -14,7 +13,7 @@ Before starting new work, run:
 ./ww discover
 ```
 
-It lists the project's workflows, modes, the start command, resume commands, and
+It lists the project's workflows, modes, the start command, 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
@@ -23,6 +22,17 @@ 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.
 
+A request that names a ticket or clearly matches a workflow's description, and
+is more than a small change: propose that workflow, and offer the alternative in
+the same choice, "run `<workflow>`" / "just do it, register afterwards". Any
+other request is direct work: do it as in a plain conversation, ask nothing,
+then run `./ww record <task> --summary "..."` (`./ww lookup [<task>] --agent
+<agent>` names the task). Judge each prompt on its own; a series of small
+requests stays direct work, never a workflow. Ask only when genuinely ambiguous,
+and never again on a task once the operator chose direct work. If `record`
+fails or is forgotten, ww records the commits on the next manager
+page (`instruction --role manager`): do not retry.
+
 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>`.

ww_agentic_workflows-1.0.0.dev5/documentation/agent-hooks.md

@@ -0,0 +1,135 @@
+# Agent hooks
+
+ww's instructions to agents are static, so a session needs one pointer to
+find ww at all. Agent hooks are the agent's own hooks, installed with `ww hook`
+— not the workflow hooks of `ww.yaml` (see
+[Workflow hooks, variables, and transitions](features.md#workflow-hooks-variables-and-transitions)
+in the feature reference), which run as part of a plan and can run
+handlers, gate completion, or trigger a check. Agent hooks are gentle by
+design: they add one line of context, and nothing they do ever blocks the
+agent.
+
+ww registers one hook, `session-start`, which runs when a session starts,
+resumes, or is compacted. It prints a reminder that ww coordinates work here
+(under `"enabled": "on_request"`: that ww is used only when the user asks for
+it) and how to list its workflows. It lists no task: `discover` lists the
+project's workflows, and the operator names the task to continue.
+
+There is no pre-spawn hook yet: ww does not intercept an agent's own
+subagent calls. `subagents: false` is enforced only through the step's
+page today; see [Agent limitations](limitations.md#agent-limitations).
+
+## What `session-start` prints
+
+What `session-start` prints stays in the agent's context for the whole
+session, so it is one line:
+
+```text
+This project coordinates work through ww: `./ww discover` lists its workflows.
+```
+
+After a compaction it starts with a line before that one: "Context was
+compacted; ww's task state is authoritative." Only the main session gets this
+context: no hook is registered for a subagent's start, since a worker receives
+its bootstrap command from the manager.
+
+## `stop` and `interrupt` are retired
+
+Earlier versions of ww also registered `stop` and `interrupt` hooks, which
+listed unfinished tasks, reminded an agent to close a step, and recorded
+interrupted sessions. They are gone: a reminder written for one session
+confused another, and nothing in them was needed to continue a task.
+
+The events stay accepted so a hooks file written by an older ww keeps
+working. `ww hook stop` and `ww hook interrupt` exit 0 with no output and
+record nothing; the audit log notes the call. The `agent_hooks` keys
+`check_unfinished` and `recent_days` in `ww.json` are still validated and
+still accepted, and have no effect. Running `hook install` again replaces an
+older registration with the one `session-start` entry, and `hook uninstall`
+removes every ww entry, whichever events it registered.
+
+## Agents and their files
+
+| Agent | Project file | Native event | Local file |
+| --- | --- | --- | --- |
+| Claude Code | `.claude/settings.json` | `SessionStart` | `.claude/settings.local.json` |
+| Codex | `.codex/hooks.json` | `SessionStart` | none; user file `~/.codex/hooks.json` |
+| Cursor | `.cursor/hooks.json` | `sessionStart` | none; user file `~/.cursor/hooks.json` |
+| Antigravity | `.agents/hooks.json`, group `ww` | `PreInvocation` | none; user file `~/.gemini/config/hooks.json` |
+
+Claude Code's `SessionStart` has no matcher, so it fires for every source,
+compaction included. Antigravity has no session-start event, so ww answers
+only its first pre-invocation of a conversation, as an ephemeral message that
+never accumulates. Codex loads project hooks only once the project's `.codex/`
+layer is trusted: review them with `/hooks` in Codex.
+
+These per-agent gaps (no session-start event, a trust gate) are permanent
+differences between agents, not bugs; see
+[Agent limitations](limitations.md#agent-limitations) for the summary.
+
+## Install, remove, and show
+
+```console
+ww-agentic-workflows hook install --agent claudecode
+ww-agentic-workflows hook uninstall --agent codex
+ww-agentic-workflows hook show --agent cursor
+ww-agentic-workflows hook install --agent claudecode --local
+```
+
+`install` merges ww's entry into whatever the file already holds and leaves
+every other entry alone. ww recognises its own entries by their command, so a
+second `install` changes nothing and `uninstall` removes exactly what ww added,
+including the `stop` and `interrupt` entries an older ww registered. `show`
+prints the file and the exact snippet, that is, what ww registers, for a
+machine or an agent where `install` cannot run. A file that is not valid JSON,
+or cannot be written, makes `install` fail with the path and the full snippet
+to add by hand.
+
+`--local` writes the agent's project file kept out of version control, so the
+hooks stay one person's choice. Only Claude Code has one,
+`.claude/settings.local.json`; for the other agents `--local` fails and names
+their user-level file, which applies to every project on the machine. Without
+`--local` the hooks go into the shared project file, which is usually committed,
+so everyone who clones the project gets them. When ww's hooks sit in both of
+Claude Code's files every hook would run twice, so `install` and `show` print a
+notice with the command that removes one copy.
+
+The registered command calls the project's tracked `./ww` launcher: through
+`"$CLAUDE_PROJECT_DIR"` for Claude Code, from the project root for Cursor, and
+from the repository's top level (`git rev-parse --show-toplevel`) for Codex and
+Antigravity. The launcher resolves the durable root through the shared Git
+directory, so a session in a task worktree reaches the same state; the launcher
+must therefore be tracked for worktree sessions.
+
+The runtime form, `ww hook session-start|stop|interrupt --agent <agent>`, is
+what the agents call; it reads the agent's JSON payload on stdin.
+
+## When a hook fails or runs too often
+
+A hook never breaks the agent. On any error, a bad argument, or outside a ww
+root, it exits 0 with no output: some agents read exit code 2 as "continue", and
+an unexpected message would enter the agent's context. The worst outcome is a
+lost hint. When the command cannot start at all, for example a missing
+launcher or an untrusted Codex hook, the agent shows its own non-blocking hook
+error. A hook that times out is killed by the agent, which carries on.
+
+Running more often than needed is harmless. Antigravity calls its
+pre-invocation hook before every model call; only the first one returns
+context.
+
+Every hook call is written to the audit log, `.ww/executions.jsonl`, with the
+event, the agent, and ww's decision, so a session can be followed there:
+
+```json
+{"command": "hook", "hook_event": "session-start", "hook_agent": "claudecode", "hook_decision": "context", "outcome": "ok"}
+```
+
+A failure is logged with `outcome: error` and the exception type. The agent's
+payload is never logged.
+
+## See also
+
+- [Agent limitations](limitations.md#agent-limitations): per-agent hook
+  gaps, nested subagents, and why a worker cannot talk to the operator.
+- [architecture.md](architecture.md#agent-hooks) for how the hook answers
+  are computed internally.

{ww_agentic_workflows-1.0.0.dev3 → ww_agentic_workflows-1.0.0.dev5}/documentation/architecture.md

@@ -29,7 +29,7 @@ produce those definitions directly through the same loader contract. Shared
 cross-definition rules live in `../src/ww/workflow_validation.py`, so notation
 parsers do not acquire different workflow semantics. Validation is also where
 the built-in workflows join the configured ones: `../src/ww/builtin_workflows.py`
-parses the YAML files shipped in `../src/ww/assets/workflows/` (`catchall`, `scriptize.yaml` with `ww-scriptize-rules`, and
+parses the YAML files shipped in `../src/ww/assets/workflows/` (`scriptize.yaml` with `ww-scriptize-rules`, and
 `onboarding.yaml` with ww's learning and setup workflows) with the same frontend, once per process, and adds each workflow the
 configuration does not define itself and `../ww.json` does not
 switch off, with the documents and modes its file declares, dropping a
@@ -43,11 +43,17 @@ it. The scriptizing workflow declares its own Git lifecycle hooks to isolate
 tool installs and configuration changes from the operator's current branch.
 `ww/git` always branches it from the required default base and follows its
 worktree settings; built-in composition needs no project lane setting.
-`lookup` (`../src/ww/cli/lookup.py`) is the catch-all's entry
-point: `../src/ww/task_references.py` maps what the operator called a task onto
-the task format and the IDs the storage port lists, and the command answers
-with one next step, asking the operator through the agent's choice menu
-(`../src/ww/agents.py`) before a new task is created. `inherit` is resolved by
+`lookup` (`../src/ww/cli/lookup.py`) is the entry point of direct work:
+`../src/ww/task_references.py` maps what the operator called a task onto the
+task format and the IDs the storage port lists, and the command answers with
+one next step, continuing an open run or naming the `record` command, and
+asking the operator through the agent's choice menu (`../src/ww/agents.py`)
+only when the reference matches several tasks. `../src/ww/direct_work.py` holds
+the direct-work entries kept in each task's `direct-work.json` (a
+`TaskDirectWorkStorage` port of the storage adapters) and finds the commits for
+them from the ww/git records and `git log`; `WorkflowService.record_direct_work`
+backs `record`, and `reconcile_direct_work` runs before a manager's
+`instruction` page. `inherit` is resolved by
 the YAML frontend itself, once every workflow is parsed: the heir becomes a
 complete copy with its own settings on top, and global hooks filtered to a
 workflow are extended to its heirs, so validation, the compiler, `plan`, and
@@ -954,7 +960,8 @@ builds from the saved state (`instructions/handoff.py`): the items performed
 with their outcomes, artifacts, checks, fix rounds and change set, plus the
 worker's capped `--summary`. The service takes the open
 assignment's items before a worker command runs, so the block can still name
-them after the command closed the assignment. A worker's `complete` or `loop`
+them after the command closed the assignment. `WorkflowService` builds the block in one method, used by both the completion
+path and `ww handoff`, which reprints it for an ended assignment from the saved records. A worker's `complete` or `loop`
 on a `role: manager` item is refused; the manager completes it with `--role
 manager`.
 A step's `role` says who performs it, and it is resolved along the same chain
@@ -1371,9 +1378,7 @@ waiting while the child it could not launch has no run.
 `complete --role manager` is composed in the CLI: the policy (`manager_continues_itself`)
 reads the page the completion returned and, when the next step is the manager's own,
 the command calls `next` as the manager would; the service's `complete` never
-dispatches, so every other caller keeps its single-step contract. The stop hook
-treats a task with an open child below it, or a delegated step in progress, as a
-manager that is waiting (`OpenTask.waiting_on_another`). `init`'s opt-in Claude Code
+dispatches, so every other caller keeps its single-step contract. `init`'s opt-in Claude Code
 permission rules live in `ww.claude_permissions` (merge, never clobber, keep ignored).
 
 Amendments to a task's requirements live behind their own storage port
@@ -1410,6 +1415,15 @@ extension namespace values, for agent pages, automatic handlers, and the
 reuses the loop exit: `finish_loop_exit` skips the remaining per-child items
 and the drain marks the children that never started `skipped`.
 
+`add-child` is also accepted while a per-child stage is the active item. The
+guard in `WorkflowService.add_child` refuses once the cursor has left the
+per-child items. Otherwise the new child is appended and
+`append_child_lifecycle` (in `../src/ww/transitions.py`) expands one more
+lifecycle from `snapshot.template_plan` through `_expand_templates`, with no
+replaced items and placed after the last planned child's last item. The child
+record and the grown plan are committed in the same task lock, so a child is
+never recorded without its stages.
+
 The scope is deliberately one level: a child workflow cannot itself declare
 `children`. When the last child completes, ww completes
 the parent coordinator and resumes the parent's ordinary completion lifecycle,
@@ -1604,13 +1618,9 @@ completion is refused until it was ended. How the operator is asked is the
 agent's business; the choice mechanisms table in `agents.py` is core knowledge
 of what each integration offers, not an extension point.
 
-The `interrupt` hook is the record's safety net. For a step still in
-conversation, `hooks/transcripts.py` reads the session's own transcript
-(Claude Code's session JSONL, Codex's rollout JSONL), keeps the two sides'
-messages since the attempt started, and the hook appends them through
-`InteractionLog` under speakers marked `(recovered)`. It writes no task state
-and takes no task lock: the session that held the conversation is the one
-ending, and the step record's entry count stays the agent's.
+A session that ends mid-conversation loses what was not yet recorded; ww does
+not recover it from the agent's transcript, and the next session asks the
+operator where they were.
 
 The operator page is an extra on top of that, not part of it. The core knows
 it by one flag, `interactive: page` on a per-item stage (`ui` on the
@@ -1642,24 +1652,32 @@ the operator left, and only the operator's own words lift it.
 ## Agent hooks
 
 See [documentation/agent-hooks.md](agent-hooks.md) for the user-facing
-behaviour (events, per-agent table, install/uninstall/show, interrupted
-tasks); this section is the internal design behind it.
-
-Agent hooks exist to carry state the static instructions cannot: which task
-is unfinished when a session starts or compacts, and whether it is ending with
-an agent-owned step still open. Every decision lives in ww. `ww.open_work`
-answers from the persisted runs alone which tasks are open and whether an
-agent step is dispatched and in progress, reusing the control policy's
-`operator_reason` so a task waiting for input or the operator never counts; it
-renders nothing, compiles nothing, and loads no extension, which keeps a hook
-fast. It returns `OpenWork`: the open tasks and, as `UnreadableTask`, every
-task whose record raised `StateError` (both storage adapters wrap a bad record
-that way), so one broken task never hides the others. The interruption scan in
-`ww.hooks.records` skips such a task, and `discover` lists what `open_work`
-reports; only commands addressing such a task still fail. `ww.hooks.runtime` turns that into the three answers, and the adapters in
-`ww.hooks.agents` only translate: each reads its agent's payload into one
-neutral record and renders ww's answer in the agent's reply shape. A new agent
-is one more adapter.
+behaviour (the session-start line, per-agent table, install/uninstall/show);
+this section is the internal design behind it.
+
+The hooks stay small on purpose. ww once listed unfinished tasks at session
+start, reminded an agent to close a step when it stopped, recorded interrupted
+sessions, and recovered conversations from transcripts. The result confused
+sessions that had nothing to do with the task, so only the one line a session
+needs to find ww remains. `ww.hooks.runtime` answers it: `session-start`
+prints `session_context` from `ww.hooks.notices`, and every other event
+answers nothing. The adapters in `ww.hooks.agents` only translate: each reads
+its agent's payload into one neutral record and renders ww's answer in the
+agent's reply shape. A new agent is one more adapter. The three events, the
+payload fields (including the ones nothing reads now) and the `agent_hooks`
+keys stay accepted, so a hooks file or `ww.json` written by an older ww keeps
+working; `stop` and `interrupt` calls from an older installation exit 0 with no
+output and write no state. ww keeps no hook record per task: `reset` only
+removes the `interrupted.json` and `stop-reminders.json` an older version
+may have left, so they cannot keep the task directory alive.
+
+`ww.open_work` is reduced to what the operator surface `discover` needs: it
+reads every task's record and returns, as `UnreadableTask`, the ones that
+raised `StateError` (both storage adapters wrap a bad record that way), so a
+broken task is named instead of hidden; only commands addressing such a task
+still fail. It is not used by the hooks, and no command lists unfinished tasks:
+the operator names the task, and `lookup`'s "continue" outcome and
+`instruction` find the open run.
 
 The runtime form is intercepted before normal command parsing. It always
 exits 0 without stderr, because exit code 2 means "continue" to some agents'
@@ -1667,32 +1685,9 @@ stop hooks and stray text would enter the agent's context, and it skips the
 update notice. It still writes one audit record per call with ww's decision,
 never the payload, so a session can be followed without the agent's text.
 
-The stop hook is a one-time reminder rather than a block. A reminder is
-recorded per task, run, item, and attempt in `stop-reminders.json` beside the
-interaction log, and the check and the record happen under a lock of their own:
-agents run matching hooks in parallel, and the task lock would stall behind a
-long-running command. An agent's own loop guard is honoured as well.
-
-Stop and interrupt pick the tasks a session concerns in one function,
-`ww.open_work.tasks_for_session`. A workspace selects a task only when it is not
-the root: the root holds every task's state, and a worktree-less task works
-there, so matching it would tie every root session to every such task.
-Otherwise the run's recorded agent must be the hook's agent, because a session
-has no business closing another integration's step. The stop hook further
-separates a manager from its workers: `OpenTask.delegated` marks a step an
-`auto` run hands to a worker, and only a stop the adapter reports as a
-worker's (`HookPayload.from_worker`) reminds about it. Messages name work
-through `OpenTask.label`, which names a hook item by itself and its step,
-since a hook records the step it is attached to. The
-interruption record, `interrupted.json`, is cleared lazily in the one place
-that reads it, once that attempt completed, failed, or was superseded, never
-because a notice showed it, so compaction between reading and acting cannot
-lose it. Listing interruptions scans the markers instead of keeping an index
-that could drift. Both records belong to the task, and `reset` removes them
-before the storage adapter removes the task directory.
-
 Installation writes only the agent's project file, or with `--local` the one it
-keeps out of version control, merging ww's entries and recognising them by
+keeps out of version control, merging ww's one `session-start` entry and
+recognising ww's entries, including older `stop` and `interrupt` ones, by
 their command. `init` offers it per agent and treats a failure as a manual
 action, never as an init failure.