@miroshnik/elves 0.0.0 → 2026.1018.0

package/dist/spec/scripts/harness.js

@@ -0,0 +1,53 @@
+import {
+  marksIn2,
+  exceptionsIn2,
+  exceptionFiles2,
+  invariant2,
+  examples2,
+  eslintLinter2,
+  source2,
+  sources2,
+  codeFiles2,
+  codeOnly2,
+  disablesIn2,
+  lintExceptions2,
+  testFileIn2,
+  journal2,
+  resetJournal2,
+  trace2,
+  sequence2,
+  deadCode2,
+  ENV_SERVICE2,
+  configGet2,
+  envNamesIn2,
+  envNamesInCode2,
+  dotenvNames2,
+  envVars2
+} from "./harness-v9s1v9w3.js";
+import"./harness-qzb932c8.js";
+export {
+  ENV_SERVICE2 as ENV_SERVICE,
+  codeFiles2 as codeFiles,
+  codeOnly2 as codeOnly,
+  configGet2 as configGet,
+  deadCode2 as deadCode,
+  disablesIn2 as disablesIn,
+  dotenvNames2 as dotenvNames,
+  envNamesIn2 as envNamesIn,
+  envNamesInCode2 as envNamesInCode,
+  envVars2 as envVars,
+  eslintLinter2 as eslintLinter,
+  examples2 as examples,
+  exceptionFiles2 as exceptionFiles,
+  exceptionsIn2 as exceptionsIn,
+  invariant2 as invariant,
+  journal2 as journal,
+  lintExceptions2 as lintExceptions,
+  marksIn2 as marksIn,
+  resetJournal2 as resetJournal,
+  sequence2 as sequence,
+  source2 as source,
+  sources2 as sources,
+  testFileIn2 as testFileIn,
+  trace2 as trace
+};

package/dist/spec/scripts/knip-hints.cjs

@@ -0,0 +1,34 @@
+/**
+ * knip-hints — a knip reporter for the harness's `deadCode`: configuration hints (a redundant `ignore`, an `entry`
+ * without matches, a redundant workspace) as a JSON line
+ * `{ "configurationHints": [{ type, identifier, workspace, file? }] }`. knip's `json` reporter doesn't print them,
+ * and `--treat-config-hints-as-errors` gives only an exit code — the hints themselves aren't visible.
+ *
+ *   knip --reporter json --reporter .agents/skills/spec/scripts/knip-hints.cjs
+ *
+ * The second output line is its own: `deadCode` joins both. CommonJS, not TypeScript: the harness takes the file
+ * path (`report.file`) with a static import — `import.meta` in a module that Playwright and Jest load as CommonJS is
+ * a syntax error (tests/standards/harness-load); knip loads it under both Node and Bun. Types — `knip-hints.d.cts`.
+ */
+"use strict";
+
+const path = require("node:path");
+
+/**
+ * Hints as knip collected them (`ReporterOptions.configurationHints`): an identifier may be a regex (an `ignore`
+ * pattern), a file path is absolute; `--no-config-hints` — the project itself opted out of hints.
+ */
+function report(options) {
+  const hints = options.isDisableConfigHints
+    ? []
+    : options.configurationHints.map((h) => ({
+        type: h.type,
+        identifier: h.identifier instanceof RegExp ? h.identifier.source.replaceAll("\\/", "/") : String(h.identifier),
+        workspace: h.workspaceName ?? ".",
+        ...(h.filePath ? { file: path.relative(options.cwd, path.resolve(options.cwd, h.filePath)).split(path.sep).join("/") } : {}),
+      }));
+  process.stdout.write(JSON.stringify({ configurationHints: hints }) + "\n");
+}
+
+report.file = __filename;
+module.exports = report;

package/docs/ci-concurrency.md

@@ -0,0 +1,82 @@
+# CI: parallel tasks — the rule and workflow fragments
+
+A reference for the "CI: parallel tasks" section of `AGENTS.md`: here is the
+full rule and ready-made fragments to copy.
+
+## Rule
+
+Every branch and every PR runs independently; only the branch's own stale run
+is cancelled. Serialization — only where there is a shared resource (a deploy
+environment, a shared database, an external service with limits). One queue
+for all of CI is not a solution: it slows down every task, and without
+`queue: max` it also cancels pending runs. Workflow fragments — below.
+
+- **Branches and PRs run in parallel:** a `concurrency` group by PR number or
+  branch, `cancel-in-progress: true`.
+- **`main`, tags and manual runs are never cancelled:** their runs deploy, and
+  an interrupted deploy is worse than an extra run. Instead of cancelling —
+  `queue: max` (by default GitHub keeps one pending run and evicts it with the
+  next one: a third merge in a row would cancel the second).
+- **Deploy — a queue per environment:** the deploy job has the group
+  `deploy-<env>`, shared by all workflows of the repository, and `queue: max`.
+  Without it the job queue evicts pending jobs, just as at the workflow level:
+  at run time the environment's third deploy job cancels the waiting second
+  one, and a manual run cancels a waiting tag deploy.
+- **CI and deploy — in different workflows:** `queue: max` is incompatible
+  with `cancel-in-progress: true`. In one workflow —
+  `cancel-in-progress: ${{ github.event_name == 'pull_request' }}` without
+  `queue: max`: the deploy won't be interrupted, but a pending run may be
+  evicted.
+- **The agent doesn't cancel or re-run others' runs** (`gh run cancel` and
+  `gh run rerun` — only its own run on its own branch). Waiting for its own
+  checks and merging — the "Git, PRs and merging" section of `AGENTS.md`.
+
+## Workflow fragments
+
+Checked against the GitHub Actions documentation ("Control the concurrency of
+workflows and jobs"): `queue: max` allows up to 100 pending runs (beyond that
+they are cancelled) and is incompatible with `cancel-in-progress: true`;
+`false` is the default; `queue` also works on `jobs.<id>.concurrency`, which
+is supported on a job with `uses:` (reusable workflow) too;
+`cancel-in-progress` accepts expressions; a deploy job's group is shared
+across the repository, so the same name in different workflows gives one
+queue.
+
+```yaml
+# ci.yml — branches and PRs in parallel; a branch's stale run is cancelled
+on:
+  pull_request:
+concurrency:
+  group: ci-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+```
+
+```yaml
+# cd.yml — main, tags, manual runs: nothing is cancelled, runs wait in a queue
+on:
+  push:
+    branches: [main]
+    tags: ['v*']
+  workflow_dispatch:
+concurrency:
+  group: cd-${{ github.ref }}
+  queue: max
+jobs:
+  deploy-dev:
+    concurrency:
+      group: deploy-dev          # environment = queue, shared by all workflows
+      queue: max                 # the next deploy doesn't evict a pending one
+```
+
+If CI and deploy are in one workflow (they can't be split right now):
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+```
+
+A running deploy on `main` won't be interrupted this way, but of three merges
+in a row the third run evicts the pending second one — the third deploys
+everything together, and the second commit is left without a CI status on
+`main`.

package/docs/cloud-sessions.md

@@ -0,0 +1,203 @@
+# Claude Code cloud session
+
+Reference for the cloud-session line in `AGENTS.md`. A cloud session is
+Claude Code on claude.ai/code, including one started from the phone app: a
+temporary container into which only the project repository is cloned.
+A dispatcher's executor can be one (`AGENTS.md`, "Session and branch — one
+task"): at most 3 subagents and 5 cloud sessions at once, the owner's number
+replaces either — a cloud session's container doesn't load the machine.
+
+## What it sees
+
+Only the project repository. The canon, the skills and the agent's memory of
+the user's machine (`~/.agents`, `~/.claude`) aren't there: the flow comes
+from the project's **`SessionStart` hook** — `.claude/settings.json`, which
+`install` and `update` put into a thin project (#610). The cloud runs a
+project's hooks — not `~/.claude/settings.json` — after Claude Code starts,
+on every start and resume. With `CLAUDE_CODE_REMOTE=true` the hook does what
+an environment's setup script did (#555), without the owner's step: `npm i -g
+bun@latest @miroshnik/elves && elves install -g`, then `check --hook` into the
+context; outside the cloud it exits at once. The canon already on the machine
+— nothing to install; a failed step — a line with its command, code 0. An
+Elves clone carries the hook in its commit: Bun, zsh for its tests
+(`tests/capabilities/agent-shell`) and the flow from the clone itself —
+`install -g --link`, the branch's canon, no npm. A fresh start of the clone's
+hook with zsh in place took 4.4 s (2026-10-17: npm about 3 s, `check --hook`
+about 1 s); without zsh `apt-get update` and its install add about 6 s.
+
+- `bun@latest` — the image's Bun lags behind a project's `packageManager`
+  (1.4.2 on 2026-10-16, without the `bun check` of 1.4.3): npm's global
+  directory comes before `~/.bun/bin` in the image's `PATH`, while `bun
+  upgrade` in the session gets 403 from GitHub.
+- **No apt lists in the image** (2026-10-17): `apt-get install zsh` alone —
+  "Unable to locate package"; `apt-get update` first. `--force-confold` — the
+  image has its own `/etc/zsh/zshrc`: without it dpkg asks whether to replace
+  it and fails without a terminal (#598).
+- **npm has no release yet** (2026-10-17): `@miroshnik/elves` there is the
+  `0.0.0` stub without the `elves` command, so a thin project's hook prints
+  "the flow isn't installed (exit 127)" until CI publishes a release (README,
+  "Installation" — the owner's step). The clone's hook doesn't need npm.
+- **The setup script** is optional, a faster start: the environment caches
+  its result for about 7 days, and the hook then installs nothing. Network
+  access — Trusted (the default), about 7 s:
+
+  ```bash
+  npm i -g bun@latest @miroshnik/elves && elves install -g
+  # an Elves clone's environment: zsh for its tests (tests/capabilities/agent-shell), CI installs it too
+  apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y -o Dpkg::Options::=--force-confold zsh
+  ```
+
+- **The project's version** — `@miroshnik/elves` in its `devDependencies`,
+  only from npm: bun installs it through the session's proxy, `github:` in
+  the session is 403. It works in the project language, just like a local
+  session: `language` in `.agents/elves.json`, which comes with the clone.
+- **A thin project behind** — updated in the session's task, as locally:
+  `bunx @miroshnik/elves update` raises the package version, a few lines into
+  the task's branch; a project without the hook yet gets it the same way, and
+  until then — `check` by hand.
+- **No machine hook:** the cloud doesn't read `~/.claude/settings.json`; the
+  project's hook runs `check --hook` instead, without `github task resume`
+  (Projects are closed there). An environment without Bun or zsh all the same
+  — `check` names it with a `cloud environment:` line and the command, which
+  the session runs itself.
+- **A project with a copy of the flow** loads the canon twice in the cloud —
+  the copy's `.claude/rules` and the setup script's — until its move to the
+  thin project; a copy gets no project hook, nothing names it.
+
+**What is visible at the start** — checked from inside a cloud session
+(2026-10-17, Claude Code 2.1.302, #610), which itself started without the
+hook:
+
+- Skills `install -g --link` put into `~/.claude/skills` mid-session —
+  Claude Code picked them up at once (the skills list in the context
+  changed).
+- Rules `~/.claude/rules/elves*.md` written mid-session didn't reach the
+  context of that turn. By the diagnostics log (`$CLAUDE_CODE_DIAGNOSTICS_FILE`)
+  Claude Code reads memory files at the start of a user turn
+  (`cli_turn_started`, then `memory_files_completed` with `file_count`), so
+  the rules the hook writes before the first turn should load.
+- The clone hook's command, run as Claude Code runs it (`sh -c`, a fresh
+  `HOME`): code 0, the output is `check --hook`'s; outside the cloud — no
+  output.
+
+Still to check — in the first cloud session of the clone after the merge:
+the hook's output in the context; `memory_files_completed` at the first
+`cli_turn_started` has `file_count` 3 (the clone's `.claude/CLAUDE.md` and
+both rules); ask the agent to quote a rule from `AGENTS.md` and list the
+skills — `est`, `spec`, `ci-wait` must be there. The rules didn't load — the
+hook prints the canon (#610, question 2).
+
+## What the cloud lacks (checked 2026-09-25, 2026-10-17)
+
+- **GitHub GraphQL** is closed by the session proxy ("use the REST API").
+  REST — only `repos/{owner}/{repo}/…` paths of the session's repositories;
+  **Projects v2** (`users/…/projectsV2…`, `orgs/…`) — 403. Project fields
+  (`Status`, `Estimate, h`, `Actual, h`, tokens, cost) can't be set from the
+  cloud; `est` computes neither the estimate nor the actual.
+- **Writing to the repository** (push, editing issues, comments, PRs) — only
+  if the Claude GitHub App has access to the repository. No access — 403
+  ("Resource not accessible by integration", "Claude doesn't have GitHub
+  access"): the user installs or reconnects the app
+  (claude.ai → Settings → Connectors → GitHub; github.com/apps/claude).
+- **The cloud assigns the branch** (`claude/<slug>`) and forbids pushing to
+  others without explicit permission. A branch by the `<type>/<N>-<slug>`
+  convention — create it after asking the user at the start, together with
+  the task's questions.
+- **The session title** (`set_session_title`) is stored on the server and
+  doesn't get into the transcript: `est` links cloud work to the task only by
+  the branch, the only `#N` in the first prompt (section "The brief") and
+  commit hashes.
+- **The container is temporary**: anything unpushed is lost.
+- **Root:** the session runs as uid 0 — `chmod` doesn't deny writes. The
+  flow's write-denial tests (`install`, `slot`) run the checked process as
+  `nobody` (`setpriv`); a test relying on permissions without that is green
+  or red for the wrong reason.
+- **GitHub Actions job logs** over REST (`actions/jobs/<id>/logs`) — 403: the
+  answer redirects to blob storage the proxy doesn't let through;
+  `get_job_logs` of the GitHub MCP works.
+- **GitHub search** (`search/issues`) — 403 ("sessions are bound to their
+  configured repositories"): the duplicate check before a new task — by
+  listing `repos/{owner}/{repo}/issues`.
+- **The `github` skill's scripts** — `task show`, `task answer`, `task new`
+  over the repository's REST (#603): without the project — `task new` names
+  Status and the estimate in a line for a local session; the rest refuse
+  (`CLAUDE_CODE_REMOTE`). The scenarios section — by hand over REST (`PATCH
+  repos/…/issues/N`). The proxy ends a description it writes with its
+  "Generated by Claude Code" signature after `---` (doesn't add a second one):
+  the questions section ends at `---`, the signature isn't its last question's.
+
+## The brief — `#` only for its task
+
+The cloud names the branch itself (`claude/<slug>`), so `est` links a session
+to its task by the first prompt: it takes every `#N` of the whole prompt —
+with the "Background (from the session that started this one)" block the
+harness puts before the task — and links only by exactly one (#594). Whoever
+writes a cloud session's first prompt — the owner or a dispatcher session —
+names only its task with `#`, in the background too; the epic, other tasks and
+PRs — a number without `#` ("epic 40", "tasks 41 and 43") or a title. The
+executor prompt of `github task queue` has `(epic #M)`: fine for a subagent,
+whose assignment `est` reads by the word "Task"; a cloud executor's brief is
+`github task queue --assignment <N> --cloud` — whole (`task queue` refuses
+in the cloud), the epic and numbers in the title without `#`. Two `#N` —
+`est fact <N>` in the cloud prints `Actual unavailable (cloud)` though the
+transcript is in the container.
+
+## Closing a task from the cloud
+
+`github task close` refuses in the cloud (GitHub Projects are unavailable)
+and prints the same steps:
+
+1. `est fact <N>` computes this session's part of the actual from its
+   transcript in the container (linking — the branch `<type>/<N>-…` or the
+   only `#N` in the first prompt, section "The brief") and prints an
+   `Actual (cloud)` comment
+   with hours, tokens, a link to the session and a part marker — post it to
+   the issue with a GitHub tool. Project fields (`Actual, h`, tokens, cost)
+   are set by the next local session: `est fact <N> --write` or
+   `est fact --sweep --write` adds the cloud part to the local work. The
+   transcript didn't link — `Actual unavailable (cloud)`, and a local session imports the session's events via the browser
+   (the `est` skill, "Cloud session").
+2. `Status` = Done is set by the project's built-in workflow "Item closed"
+   (whether it is enabled — a local session checks with the `github` skill);
+   not enabled — ask the user to set the status.
+3. Epic refresh — by a subagent with a fresh context, as locally (issues,
+   sub-issues, milestones are available through the repository's REST); what
+   can't be done from the cloud (project fields, estimates of new tasks via
+   `est`) — into a State comment for the local session.
+
+**A local dispatcher learns of it by the task's closing** (#609): a cloud
+session can't message the local one that started it. `send_message` to a
+local session is refused — `elevated_session_untrusted_device`, then "target
+session could not be verified" on every retry (checked 2026-10-17);
+`create_trigger` (`persistent_session_id`) and `get_session` don't take a
+local session's id (`local_…`); `ListAgents` in the cloud sees no sessions of
+the owner's machine; the owner's approval on a trusted device
+(`confirm_repository_trust` with the `content_digest` of such a refusal —
+these carried none) is, by the tool's description, for one cloud session,
+i.e. per executor. So the brief tells the executor not to message the
+dispatcher and not to archive its session, and the dispatcher waits for the
+merge's `Closes #N`: `ci-wait issue <N>` as its own background command; PASS
+— `github task close <N>` locally (the actual with `--write`, `Status`, the
+merged `claude/<slug>` branch), then archiving the executor's session where
+it has the tool (till then its transcript may be needed for `est`); TIMEOUT —
+the task's questions section and State comment, the executor's session, the
+wait again. After the app restarts the queue's `=` line names the wait.
+
+## Push failed — a local session finishes
+
+A cloud session that can't write hands the work over as files: the branch —
+`git bundle` or `git format-patch --stdout` (a session attachment), answers
+to questions — in the PR text or the final message. A local session, by the
+task number:
+
+1. Answers from the cloud — into the task's questions section
+   (`github task answer`), before code.
+2. The branch — from a fresh `origin/main`:
+   `git fetch <file>.bundle <branch>:<branch>` or `git am <file>.mbox`; if the
+   cloud didn't start from it — rebase.
+3. Review the diff and the same checks as CI **on this machine**: the cloud
+   is Linux, and platform differences (symlinks via `/var` → `/private/var`
+   on macOS) aren't visible there.
+4. Then as usual: PR, green checks, merge, actual. The actual sees only the
+   local part of the work — add the line `Reason: missed work: …`
+   (reason: missed work) with a link to the cloud session.

package/docs/judgment.md

@@ -0,0 +1,81 @@
+# Judgment and edits: where a mistake looks like a result — for "Tests and code"
+
+Reference for the "Tests and code" section of `AGENTS.md`: the full rules and
+examples (made up). What the four have in common: such a mistake is caught
+neither by green checks nor by plausible numbers — only by the question of
+what the result, the label or the request is really about.
+
+## A mistake disguised as an outcome
+
+The most dangerous defect of a plan is one whose symptom matches one of the
+expected results: neither a check nor reading the numbers will catch it — the
+outcome is plausible, and it will be read as the answer.
+
+- **Before a measurement or a launch** (an experiment, a campaign, a load
+  run, a data migration) — write down the expected outcomes and for each one
+  ask: which of our mistakes would give exactly the same result?
+- **There is one — a separate check before the launch,** not an analysis
+  after it: after the launch its outcome can no longer be told apart from the
+  answer.
+- **An unchecked number is marked in the table itself** (in the cell, in the
+  row), not in a footnote: it may reverse the conclusion, and not everyone
+  reads footnotes.
+
+Example. A bid of "0.60" in an ad account whose currency turns out to be not
+the euro but one where 0.60 is next to nothing: there are no impressions, and
+it will be read as "no demand". The check before the launch — the account's
+currency and a test impression.
+
+## A label is a claim
+
+A label, a unit and a condition ("per month", "excl. VAT", "per user") claim
+what the number under them means. A request to "make the labels (units,
+conditions) the same" — first check against the source of each number that
+they are about the same thing, and only then change the text.
+
+- About the same thing — I align them.
+- About different things — I say so plainly and give options: recalculate to
+  one meaning, honestly different labels, leave as is.
+- Green checks (a snapshot, a text lint, a "labels match" test) compare
+  labels with each other, not with what the number means: the same label over
+  different numbers passes them all.
+
+Example. One table says "Revenue, ₽", another "Revenue, thousand ₽"; the
+request is for identical labels. First — what units the numbers are really
+in: otherwise one of the labels becomes false by a factor of a thousand.
+
+## Editing exactly what was named
+
+Asked for order, alignment or formatting — I change only that: not the
+content, not the composition, not the neighboring wording. The rule isn't
+only for an autonomous routine ("What I do without asking and what needs a
+yes" in `AGENTS.md`): any request names its own scope.
+
+- **The named change requires deleting an entity** (a row, a field, a
+  section, a test) — the solution is wrong, not the entity redundant: I look
+  for another one.
+- **The requirements really are incompatible** — I say so and let the person
+  choose, rather than resolving it by deletion.
+
+Example. The request is to align pricing cards by height; one is taller than
+the rest by one item. Removing the item is no longer alignment: height by the
+longest one, wrapping into two columns or shortening the text — the human
+chooses.
+
+## "It doesn't reproduce for me"
+
+A discrepancy between what the human sees and what I see is a claim about my
+tool, not about the product. I don't argue, but:
+
+- name what I measured with and where: browser and version, window width,
+  data and account, environment (local, preview, production), cache;
+- ask for the human's conditions and reproduce in them;
+- still didn't reproduce — I say what was checked and ask for what's missing
+  (a screenshot, an address, a time), rather than closing it as "not a bug".
+
+Example. The human sees buttons overlapping each other, for me they're even:
+I looked at a width of 1440 px in a clean profile, the human — at 390 px with
+a long name in the header. One product in the conversation, two tools.
+
+"Didn't help" after a fix is a different rule: the "Production and debugging"
+section of `AGENTS.md` (production facts, not a third reproduction).