openfactory 0.2.0__tar.gz → 0.3.0__tar.gz

openfactory-0.3.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.4
+Name: openfactory
+Version: 0.3.0
+Summary: A framework to run software tickets autonomously with coding agents — policies authorize actions, humans evaluate results.
+Author: The OpenFactory Authors
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://openfactory.digital
+Project-URL: Repository, https://github.com/Open-Factory-Digital/openfactory-core
+Project-URL: Issues, https://github.com/Open-Factory-Digital/openfactory-core/issues
+Keywords: sdlc,agents,automation,devops,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pyjwt[crypto]>=2.8
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=12
+Provides-Extra: runtime
+Requires-Dist: temporalio>=1.7; extra == "runtime"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: bandit>=1.7; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: types-pyyaml; extra == "dev"
+Requires-Dist: temporalio>=1.7; extra == "dev"
+Requires-Dist: pytest-randomly>=3.15; extra == "dev"
+Requires-Dist: pytest-xdist>=3.6; extra == "dev"
+Dynamic: license-file

openfactory-0.3.0/README.md

@@ -0,0 +1,232 @@
+# OpenFactory
+
+**An autonomous software factory.** It takes tickets from your board and returns reviewed pull
+requests — planned, implemented, validated by *your* test suite, independently reviewed, and
+merged under the policy you chose. Humans stop authorising every step and start evaluating
+results; production stays behind a human gate, always.
+
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](pyproject.toml)
+
+It is **not a coding agent** — it orchestrates the ones you already use (Claude Code, Codex,
+Kimi, OpenCode) behind one adapter contract. It is **not a SaaS** — it runs on your machines,
+against your board, with your credentials, and no cloud account is required.
+
+## Why this one
+
+- **Policies authorise, humans evaluate.** The manifest declares the merge policy, the quality
+  floor and the promotion chain; the factory refuses vacuous green — a project with no declared
+  test command is *held*, not "passed".
+- **The box is proven before money is spent.** `box prove` runs your own `setup:` and
+  `validate:` inside the real sandbox before any ticket is picked up. A misconfigured
+  environment is a named finding, not a burned agent pass.
+- **Every stall speaks.** A blocked job parks with executable options for a human; a silent
+  forever-wait is treated as the platform's own defect class.
+- **Provider axes, not provider lock-in.** Tracker, board, forge, CI observer, notifier, coding
+  agent and sandbox are independent adapters — GitHub Issues + Projects, Jira, Azure DevOps
+  (work items → Azure Repos PRs, end to end), chosen per project in a registry.
+- **An independent review, structurally.** The reviewer can run on a *different* engine from the
+  executor, so "you did not write this code" is true by construction.
+- **Honest docs.** What does not work is written down (`docs/STATUS.md`)
+  before you decide anything.
+
+## Quickstart — one machine
+
+The shortest path is your own repository and the coding agent you already pay for: **one
+credential, no Docker, no account anywhere**. The factory branches from your repository, opens a
+pull request in it, reviews the change and fast-forwards your base.
+
+Prerequisites: git, Python 3.12+, and a coding agent on your PATH already signed in (`claude`,
+`codex`, `kimi` or `opencode`).
+
+```bash
+git clone https://github.com/Open-Factory-Digital/openfactory-core.git && cd openfactory-core
+python3 -m venv .venv && source .venv/bin/activate      # 3.12+; see docs/ONBOARDING.md §0
+pip install -e '.[runtime]'                             # the durable engine's worker runs on the extra
+
+openfactory init                         # press Enter twice: your code and your tickets live HERE
+openfactory project init myapp ~/code/myapp   # a path registers as itself — no owner, no board
+openfactory doctor myapp                 # on this door, green IS the prerequisite list
+
+openfactory act card_create -p myapp -P title="Add a health endpoint" -P body="## Objective
+Serve 200 at /health
+
+## Acceptance criteria
+- GET /health returns 200"
+openfactory act card_move -p myapp -i 1 -P column=TO-DO
+openfactory poll myapp                   # one card, all the way to Done
+```
+
+`openfactory serve` serves the same thing in a browser at http://localhost:8787 — the Board, the
+job, the pull request. The whole door is **[docs/setup/one-machine.md](docs/setup/one-machine.md)**,
+including what happens to your working tree when a merge lands.
+
+## Quickstart — with Docker, on a hosted forge
+
+The other door: the compose stack, a real forge and a real board, several people watching the same
+panel. **Two credentials are irreducible here** — the coding agent's
+(`CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`, or `ANTHROPIC_API_KEY`) and a forge
+credential (a PAT to try things out, a GitHub App for real use). Docker is asked for at this hour,
+not before.
+
+**Docker. Only Docker.** No Python on the host, no `sudo`, one line:
+
+```bash
+curl -fsSL https://openfactory.digital/install.sh | sh
+```
+
+| | |
+|---|---|
+| **read it first** | `curl -fsSL https://openfactory.digital/install.sh -o install.sh && less install.sh && sh install.sh` |
+| **no script at all** | the four commands below |
+
+> The worker mounts the host's Docker socket — that is how `sandbox: container` starts a box, and
+> it is root-equivalent on the host. It is the same trade `docker compose up` has always made here.
+
+> The installer sends nothing anywhere. There is no telemetry in this project.
+
+Re-running the installer is the upgrade path: it resolves the newest release, pulls it, and
+restarts the stack. Your answers and your data survive it.
+
+<a id="the-un-piped-equivalent"></a>
+Prefer to do it by hand? These are the same four steps, and nothing else:
+
+```bash
+REPO=https://github.com/Open-Factory-Digital/openfactory-core
+VERSION=$(curl -fsSLI -o /dev/null -w '%{url_effective}' $REPO/releases/latest); VERSION=${VERSION##*/tag/}
+curl -fsSL $REPO/releases/download/$VERSION/docker-compose.yml -o docker-compose.yml
+curl -fsSL $REPO/releases/download/$VERSION/SHA256SUMS | sha256sum -c --ignore-missing
+docker run --rm -it -v "$PWD:/out" -u "$(id -u):$(id -g)" \
+  ghcr.io/open-factory-digital/openfactory-cli:$VERSION init --out /out/.env.compose
+echo "OPENFACTORY_VERSION=$VERSION" >> .env.compose
+docker pull ghcr.io/open-factory-digital/openfactory-sandbox:$VERSION
+docker compose --env-file .env.compose up -d
+```
+
+Three of those lines look optional and are not. The **version is resolved once** and written into
+`.env.compose`, because `docker-compose.yml` defaults to `main` — right for a contributor working
+on the branch, wrong for anybody running a factory. The **box image is pulled by hand** because
+`docker compose up` does not fetch it: the worker launches it as a sibling container on your own
+daemon. And the **checksums are verified**, which is why the files come from the release rather
+than from the website — a static host can serve a file and cannot checksum one.
+
+Then open http://localhost:8787 in a browser — the panel (8080 is the engine's own UI).
+
+**Two credentials are irreducible for a real ticket** — the coding agent's
+(`CLAUDE_CODE_OAUTH_TOKEN` from `claude setup-token`, or `ANTHROPIC_API_KEY`) and a forge
+credential (a PAT to try things out, a GitHub App for real use). `openfactory init` asks for
+neither and names both; only the agent's cannot be postponed past the first hour.
+
+`openfactory preflight` says what is still missing on this machine, one line each with a remedy.
+
+Register a project **inside the worker** (the compose stack has its own registry; a
+laptop-registered project is invisible to it). One command registers it and creates the board
+with the platform's columns:
+
+```bash
+docker compose --env-file .env.compose exec worker \
+  openfactory project init myapp https://github.com/<owner>/myapp.git   # your org or username
+docker compose --env-file .env.compose exec worker openfactory doctor myapp
+```
+
+(`project add` is the variant for a board you already have, or for none at all. On Azure
+DevOps, register with your `dev.azure.com` clone URL — it carries the
+organisation/project/repository, and Azure Boards ships with the project, so there is no board
+to create: **[docs/setup/azure-devops.md](docs/setup/azure-devops.md)**.)
+
+`doctor` runs nine checks always and up to four more when they apply, naming every missing
+prerequisite with its remedy — including the
+agent credential and the forge credential. From there, the guided first hour is
+**[docs/ONBOARDING.md](docs/ONBOARDING.md)**: the environment session that reads your repository
+and proposes its own manifest, the box proof, a costed rehearsal on a synthetic ticket, and the
+first real card.
+
+## Your first ticket
+
+An ordinary issue, in English or Portuguese:
+
+```markdown
+## Objective
+Users can export their report as CSV.
+
+## Acceptance criteria
+- a `GET /reports/{id}/export` endpoint returns text/csv
+- the export respects the report's current filters
+```
+
+Drag it to **TO-DO**. The factory sizes it, proves the box, plans, implements, runs *your*
+gates, opens the PR, has it independently reviewed — and with `merge_policy: human` (the
+recommended start) waits for your merge. The panel at `:8787` shows every step live.
+
+## The shape
+
+```
+openfactory/
+├── contracts/     Pydantic models — the framework↔project↔agent↔board interface
+├── registry.py    the set of projects one deployment drives (add one = data, not code)
+├── policy/        the quality floor: stack presets + org defaults + conformance
+├── adapters/      the provider axes — a project mixes them freely; the core ships GitHub,
+│   │              Azure DevOps and Jira on every axis below that has a vendor, and an
+│   │              add-on package adds a kind through the `openfactory.adapters` entry points
+│   ├── tracker/     GitHub Issues, Jira, Azure DevOps work items
+│   ├── board/       GitHub Projects, Jira status, Azure DevOps boards
+│   ├── forge/       GitHub, Azure Repos — branches, PRs, merges, tags
+│   ├── environment/ CI / deploy / health, read-only — GitHub Actions, Azure Pipelines
+│   ├── agent/       CodingAgentAdapter — Claude Code, Codex, Kimi, OpenCode
+│   ├── reviewer/    the independent review
+│   ├── channel/     the panel — the reference surface; a chat channel is an add-on package (openfactory-slack)
+│   └── sandbox/     container = real; worktree = local/test; a cloud box is an add-on package (openfactory-aws)
+├── orchestrator/  the deterministic state machine (the spine)
+├── runtime/       the durable engine (Temporal): poller, jobs, promotion tail
+└── cli.py         `openfactory` — project-first commands
+```
+
+## The roles you can switch on
+
+| role | what it is | where it lives |
+|---|---|---|
+| **engineering loop** | ticket → reviewed PR → merge | on by default; this README |
+| **post-merge** | watch your deploy, walk your stages, gate production | opt-in per project — [ONBOARDING §13](docs/ONBOARDING.md) says what silence means |
+| **tech-lead** | diagnoses parked jobs, proposes the fix, acts on your yes | the panel; a chat channel such as Slack is an add-on package (openfactory-slack), never a prerequisite |
+| **product owner** | requirements as reviewed docs in a context repo; accept/queue/release | `/product/<name>` on the panel — [docs/reference/product-role.md](docs/reference/product-role.md) |
+| **release gate** | production is approved by a named human with a password, always | [docs/reference/product-role.md §3](docs/reference/product-role.md) |
+
+## Documentation
+
+**One path, three references.** The map is [docs/README.md](docs/README.md); this is the short
+form:
+
+| read this | when |
+|---|---|
+| [docs/ONBOARDING.md](docs/ONBOARDING.md) | **start here** — the whole guided session on your own codebase, and the only onboarding there is |
+| [docs/setup/one-machine.md](docs/setup/one-machine.md) | one repository, one terminal, one credential — the door that needs no account anywhere |
+| [docs/setup/github.md](docs/setup/github.md) | the path sends you here for GitHub: the App screen by screen, a personal account's board token, a board by hand |
+| [docs/setup/azure-devops.md](docs/setup/azure-devops.md) | …or here for the all-Microsoft side: PAT scopes, board states, registration by clone URL |
+| [docs/STATUS.md](docs/STATUS.md) | the honest read before deciding anything |
+| [docs/reference/configuration.md](docs/reference/configuration.md) | manifest / registry / environment — who owns which setting, promotion chains |
+| [docs/reference/cli.md](docs/reference/cli.md) | every command (the `env`/`box`/`product` surfaces are walked in ONBOARDING) |
+| [docs/reference/product-role.md](docs/reference/product-role.md) | switching on the product owner |
+| [docs/writing-an-addon.md](docs/writing-an-addon.md) | your deployment needs a provider the core does not ship — a row, end to end, editing nothing here |
+| [docs/adr/](docs/adr/) | why it is built this way (49 decision records) |
+
+## Status
+
+Working, and honest about where. The whole loop — sizing → box proof → agent → your gates → PR
+→ independent review → merge — has run end to end on four stacks (Python,
+serverless TypeScript, .NET, multi-repo) against real GitHub, real Jira and real Azure DevOps.
+The suite runs in both orders on every change and new guards are proven by mutation before they
+count — the current size, the commit it was measured at, and everything that is NOT settled are
+in [`docs/STATUS.md`](docs/STATUS.md), which is the one place any of those numbers live.
+
+## Taking part
+
+Issues and pull requests are welcome, and the bar is written down rather than implied:
+[CONTRIBUTING.md](CONTRIBUTING.md) explains the house rules (a guard for every behaviour, a
+mutation for every guard) and how to add a provider to an axis without touching the core.
+**There is no CLA** — Apache-2.0 §5 already covers what you submit, and you keep the copyright
+on what you write. Everyone taking part is held to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+[Apache-2.0](LICENSE). The [NOTICE](NOTICE) file separates the free code from the defended
+brand. Security reports: see [SECURITY.md](SECURITY.md). Contributions: [CONTRIBUTING.md](CONTRIBUTING.md).

openfactory-0.3.0/openfactory/__init__.py

@@ -0,0 +1,7 @@
+"""openfactory-platform — a framework to run software tickets autonomously.
+
+Policies authorize actions; humans evaluate results. See
+docs/adr/0001-foundational-conceptual-model.md for the conceptual model.
+"""
+
+__version__ = "0.3.0"

openfactory-0.3.0/openfactory/actions/__init__.py

@@ -0,0 +1,369 @@
+"""The action layer — everything a human can ask the factory to DO, written once (C-23).
+
+WHAT WAS ACTUALLY WRONG. The Slack bot never calls the HTTP API: zero httpx, zero requests, zero
+aiohttp. The two front ends were written independently against the same domain, and by the time
+this card was opened they had drifted in ways nobody chose:
+
+    resume          the panel passes the DecisionRequest option key; Slack hard-codes ""
+                    → a job parked with a real question can be answered from the panel and only
+                      resumed blindly from Slack, in a channel where the question was posted
+    ack             exists in Slack, does not exist in the panel at all
+    enable / scan    exist in the panel, do not exist in Slack
+    approve_prod    two implementations — a durable signal and an in-process PromotionRunner —
+                    reachable from one front end each, under names that suggest they are the same
+    validation      the panel checks the ref shape; Slack checks nothing
+
+None of that is a bug anybody wrote. It is what happens when a capability has no home, and it is
+the manifesto's empty SDK box: there was no layer for a third front end to be written against, so
+a third front end would have made it three.
+
+WHAT THIS LAYER IS. A table of actions. Each takes values and `by: Actor`, returns an `Outcome`,
+and speaks no transport: no HTTP status, no mrkdwn, no Slack block, no exception escaping. The
+front ends become mappings — a route or a verb picks a name and renders the result.
+
+WHAT IT IS NOT. It is not authorization (C-26 / #55): `Actor.admin` is still decided by whoever
+carried the request, and this layer only carries and records it. It is not the conversational
+tech-lead (C-24 / #52): `ask` and `diagnose` are catalogued here and their brains still live in
+the Slack package until that card moves them. Both are deliberate — putting either in this card
+would mean designing identity or the agent's memory model inside a refactor, and that is how a
+refactor becomes a rewrite.
+
+REACHING IT. Two universal transports dispatch the whole catalog by name:
+
+    POST /api/act/{name}    the panel and anything holding its token
+    openfactory act <name> …  a shell on the host
+
+and the named front-end paths (`/api/temporal/act`, the Slack verbs, `/api/projects/{n}/enabled`)
+are mappings onto the same rows. That is the property the guards in
+`tests/test_the_action_layer.py` hold: **every action is reachable from at least two transports and
+implemented by none of them.**
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+
+from openfactory.actions.base import (
+    CODES,
+    CONFLICT,
+    DENIED,
+    FAILED,
+    FLOOR,
+    INVALID,
+    NOT_FOUND,
+    OK,
+    PRODUCT,
+    SCOPES,
+    SYSTEM,
+    UNAVAILABLE,
+    UNIMPLEMENTED,
+    ActionSpec,
+    Actor,
+    Outcome,
+    done,
+    not_moved_yet,
+    refused,
+)
+
+log = logging.getLogger("openfactory.actions")
+
+__all__ = [
+    "CATALOG", "CODES", "CONFLICT", "DENIED", "FAILED", "FLOOR", "INVALID", "NOT_FOUND", "OK",
+    "PRODUCT", "SCOPES", "SYSTEM", "UNAVAILABLE", "UNIMPLEMENTED", "ActionSpec", "Actor",
+    "Outcome", "done", "names", "not_moved_yet", "perform", "proposable", "refused",
+    "run_staged", "spec",
+]
+
+
+async def run_staged(*, project: str, by: Actor, token: str = "") -> Outcome:
+    """Perform what the tech-lead staged for `project` — see `catalog.run_staged`.
+
+    Re-exported lazily for the same reason `_Catalog` is: importing the implementations costs
+    `temporalio`, and the panel is built to serve without the runtime extra."""
+    from openfactory.actions.catalog import run_staged as _run
+
+    return await _run(project=project, by=by, token=token)
+
+
+def _catalog() -> dict[str, ActionSpec]:
+    from openfactory.actions.catalog import CATALOG as rows
+
+    return rows
+
+
+class _Catalog:
+    """A lazy mapping over `catalog.py`, so importing `openfactory.actions` costs nothing.
+
+    The catalog's implementations reach Temporal, the forge and the approver store. Importing them
+    eagerly would put `temporalio` on the import path of every front end — including the panel,
+    which is explicitly built to serve without the `runtime` extra installed. The bodies already
+    import lazily; this keeps the module itself lazy too, so the guard tests can walk the table on
+    a machine that has none of it.
+
+    THAT PROMISE IS HELD BY A GUARD SINCE #178, because for a while it was only written down: the
+    page's own words came from `view.py` and `workflow.py`, so `/` and `/api/floor` answered 500
+    on exactly the install this paragraph describes. It asks every GET route in an interpreter
+    where `temporalio` cannot be found:
+    `tests/test_the_panel_serves_without_the_engines_client.py`."""
+
+    def __getitem__(self, name: str) -> ActionSpec:
+        return _catalog()[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in _catalog()
+
+    def __iter__(self):
+        return iter(_catalog())
+
+    def __len__(self) -> int:
+        return len(_catalog())
+
+    def values(self):
+        return _catalog().values()
+
+    def items(self):
+        return _catalog().items()
+
+    def get(self, name: str, default=None):
+        return _catalog().get(name, default)
+
+
+#: The one table. Iterating it is how a front end lists what it can offer, and how the guards
+#: check that every row is reachable.
+CATALOG = _Catalog()
+
+
+def names() -> tuple[str, ...]:
+    """Every action, in catalog order — which is grouped by what an operator is doing, not
+    alphabetical, because this is what `openfactory act --list` prints."""
+    return tuple(_catalog())
+
+
+def spec(name: str) -> ActionSpec | None:
+    return _catalog().get((name or "").strip().lower())
+
+
+#: What a proposal may CARRY. It was `{project, issue}` — a ticket and nothing else — because the
+#: channel back was `[[SUGGEST verb #NN]]`, with nowhere to put a sentence. That dropped `adjust`,
+#: and the consequence was the shape of the whole role: the tech-lead could propose that you throw
+#: work away (`discard`) or rerun it blind (`resume`), and could not propose the one thing a senior
+#: engineer actually says, which is WHAT TO CHANGE (#170).
+#:
+#: A SECRET IS STILL NOT ADDRESSABLE, and that is the line this set now draws. `_SECRET` below
+#: names what may never travel through a proposal; a parameter outside it is prose a human reads on
+#: the button before pressing it.
+_ADDRESSABLE = frozenset({"project", "issue", "instruction"})
+
+
+def proposable(by: Actor) -> tuple[str, ...]:
+    """The actions this actor may perform AND the tech-lead may propose, in catalog order (#121).
+
+    THREE FILTERS, ALL DERIVED, because the alternative is the sentence this replaces: the
+    tech-lead's guidance said *"never suggest prod/merge actions"* — a rule written when the
+    catalogue had no merge row. #120 added one, gated, reachable from the chat, and the guidance
+    went on forbidding it. A hand-written list of verbs in a prompt is a second copy of the
+    catalogue that nobody updates.
+
+    1. **The asker's own credential**, by the SAME two checks `perform` applies and in the same
+       order — scope, then admin. A credential that cannot press the button must not be told to
+       ask for it; being handed an action and then refused is worse than not being offered it.
+    2. **What a human could have typed.** A suggestion is a proposal somebody approves with one
+       word, so it must be something they could have said themselves: the operator grammar
+       (`contracts/commands.py`, which is `resume`/`skip` and deliberately excludes prod) and the
+       floor matcher (`actions/floor_intents.py`, which is merge/discard/adjust). Rows like
+       `start`, `diagnose` and `product_release` are addressable by a ticket and are NOT things
+       the floor's own grammar accepts — which is exactly the line the old rule was reaching for.
+    3. **What a proposal can carry** — see `_ADDRESSABLE`. This used to drop `adjust`, because
+       the channel was one verb and one ticket wide. It carries an instruction now (#170), and the
+       blast radius is closed by (2): `typeable` is `{adjust, discard, merge, resume, skip, stop}`,
+       so relaxing this admits EXACTLY `adjust`. `approve_prod` and `promote` stay out where they
+       already were — not in the floor grammar — rather than by this filter's accident.
+
+    `ack` is deliberately absent from (2). It is a person saying they have seen something, and
+    nobody can propose that on somebody else's behalf.
+    """
+    from openfactory.actions.floor_intents import FLOOR_ROWS
+    from openfactory.contracts.commands import ACTION_OF
+
+    typeable = set(ACTION_OF.values()) | set(FLOOR_ROWS.values())
+    out: list[str] = []
+    for name, found in _catalog().items():
+        if name not in typeable:
+            continue
+        if not by.may_enter(found.scope):
+            continue
+        if found.needs_admin and not by.admin:
+            continue
+        if set(found.required) - _ADDRESSABLE or "issue" not in found.required:
+            continue
+        out.append(name)
+    return tuple(out)
+
+
+async def perform(name: str, *, by: Actor, **params: object) -> Outcome:
+    """Run one action. Never raises. Always returns an `Outcome`.
+
+    THE FIVE THINGS THAT HAPPEN HERE RATHER THAN IN THREE FRONT ENDS:
+
+    1. **The name is resolved**, and an unknown one is refused with the list of what exists —
+       the registry rule this codebase already holds everywhere else (`adapters/*/registry.py`).
+    2. **Parameters are checked** against the spec, in both directions. A missing one is named; so
+       is an unexpected one, because a front end that renames a field and keeps working silently
+       is how `image=` came to be omitted at all four job-launch sites (see
+       `a-negative-guard-needs-a-positive-twin`).
+    3. **A ticket ref is normalised once.** `#189` and `189` are the same ticket, and until now the
+       panel knew that and Slack did not.
+    4. **`needs_admin` is enforced.** Slack had this gate, the panel had a token, the CLI had
+       nothing; now the three answers meet in `Actor.admin` and the decision is made in one place.
+    5. **Everything is logged with the actor**, whatever the result. This is the audit line — the
+       first time this platform can say who asked for a thing, which is the question an enterprise
+       security review opens with.
+
+    NEVER RAISING IS NOT POLITENESS. Both front ends already have a hard must-always-reply rule,
+    and both implemented it by wrapping every call in `except Exception`. Doing it here means an
+    action author cannot forget, and means the exception's real message survives — `first_message`
+    walks the chain, because an error crossing a Temporal activity boundary otherwise arrives as
+    the fixed string "Activity task failed" (#66).
+    """
+    key = (name or "").strip().lower()
+    found = _catalog().get(key)
+    if found is None:
+        return refused(
+            NOT_FOUND,
+            f"there is no action called {name!r} — this deployment does: " + ", ".join(names()),
+        )
+
+    problem = _check_params(found, params)
+    if problem:
+        return refused(INVALID, problem)
+
+    if "issue" in params:
+        ref, bad = _clean_ref(str(params["issue"]))
+        if bad:
+            return refused(INVALID, bad)
+        params["issue"] = ref
+
+    # SCOPE BEFORE ADMIN, because they answer different questions and the order is the point: a
+    # business analyst holding a product credential IS an admin of the product area — accepting a
+    # requirement is the most consequential act there — and must still be refused `merge` outright.
+    # Asking `admin` first would let that credential through on every row it happens to satisfy.
+    if not by.may_enter(found.scope):
+        log.warning("DENIED_SCOPE %s (%s) by %s (%s)", key, found.scope, by, _loggable(params))
+        return refused(
+            DENIED,
+            f"this credential is scoped to {', '.join(sorted(by.scopes or ())) or 'nothing'} and "
+            f"{key} belongs to the {found.scope}. Nothing was done — ask somebody whose "
+            f"credential covers the {found.scope}.",
+        )
+
+    if found.needs_admin and not by.admin:
+        log.warning("DENIED %s by %s (%s)", key, by, _loggable(params))
+        return refused(
+            DENIED,
+            f"{by} is not allowed to {key} — ask somebody listed as an admin for this project.",
+        )
+
+    try:
+        outcome = await found.run(by=by, **params)
+    except Exception as exc:  # noqa: BLE001 — an action must never take its caller down
+        log.exception("action %s raised for %s", key, by)
+        return refused(FAILED, f"could not {key}: {_why(exc)}")
+    if not isinstance(outcome, Outcome):  # an action that returns None is a silent success (F5)
+        log.error("action %s returned %r, not an Outcome", key, type(outcome).__name__)
+        return refused(
+            FAILED,
+            f"'{key}' did not report what it did — treat this as a failure and check the logs "
+            f"before assuming it happened.",
+        )
+    log.info("action=%s by=%s ok=%s code=%s params=%s", key, by, outcome.ok,
+             outcome.code or "-", _loggable(params))
+    return outcome
+
+
+#: Parameters whose VALUE must never reach a log line. `approve_prod` and `promote` take the
+#: approver's password, and this module writes an audit line on every call including the refusals —
+#: which is precisely the path a wrong password takes.
+_SECRET = frozenset({"password", "token", "secret", "key"})
+
+
+def _why(exc: Exception) -> str:
+    """What the refusal says an action died of — the install, when the install is what is missing.
+
+    THE ROWS THAT ARE THE ENGINE'S IMPORT ITS MODULES INSIDE THEIR BODIES, by design: that is what
+    keeps `temporalio` off every front end's import path (see `_Catalog`). So on an install made
+    without the `runtime` extra, `start`, `stop`, `approve` and the rest raise here, and the person
+    read `could not start: No module named 'temporalio'` — a cause with no remedy. The catch-all
+    above is the one guard all of them share, so it is the one place that names the install:
+    `host.CLIENT_MISSING`, the sentence every other surface gives for that condition (#178)."""
+    from openfactory.runtime.host import CLIENT_MISSING, the_client_is_what_is_missing
+    from openfactory.util.causes import first_message
+
+    # The chain, not only its head: a row that wraps its own failures still died of the import.
+    link: BaseException | None = exc
+    for _ in range(8):  # bounded: a chain is short, and a hand-built cyclic one must not spin
+        if link is None:
+            break
+        if the_client_is_what_is_missing(link):
+            return CLIENT_MISSING
+        link = link.__cause__ or link.__context__
+    return first_message(exc)
+
+
+def _loggable(params: dict[str, object]) -> dict[str, object]:
+    return {k: ("***" if k in _SECRET else v) for k, v in params.items()}
+
+
+def _check_params(found: ActionSpec, params: dict[str, object]) -> str:
+    missing = [p for p in found.required if p not in params or params[p] in (None, "")]
+    if missing:
+        return (f"'{found.name}' needs {', '.join(missing)} — it takes "
+                + ", ".join(found.parameters) + ".")
+    unexpected = [p for p in params if p not in found.parameters]
+    if unexpected:
+        return (f"'{found.name}' does not take {', '.join(sorted(unexpected))} — it takes "
+                + (", ".join(found.parameters) or "no parameters") + ".")
+    return ""
+
+
+#: What a tracker actually calls a ticket: `189` (GitHub, optionally `#`-prefixed), `CONT-412`
+#: (Jira), `1234` (Azure DevOps). Letters, digits, one kind of separator, nothing else.
+#:
+#: Lifted verbatim from `api/app.py::_valid_issue`, which is the point: the panel held this and
+#: Slack held nothing, so a ref typed in a channel went straight into a Temporal workflow id. The
+#: bound matters for the same reason it did there — a ref becomes part of a workflow id and, via
+#: `paths.journal_stem`, part of a filename.
+_ISSUE_RE = re.compile(r"^[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$")
+#: …and the same ref carrying the repository it lives in (C-18): `owner/name#189`. One product can
+#: own several repositories, so on a multi-repo board a bare number names no single ticket. Kept as
+#: a SECOND, fully-anchored pattern rather than by loosening the first: `/` and `#` reach a
+#: workflow id and a filename, and the way to allow exactly two segments and one hash is to spell
+#: that out, not to add characters to a class and hope.
+_QUALIFIED_RE = re.compile(
+    r"^[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*#[A-Za-z0-9]+(?:[-_][A-Za-z0-9]+)*$")
+_ISSUE_MAX = 64
+#: The qualified form needs room for `owner/name#` on top of the ref itself. A SEPARATE bound, so
+#: widening it here cannot quietly widen what a bare ref may be — the bound is what keeps a ref
+#: from becoming an unreasonable workflow id or filename, and each shape deserves its own.
+_QUALIFIED_MAX = 160
+
+
+def _clean_ref(issue: str) -> tuple[str, str]:
+    """`(ref, problem)` — the provider's own ref without the decoration a human types.
+
+    `#189` and `189` must not be two tickets. The panel already knew that in `_valid_issue`; Slack
+    passed whatever was typed straight into a Temporal workflow id, so `skip #250` and `skip 250`
+    addressed different workflows and only one of them existed.
+
+    REJECTING IS STILL WORTH DOING even though `paths.py` neutralises a hostile ref on its own
+    (C-06a). This is where there is somebody to tell: a sentence naming the problem beats a job
+    launched against a ref no provider will ever recognise, which surfaces minutes later as an
+    unexplained 404."""
+    ref = (issue or "").strip().lstrip("#").strip()
+    bare = bool(ref) and len(ref) <= _ISSUE_MAX and bool(_ISSUE_RE.match(ref))
+    qualified = bool(ref) and len(ref) <= _QUALIFIED_MAX and bool(_QUALIFIED_RE.match(ref))
+    if not (bare or qualified):
+        return "", ("that is not a ticket reference — letters, digits, '-' or '_', optionally "
+                    "with the repository it lives in "
+                    f"(e.g. 189, #189, CONT-412, owner/name#189), got {issue!r}")
+    return ref, ""