create-open-autonomy 2.4.9 → 2.5.0

package/README.md

@@ -31,10 +31,10 @@ LICENSE              Apache-2.0, seeded; the project's own
 package.json, test/  the project's own check (`bun run check`), starting with one test
 hermes/              the agent: SOUL.md, its three skills (develop, pm, community; a project's own skills live beside them, in hermes/skills/<project>/, and are the project's), profiles/treasurer (the second profile: the one that pays), kanban.seed.json (the board's first tasks, in order),
                      cron/jobs.seed.json (the PM, hourly; the community desk, every quarter hour), config.yaml (the model: the project's own choice), the seed hook
-.open-autonomy/      the platform connection: config.yaml (account, publish policy, the model and rail bounds the platform holds the project's funds to), reporter.ts (the publisher:
+.open-autonomy/      the platform connection (PRODUCTION.md: how a project ships — a human-cut tag, a reviewed environment, the workflows the owner's): config.yaml (account, publish policy, the model and rail bounds the platform holds the project's funds to), reporter.ts (the publisher:
                      sessions, the board, the setup), mint-key.ts (the key, the adopter way), start.ts (the agent's four
                      processes, the one way it starts), the vendored SDK, kit.json (which kit, version and parameters made this repository)
-container/           a real setup: one image whose entrypoint is start.ts as root, dropping the gateway to the image's user; the pinned Hermes
+container/           the default for a real deployment (bare is for development and fast debugging): one image whose entrypoint is start.ts as root, dropping the gateway to the image's user; the pinned Hermes
 .github/workflows/   ci.yml (the project's check on every branch), land.yml (the landing convention)
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-open-autonomy",
-  "version": "2.4.9",
+  "version": "2.5.0",
   "description": "The default Open Autonomy starter kit: a complete repository that runs its own Hermes agent against the platform, with the SDK wired in. `bun create open-autonomy <dir>` scaffolds one.",
   "license": "Apache-2.0",
   "repository": {

package/src/kit.ts

@@ -9,7 +9,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 
-export const KIT = { name: 'hermes', version: '2.4.9' } as const;
+export const KIT = { name: 'hermes', version: '2.5.0' } as const;
 export const KIT_FILE = '.open-autonomy/kit.json';
 const TEMPLATE = resolve(import.meta.dir, '..', 'template');
 
@@ -19,7 +19,7 @@ export interface KitRecord { kit: string; version: string; params: KitParams; di
 // What the kit keeps current. Everything else in the template is seeded once.
 // A project's own, seeded once: its config (the treasurer's too: the model is the project's choice for both profiles),
 // its board seed, its schedule, and any skill of its own outside hermes/skills/open-autonomy/ (the kit's three).
-const OWNED = [/^hermes\/(?!config\.yaml$|kanban\.seed\.json$|cron\/jobs\.seed\.json$|profiles\/treasurer\/config\.yaml$|skills\/(?!open-autonomy\/))/, /^\.open-autonomy\/(reporter\.ts|mint-key\.ts|start\.ts|community\.ts|package\.json|sdk\/)/, /^container\//, /^\.github\/workflows\/(ci|land)\.yml$/];
+const OWNED = [/^hermes\/(?!config\.yaml$|kanban\.seed\.json$|cron\/jobs\.seed\.json$|profiles\/treasurer\/config\.yaml$|skills\/(?!open-autonomy\/))/, /^\.open-autonomy\/(reporter\.ts|mint-key\.ts|start\.ts|community\.ts|PRODUCTION\.md|package\.json|sdk\/)/, /^container\//, /^\.github\/workflows\/(ci|land)\.yml$/];
 export const isOwned = (rel: string): boolean => OWNED.some((re) => re.test(rel));
 
 export function validateParams(p: Partial<KitParams>): KitParams {

package/template/.open-autonomy/PRODUCTION.md

@@ -0,0 +1,45 @@
+# Production: how a kit project ships
+
+The agent lands code. A human decides what goes live. The platform never holds a deploy credential, and neither
+does any machine an agent runs on. This is how that is arranged on GitHub, with nothing but GitHub's own features;
+the reference project (`open-autonomy-org/hookline`) runs exactly this.
+
+## The shape
+
+- **Landing is the agent's.** It pushes `agent/<task>` branches; the landing workflow opens the pull request and
+  merges it. Nothing pushes `main` directly, maintainers included (`main-protected` ruleset: pull request required,
+  no bypass).
+- **The workflows are the owner's.** `.github/CODEOWNERS` names the owner for `/.github/`, and the `main` ruleset
+  requires code-owner review, so a landing that touches a workflow waits for the owner while everything else lands
+  with no review. The file that runs with a secret is never changed by the agent.
+- **Production runs only from a human-cut tag.** A `production` environment with the owner as required reviewer,
+  whose deployment branches are the tag pattern `deploy-v*` and nothing else, never `main`. Its secrets are the
+  deploy credential and nothing more. A `deploy-tags-admin-only` tag ruleset lets only an org admin create such a
+  tag. The deploy workflow fires on the tag (or a dispatch from it), so the workflow that holds the credential is
+  always the one a human tagged.
+- **The build says what it is.** The deploy stamps the commit into the artifact (Hookline: `HOOKLINE_VERSION` from
+  `git rev-parse --short HEAD`, answered at `/api`), so the live service names its own commit.
+
+## Setting it up, once per project
+
+1. `.github/CODEOWNERS`: `/.github/ @<owner login>` (a user or a team; an org is not a code owner).
+2. Ruleset `main-protected` on `refs/heads/main`: `pull_request` (0 approvals, code-owner review required),
+   `non_fast_forward`, `deletion`; no bypass actors.
+3. Ruleset `deploy-tags-admin-only` on `refs/tags/deploy-v*`: `creation`, `update`, `deletion`; bypass:
+   OrganizationAdmin, always.
+4. Environment `production`: required reviewer the owner; deployment branches "selected", one tag pattern
+   `deploy-v*`; the deploy credential as an environment secret (never a repository secret); the account id as a
+   repository variable.
+5. `.github/workflows/deploy.yml`: `on: push: tags: ['deploy-v*']` and `workflow_dispatch`; `permissions:
+   contents: read`; `environment: production`; egress allow-listed to GitHub, npm and the deploy target; actions
+   pinned by SHA; no restored caches.
+
+## Shipping
+
+```bash
+git tag -a deploy-v<date> <sha> -m "<what ships>" && git push origin deploy-v<date>   # the owner, on a commit they read
+```
+
+The run waits for the reviewer; approving it is the second human act. Rolling back is tagging an earlier commit.
+Secrets the service itself needs (webhook secrets, keys) are environment secrets the deploy workflow installs, so
+they too are set by a human through the gate and never by the agent.

package/template/.open-autonomy/start.ts

@@ -1,8 +1,10 @@
 #!/usr/bin/env bun
 // Start the agent. The same processes wherever it runs; only how this script is started differs:
-//   on your machine   `bun .open-autonomy/start.ts` — everything as you, no isolation, for development
-//   in a container    the image's entrypoint, as root with the secrets mounted for root alone and `--as <user>`:
-//                     the gateway and the reporter run as that user and can reach no key (container/README.md)
+//   in a container    the default for a real deployment: the image's entrypoint, as root with the secrets mounted for
+//                     root alone and `--as <user>`; the gateway and the reporter run as that user and can reach no
+//                     key (container/README.md)
+//   on your machine   `bun .open-autonomy/start.ts` — everything as you, no isolation: for development and fast
+//                     debugging, where the agent reaching its own keys is an accepted trade
 //
 //   bun .open-autonomy/start.ts [--home <dir>] [--secrets <dir>] [--project <dir>] [--origin <url>] [--as <user>] [--valve <port>]
 //

package/template/container/README.md

@@ -4,7 +4,7 @@ The agent is four processes: an ssh-agent holding the deploy key, the valve hold
 developer's on :8787, the treasurer's on :8788 — `--valve <port>` moves both — each re-read when its file changes), the keyless reporter, and
 the Hermes gateway. One script starts them, `.open-autonomy/start.ts`, and it is the only way they are started.
 
-**On your machine**, for development: everything as you, no isolation.
+**In a container** is the default for a real deployment. **On your machine**, for development and fast debugging: everything as you, no isolation, the agent able to reach its own keys — an accepted trade while debugging, never the shape of production.
 
 ```bash
 bun .open-autonomy/mint-key.ts                                   # the developer's key → ~/.config/open-autonomy/agent.env

package/template/hermes/config.yaml

@@ -23,7 +23,7 @@ compression:
   threshold: 0.50
 
 agent:
-  max_turns: 80
+  max_turns: 160
 
 # The board (Hermes Kanban) the schedule files roadmap items on. Its dispatcher runs inside the gateway and
 # the review lane verifies every handoff; the interval is how soon a filed task is picked up.

package/template/hermes/skills/open-autonomy/develop/SKILL.md

@@ -31,7 +31,9 @@ is not done.
    `bun run check` once, green, before every push.
 5. Commit small, signed as the agent, the task id first in the subject:
    `git commit -s --author="Open Autonomy agent <agent@open-autonomy.org>" -m "<task id>: <what changed>"`.
-6. Push the branch: `git push -u origin agent/<task id>`. The landing workflow opens the pull request and merges
+6. Push the branch once, when every acceptance line is true: `git push -u origin agent/<task id>`. The landing
+   merges whatever is pushed, so a push mid-task lands half a feature on main; commit as often as you like, push
+   at the handoff. The landing workflow opens the pull request and merges
    it when the checks pass. Never wait for it; never open a pull request; never push to `main`; never rewrite
    history. If the branch exists from an earlier attempt, push to `agent/<task id>-<YYYYMMDD-HHMM>`.
 7. Hand off: `kanban_request_review` naming the branch and the commit, and what is verified how. Name no reviewer: