ace-lab 0.9.0 → 0.13.0

data/README.md

@@ -1,122 +1,88 @@
-## ace-lab
-
-Topology, routing, and scoped service request CLI for the Lab. Part of ACE
-(Agentic Coding Environment).
-
-`ace-lab` answers one question -- *what is the stable ID of the project, agent,
-or service I mean, and what is it authorized and able to do?* -- from
-configuration. Topology queries never invoke a service. The `service`
-commands submit configured operations through a verified executor and use
-`ace-assign` for durable request evidence. No command hands credentials to
-the caller or guesses transient pane or session identifiers.
-
-### Install
-
-    gem install ace-lab
-
-### Usage
-
-Configure topology via the ADR-022 cascade (`~/.ace/lab/config.yml` or
-`.ace/lab/config.yml`; deployed values are owned by the `lab-config`
-repository). Authorization grants live in a separate deployment-controlled
-file at the fixed path `/etc/lab/ace-lab/authorization.yml` -- root-owned and
-not group/world-writable, verified at every query -- never in the
-caller-writable cascade and never at a caller-selected location:
-
-```yaml
-# .ace/lab/config.yml -- topology only
-schema_version: 1
-topology:
-  projects:
-    - { id: atlas, label: Atlas platform }
-  agents:
-    - id: atlas-planner
-      project: atlas
-      role: planner
-      capabilities: [planning]
-      binding: { kind: runtime, state: active, instance_id: i1, attested_instance_id: i1 }
-  services:
-    - id: atlas-search
-      project: atlas
-      capabilities: [search]
-      default_for: [search]
-      endpoint: { kind: http, url: "https://search.example.internal/query?token=secret" }
-      binding: { kind: service, state: active, instance_id: i2, attested_instance_id: i2 }
-```
-
-```yaml
-# trusted grants file (deployment-owned)
-principals:
-  "<verified-local-uid>": { projects: ["atlas"] }
-```
-
-Query it:
-
-    ace-lab projects --format json
-    ace-lab agents --project atlas --format json
-    ace-lab services --project atlas --format json
-    ace-lab resolve --id atlas-planner --format json
-    ace-lab route --project atlas --capability search --format json
+# ace-lab
 
-Request a configured operation for an active, managed assignment attempt:
+Environment and project preparation for the local, file-based ACE Lab. Part of
+ACE (Agentic Coding Environment).
 
-    ace-lab service request --project atlas --assignment A --attempt ATT \
-      --operation publish --input release.json --authorization DECISION \
-      --request-id REQUEST --dry-run
-    ace-lab service status --request REQUEST --format json
+> **State owner:** none for task work. `ace-lab` prepares lab environments and
+> projects; task/assignment state belongs to `.ace-tasks/` (ace-task) and the
+> local stores under `.ace-local/`. The canonical flow is
+> [docs/lab-flow.md](../docs/lab-flow.md).
 
-The trusted grants file may also contain exact `operations` and
-`authorizations` mappings. See [usage](docs/usage.md) for the request schema,
-executor transport, and uncertain-state recovery.
+> **Planned (L8):** project onboarding and readiness verification are not
+> available yet; the installer's preparation phase is delivered as
+> `ace-lab prepare` (L8.1).
 
-Every command prints one deterministic JSON document:
+## What exists today
 
-    {"status":"ok","data":{"entry":{"id":"atlas-search","project":"atlas",
-     "capabilities":["search"],"default_for":["search"],
-     "binding":{"kind":"service","state":"available",
-     "endpoint":{"kind":"http","url":"https://search.example.internal"}}}}}
+`ace-lab` is the Lab environment package. Its installer and project-onboarding
+capabilities are the L8 target; today the package ships read-only topology
+queries, the lab status snapshot, and the `prepare` phase. It does not run a
+queue, daemon, journal, authorization service, or command kernel.
 
-Failures are classified: `missing`, `ambiguous`, `stale`, `unauthorized`,
-`invalid_configuration` -- for example a replaced agent process:
+### Topology queries
 
-    {"status":"error","error":{"code":"stale","message":"stable ID
-     \"atlas-planner\" has a stale runtime binding; ...","id":"atlas-planner",
-     "project":"atlas"}}
+Topology configuration uses the ACE configuration cascade
+(`~/.ace/lab/config.yml` or `.ace/lab/config.yml`). Queries never invoke a
+service and never hand credentials to the caller.
 
-### Guarantees
+```bash
+ace-lab projects --format json
+ace-lab agents --project atlas --format json
+ace-lab services --project atlas --format json
+ace-lab resolve --id atlas-planner --format json
+ace-lab route --project atlas --capability search --format json
+```
 
-- **Stable IDs are canonical.** Labels are display values and never resolve.
+Every query prints one deterministic JSON document. Failures are classified
+(`missing`, `ambiguous`, `stale`, `unauthorized`, `invalid_configuration`).
+Stable IDs are canonical; labels are display values and never resolve.
 
-  Exact match or a classified `missing` error.
+### Lab status
 
-- **Public output never leaks.** Tokens, auth-file paths, endpoint userinfo,
+```bash
+ace-lab status                 # configuration + local file state (read-only)
+ace-lab status --format json
+```
 
-  query parameters, fragments, pane/session identifiers, and instance
-  identities are excluded by an allowlist projection, not field redaction.
+`ace-lab status` distinguishes a valid empty set, missing configuration, and a
+source error — never presenting an incomplete lab as empty-and-ready. The
+enriched worktree view stays `ace-git-worktree list`; live terminal layout is
+`ace-herdr status`.
 
-- **Authorization comes from the verified local process owner**, matched
+### Lab preparation (`prepare`, L8.1)
 
-  against configured principals. There is no `--role` or `--principal` flag;
-  identity flags are rejected outright.
+```bash
+ace-lab prepare --dry-run
+```
 
-- **Routing is project-local.** Candidates are capable services of the
+Idempotently prepares accounts, directories (mode/ownership), ed25519 key
+pairs and the role catalog from the trusted root-owned install manifest at
+`/etc/lab/ace-lab/install.yml` (verified fail-closed like the authorization
+document; no `--manifest` flag by design). Reports fingerprints, never key
+material; refuses foreign-takeover of existing directories and key paths
+inside git worktrees. See [docs/usage.md](docs/usage.md) for the manifest
+schema, status table and L8.2–L8.5 boundaries.
 
-  requested project with fresh (active + attested) bindings. Zero candidates
-  are `missing`; several equal candidates need a configured `default_for`, or
-  the result is `ambiguous`. Another project's service is never picked.
+## Not owners of the flow
 
-- **Execution evidence is separate from topology.** `ace-lab service` uses a
+`ace-lab` does not own task state, assignment plans, HITL events, worktrees, or
+a queue. There is no journal, no authority/admission service, no listener that
+blocks ordinary work, and no second state store.
 
-  managed `ace-assign` attempt and its evidence ref. A lost executor receipt
-  remains uncertain and a repeated request ID never replays the effect.
+The installed authority/admission/journal/command path is removed in L1: the
+`service request|status|listen`, `ace-lab assignment …`, `run`, `run-status`,
+and `command execute` commands no longer exist, and the local file-based flow
+does not use them. The Forgejo merge adapter and its trusted configuration
+loader remain as provider building blocks; the local flow does not invoke them.
 
-### Non-goals
+## Install
 
-`ace-lab` does not track Works or schedule anything. `ace-assign` owns attempt
-state; deployed operation handlers and topology values are owned by `lab-config`
-(`8wl.t.gad`); this package defines and validates the schema.
+```bash
+gem install ace-lab
+```
 
-### Development
+## Development
 
-    bundle install
-    bin/ace-test ace-lab all
+```bash
+bin/ace-test ace-lab all
+```