feat(ctx): integrate ctx as an opt-in skill source for loops

.claude/skills/loopflow/SKILL.md

@@ -41,6 +41,8 @@ allow edits automatically, but ask me before <classes>   action policy
 each cycle: plan, then act, then observe   the repeated steps (any subset, in order)
 also: <pass>, <pass>      extra finishing passes after the goal is met
 use skills: <a>, <b>      named skills the loop may invoke during plan/act
+use skills recommended by ctx   ctx recommends + installs the skills for the goal (needs the ctx MCP server); add `for "<intent>"` to override the query
+top up skills from ctx    run-time: pull more skills from ctx when a cycle fails and reflects
 remember in "<file.md>"   cross-run memory: read lessons on start, append an outcome on stop
 when it fails: reflect on <focus>, then plan again
 when it passes and the goal is met: stop
@@ -57,6 +59,9 @@ models: fast <m>, strong <m> model tiering — plan/reflect/also→fast, act→s
 schedule: <when>             run unattended on a cadence
 runner: <agent>              which agent executes the loop
 target: <dir>                operate on another directory/repo
+recommend skills with ctx    ctx is this file's skill source — recommends + installs skills per loop goal
+grant ctx: skills, agents, mcps, harnesses   capability groups ctx may recommend (fail-closed; default skills+agents; mcps/harnesses are recommend-only)
+ctx may use my own model "<provider>/<model>"   declares a user-owned model — unlocks harness recommendations (dry-run only)
 ```
 
 Predicates:
@@ -158,6 +163,34 @@ Walk these quickly, naming the keyword each time so they learn it:
 Don't forget the menu in Step 2 also covers `use the <method> method` — pull a whole
 preset (e.g. BMAD) instead of hand-picking passes.
 
+### Skill discovery — offer ctx when the right skills aren't named yet
+
+`use skills:` assumes the skills already exist in `~/.claude/skills`. If the user doesn't
+already know which skills the loop needs, offer to let **ctx**
+([claude-ctx](https://github.com/stevesolun/ctx)) pick them: it recommends the smallest
+useful bundle for the goal and installs the bodies, so the names resolve. It is **opt-in**
+and only works when the ctx MCP server is attached (`claude mcp add ctx -- ctx-mcp-server`).
+
+When ctx's tools are available (`ctx__loop_provision`, `ctx__recommend_bundle`):
+1. After the goal is set, call `ctx__recommend_bundle` (read-only preview) or
+   `ctx__loop_provision` with the goal — show the user the recommended skills with their
+   reasons before installing anything.
+2. On approval, `ctx__loop_provision` installs them and returns the resolved names. Write a
+   real `use skills: <names>` line **and** a `use skills recommended by ctx` line — the
+   first keeps the `.loop` self-contained and reproducible; the second lets a headless
+   `loop run` re-resolve the bundle from ctx.
+3. Offer `top up skills from ctx` if the loop should pull more skills when a cycle fails.
+4. **Beyond skills** — if the goal needs more than skills, add a `grant ctx: skills, agents,
+   mcps, harnesses` line for the groups that apply (fail-closed; omit it for skills-only).
+   `mcps` and `harnesses` are **recommend-only** — ctx surfaces them with an install command
+   the user runs; the loop never auto-installs them. Harnesses additionally need a
+   `ctx may use my own model "<provider>/<model>"` line, and always come as a `--dry-run`
+   command. Pass the granted groups (and own-model) to `ctx__loop_provision` as `permissions` /
+   `own_llm` / `model_provider` / `model`.
+
+When ctx is **not** attached, skip this silently and author `use skills:` by hand as usual —
+the loop runs the same either way.
+
 Offer the defaults inline (*"I'll add a tests + security pass, gate the migration, a
 6-try guard, work on a branch, one model throughout, no schedule — sound right?"*) so the
 whole interview is one exchange. Name every topic once even when you default it, so the
@@ -280,6 +313,13 @@ the user explicitly asks for the headless runner.)
    - **plan** — inspect the `look at:` files; decide the smallest change toward the goal.
      If the loop declares `use skills:`, you may invoke those named skills (via the Skill
      tool) to do the work — coordinate them rather than re-deriving everything inline.
+   - **ctx skills** — if the loop declares `recommend skills with ctx` /
+     `use skills recommended by ctx`, resolve the bundle once at the start of the run: call
+     `ctx__loop_provision` with the goal (and any `for "<intent>"`) to install the skills
+     and get their names, then treat those as part of `use skills:` for this run. If the
+     loop also says `top up skills from ctx`, call `ctx__loop_topup` with your reflection
+     after a failed cycle and fold any new skills in before re-planning. If the ctx tools
+     aren't attached, skip this and run with whatever `use skills:` already names.
    - **act** — make the edits. Honor the policy: for `ask me before <X>`, ask the user
      before doing X (migrations, pushes, etc.); auto classes you may do directly.
    - **observe** — run the `done when` check and read pass/fail. For a command or named test,

AGENTS.md

@@ -76,6 +76,8 @@ allow edits automatically, but ask me before <classes>   action policy
 each cycle: plan, then act, then observe   the repeated steps (any subset, in order)
 also: <pass>, <pass>      extra finishing passes run after the goal is met
 use skills: <a>, <b>      named skills the loop may invoke during plan/act
+use skills recommended by ctx        let ctx pick + install the skills for the goal (needs the ctx MCP server); add `for "<intent>"` to override the query
+top up skills from ctx               run-time: pull more skills from ctx when a cycle fails and reflects (pairs with the line above)
 remember in "<file.md>"   cross-run memory: read lessons on start, append an outcome on stop
 reflect                   turn a failure into context for the next plan (the back-edge)
 
@@ -96,6 +98,9 @@ each cycle: plan, then act, then observe   (config tier: the default cycle for e
 rigor: vibe coding | structured ai-assisted | agentic engineering   (the spectrum dial; structured/agentic give every loop a back-edge + thrash guard for free)
 mode: conductor | orchestrator   (supervision posture: in-session/sync vs async/opens-a-PR)
 runs as: <identity>   (an auditable principal for unattended runs)
+recommend skills with ctx   (config tier: ctx is this file's skill source — recommends + installs skills per loop goal; see "Skill source: ctx" below)
+grant ctx: skills, agents, mcps, harnesses   (config tier: capability groups the file lets ctx recommend; fails closed, default skills+agents; mcps/harnesses are recommend-only)
+ctx may use my own model "<provider>/<model>"   (config tier: declares a user-owned/local/API model — unlocks ctx harness recommendations, always dry-run)
 observe:   (block) trace every cycle / meter tokens and cost / stop and warn if cost exceeds "$N"
 sandbox:   (block) no network access / allow egress to "host" only / cap cpu at … memory at … time at …
 hooks:     (loop body block) before each cycle | after act | on commit | on stop : "<cmd>" passes|finds nothing   (a failing hook blocks)
@@ -111,9 +116,11 @@ stages in parallel:    (inside a pipeline: the indented stages run concurrently)
 done when the test "billing.spec.ts::apostrophe" passes   # a named test
 done when "pnpm test" passes                               # a shell command, exit 0
 done when "semgrep --severity=high" finds nothing          # a shell command, empty output
+done when "pnpm test flaky" passes 3 times                 # flake guard: re-run the check, EVERY run must pass
 done when a human confirms "looks right at 375px"          # a human check
 done when the skill "email-review" approves                # an eval: approved / not
 done when the skill "email-review" scores 8 or more        # an eval: numeric threshold
+done when the skill "code-review" approves by 3 judges     # consensus: N independent verdicts, majority wins
 done when the skill "api-review" scores 8 or more on the output       # an eval of WHAT was produced
 done when the skill "path-review" approves on the trajectory          # an eval of HOW the agent got there
   the bar: didn't weaken a test to go green; no writes outside api/   # the rubric the judge scores against
@@ -122,6 +129,16 @@ done when the skill "path-review" approves on the trajectory          # an eval
 The command in a predicate runs in the user's shell with their privileges (like an npm
 script). It IS meant to be a real command. Prefer a fast, deterministic check.
 
+**Flake guard — `passes N times`.** Append `N times` to a `test` or command predicate to re-run
+it `N` times and require every run to pass (the first failure short-circuits). Reach for it when a
+green can pass by luck — a timing- or order-dependent test — so "done" means "passes *reliably*",
+not "passed *once*".
+
+**Judge panel — `by N judges`.** Append `by N judges` to a skill predicate to collect `N`
+independent verdicts and take the majority (early-exit once decided). A single LM judge wobbles
+near the bar; consensus smooths the noise. The deterministic counterpart of the flake guard:
+flake guard for tests, judge panel for evals.
+
 ### Tests vs evals — list as many `done when` as you need
 
 A loop may have **multiple `done when` lines, and ALL must pass** (a conjunction). Use this to
@@ -159,6 +176,58 @@ then have the loop coordinate them. Don't invent a loop around skills that don't
 prove the skill manually, then wire it in (as an execution skill via `use skills:`, or as a
 verifier via `done when the skill "…" approves`). See `examples/skills_memory.loop`.
 
+### Skill source: ctx — let a recommender pick + install the skills
+
+`use skills:` assumes the skills already exist in `~/.claude/skills`. **ctx**
+([claude-ctx](https://github.com/stevesolun/ctx)) is the recommender that fills that gap:
+point it at a goal and it recommends the smallest useful bundle and installs the skill bodies
+into `~/.claude/skills` — so the names resolve. ctx is the layer beneath Loop; Loop stays the
+top, user-facing layer.
+
+```loop
+recommend skills with ctx               # config tier: ctx is this file's skill source
+
+loop "harden the stripe webhook handler":
+  goal: webhook retries are idempotent and signature-checked, with tests
+  use skills recommended by ctx for "stripe webhook idempotency"   # bake at author time, resolve at run time
+  top up skills from ctx when a step needs more                    # pull more on a failing cycle
+  done when "pnpm test api/webhooks" passes
+```
+
+- **Author time** (`/loopflow`): ctx recommends for the goal, you approve, the names are
+  installed and written into a `use skills:` line so the `.loop` stays self-contained.
+- **Run time** (`loop run`): the runtime resolves `use skills recommended by ctx` via the ctx
+  MCP server before the first plan, and `top up skills from ctx` after a failed cycle reflects.
+- **No ctx attached?** The lines are inert — the loop runs exactly as it would without them.
+
+**Beyond skills — the full capability set.** By default ctx provisions only `skills`
+(and the agents Loop loads the same way). A `grant ctx:` line widens what ctx may recommend to
+any of `skills, agents, mcps, harnesses`, **failing closed** — only listed groups are returned:
+
+```loop
+recommend skills with ctx
+grant ctx: skills, agents, mcps, harnesses          # capability grants (fail-closed)
+ctx may use my own model "ollama/llama3.1"          # unlocks harness recs (dry-run only)
+
+loop "stand up a local agent loop":
+  goal: an MCP agent loop running on local ollama with filesystem access
+  use skills recommended by ctx
+  done when "pytest tests/agent_loop" passes
+```
+
+- **skills / agents** install into `~/.claude/skills` (as before) and merge into the cycle's
+  skill set.
+- **mcps** are **recommend-only**: ctx surfaces fitting MCP servers + a suggested
+  `ctx-mcp-install <name>`; the runtime emits them on a `ctx` event, it never auto-registers one.
+- **harnesses** (autogen, langfuse, …) recommend **only** when you declare a user-owned model
+  (`ctx may use my own model "…"`), and ship as an explicit `ctx-harness-install <name> --dry-run`
+  command — never an automatic install. This is the one capability that pulls real software, so it
+  stays human-gated by design.
+
+Setup: `claude mcp add ctx -- ctx-mcp-server` (needs `pip install claude-ctx`). See
+`examples/ctx_skills.loop`, `examples/ctx_capabilities.loop`, and `docs/ctx-skill-source.md`.
+Full customer-facing walkthrough (setup, own-model, the capability model): `docs/ctx-integration-guide.md`.
+
 ### `remember in` — cross-run memory
 
 A loop forgets everything between runs unless you give it a memory file. `remember in` makes
@@ -381,6 +450,11 @@ flow, show the file chain. `loop-run ls` lists every loop in the repo.
 
 - `loop-run run file.loop` — execute it on Claude Code (plan/act/observe, reflect on failure,
   verify with `done when`, pause at human gates).
+- `loop-run run file.loop --log run.log` — also append every event to a local NDJSON log
+  (secrets are scrubbed before anything is persisted).
+- `loop-run run file.loop --resume run.log` — resume an interrupted run from its log: satisfied
+  stages / flow steps / for-each items are skipped, the first incomplete unit picks up (flow
+  carry-forward summaries restored from the log).
 - `loop-run show file.loop` — print the loop's flow as compact ASCII (and `loop-run ls` to list them).
 - `loop-run explain file.loop` — describe the loop in plain English (a friendly check of what it will do).
 - `loop-run viz file.loop` — open a visual HTML schematic of the flow.

CHANGELOG.md

@@ -6,6 +6,42 @@ Versions track the `@loop-lang/loop` installer package.
 
 ## [Unreleased]
 
+## [0.7.0] — 2026-07-02
+
+> `@loop-lang/loop` 0.7.0 · `@loop-lang/{parser,runtime,stdlib,viz}` 0.4.0 · `loopflow` (vscode) 0.5.0
+
+### Added
+- **ctx as a skill source** — `recommend skills with ctx` / `use skills recommended by ctx`
+  / `top up skills from ctx`: a loop equips itself via the ctx MCP server before the first
+  plan and re-equips after a failed cycle reflects. Capability grants
+  (`grant ctx: skills, agents, mcps, harnesses`, fail-closed) and own-model gating
+  (`ctx may use my own model "…"`, dry-run-only harness recommendations).
+- **Verification reliability** — the flake guard (`done when "…" passes 3 times`: every
+  run must pass, first failure short-circuits) and judge panels
+  (`the skill "…" approves by 3 judges`: majority of independent verdicts, early-exit
+  once decided). Rendered in `show`/`explain` (`×3`, `· 3 judges`).
+- **Event log & telemetry** — `--log <path>` / `LOOP_LOG_FILE` appends every runtime
+  event as durable NDJSON (header + seq'd lines); `LOOP_EVENTS_URL` streams the same
+  events to a control-plane collector (shared run id, fan-out). **Secret redaction on by
+  default**: env-derived values and well-known credential shapes are scrubbed before any
+  sink persists an event (`LOOP_REDACT=off` to disable).
+- **Resume** — `loop-run run <file> --resume run.log` skips every unit the log proves
+  satisfied (definitions, stages, flow steps, for-each items), restores flow carry-forward
+  summaries, and warns when the `.loop` source changed since the logged run.
+- **Browser playground** — `docs/playground.html`: the parser, ASCII shape view, explain,
+  and soft linter bundled to 27 kB of client-side JS; parse-on-type with inline errors and
+  example loops. Linked from the tutorial.
+- **Docs** — "How verification works: what 'done' actually depends on" in the manual
+  (verdict factors: working dir, shell env, exit codes, `finds nothing` semantics, flake /
+  judge hardening); event-log, resume, and redaction sections; README aligned with the
+  tutorial (all `.loop` blocks verified against the parser).
+
+### Changed
+- **New logo** — the gap ring (one ring, one gap: the loop still iterating), with a
+  solid-tile variant as the favicon / app icon across the site and README.
+- `loopflow` (vscode) 0.5.0 — bundles the 0.4.0 parser (judge panels, flake guard, ctx
+  lines all recognized); output panel renders `⏩ resumed` events.
+
 ## [0.6.0] — 2026-06-29
 
 > `@loop-lang/loop` 0.6.0 · `@loop-lang/{parser,runtime,stdlib,viz}` 0.3.0 · `loop-vscode` 0.4.0