@plainconceptsplatform/workflows 0.28.9 → 0.28.11

package/dist/catalog-installation.js

@@ -15,6 +15,7 @@ const sourceMappings = [
     ["actions", ".github/actions"],
     ["workflows", ".github/workflows"],
     ["scripts", "scripts"],
+    ["docs", "docs"],
 ];
 export function mandatoryFileSpecs(sourcePath) {
     return mandatoryFiles.map((spec) => ({
@@ -183,7 +184,7 @@ function hasEmptyVerifyCommands(current) {
 // consumer forever: that is how `stale-recovery` and `update-changelog` outlived the code that
 // called them. Deliberately not `.github/workflows/`, where a worker's absence means the route
 // is not installed rather than gone, and never anything without a header, which is a fork.
-const pruneRoots = [".github/actions", ".github/workflows/shared"];
+const pruneRoots = [".github/actions", ".github/workflows/shared", "docs"];
 async function orphanedManagedFiles(repositoryPath, keep) {
     const orphans = [];
     for (const root of pruneRoots) {

package/dist/workflow-catalog.d.ts

@@ -7,7 +7,7 @@ export interface WorkflowRoute {
     readonly defaultEnabled: boolean;
 }
 export declare const workflowRoutes: readonly WorkflowRoute[];
-export declare const packageOwnedTargets: readonly [".github/actions", ".github/workflows/agent-*.md", ".github/workflows/shared/platform-defaults.md", ".github/workflows/shared/opencode-ci.md", ".github/workflows/work-router.yml", "scripts/compile-agent-workflows.mjs", "opencode.ci.json"];
+export declare const packageOwnedTargets: readonly [".github/actions", ".github/workflows/agent-*.md", ".github/workflows/shared/platform-defaults.md", ".github/workflows/shared/opencode-ci.md", ".github/workflows/work-router.yml", "scripts/compile-agent-workflows.mjs", "opencode.ci.json", "docs/diagrams.md"];
 export interface MandatoryFile {
     readonly source: string;
     readonly target: string;

package/dist/workflow-catalog.js

@@ -24,6 +24,7 @@ export const packageOwnedTargets = [
     ".github/workflows/work-router.yml",
     "scripts/compile-agent-workflows.mjs",
     "opencode.ci.json",
+    "docs/diagrams.md",
 ];
 export const mandatoryFiles = [
     { source: "templates/opencode/opencode.ci.json", target: "opencode.ci.json" },

package/loops/docs/diagrams.md

@@ -0,0 +1,659 @@
+---
+# Managed by @plainconceptsplatform/workflows. Source: loops/docs/diagrams.md. Update with workflows update --force; consumer edits may be overwritten.
+---
+# Diagrams
+
+One picture per route, plus the router that chooses between them.
+
+These used to live at the bottom of each worker's markdown file. Everything below a worker's
+frontmatter is the prompt, so each diagram was sent to the model on every run and then explicitly
+skipped by a closing instruction telling it to ignore the section. They were about 240 lines across
+the eight workers, and in the release worker's case 21 of its 48 prompt lines. They are documentation
+for people, so they live here, and `verify-route-matrix.sh` fails if one reappears in a prompt.
+
+Every diagram uses the same shapes and the same palette, so reading one teaches you the rest:
+
+| Shape | Means |
+|---|---|
+| Rounded, indigo | a job that does something |
+| Square, amber | a decision the workflow or the agent makes |
+| Doubled circle, green | a terminal state that made progress |
+| Doubled circle, red | a terminal state that needs a person |
+| Doubled circle, dark | nothing to do, the run ends idle |
+| Dotted arrow | the unhappy path |
+
+Each worker diagram also names the rung each stage sits on, from the determinism ladder in
+`skills/workflow-author`: the lower the rung, the cheaper and more reproducible the decision.
+
+---
+
+## The router
+
+Every trigger the repository has arrives here, and exactly one thing happens per event. Nothing
+else in the system subscribes to a public event, which is what makes a route addable or removable
+without touching the others.
+
+```mermaid
+flowchart TD
+    ev{"One GitHub event"} --> classify
+    classify["classify (rung 1)<br/>pure shell, no network<br/>one event in, one route out"] --> authorize
+    authorize{"authorize (rung 1)<br/>Write permission, and is the<br/>actor one of the org's own?"}
+    authorize -->|"human, trusted"| work
+    authorize -->|"outside collaborator"| triageOnly
+    authorize -.->|"no permission"| idle
+    work{"route"} -->|refine| wRefine
+    work -->|implement| wImpl
+    work -->|apply-review| wReview
+    work -->|merge-gate| wGate
+    work -->|audit| wAudit
+    work -->|release| wRelease
+    triageOnly("dispatch-triage<br/>re-enters as the App, so the<br/>worker sees a trusted actor") --> wTriage
+    wRefine("agent-refine")
+    wImpl("agent-implement")
+    wReview("agent-apply-review")
+    wGate("agent-merge-gate<br/>one lock for the whole repo")
+    wAudit("agent-audit")
+    wRelease("agent-release")
+    wTriage("agent-triage")
+    classify -.->|"cron or dispatch"| plumbing
+    plumbing["deterministic jobs<br/>no model runs in any of these"] --> pJobs
+    pJobs("bot-approve · audit-close<br/>cleanup-artifacts · validate<br/>reconcile-bot-pr-runs · detect-pr-conflicts")
+    idle(("Idle<br/>run ends, ~10s, every job skipped"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    class ev start
+    class classify,triageOnly,plumbing,pJobs,wRefine,wImpl,wReview,wGate,wAudit,wRelease,wTriage action
+    class authorize,work decision
+    class idle idle
+```
+
+A run still appears for every matching event even when the router decides nothing downstream
+happens; those cost about ten seconds with every job skipped. Reducing the count means generating
+fewer events, not adding more guards.
+
+### How the routes chain
+
+```mermaid
+flowchart LR
+    open("Issue opened") --> triage
+    triage{"triage<br/>outside collaborator"} -->|pass| refine
+    triage -.->|block| closed(("Closed"))
+    triage -.->|needs-info| author("Author replies") --> triage
+    write("Write+ user<br/>self-labels") --> refine
+    refine{"refine<br/>estimate in points"} -->|"5 or less"| implement
+    refine -->|"8 or more"| split("Split into children") --> refine
+    refine -.->|questions| author
+    implement("implement<br/>branch, PR, closes the issue") --> ci("CI")
+    ci --> gate{"merge-gate"}
+    gate -->|merge| merged(("Merged"))
+    gate -.->|"CI failed"| fix("Fix, push, CI again") --> gate
+    gate -.->|"risk or protected"| human(("Human review"))
+    review("Someone reviews the PR") --> applyReview("apply-review") --> ci
+    audit("audit, weekly") -->|"files one issue"| refine
+
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    class open,write,review,audit start
+    class refine,split,implement,ci,fix,applyReview,author action
+    class triage,gate decision
+    class human,closed failure
+    class merged success
+```
+
+Audit creates work rather than consuming it, and files into `refine` rather than straight to
+`implement`, so a report of several unrelated findings becomes one properly sized issue per finding
+instead of one pull request that has to fix them all.
+
+---
+
+## agent-triage.md
+
+The front door for issues opened from outside the organisation. The gate is membership, not permission
+level: an org member with write skips triage and self-labels into the pipeline, while an outside
+collaborator goes through it even when they hold write.
+
+Four outcomes, and only one of them closes anything. `needs-maintainer` is the one worth knowing: the
+request is legitimate but addressed to the wrong intake, so the issue stays open with `review` and a
+maintainer takes it on by adding `refine`.
+
+```mermaid
+flowchart TD
+    triStart("Work Router<br/>triage route") --> triPick
+    triPick{"Opened by an<br/>outside collaborator?"} -->|yes| triReserve
+    triPick -.->|"no, write+ user"| triIdle
+    triReserve("Reserve (rung 4)<br/>bot-working + triage") --> triFacts
+    triFacts("Facts (rung 3)<br/>Issue, comments and every open<br/>issue written to disk") --> triRound
+    triRound["Round N of 3<br/>counted from the markers<br/>already on the issue"] --> triAgent
+    triAgent("Agent (rung 5)<br/>10 checks: template, security, size,<br/>danger, duplicates, clarity, repro,<br/>acceptance, cross-cutting, product scope") --> triValidate
+    triValidate{"Outcome valid?"} -->|yes| triOutcome
+    triValidate -.->|no| triIncomplete
+    triOutcome{"Verdict"} -->|pass| triPass
+    triOutcome -->|needs-info| triReview
+    triOutcome -->|needs-maintainer| triMaintainer
+    triOutcome -->|block| triBlocked
+    triRound -.->|"round 3: needs-info<br/>is no longer allowed"| triAgent
+    triPass(("Passed<br/>refine added, triage removed<br/>enters the pipeline, no human"))
+    triReview(("Needs info<br/>questions posted, review added<br/>triage kept, so a reply re-runs it"))
+    triReview -->|"author or write+ replies<br/>re-enters via the router"| triStart
+    triMaintainer(("Needs a maintainer<br/>out of product-owner scope, so it stays<br/>OPEN with review; triage removed.<br/>Add refine to take it on"))
+    triBlocked(("Blocked<br/>cannot be done, unsafe, or still<br/>ambiguous: closed with a reason"))
+    triIdle(("Idle<br/>write+ user, skipped"))
+    triIncomplete(("Incomplete<br/>review added, label kept for a retry"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class triStart start
+    class triReserve,triFacts,triAgent action
+    class triPick,triRound,triValidate,triOutcome decision
+    class triIdle idle
+    class triIncomplete,triBlocked failure
+    class triPass,triReview,triMaintainer success
+```
+
+---
+
+## agent-refine.md
+
+Decides the size of the work, which is the decision that determines whether it ever lands. An
+estimate of 8 or more is split into children of 5 or less, and each child walks the pipeline alone.
+The refined story is wrapped in the repository's own issue form, and when questions remain the
+worker leaves a temporal draft on the issue and asks everything in one batched comment.
+
+```mermaid
+flowchart TD
+    refStart("Work Router<br/>refine route") --> refReserve
+    refReserve("Reserve (rung 4)<br/>bot-working") --> refFacts
+    refFacts("Facts (rung 3)<br/>Issue and comments to disk") --> refExplore
+    refExplore("Explore (rung 5)<br/>one work unit at a time,<br/>self-answer from the code,<br/>at most 5 questions each") --> refClassify
+    refClassify{"Trivial?<br/>every TRIVIAL_CRITERIA<br/>condition holds"}
+    refClassify -->|yes| refTrivial
+    refClassify -->|no| refStory
+    refTrivial("Trivial plan<br/>marker, summary, checklist<br/>no Gherkin, no diagram") --> refEstimate
+    refStory("Story<br/>Given/When/Then per work unit,<br/>grounded in the code") --> refWrap
+    refStory -.->|"cannot ground it"| refFail
+    refWrap("Wrap<br/>story into the repository's<br/>own issue form") --> refProse
+    refProse("Prose<br/>@humanizer over the final text") --> refEstimate
+    refEstimate["Estimate<br/>Fibonacci, against ESTIMATE_BANDS"] --> refSplit
+    refSplit{"8 or more?"}
+    refSplit -->|no| refOutcome
+    refSplit -->|"yes, and it splits"| refChildren
+    refSplit -->|"yes, indivisible"| refOutcome
+    refChildren(("Split<br/>2-6 children, each 5 or less<br/>parent becomes their tracker"))
+    refOutcome{"Questions left<br/>for the author?"}
+    refOutcome -->|no| refDone
+    refOutcome -->|yes| refAsk
+    refDone(("Refined<br/>estimate recorded, implement added"))
+    refAsk(("Questions<br/>temporal draft on the issue,<br/>one batched comment,<br/>review added"))
+    refAsk -->|"author replies<br/>re-enters via the router"| refStart
+    refFail(("Incomplete<br/>refine label kept for a retry"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class refStart start
+    class refReserve,refFacts,refExplore,refTrivial,refStory,refWrap,refProse action
+    class refClassify,refEstimate,refSplit,refOutcome decision
+    class refFail failure
+    class refDone,refAsk,refChildren success
+```
+
+---
+
+## agent-implement.md
+
+Writes the code and opens one pull request. It stops there: the merge decision belongs to the gate,
+because waiting for CI inside this run would hold a fleet machine doing nothing.
+
+```mermaid
+flowchart TD
+    implStart("Work Router<br/>implement route<br/>router already confirmed<br/>no open PR for this issue") --> implEligible
+    implEligible{"eligibility (rung 4)<br/>Issue still open?<br/>Not labelled future?"}
+    implEligible -.->|no| implIdle
+    implEligible -->|yes| implReserve
+    implReserve("Reserve (rung 4)<br/>bot-working") --> implFacts
+    implFacts("Facts (rung 3)<br/>Issue and comments to disk") --> implCheck
+    implCheck{"Trivial marker<br/>left by refine?"}
+    implCheck -->|yes| implTodos
+    implCheck -->|no| implCode
+    implTodos("Direct path<br/>one todo per checklist item") --> implVerify
+    implCode("Standard path<br/>the pc-plan-goal pipeline:<br/>explore, propose, apply, verify,<br/>archive; skips ahead when the<br/>issue is already refined") --> implVerify
+    implVerify{"Verify<br/>scoped to the changed files,<br/>because a whole-repo run<br/>gets OOM-killed"}
+    implVerify -.->|fails| implCode
+    implVerify -->|passes| implPr
+    implPr("create_pull_request<br/>one safe output, complete first time") --> implHandoff
+    implPr -.->|"run died"| implRetry
+    implRetry{"Died under 6 minutes<br/>with no answer?"}
+    implRetry -->|"yes: provider outage"| implAgain(("Retry<br/>attempt N of 5, label kept"))
+    implRetry -.->|"no: it answered, wrongly"| implFail
+    implAgain -->|"re-enters via the router"| implStart
+    implHandoff(("Handed off<br/>PR open, bot-working removed,<br/>the gate decides next"))
+    implIdle(("Idle<br/>closed, or held by future"))
+    implFail(("Parked<br/>review added, a rerun<br/>would fail the same way"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class implStart start
+    class implReserve,implFacts,implTodos,implCode,implPr action
+    class implEligible,implCheck,implVerify,implRetry decision
+    class implIdle idle
+    class implFail failure
+    class implHandoff,implAgain success
+```
+
+The retry belt exists because a provider outage kills a run in a couple of minutes with no answer,
+and that used to burn the issue and hand it to a human. A run that worked for half an hour and then
+failed produced an answer that was wrong; repeating it costs the whole fleet the same half hour to
+be wrong again, so only the short deaths are retried.
+
+---
+
+## agent-merge-gate.md
+
+The only worker that merges. It runs one at a time for the whole repository, because several
+overnight pull requests mean every merge moves the default branch under the rest.
+
+```mermaid
+flowchart TD
+    gateStart("Work Router<br/>merge-gate route<br/>CI reported, or the hourly<br/>reconcile belt dispatched it") --> gateSubject
+    gateSubject{"subject (rung 4)<br/>Our open PR?<br/>Closes an implement issue?"}
+    gateSubject -.->|no| gateIdle
+    gateSubject -->|yes| gateBranch
+    gateBranch("Check out the PR branch<br/>the push is fast-forward only,<br/>so never rebase") --> gateFacts
+    gateFacts("Facts (rung 3)<br/>Diff, PR shape, failing CI logs") --> gateCi
+    gateCi{"What did CI conclude?"}
+    gateCi -->|success| gateProtected
+    gateCi -->|failure| gateFix
+    gateFix("Repair<br/>read the failure, fix, verify.<br/>Empty evidence on a conflicting<br/>PR means the conflict is the fault") --> gatePush
+    gatePush(("Pushed<br/>CI runs again, gate re-enters"))
+    gateFix -.->|"cannot fix"| gateHuman
+    gateProtected{"protected_changes (rung 4b)<br/>blast radius from paths,<br/>CODEOWNERS and diff shape"}
+    gateProtected -.->|"protected path"| gateOwner
+    gateProtected -->|"measured low, medium or high"| gateAssess
+    gateAssess("Agent (rung 5)<br/>find defects, verify them,<br/>rate recoverability") --> gateDisposition
+    gateDisposition{"Disposition<br/>computed in shell from<br/>the facts and the report"}
+    gateDisposition -->|"no verified blocker,<br/>radius low or recoverable medium"| gateMerge
+    gateDisposition -.->|"radius high, protected<br/>or owner path"| gateOwner
+    gateDisposition -.->|"fragile, unmet criteria<br/>or low confidence"| gateHuman
+    gateDisposition -.->|"CI red or a verified<br/>high finding"| gateBlocked
+    gateMerge(("AUTO-MERGE<br/>squash, issue closed,<br/>pr-pending removed"))
+    gateHuman(("HUMAN REVIEW<br/>review label,<br/>implement label kept"))
+    gateOwner(("OWNER REVIEW<br/>review + owner-review,<br/>CODEOWNERS asked when named"))
+    gateBlocked(("BLOCKED<br/>review + blocked,<br/>the belt does not retry"))
+    gateIdle(("Idle<br/>not ours, or not open"))
+    gateFix -.->|"attempt 6 of 6"| gateBlocked
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class gateStart start
+    class gateBranch,gateFacts,gateFix,gateAssess action
+    class gateSubject,gateCi,gateProtected,gateDisposition decision
+    class gateIdle idle
+    class gateHuman,gateOwner,gateBlocked failure
+    class gateMerge,gatePush success
+```
+
+A protected-path match holds the merge but does not stop the repair path: the agent may still fix
+failed CI on those files, and `conclude` is what refuses to merge them.
+
+The agent does not pick the disposition. It reports what it found and what it verified; the
+validator computes the outcome from that report and from the blast radius measured before the
+agent ran. A category the diff touches is no longer, on its own, a reason to park a pull request:
+only a verified high or critical finding, a sensitive path, or a change that would be hard to undo
+sends it to a person.
+
+---
+
+## agent-apply-review.md
+
+Applies a reviewer's feedback to a pull request the bot already opened, and pushes to the same
+branch.
+
+```mermaid
+flowchart TD
+    fbStart("Work Router<br/>apply-review route<br/>review or comment on a bot PR") --> fbSubject
+    fbSubject{"subject (rung 4)<br/>Our open PR?<br/>Reviewer has write?"}
+    fbSubject -.->|no| fbIdle
+    fbSubject -->|yes| fbFacts
+    fbFacts("Facts (rung 3)<br/>Every thread with its resolved state,<br/>every inline comment, the diff") --> fbTriage
+    fbTriage{"Anything actionable<br/>and still outstanding?<br/>Account for every PRRT_ id"}
+    fbTriage -.->|"nothing, or all addressed"| fbSatisfied
+    fbTriage -->|yes| fbApply
+    fbApply("Apply<br/>only what the feedback justifies:<br/>a comment is not licence to refactor") --> fbVerify
+    fbVerify{"Verify<br/>scoped to the changed files"}
+    fbVerify -.->|fails| fbApply
+    fbVerify -->|passes| fbPush
+    fbApply -.->|"ambiguous or unsafe"| fbHuman
+    fbPush(("Implemented<br/>pushed to the same branch,<br/>CI runs, the gate re-enters"))
+    fbSatisfied(("Already satisfied<br/>nothing pushed, the reviewer<br/>has to confirm"))
+    fbHuman(("Needs a human<br/>review added"))
+    fbIdle(("Idle<br/>not ours, or not a write reviewer"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class fbStart start
+    class fbFacts,fbApply action
+    class fbSubject,fbTriage,fbVerify decision
+    class fbIdle idle
+    class fbHuman failure
+    class fbPush,fbSatisfied success
+```
+
+A reviewer often makes one point across several comments, so the whole conversation is on disk
+before anything changes. Applying them one at a time produces contradictory commits.
+
+---
+
+## agent-audit.md
+
+The only worker that creates work rather than consuming it. Read-only: it files an issue and
+changes nothing.
+
+```mermaid
+flowchart TD
+    auStart("Work Router<br/>audit route<br/>weekly cron, or dispatch") --> auBack
+    auBack{"Backpressure (rung 1)<br/>Fewer than 3 open reports?"}
+    auBack -.->|no| auIdle
+    auBack -->|yes| auFacts
+    auFacts("Facts (rung 3)<br/>Every open issue's title<br/>and labels to disk") --> auRun
+    auRun("Audit (rung 5)<br/>/repo-audit over AUDIT_FOCUS,<br/>read-only throughout") --> auFilter
+    auFilter{"Each finding: specific,<br/>reproducible, real impact,<br/>fixable without more digging?"}
+    auFilter -->|keeps some| auScore
+    auFilter -.->|keeps none| auQuiet
+    auScore("Score 1-10<br/>severity, likelihood, blast radius") --> auDedupe
+    auDedupe{"Already tracked, or<br/>previously rejected?"}
+    auDedupe -.->|"all of them"| auQuiet
+    auDedupe -->|"some are new"| auFile
+    auFile("One issue: every finding,<br/>top 3 refined into stories") --> auReport
+    auReport(("Filed<br/>labelled refine, so it gets<br/>sized and split per finding"))
+    auQuiet(("Nothing to file<br/>the right outcome on a<br/>clean codebase"))
+    auIdle(("Idle<br/>backlog already full"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class auStart start
+    class auFacts,auRun,auScore,auFile action
+    class auBack,auFilter,auDedupe decision
+    class auIdle idle
+    class auReport,auQuiet success
+```
+
+Memory matters here: open issues only cover what is still open, so a finding reported weeks ago and
+consciously not acted on would come back every single run. The audit records its dispositions and
+reads them next time.
+
+---
+
+## agent-release.md
+
+Manual dispatch only. The agent writes prose; a deterministic job does everything irreversible.
+
+```mermaid
+flowchart TD
+    relStart("Work Router<br/>release route<br/>operation=release") --> relFacts
+    relFacts("Facts (rung 3)<br/>Commit log since the last tag<br/>and the current version, to disk") --> relAgent
+    relAgent("Agent (rung 5)<br/>Categorise by conventional-commit<br/>prefix, write release-notes.md.<br/>The only judgement in this route") --> relNoop
+    relNoop("noop<br/>the agent writes a file,<br/>not a GitHub object") --> relConclude
+    relConclude["conclude (rung 6)<br/>Bump: BREAKING is major,<br/>feat is minor, else patch"] --> relPush
+    relPush("Commit, tag, push,<br/>create the GitHub Release") --> relDone
+    relConclude -.->|fails| relFail
+    relDone(("Released<br/>tag and Release published"))
+    relFail(("Failed<br/>no tag created, nothing partial"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class relStart start
+    class relFacts,relAgent,relNoop,relPush action
+    class relConclude decision
+    class relFail failure
+    class relDone success
+```
+
+The version bump, the tag and the Release are deterministic on purpose. The agent's only output is
+a file on disk, so a confused model cannot publish a release.
+
+
+---
+
+## agent-visual-verify.md
+
+Runs after the merge gate decides auto-merge and before the merge itself. The agent reads the
+change, writes a verification plan as JSON waypoints, and a post-agent shell step drives
+agent-browser to capture screenshots at each waypoint. A final step attaches the screenshots
+to the linked issue as a comment. Failures never block the merge.
+
+```mermaid
+flowchart TD
+    vvStart("Merge Gate<br/>auto-merge verdict") --> vvSubject
+    vvSubject{"subject (rung 4)<br/>PR open? Visual<br/>verify enabled?"}
+    vvSubject -.->|"no"| vvIdle
+    vvSubject -->|"yes"| vvActivation
+    vvActivation("Activation (rung 3)<br/>Checkout, load issue context,<br/>build the prompt") --> vvAgent
+    vvAgent("Agent (rung 5)<br/>Explore the change, write<br/>plan.json with waypoints<br/>(url + selector per step)") --> vvBuild
+    vvBuild("Build and start app<br/>VISUAL_VERIFY_BUILD_COMMAND,<br/>then VISUAL_VERIFY_START_COMMAND<br/>on the configured port") --> vvAppUp{"App up on<br/>the port?"}
+    vvAppUp -.->|"no"| vvWarn
+    vvAppUp -->|"yes"| vvCapture
+    vvCapture["Capture screenshots<br/>agent-browser opens each waypoint,<br/>waits for selectors,<br/>screenshot --full --no-sandbox"] --> vvGotShots{"Any captured?"}
+    vvGotShots -->|"yes"| vvAttach
+    vvGotShots -.->|"no, all failed"| vvWarn
+    vvAttach("Attach to issue<br/>post plan + screenshots<br/>as a single comment") --> vvDone
+    vvDone(("Screenshots posted<br/>visual evidence on the issue"))
+    vvWarn(("Warning posted<br/>no screenshots, merge proceeds"))
+    vvIdle(("Idle<br/>not enabled or not our PR"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef idle fill:#202c40,stroke:#738198,stroke-width:2px,color:#ffffff
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class vvStart start
+    class vvActivation,vvAgent,vvBuild,vvCapture,vvAttach action
+    class vvSubject,vvAppUp,vvGotShots decision
+    class vvIdle idle
+    class vvWarn failure
+    class vvDone success
+```
+
+The agent does not take screenshots itself. It writes a plan; a shell step runs agent-browser
+against the running app. Chromium needs --no-sandbox on CI runners (set via
+AGENT_BROWSER_ARGS), and the explicit apt-get install covers libraries gent-browser
+install --with-deps misses on ubuntu-24.04.
+
+---
+
+## housekeeping
+
+Not a worker: a deterministic job in the router, on its own six-hourly cron, with no model. It is
+the answer to a specific measured problem. Across the four consumers, 58 of 237 issues closed since
+1 August were closed by the bot; autonomy ran between 6% and 50%. The gap was not bad decisions, it
+was silence — work that stopped and told nobody, and state that nothing ever cleaned up.
+
+The one rule that shapes it: **retry a failure, report a decision.** A crash, a timeout or an empty
+output is a machine failure, and the worker marks it `stalled`; those are worth running again. A
+triage `needs-maintainer`, a refine `questions` or a merge-gate `review` is a verdict the agent
+reached on purpose, and running it again just reproduces it.
+
+```mermaid
+flowchart TB
+    hkCron("cron 23 */6 * * *") --> hkScan("List open issues,<br/>pull requests and branches")
+    hkScan --> hkPark{"Issue carries<br/>review?"}
+    hkPark -.->|no| hkStrand
+    hkPark -->|yes| hkWhy{"and stalled?"}
+    hkWhy -.->|"no: a decision"| hkDigest
+    hkWhy -->|"yes: a machine failure"| hkBudget{"waited 6h,<br/>under 3 tries?"}
+    hkBudget -.->|"budget spent"| hkDigest
+    hkBudget -->|yes| hkRetry("Comment the attempt,<br/>drop review and stalled,<br/>dispatch the work route")
+    hkRetry --> hkStrand
+
+    hkStrand("Strands: drop pr-pending<br/>where no open PR closes the issue") --> hkParent("Close a split parent<br/>once every child is closed")
+    hkParent --> hkBranch{"Branch whose PRs<br/>are all finished<br/>and all bot-authored?"}
+    hkBranch -->|yes| hkDelete("Delete the branch")
+    hkBranch -.->|"open PR, human PR,<br/>or the default branch"| hkDigest
+    hkDelete --> hkDigest
+    hkDigest("Rewrite one issue:<br/>Needs a human") --> hkEnd
+    hkEnd(("One place to look<br/>instead of four repos"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    class hkCron start
+    class hkScan,hkRetry,hkStrand,hkParent,hkDelete,hkDigest action
+    class hkPark,hkWhy,hkBudget,hkBranch decision
+    class hkEnd success
+```
+
+Three things make it safe to leave running unattended. It uses the App token, because GitHub starts
+no workflow run from an event raised with `GITHUB_TOKEN`, so with the default token every retry
+would be a green no-op. Every write goes through one `act()` wrapper, which is the only place
+`dry-run` is read, so there is no second path that forgets to check it. And it closes exactly two
+kinds of issue — a split parent whose children are all done, and its own digest — which the route
+matrix asserts by counting.
+
+---
+
+## agentics-app-errors
+
+An optional template, installed only where there is an Application Insights resource to read, and
+the mirror image of `agentics-error-report` below it. That one carries a *workflow* failure out of a
+private consumer into the public package, so it is built to send almost nothing. This one reads the
+*application's* own exceptions, and they are the private repository's own business: the issue is
+filed beside the code that threw it and nothing travels anywhere.
+
+It runs no model, for the reason that one does not: a model asked to summarise a stack trace
+paraphrases it, and a paraphrased stack trace is a wrong issue that costs somebody an afternoon. The
+agent work happens afterwards, on the belt, because the issue is labelled `bug` + `refine` and that
+is the same handoff the audit already uses.
+
+```mermaid
+flowchart TB
+    aeCron("cron 41 7 * * *") --> aeConfig{"infra/&lt;env&gt;.env<br/>present?"}
+    aeConfig -.->|no| aeIdle(("Job summary only<br/>warning, not a red run"))
+    aeConfig -->|yes| aeLogin("azure/login, OIDC<br/>on the matching Environment")
+    aeLogin --> aeQuery("AppExceptions, one table,<br/>grouped by ProblemId,<br/>sum(ItemCount) for sampling")
+    aeQuery --> aeFloor{"Above the floor,<br/>and any slot left<br/>under the ceiling?"}
+    aeFloor -.->|no| aeDefer("Named in the summary,<br/>picked up tomorrow")
+    aeFloor -->|yes| aeScrub("Mask GUIDs, emails,<br/>paths, query strings")
+    aeScrub --> aeFields{"Every field on<br/>the allowlist?"}
+    aeFields -.->|"no: the module changed"| aeStop(("Nothing filed<br/>run goes red"))
+    aeFields -->|yes| aeScan{"Leak scanner:<br/>a GUID, a secret,<br/>a path, an address?"}
+    aeScan -.->|"this one trips"| aeWithhold("Withheld, the others<br/>still filed, run goes red")
+    aeScan -->|clean| aeSeen{"Filed before?"}
+    aeSeen -.->|"closed and accepted"| aeLeave(("Left alone, for good"))
+    aeSeen -->|"open"| aeNote("A dated line added")
+    aeSeen -->|"closed, not accepted"| aeReopen("Reopened: it came back")
+    aeSeen -->|"never"| aeFile("New issue,<br/>bug + refine + app-error")
+    aeFile --> aeBelt(("On to refine"))
+    aeNote --> aeBelt
+    aeReopen --> aeBelt
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    classDef idle fill:#f4f4f6,stroke:#5b5b66,stroke-width:2px,color:#2b2b33
+    class aeCron start
+    class aeLogin,aeQuery,aeScrub,aeNote,aeReopen,aeFile,aeDefer action
+    class aeConfig,aeFloor,aeFields,aeScan,aeSeen decision
+    class aeStop,aeWithhold failure
+    class aeBelt success
+    class aeIdle,aeLeave idle
+```
+
+Two failures, handled two different ways, and the difference is the point. A field nobody agreed to
+publish means the module changed and the new field is probably on every finding, so nothing is filed
+at all. A body that still trips the scanner after scrubbing is one unlucky row: that report is
+withheld and the rest are filed, because one bad operation name must never mean the belt stops
+hearing about anything. Both turn the run red.
+
+Scrubbing comes before scanning for the same reason. Masking a GUID keeps the job alive where
+refusing over one would have left it red every morning and filing nothing, which is how a workflow
+gets switched off. The scanner is the backstop for whatever the masks missed, not the first line.
+
+The route matrix asserts the query names one table and only inside the query itself, that counts are
+summed rather than counted, that the reportable field set has not grown a run id, that the scrubs and
+the scanner both still exist, that both `setFailed` paths are intact, and that no model has appeared.
+Every one was mutation-tested. Four of the first drafts used the file's own `count()` helper inside
+an `if`, and since that helper is `grep || true` those guards were true whatever they found: they
+failed open, which is the exact bug this section exists to catch.
+
+---
+
+## agentics-error-report
+
+An optional template, installed everywhere, and the only job in the fleet that sends anything out of
+the repository it runs in. Every consumer is private, so that is the whole design constraint.
+
+What crosses the boundary is a fixed, enumerable set of facts about workflows **this package ships**:
+their file names, their job and step names, a conclusion, a runner label, a count, and the id of a
+matched entry from a catalogue of sixteen known failure shapes. What never crosses it is free text
+of any kind — no log line, no branch name, no issue title, no path, no URL, no number that could be
+looked up. Hence no model: a model asked to summarise a failure paraphrases whatever the log held.
+
+```mermaid
+flowchart TB
+    erCron("cron 11 7 * * *") --> erRuns("List this repo's runs<br/>from the last 24h")
+    erRuns --> erOwned{"Is the workflow one<br/>this package ships?"}
+    erOwned -.->|"no: the name could describe<br/>a product or a customer"| erCount("Counted, never inspected")
+    erOwned -->|yes| erState{"Failed, or queued<br/>past 45 minutes?"}
+    erState -.->|neither| erCount
+    erState -->|yes| erClassify("Read the log tail,<br/>match the catalogue,<br/>keep only the matched id")
+    erClassify --> erBody("Build the report from<br/>package-owned names,<br/>a conclusion and a count")
+    erBody --> erScan{"Leak scanner:<br/>repo or owner name, a URL,<br/>an email, a path, a token,<br/>an issue number, a ref?"}
+    erScan -.->|"anything matches"| erWithhold(("Withheld<br/>nothing filed, run goes red"))
+    erScan -->|clean| erToken{"Upstream token<br/>available?"}
+    erToken -.->|no| erSummary(("Job summary only<br/>warning, not a red run"))
+    erToken -->|yes| erFile("One upstream issue<br/>per signature, appended<br/>rather than repeated")
+    erFile --> erDone(("Filed upstream"))
+
+    classDef start fill:#ffffff,stroke:#172033,stroke-width:2px,color:#172033
+    classDef action fill:#eef0ff,stroke:#554cff,stroke-width:2px,color:#172033
+    classDef decision fill:#fff8e8,stroke:#c75b00,stroke-width:2px,color:#172033
+    classDef failure fill:#fff0f0,stroke:#ef2929,stroke-width:2px,color:#8b1a1a
+    classDef success fill:#e8f8ec,stroke:#18883c,stroke-width:2px,color:#145a32
+    classDef idle fill:#f4f4f6,stroke:#5b5b66,stroke-width:2px,color:#2b2b33
+    class erCron start
+    class erRuns,erClassify,erBody,erFile,erCount action
+    class erOwned,erState,erScan,erToken decision
+    class erWithhold failure
+    class erDone success
+    class erSummary idle
+```
+
+The scanner fails closed, and its failure is loud: a report it flags is not filed and the run goes
+red, so the field that carried private text gets fixed rather than leaking again the next morning.
+The route matrix asserts the scanner exists, that both exit paths call `setFailed`, that there are
+at least as many scans as upstream writes, that each individual check is still present, and that no
+model or `OPENAI_API_KEY` has appeared in the action. Every one of those was mutation-tested; three
+earlier versions of them passed against a deliberately broken guard and were rewritten.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plainconceptsplatform/workflows",
-  "version": "0.28.9",
+  "version": "0.28.11",
   "description": "Install and update Platform GitHub agentic workflows.",
   "keywords": [
     "github-actions",