@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/llm-context/llms-patterns.txt

@@ -194,7 +194,7 @@ Sometimes you want a workflow that does **not** fire on pushes, pull requests, t
 
 There are two ways to "explicitly invoke" a `dispatch()` workflow:
 
-1. **Locally from your laptop**, with `kici run local dispatch` — no orchestrator, no agent, no webhook, nothing deployed. This is the only path while you haven't wired the repo to a deployed KiCI orchestrator.
+1. **Locally from your laptop**, with `kici run dispatch --local` — this machine joins as an ephemeral agent through the warm local dev plane, so no orchestrator deployment is required. This is the path to use while you haven't wired the repo to a deployed KiCI orchestrator.
 2. **Remotely**, if the repo is connected to a KiCI orchestrator via a GitHub App, by calling GitHub's repository-dispatch API: `curl -X POST -H "Authorization: token <PAT>" -H "Accept: application/vnd.github+json" https://api.github.com/repos/<owner>/<repo>/dispatches -d '{"event_type":"hello"}'`. GitHub fans the webhook out to the App, the orchestrator normalizes it into a KiCI `dispatch` event (see `packages/orchestrator/src/providers/github/normalizer.ts`), and the matched workflow runs.
 
 Note that GitHub's `workflow_dispatch` event (the "Run workflow" button / `/actions/workflows/.../dispatches` API) is GitHub-Actions-internal and is **not** delivered to KiCI. The SDK has no `workflowDispatch()` trigger. Only `repository_dispatch` reaches KiCI.
@@ -217,36 +217,18 @@ export default workflow('hello-world', {
 });
 ```
 
-Run it locally, without any orchestrator or agent infrastructure:
+Run it locally, without any orchestrator deployment:
 
 ```bash
 npx kici compile           # regenerate .kici/kici.lock.json
-npx kici run local dispatch
+npx kici run dispatch --local
 ```
 
-`kici run local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs directly on your machine with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run local`](https://docs.kici.dev/user/cli-reference/#kici-run-local) for options like `--job`, `--env`, `--json`, and `--junit`.
-
-### Scoping to a single workflow
-
-Because `kici run local dispatch` matches **every** workflow that listens for a `dispatch` event, running it in a repo with several dispatch-triggered workflows will fire all of them. Narrow execution to one with `--workflow <name>`:
-
-```bash
-npx kici run local dispatch --workflow hello-world
-```
-
-`--workflow` is a post-match filter: the workflow still has to have a trigger that matches the event argument. If `hello-world` does not list a `dispatch()` trigger, the command reports `No workflow named "hello-world" matched the event` and exits successfully without running anything.
-
-If you do not want to memorise event args, use the interactive picker instead:
-
-```bash
-npx kici run local --pick
-```
-
-`--pick` (aliased as `-p`) lists every workflow alongside a compact summary of its triggers, lets you select one, and derives a matching event arg from the chosen trigger — so the execution still flows through the normal trigger-matching pipeline and "cannot produce an inconsistent run". Multi-trigger workflows show a second prompt for which trigger to simulate. `--pick` is mutually exclusive with `--workflow`; in a non-TTY shell it prints the workflow list and exits without running anything.
+`kici run dispatch --local` compiles the workflow, matches triggers against a simulated `dispatch` event, and executes the matched jobs on this machine — which joins as an ephemeral agent through the warm local dev plane — with DAG-based scheduling. No webhook, no GitHub, no deployed orchestrator involved. See [`kici run <event> --local`](https://docs.kici.dev/user/cli/runs-and-approvals/#kici-run-event---local) for options like `--env`, `--in-place`, and `--offline`.
 
 ### Unfiltered vs typed `dispatch()`
 
-Leave `dispatch()` unfiltered while you drive it from `kici run local`. The CLI currently simulates a dispatch event with no event type (i.e. `action` is undefined), so a trigger defined as `dispatch({ types: ['deploy', 'rollback'] })` will not match `kici run local dispatch` — the typed form is intended for real `repository_dispatch` deliveries from the orchestrator.
+Leave `dispatch()` unfiltered while you drive it from `kici run <event> --local`. The CLI simulates a dispatch event with no event type (i.e. `action` is undefined), so a trigger defined as `dispatch({ types: ['deploy', 'rollback'] })` will not match `kici run dispatch --local` — the typed form is intended for real `repository_dispatch` deliveries from the orchestrator.
 
 ## Conditional execution with rules
 
@@ -369,7 +351,7 @@ With a single-dimension matrix, the current value is available as `matrix.value`
 
 ### Multi-dimensional matrix
 
-Use an object to define multiple dimensions. KiCI expands all combinations (capped at 256):
+Use an object to define multiple dimensions. KiCI expands all combinations (capped at 256, and each combination must be unique — a repeated value fails the job rather than running it twice):
 
 ```typescript
 const test = job('test', {
@@ -420,7 +402,9 @@ const test = job('test', {
 });
 ```
 
-Exclude is applied first (removes matching combinations), then include adds additional entries.
+Exclude is applied first (removes matching combinations), then include adds additional entries. An
+include entry's values appear in the child job name ordered by dimension name, whichever order you
+write the keys in — see [Include and exclude](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#include-and-exclude).
 
 ### Dynamic matrix
 
@@ -608,9 +592,7 @@ post-restart job until the host completes a reboot cycle, then dispatches it.
 import { workflow, job, step, restartHost, waitForHostAlive } from '@kici-dev/sdk';
 
 export default workflow('patch-and-verify', {
-  on: [
-    /* ... */
-  ],
+  on: [/* ... */],
   jobs: [
     // Restart job: apply updates, then reboot. restartHost() MUST be the last step.
     job('patch', {
@@ -745,6 +727,12 @@ export const postDeploy = workflow('post-deploy', {
 
 `workflowComplete()` / `jobComplete()` start a **separate** workflow run that reacts to the prior one finishing, gated on its status. They are the right tool when a _different_ workflow should respond. When you instead need to add more jobs to the **same** run based on what a job just produced — fanning out follow-up work from a prior job's outputs — use a result-aware generator (next section), not a completion-event chain.
 
+#### Failure notifier (any source → any destination)
+
+Because the orchestrator auto-emits `workflow_complete` for **every** run, a single workflow with `on: workflowComplete({ status: ['failed'] })` (no `source` filter) becomes an org-wide failure notifier: every failed workflow, whatever repo or provider triggered it, dispatches this one workflow. The runnable example `examples/workflows/failed-workflow-slack-notifier.ts` builds exactly that — it maps the failed run's repo (`ctx.sourceRepo?.identifier`) through an inline `repo → { channel, tag }` table and posts to Slack with `fetch`, guarding the real POST behind `ctx.isTestRun` so a test run never messages a live channel. Swap the `fetch` body for Discord, Teams, PagerDuty, or a plain HTTP endpoint to change the destination — no external package required.
+
+The one failure class this pattern cannot catch is a **dead orchestrator**: a workflow can only run while the orchestrator that would dispatch it is alive, so if the orchestrator itself is gone, nothing dispatches the notifier. Watching for an orchestrator that has stopped reporting is the managed notification plane's job, not a workflow's.
+
 ### Same-run discovery → fan-out
 
 A result-aware [`dynamicJob(group, { needs, generate })`](https://docs.kici.dev/user/sdk/rules-matrix-dynamic/#dynamicjob--result-aware-generation) is deferred until its declared upstreams complete, then runs with their frozen outputs as `ctx.needs` — so a discovery job can emit a list at runtime and the generator fans out one follow-up job per item, all in the same run:
@@ -1279,7 +1267,7 @@ export const testSuite = workflow('test-suite', {
           await $`pnpm test`;
         }),
         step('emit-results', async (ctx) => {
-          await ctx.emit(testsPassedEvent.name, {
+          await ctx.emit(testsPassedEvent, {
             branch: 'main',
             commit: 'abc123',
             testCount: 142,

package/dist/llm-context/llms-providers.txt

@@ -10,7 +10,9 @@ The **GitHub App** is KiCI's flagship source. A single App:
 
 1. receives `push`, `pull_request`, and related events from every repo it's installed on,
 2. clones repos with a short-lived installation token (no deploy key to manage),
-3. posts workflow / job / step Check runs back to the pull request (see
+3. posts workflow / job / step Check runs back to the commit — visible on
+   the commit view for a plain `push` and on the **Checks** tab of any pull
+   request that contains it (see
    [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/)).
 
 You don't need an App for every scenario — if you only care about `push`
@@ -347,6 +349,13 @@ driven by the orchestrator's reporting module; no workflow
 configuration is required beyond installing the App with the
 `checks: write` permission.
 
+Check runs are keyed to the head commit SHA, so they surface whether or
+not a pull request exists: after a `push` you see the pass/fail directly
+on the commit (a red ✗ / green ✓ next to the SHA in GitHub's commit list
+and on the commit page), and the same checks roll up into the **Checks**
+tab of any pull request that later includes the commit. A failing run is
+therefore visible in GitHub itself without opening the KiCI dashboard.
+
 For architecture details see
 [GitHub checks architecture](https://docs.kici.dev/architecture/webhooks/github-checks/).