@hybridlabor-api/aos 4.13.2 → 4.14.0

package/skills/global_config/factory-lookback/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: factory-lookback
+description: >-
+  Experimental workflow for auditing recurring feedback, telemetry, errors,
+  and brittle delivery paths to find systemic fixes. Use for periodic or
+  requested cross-source lookbacks, not routine single-item intake.
+category: engineering-method
+source: BuilderIO/skills
+---
+
+# Factory Lookback
+
+Read `.agent-factory/config.yaml` and apply the optional
+`skill_prompts.factory-lookback` entry as additional project guidance. Use this
+workflow when asked to look back across a bounded period or when an enabled
+`workflows.lookback` automation runs. Its purpose is to find patterns that
+normal item-by-item flows keep missing or fixing only temporarily.
+
+## Build a bounded evidence set
+
+1. Confirm the configured sources, scope, time window, comparison period, and
+   output policy before querying. Use only connected sources the host can read.
+2. Enumerate the full configured range, follow every page or cursor, and record
+   source filters, dates, counts, and unavailable or truncated sources. Do not
+   report a complete lookback when coverage is partial.
+3. Include relevant feedback, analytics or telemetry, runtime errors,
+   recurring CI or review failures, repeated recovery attempts, replies to
+   earlier information requests, and prior fixes marked shipped or verified
+   when those records are available.
+4. Cluster records by underlying symptom and affected boundary, not wording
+   alone. Keep event counts, affected users or sessions, time range, versions,
+   and distinct source links separate; do not infer identity or impact from
+   unstable identifiers.
+
+## Find the systemic cause
+
+For each recurring cluster, trace representative reports to their original
+source and inspect prior dispositions, commits, tests, and release evidence.
+Check whether the symptom recurred after a claimed fix, appeared through a
+sibling caller, or escaped because the normal workflow lacked a signal, owner,
+verification step, or recovery path.
+
+For a report previously held for more information, inspect the full source
+thread for new replies. Re-triage the original report with the new details and
+check whether the normal fix flow now has enough evidence to proceed. Keep the
+item open when the answer is still incomplete; do not treat a reply as a fix or
+as permission for another action.
+
+Reproduce a representative current case when possible. Trace related callers
+and surfaces to the shared boundary that can explain the evidence. Prefer one
+verified correction at that boundary over a pile of caller-specific patches.
+Separate confirmed causes from hypotheses, and state what evidence would
+disprove each proposed explanation.
+
+## Change and verify
+
+Recommend only by default. Prepare a fix locally only when `workflows.lookback.implement` allows it and the user asked for it in this conversation; publishing needs the user's GO. A recurring pattern is evidence for
+investigation, not automatic permission to edit code or take an external
+action. Keep reply, issue closure, PR approval, merge, deployment, and
+notification under their own configured policies.
+
+When implementation is allowed, make the smallest systemic fix that addresses
+the confirmed cause. Add or update a regression check at the boundary, exercise
+the representative failure and relevant sibling paths, and inspect the same
+signals again after the fix. A test, merge, or “fixed” label alone does not
+prove that the live recurrence stopped.
+
+## Report
+
+For each pattern, report:
+
+- the source links, date range, query coverage, counts, and impact evidence;
+- prior fixes or dispositions and whether the symptom returned;
+- information requests, answers received, and whether they changed the
+  evidence or next step;
+- confirmed cause, alternatives still uncertain, and the shared boundary;
+- recommended or completed systemic change, regression proof, and remaining
+  rollout or live-verification work;
+- independent reply, close, publish, approval, merge, deployment, and notify
+  decisions, plus any exact human decision required.
+
+Do not treat unavailable telemetry or an incomplete history as evidence that a
+pattern does not exist.
+
+## AOS safety rules
+
+- Configuration lives in `.agent-factory/config.yaml`. If it is missing, stop and
+  ask the user; never create it or guess sources.
+- Nothing in the config can open the AOS GO gate. `git push`, `gh pr merge`,
+  `gh release create` and every external write (reply, comment, approval, close,
+  status change, notification) need the user's literal GO for that exact action.
+  Prepare the change or draft text, show it, and stop.
+- Scheduled or unattended runs are read-only. Report; do not act.
+- Connectors are whatever the host already exposes. Do not install or register
+  integrations or MCP servers.

package/skills/global_config/factory-review-prs/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: factory-review-prs
+description: >-
+  Experimental workflow for reviewing configured repositories' pull requests.
+  Use for manual or scheduled PR triage, approval, or merge decisions.
+category: engineering-method
+source: BuilderIO/skills
+---
+
+# Factory Review PRs
+
+This skill reviews a filtered queue. For one long-lived, explicitly authorized
+PR, use `factory-babysit-pr`. Read the filters and independent action policies
+from `.agent-factory/config.yaml`.
+Apply the optional `skill_prompts.factory-review-prs` entry as additional
+project guidance; it does not replace this skill or authorize an action
+disabled by policy.
+
+## Review the queue
+
+For each candidate PR:
+
+1. Read live state from the configured host. Exclude drafts and PRs outside the
+   configured filters. Skip a PR with a current review unless re-review is
+   requested by policy.
+2. Inspect the diff, linked issues, required checks, review threads, author
+   eligibility, and exact head revision. Treat bot findings as leads and
+   preserve human review direction unless source evidence disproves it.
+3. Report actionable findings with file, line, impact, and a concrete fix. If
+   none exist, record that outcome without inventing a comment.
+
+Unavailable or partial state is unknown, never a clean result.
+
+## Apply separate action gates
+
+| Action | Proceed only when |
+| --- | --- |
+| Review | The PR matches configured filters and has not already had the required current review. |
+| Reply or other PR write | Draft only. Put the exact text in the report; posting needs the user's GO. |
+| Approve | Report whether approval conditions hold on the exact head. Approving needs the user's GO for that PR. |
+| Merge | Report merge readiness only. `gh pr merge` is blocked by the GO gate unless the user sends a literal GO. |
+
+Host-level mergeability, one green check, or a bot approval does not prove all
+gates passed. Re-read the exact head and live state immediately before an
+approval or merge. Restart a configured soak if the head or a gate changes.
+
+## Report
+
+For each PR, state the decision and evidence. List skipped, unavailable, and
+held PRs with the reason. Keep review findings separate from approvals, replies,
+and merge decisions.
+
+## AOS safety rules
+
+- Configuration lives in `.agent-factory/config.yaml`. If it is missing, stop and
+  ask the user; never create it or guess sources.
+- Nothing in the config can open the AOS GO gate. `git push`, `gh pr merge`,
+  `gh release create` and every external write (reply, comment, approval, close,
+  status change, notification) need the user's literal GO for that exact action.
+  Prepare the change or draft text, show it, and stop.
+- Scheduled or unattended runs are read-only. Report; do not act.
+- Connectors are whatever the host already exposes. Do not install or register
+  integrations or MCP servers.

package/skills/global_config/git-pr-review/SKILL.md

@@ -152,6 +152,9 @@ Only if relevant:
 
 ---
 
+## Visual recap
+For a reviewer-friendly page next to the text description, run `/pr-recap` on the same range. It is informational and does not gate the PR. It never posts to GitHub; sharing it is the human's call.
+
 ## Limitations
 
 - Relies on commit message quality; vague commits may reduce accuracy

package/skills/global_config/grilling/SKILL.md

@@ -40,3 +40,5 @@ This is the primitive. Two skills compose it, and neither duplicates it:
 Grilling produces a shared understanding, not a plan. Once the frontier is empty, hand off to whichever pipeline the work actually needs — `/startcycle` for a straight run, `/startcycle-graph` when the durable record and repair loop earn their overhead, `/startcycle-graph-user` for a throwaway fan-out. `/bdbrainstorm` and `/bdbmediastorm` invoke this skill as their own interview step rather than restating it.
 
 **Do not use the `AskUserQuestion` tool for a grilling round.** A round is numbered questions with recommended answers, answered in prose, in whatever order the user likes — several at once, or one with a correction to another. Forcing that into fixed-choice widgets loses exactly the nuance the interview exists to surface.
+
+**When the grilling ends in a written plan,** run `aos-plan-canvas modes` and offer the planning mode before opening it: standard plan-canvas (preselected) or, if detected, the pro planner. Ask every time. See "Planning mode choice" in the `plan-canvas` skill.

package/skills/global_config/mcsc/SKILL.md

@@ -15,7 +15,7 @@ AOS-installed repo — not a Claude-Code-only convenience.
 ## Why this exists
 
 Three separate, harness-specific delegation paths already exist (the Claude
-Code plugins `antigravity:antigravity-delegate`, `opencode:opencode-rescue`,
+Code plugins `antigravity:delegate`, `opencode:opencode-rescue`,
 `codex:codex-rescue` — see AGENTS.md's "Delegating to an external CLI"). Those
 are fine for interactive delegation *from a Claude Code session*, but they are
 Claude-Code-only, and none of them tell agenttrail's live board what is

package/skills/global_config/plan-arbiter/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: plan-arbiter
+description: Use when asked to compare, cross-review, merge, judge, choose, or arbitrate competing plans from multiple agents such as Codex and Claude Code; when given two or more proposed plans, session IDs, transcripts, plan documents, PR descriptions, or pasted strategies; or when the user wants one recommended execution plan after agents review each other's proposals.
+category: bdb-core
+source: BuilderIO/skills
+---
+
+# Plan Arbiter
+
+Turn competing plans into one executable direction. Preserve the best ideas,
+reject weak assumptions, and produce a clear handoff instead of a blended mush.
+
+## Workflow
+
+1. Collect the source plans.
+2. Normalize each plan into comparable claims.
+3. Cross-review the plans against each other and the real codebase or task
+   context.
+4. Choose a winner, merge a better hybrid, or send the plans back for revision.
+5. Produce one execution handoff with verification gates and rejected
+   alternatives.
+
+Planning is read-only unless the user explicitly asks you to implement after the
+decision.
+
+## Collect Source Plans
+
+Accept plans as pasted text, local files, session IDs, transcript paths, PRs,
+comments, visual-plan links, or chat history. Resolve the original artifacts
+when possible so you can see prompt changes and assumptions that may be missing
+from a final summary.
+
+If a plan is still being written and the user asked you to wait, monitor it
+until it is done or blocked. If a plan cannot be resolved, continue with the
+available plan text and mark the missing source as a risk.
+
+## Normalize
+
+For each plan, extract:
+
+- Objective and scope.
+- Key assumptions and unresolved questions.
+- Proposed files, modules, APIs, data shapes, UI states, or workflows.
+- Implementation sequence.
+- Validation strategy.
+- Rollback or migration concerns.
+- Cost, complexity, and expected executor fit.
+
+Do not reward verbosity. Prefer plans that are concrete, grounded in real code,
+and honest about tradeoffs.
+
+## Cross-Review
+
+Review each plan as if another capable agent wrote it:
+
+- Check whether it satisfies the user's actual request.
+- Verify claims against the repo, docs, tests, screenshots, or external systems
+  when those are relevant and available.
+- Identify hidden dependencies, missing tests, risky sequencing, vague steps,
+  unnecessary scope, and hard-to-reverse decisions.
+- Notice complementary strengths: one plan may have the better architecture
+  while another has the better migration or validation path.
+- Separate plan quality from executor preference. A cheaper/faster executor can
+  be the right choice for implementation even when another model produced the
+  best critique.
+
+Use subagents for independent review when the plans are large, the codebase is
+wide, or the decision would benefit from separate technical and product passes.
+
+## Decide
+
+Choose one of three outcomes:
+
+- **Adopt:** pick one plan mostly as written.
+- **Hybrid:** combine specific pieces into a stronger execution plan.
+- **Revise first:** request another planning pass because both plans miss a
+  key constraint or depend on an unresolved decision.
+
+Use this tie-break order:
+
+1. Correctness and fit to the user's request.
+2. Grounding in real files, APIs, tests, data, and UI behavior.
+3. Simpler first implementation that does not block the intended future.
+4. Better validation and rollback story.
+5. Lower token/time cost for execution once quality is acceptable.
+
+## Handoff
+
+Return a compact decision memo:
+
+```md
+Decision
+- Adopt Plan A / Hybrid / Revise first.
+
+Why
+- The deciding evidence and tradeoffs.
+
+Execution Plan
+- Ordered steps with files or surfaces to touch.
+
+Borrowed From Other Plans
+- Useful pieces kept from non-winning plans.
+
+Rejected
+- Ideas intentionally not taking, with reasons.
+
+Verification
+- Tests, browser checks, screenshots, CI, review, or deploy checks needed.
+
+Executor Recommendation
+- Which agent/model should implement and why.
+```
+
+When the user already asked for execution and the chosen path is clear, proceed
+with the selected plan after reporting the decision briefly. Otherwise stop at
+the handoff and ask for approval.
+
+## In AOS
+
+Two planners on two different harnesses make a double plan: one agent writes
+`production_artifacts/00_execution_plan.md`, a second agent (for example Gemini
+via `agy`, or Codex) writes `production_artifacts/00_execution_plan.b.md`. Run
+this skill over both, present the decision memo in `plan-canvas`, and let the
+human approve there. The dispatcher still decides every next step; the arbiter
+never calls another agent itself.

package/skills/global_config/plan-canvas/SKILL.md

@@ -3,7 +3,7 @@ name: plan-canvas
 description: Open plans and HTML artifacts in a local browser canvas where the human annotates elements, chats, and approves or requests changes without leaving the page. Use when presenting a plan for review, or when feedback like "move this, change that" is easier pointed at than typed.
 category: bdb-core
 metadata:
-  version: "1.0.1"
+  version: "1.0.2"
   origin: affaan-m/ECC
   license: MIT
 ---
@@ -69,6 +69,15 @@ aos-plan-canvas open production_artifacts/00_execution_plan.md
 aos-plan-canvas await production_artifacts/00_execution_plan.md
 ```
 
+When starting a new plan, offer the template choice first: `aos-plan-canvas templates`
+prints the available templates as JSON (`id`, `label`, `description`, `useWhen`,
+`hasBoard`; "board" = design canvas with screens + arrows), and `aos-plan-canvas new <template-id> <target-dir> [--mode standard|bdb-plan-builder]`
+copies one into an empty folder (builder mode: `plan.mdx` and `canvas.mdx` if present;
+standard mode: `plan.md`). A non-empty target or an unknown id exits 2. Then fill in
+the example content and `open` the result. The server's `GET /` page is a read-only overview of open reviews, templates and visual skills.
+
+On Builder pages, blocks carry ids like `src-plan.mdx-L42`: an annotation `selector` starting with `#src-plan\.mdx-L42` (CSS-escaped) means "edit `plan.mdx` at line 42" (`canvas.mdx` likewise; headings keep their slug id and carry `data-src` only).
+
 ### Stay listening, or the human talks to an empty chair
 
 Feedback only reaches you while an `await` is actually parked on the session.
@@ -118,8 +127,8 @@ One backstop exists, and it is not an excuse to skip the above:
 **After approve — start the live map (Trigger A).** When the approved artifact
 is a build plan (e.g. `production_artifacts/00_execution_plan.md`) and a
 multi-agent build follows, start the aos-trail live map:
-`aos-trail . --plan production_artifacts/00_execution_plan.md --no-open` — it
-prints a URL (default http://localhost:5330). Inside AO (env var
+`aos-trail --ensure` — it
+prints a URL (default http://localhost:5330). Put the live-map link in your reply (the autostart hook also adds it as context when active). Inside AO (env var
 `AO_BROWSER_CAPABILITY` set) also run `ao preview <url>`. See the `agenttrail`
 skill. Not needed for reviews that are not followed by a build.
 
@@ -150,6 +159,21 @@ if a revision takes more than a minute.
 
 **4. End** when review concludes: `aos-plan-canvas end <file>`.
 
+#### After approval
+
+Once the human approves a `bdb-plan-builder` plan, derive the live map from the same folder (run from the workspace root):
+
+```bash
+aos-plan-canvas trail <plan-dir>        # writes production_artifacts/00_execution_plan.md
+aos-trail . --plan production_artifacts/00_execution_plan.md --no-open
+```
+
+`trail` turns headings tagged `{#id}` and `<Section id title>` into components (`needs` from `<Section needs=[...]>` or frontmatter `needs-<id>: a, b`, `files` from `<ImplementationMap>`, tasks from `<Checklist>`, `url:` from an `<Archify>` whose file lives under `production_artifacts/`). It prints `{out, components, tasks, next_step}`; `--out <file>` must stay inside the workspace, an existing file is never overwritten without `--force`, and a plan with no components exits 2. It starts nothing. Inside an AO session (`AO_BROWSER_CAPABILITY` set), also run `ao preview <url>` with the URL `aos-trail` prints, as the `agenttrail` skill says.
+
+**Prototype hint.** A plan with `web`/`desktop` artboards or screens (or frontmatter `prototype: suggest`) ends with one "Suggested next step" callout naming them and pointing at the `prototype` skill for a throwaway prototype. It is plain text and starts nothing; `prototype: skip` turns it off.
+
+**Archify block.** `<Archify src="00_architecture.html" label="..." height={560} />` embeds a diagram from the `archify` skill (copy its standalone HTML into the plan folder first) in a sandboxed iframe (`allow-scripts` only). `src` is relative to the plan folder and must stay inside it; `..`, absolute paths, symlink escapes, missing files and files over 5 MB show an error card plus a warning.
+
 ## Relationship to `/startcycle`
 
 An `approve` verdict on `production_artifacts/00_execution_plan.md` satisfies
@@ -157,6 +181,15 @@ the **Architect → TechLead gate (step 1 → 2)** of `/startcycle`: it is a hum
 confirmation that the plan is ready for the capability-map review. This is
 optional — the pipeline runs unchanged without it.
 
+## Competing plans (double plan)
+
+When two plans exist for one goal, for example one from Claude Code and one from
+another harness such as Gemini (`agy`) or Codex, run the `plan-arbiter` skill
+over both and open its decision memo here. Keep each plan as its own file
+(`production_artifacts/00_execution_plan.md` and `00_execution_plan.b.md`), open
+the memo with `open`, and let the human pick Adopt, Hybrid or Revise first with
+the verdict. The arbiter never invokes the second agent; the dispatcher does.
+
 ## Diagrams (Mermaid)
 
 When part of the plan is a flow, architecture, sequence, state machine, ER
@@ -195,7 +228,29 @@ mirror at `AOS_PLAN_CANVAS_MERMAID_URL` for air-gapped use.
   (`AOS_PLAN_CANVAS_IDLE_MS`); `stop` shuts it down explicitly. State lives
   in `~/.claude/aos-plan-canvas/` (`AOS_PLAN_CANVAS_STATE_DIR`).
 
-## Examples
+## Planning mode choice
+
+Always run `aos-plan-canvas modes` first to discover what planning modes are available in your environment, then present only the available modes to the user with `standard` preselected as the default. Ask every time a plan review begins, even if modes have been configured previously — the environment may have changed between reviews.
+
+```bash
+# Discover available modes
+aos-plan-canvas modes
+# → { "default": "standard", "modes": [ {"id":"standard","label":"Standard Plan Canvas","available":true,"reason":null}, ... ] }
+```
+
+After the user chooses (or selects the preselected default), open with that mode:
+
+```bash
+aos-plan-canvas open <file> --mode <chosen-id>
+```
+
+`bdb-plan-builder` (labeled "BDB Plan Builder") and `builder` (labeled "Builder.io Visual Plan") are listed only when they are detected — respectively when `lib/plan-builder/index.js` exists in this skill's scripts directory, or when a `visual-plan` skill with a SKILL.md file is found in any of the configured skill directories (`~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills`, `~/.config/opencode/skills`, `~/.gemini/config/skills`, or custom paths in `AOS_PLAN_CANVAS_SKILL_DIRS`). Until then, only `standard` is available.
+
+### `bdb-plan-builder`
+
+For an Agent-Native-style **plan folder** (`plan.mdx` plus optional `canvas.mdx`, `prototype.mdx`, `.plan-state.json`), `open` renders the folder into ONE self-contained `plan.builder.html` in the BDB look next to the plan, then opens *that* file through the normal HTML artifact path — so annotation, chat and verdict work with no extra steps. Point it at the folder or at `plan.mdx` itself; a path with no `plan.mdx` exits 2 with the reason. Edit the MDX and re-run `open` to rebuild. Await `<plan-dir>/plan.builder.html`, not the folder.
+
+## Relationship to `/startcycle`
 
 **Plan approval flow** — Architect writes
 `production_artifacts/00_execution_plan.md` and must WAIT for confirmation:
@@ -237,9 +292,11 @@ aos-plan-canvas await <file> --reply "Reworked the risk table."
 |---|---|---|
 | `AOS_PLAN_CANVAS_PORT` | Loopback server port | `4519` |
 | `AOS_PLAN_CANVAS_STATE_DIR` | Session state directory | `~/.claude/aos-plan-canvas` |
-| `AOS_PLAN_CANVAS_IDLE_MS` | Idle shutdown timeout | 30 minutes |
+| `AOS_PLAN_CANVAS_IDLE_MS` | Idle shutdown timeout (`0` or `off` = never) | 30 minutes |
 | `AOS_PLAN_CANVAS_MERMAID_URL` | Mermaid ESM mirror | pinned jsDelivr CDN |
 
+The BDB Launchpad shows a Plan Canvas card with a start command; `aos --autostart-plan-canvas` registers an opt-in login server (idle exit off).
+
 `metadata.version` above and the `VERSION` literal in
 `scripts/plan-canvas.js` are one value in two places — bump them together when
 the vendored JS changes, so a stale detached server restarts.

package/skills/global_config/plan-canvas/scripts/lib/loopback-guard.js

@@ -39,20 +39,36 @@ function isAllowedHostHeader(hostHeader, allowedHostnames) {
 }
 
 // Origin is absent on same-origin navigations and CLI clients; when present
-// it must resolve to an allowed hostname.
-function isAllowedOrigin(originHeader, allowedHostnames) {
+// it must resolve to an allowed hostname. Loopback hostnames alone are not
+// enough: any other local web app (another dev server on 127.0.0.1) would pass
+// that test, so callers that know their port pass it and the origin must match
+// it too.
+function isAllowedOrigin(originHeader, allowedHostnames, allowedPort) {
   if (!originHeader || typeof originHeader !== 'string') return true;
   try {
     const url = new URL(originHeader);
-    return allowedHostnames.has(url.hostname.toLowerCase());
+    if (!allowedHostnames.has(url.hostname.toLowerCase())) return false;
+    if (allowedPort === undefined || allowedPort === null) return true;
+    const originPort = url.port || (url.protocol === 'https:' ? '443' : '80');
+    return originPort === String(allowedPort);
   } catch {
     return false;
   }
 }
 
+// Browsers label every request with Sec-Fetch-Site. A cross-site or same-site
+// request from another origin must never drive the canvas. Absent means a CLI
+// client or an old browser; Origin still applies to those.
+function isAllowedFetchSite(value) {
+  if (!value || typeof value !== 'string') return true;
+  const site = value.trim().toLowerCase();
+  return site === 'same-origin' || site === 'none';
+}
+
 module.exports = {
   LOOPBACK_HOSTNAMES,
   buildAllowedHostnames,
+  isAllowedFetchSite,
   isAllowedHostHeader,
   isAllowedOrigin,
   parseHostHeader