@wairon/cli 5.1.1-dev.102 → 5.1.1-dev.104

package/docs/standards/language-bindings.md

@@ -0,0 +1,120 @@
+# wairon — Language Bindings
+
+> The [Architecture Standard](architecture.md) is language-neutral: it prescribes
+> *strategies* (e.g. "wait-free reads / in-order serialized writes"), not
+> primitives. This appendix maps those strategies onto concrete primitives per
+> language. The structural model (blocks, patterns, `owns`/`dependsOn`, layering)
+> is identical everywhere — only the realization below differs.
+
+---
+
+## Structural mapping
+
+The model assumes a class-with-methods style and method-only interfaces. Every
+mainstream structured language expresses this:
+
+| Concept | Rust | Go | TypeScript / Java / C# / Kotlin | Python |
+|---|---|---|---|---|
+| "class" (component) | `struct` + `impl` | `struct` + methods | `class` | `class` |
+| module of functions (an Orchestrator) | closures capturing the collaborators, or a module of `fn`s taking a `&Deps` | a constructor func returning a struct of closures | TypeScript/Kotlin: a factory `createX(deps)` returning functions closed over `deps`; Java/C#: the class form | a factory returning closures over the collaborators |
+| interface (method contract) | `trait` | `interface` | `interface` | `Protocol` / ABC |
+| port + implementations | trait + impl structs | interface + structs | interface + classes | Protocol + classes |
+| dependency injection | constructor (`new`) | constructor func | constructor | `__init__` |
+
+Interfaces are **method contracts only** (no fields). Languages whose interfaces
+can't declare fields (Rust traits, Go interfaces) lose nothing — fields are an
+implementation detail of the concrete type, never part of the L3 contract.
+
+**Two forms of an Orchestrator.** An Orchestrator holds only its collaborators, so
+it is realized either as a class whose constructor takes them, or as a **module of
+functions** closed over them: a factory takes the collaborators once and returns
+the component's methods as functions that share them. Functional languages use the
+second form natively — a function that takes the collaborators and returns a
+record or map of functions closed over them, or partial application. In both forms
+the collaborators are the component's `dependsOn` and the functions are its L3
+methods, and nothing at module level holds state between calls: domain state
+belongs in a Store, runtime state in an Actor.
+
+---
+
+## Type mapping
+
+Contracts are typed in the neutral grammar of the
+[Architecture Standard](architecture.md#type-expressions-one-neutral-grammar);
+each language spells it with what it has. The TypeScript column is the dialect
+conformance reads code through, and the one an implementer brief carries as
+its `typeMapping`; the others are the idiomatic spellings to follow.
+
+| Neutral | TypeScript | Rust | Python | Go | Java / Kotlin / C# |
+|---|---|---|---|---|---|
+| `string` | `string` | `String` | `str` | `string` | `String` / `String` / `string` |
+| `int`, `float` | `number` | `i64`, `f64` (width per L4) | `int`, `float` | `int64`, `float64` | `long`, `double` |
+| `bool` | `boolean` | `bool` | `bool` | `bool` | `boolean` / `Boolean` / `bool` |
+| `bytes` | `Uint8Array` | `Vec<u8>` | `bytes` | `[]byte` | `byte[]` / `ByteArray` / `byte[]` |
+| `date`, `datetime`, `duration` | `string` (ISO 8601) | `chrono` types | `date`, `datetime`, `timedelta` | `time.Time`, `time.Duration` | `java.time` / `DateTime`, `TimeSpan` |
+| `list<T>` | `T[]` | `Vec<T>` | `list[T]` | `[]T` | `List<T>` |
+| `set<T>` | `Set<T>` | `HashSet<T>` | `set[T]` | `map[T]struct{}` | `Set<T>` |
+| `map<K, V>` | `Record<K, V>` | `HashMap<K, V>` | `dict[K, V]` | `map[K]V` | `Map<K, V>` / `Dictionary<K, V>` |
+| `T?` | `T \| null` | `Option<T>` | `T \| None` | `*T` | nullable `T` / `T?` |
+| `A \| B` | `A \| B` | `enum` with payload | `A \| B` | an interface both implement | `sealed` hierarchy |
+| `async T` | `Promise<T>` | `async fn` → `T` | `async def` → `T` | a blocking call or a channel | `CompletableFuture<T>` / `suspend` / `Task<T>` |
+| `result<T, E>` (returns only; `result<void, E>` for `Result<(), E>`) | `T`, throwing `E` on failure (`void` for `result<void, E>`) | `Result<T, E>` (`()` for `void`) | `T`, raising `E` | `(T, error)` | `T` with `throws E` / `Result<T>` / `T`, throwing `E` |
+| enum `E` | `type E = 'a' \| 'b'` | `enum E` | `class E(StrEnum)` | typed `string` constants | `enum E` |
+| named scalar `E` holding `P` | `type E = P` | `struct E(P)` | `E = NewType('E', P)` | `type E P` | a value class / `@JvmInline value class E` / `record struct E(P)` |
+| `any` | `unknown` | `serde_json::Value` | `Any` | `any` | `Object` / `Any` / `object` |
+
+---
+
+## Concurrency strategy → primitives
+
+### Default: wait-free reads / in-order serialized writes
+
+Readers load a snapshot reference without blocking; writers are serialized so they
+apply in order; on commit the reference is atomically swapped for all readers;
+values are held by reference so the swap is pointer-only.
+
+| Language | Reads | Writes |
+|---|---|---|
+| **Rust** | `ArcSwap<T>::load()` (wait-free) | `Mutex<()>` to serialize, clone-and-`store(Arc::new(...))` |
+| **Go** | `atomic.Value` / `atomic.Pointer[T]` load | `sync.Mutex` to serialize, store new pointer |
+| **Java** | `AtomicReference<T>.get()` | a lock to serialize, `set(newRef)` (or `ConcurrentHashMap` for maps) |
+| **C#** | `Volatile.Read` / `Interlocked` ref read | `lock` to serialize, swap reference |
+| **TypeScript (Node)** | single-threaded event loop — a plain reference read | sequential by the event loop; for workers use a message-passing queue |
+
+### Single value, simple read-modify-write (counter, flag)
+
+| Language | Primitive |
+|---|---|
+| Rust | `AtomicU64::fetch_add` / `compare_exchange` |
+| Go | `atomic.AddInt64` / `atomic.CompareAndSwap` |
+| Java | `AtomicLong.incrementAndGet` |
+| C# | `Interlocked.Increment` / `CompareExchange` |
+| TS (Node) | sequential on the event loop; `Atomics` on a `SharedArrayBuffer` across workers |
+
+Prefer the atomic op over a lock for a single value: it is one wait-free
+instruction, totally ordered, and cheaper than a mutex (which is itself built on
+atomics and may incur a syscall + context switch under contention). Use a
+compare-and-set **retry loop** only for a compound update of one location that has
+no single-instruction equivalent — never as a general strategy over composite
+state (it can livelock and wastes cycles).
+
+### Exceptions to the default
+
+| Situation | Rust | Go | Java |
+|---|---|---|---|
+| write-heavy large map | `DashMap` (sharded) or `im`/`rpds` (persistent) | sharded `map`+`RWMutex`, or `sync.Map` | `ConcurrentHashMap` |
+| cross-store atomic transaction | DB transaction via the Adapter | DB transaction via the Adapter | DB transaction via the Adapter |
+| single-writer (Actor) state | `ArcSwap` reads, no write lock | `atomic.Pointer`, no mutex | `AtomicReference`, no lock |
+| non-shared / write-once | plain ownership / `OnceCell` | plain field / `sync.Once` | `final` / `OnceCell` equivalent |
+
+---
+
+## Notes
+
+- In single-threaded runtimes (Node.js) the concurrency machinery collapses to
+  plain references; apply the *strategy* (one writer at a time, readers see a
+  consistent snapshot) at the worker/message-queue boundary instead.
+- The zero-copy/reference rule (§11 of the standard) assumes shared references are
+  cheap and safe. Where a language copies by value, use the language's shared-
+  reference type (smart pointer / GC reference) so Indexes hold pointers, not value
+  copies.

package/docs/templates.md

@@ -0,0 +1,61 @@
+# wairon — Templates
+
+A **template** is a reusable agent *shape*: a YAML file with metadata and an
+`instructions` body that is rendered (with the agent's id, name, owned paths,
+etc.) into the agent's brief. Templates are rendering shapes only — they are
+not a source of truth. The agent topology itself is derived from the spec tree.
+
+Every brief is composed live (`sdd_get_agent_brief`, `wairon agent brief <id>`)
+from the current tree. The same rendering is written to agent files on disk
+only when the project sets `rules.materializeAgentFiles: true`.
+
+Built-in templates live in `src/templates/*.yaml`. Project-local overrides can be
+placed in `.wai/templates/`.
+
+---
+
+## Built-in templates
+
+| Template | Used for |
+|----------|----------|
+| `architect` | The `system-architect` meta-agent (maintains the spec tree) |
+| `domain-owner` | A `<subsystem>-owner` or free-standing domain owner |
+| `implementer` | A `<component>-implementer` (writes code 1:1 from a spec) |
+| `reviewer` | A review-focused agent shape |
+| `tester` | A testing-focused agent shape |
+| `guardian` | A meta/guardian agent shape |
+
+`agent_resolver` picks the template for each derived agent (`architect`,
+`domain-owner`, `implementer`).
+
+---
+
+## Template format
+
+```yaml
+id: domain-owner
+name: Domain Owner
+version: 1.0.0
+description: Short description.
+requiresOwnedPaths: true
+defaultTags: []
+instructions: |
+  You are **{{agentName}}**.
+  Owns: {{ownedPaths}}
+```
+
+### Available render variables
+
+`{{agentId}}`, `{{agentName}}`, `{{agentDescription}}`, `{{ownedPaths}}`,
+`{{tags}}`.
+
+---
+
+## SDD skills (not templates)
+
+The five SDD skill files in `src/templates/skills/` (`sdd-architect`,
+`sdd-narrative`, `sdd-auditor`, `sdd-implement`, `sdd-delegate`) are different:
+they are copied verbatim (with the
+CLI command substituted) into each target tool's `skills/` directory by
+`wairon skills install` and `wairon generate`. They drive the spec-driven
+workflow in-session rather than rendering an agent file.

package/docs/vision.md

@@ -0,0 +1,59 @@
+# wairon — Vision
+
+> Long-term product direction. Aspirational; implementation is phased
+> (see [roadmap.md](roadmap.md)).
+
+---
+
+## North star
+
+wairon makes **architecture itself the interface** between humans and AI coding
+tools. You describe a system once as a validated spec tree; from it, wairon
+derives the agents that build it and enforces the boundaries they must respect —
+so AI-generated code is structurally correct and conformant by construction, not
+by review.
+
+The differentiator is not "spec-driven development" in general (many tools do the
+prose-spec → plan → tasks loop). It is the **architecture-conformance engine**:
+typed component stereotypes with enforced dependency rules, contract↔
+implementation symmetry, narrative-to-code mapping, and cycle detection — checked
+as a gate before code is written.
+
+---
+
+## Principles that don't change
+
+- **Specs are the source of truth.** Agents, boundaries, and conformance are
+  derived from `.wai/specs/`. Generated files are outputs.
+- **wairon equips, it does not orchestrate.** It produces native subagents,
+  installs skills, and exposes MCP tools. The host AI tool (Claude Code, Gemini
+  CLI, …) runs the session and spawns its own subagents.
+- **Optional, then strict.** A project opts in by creating a spec tree. Once
+  enabled, the workflow is enforced: design before code, spec is law,
+  human-in-the-loop.
+- **`.wai/` boundary, file-based, offline core.** All state is human-readable
+  files under `.wai/`; no database, and the core workflow needs no daemon or
+  network. Hosting (`wairon serve`) is an opt-in server over the same files.
+
+---
+
+## Where it goes
+
+1. **Deeper conformance.** Glob-aware ownership, richer stereotype rules,
+   actionable remediation — the engine becomes a true architecture linter for AI
+   codegen.
+2. **Adoption without greenfield.** Derive a draft spec tree from existing code
+   so teams can apply conformance to what they already have.
+3. **CI as the gate.** `wairon validate --ci` in PR checks, with conformance
+   diffs reported on the change.
+4. **Org scale.** Shared standards and template libraries across repos.
+
+---
+
+## What was deliberately dropped
+
+An earlier vision positioned wairon as a local AI **orchestration hub** —
+spawning sessions, multi-model pipelines, git worktrees, a session wrapper. That
+fought the host tools (which now have native subagents and worktrees) and spread
+the product thin. wairon instead does one thing well: turn a validated spec tree
+into a conformance gate plus the topology and skills a host AI tool consumes.

package/docs/wairon-feature-requests-hosted-mcp.md

@@ -0,0 +1,74 @@
+# Wairon Feature Request: Hosted, Multi-Tenant MCP Server
+
+**Requested by:** Robbe Vrijenhoek (Appenser / wairon wrapper project)
+**Date:** 2026-07-04
+**Context:** Building Appenser, a Make.com doctrine wrapper on wairon. Working entirely from within Langdock (an enterprise AI platform) rather than a local Claude Code / Gemini CLI setup surfaced several gaps between wairon's current (local, CLI-first) execution model and a hosted, multi-tenant, MCP-only usage pattern. This document summarizes the capabilities we'd like wairon to support.
+
+---
+
+## 1. Hosted, multi-tenant MCP server mode
+
+**Problem today:** `wairon mcp serve` is documented as a local process, `stdio`-attached to a single coding tool working against a single on-disk repo. There's no mode for running wairon as a standing service that multiple clients/projects can connect to remotely.
+
+**Request:** A `wairon mcp serve --http` (or similar) mode that:
+- Exposes the existing `sdd_*` tool surface over **streamable HTTP**, not just stdio, so it can be reached by remote MCP clients (e.g. a Langdock custom agent) rather than only a co-located CLI tool.
+- Can be packaged as a **Docker image** for self-hosting (e.g. on GCP, or any container platform) — a self-contained binary with an HTTP wrapper, no external dependencies required for a basic deployment.
+- Persists spec trees to a **local/mounted filesystem** (`/data/projects/<project-id>/.wai/...`) so wairon itself is the source of truth and durability layer — not dependent on any particular git host to function.
+
+**Why:** Removes the need to run wairon inside a sandboxed AI-tool shell (fragile, non-persistent, no real network access in many AI platform sandboxes) and instead lets any MCP-capable client connect to a real, durable, always-on wairon instance.
+
+---
+
+## 2. Multi-project support behind a single MCP endpoint, scoped by authentication (not by client-supplied parameters)
+
+**Problem today:** No multi-tenancy model exists. A hosted instance needs to serve many independent spec trees ("projects"/workspaces) without one client being able to access another's data.
+
+**Request:**
+- A single running wairon MCP endpoint should be able to serve **multiple projects**, each with its own isolated `.wai/` spec tree.
+- **Project scope must be derived from the authenticated session/token, not from a client-supplied parameter.** I.e., an API key/OAuth token issued for Project A must be server-side bound to Project A; the server rejects or ignores any attempt by that token's calls to reach another project's tree. A `project` selector parameter is acceptable as a convenience for tokens explicitly authorized for multiple projects, but must never itself be the authorization mechanism.
+- Explicitly **not requesting** a model where a new MCP server process is spawned per project — that adds operational complexity (process/port lifecycle, discovery) without a corresponding benefit, since MCP tool calls can be made stateless per-request against a shared service.
+
+**Why:** This is the standard, defensible multi-tenant pattern (auth-derived scope) and avoids both the operational cost of per-project server spawning and the security risk of trusting client-declared scope.
+
+---
+
+## 3. Authentication layer for the hosted MCP server
+
+**Problem today:** No auth story exists for a networked MCP server (local `stdio` mode has no need for one).
+
+**Request:** Support at least one straightforward auth mechanism suitable for internal/company deployments as a v1 — e.g. static API keys mapped to authorized project ID(s) via a config file or injected secret — with a clear upgrade path to OIDC/OAuth for broader or external exposure later. Full enterprise identity federation is **not** a v1 requirement; a defensible internal-tool-grade auth model is sufficient to start.
+
+---
+
+## 4. Privileged, commit-scoped `sdd_init` and `sdd_lock` MCP tools, with re-validation enforced at merge time
+
+**Problem today:** `wairon init` and `wairon lock` are CLI-only, unavailable via MCP. If exposed via MCP naively, a "lock" recorded once could be trusted even after the underlying branch/commit has since changed — a stale-approval / time-of-check-to-time-of-use gap.
+
+**Request:**
+- Expose `sdd_init` and `sdd_lock` as MCP tools, but treat them as **privileged** relative to the rest of the `sdd_*` surface (e.g. only callable by a specifically authorized identity/role, such as a hosting/orchestration layer rather than every ordinary editing session).
+- `sdd_lock` must:
+  1. Run `wairon validate` fresh, at the current state of the spec tree.
+  2. Only if validation passes, write a **lock record scoped to the exact commit/state it validated** (e.g. `{ stateId/commitSha, lockedAt, validationResult }`), not a free-floating "this project is locked" flag.
+  3. **Never perform a merge to any main/production branch or state itself.** At most, it should be able to open/update a pull request (if git-backed) or mark a change-set as "ready," leaving the actual promotion action to a separate, human-gated step.
+- Whatever mechanism promotes locked changes to the canonical/production state (a git merge, or an equivalent "promote" action in wairon's own native storage) must **re-check that the lock record's scoped commit/state ID matches the current state exactly** before allowing promotion. Any change made after locking must invalidate the lock automatically (by the state ID no longer matching), forcing re-validation and re-locking — not by requiring anyone to remember to manually invalidate a stale lock.
+
+**Why:** This closes a real correctness/safety gap: without commit-scoped lock validity plus a mandatory re-check at promotion time, it's possible to lock a valid spec tree, make further (possibly broken) changes, and still merge/promote on the strength of the earlier, now-stale lock.
+
+---
+
+## 5. (Lower priority / later) Pluggable persistence & sync backends
+
+**Problem today:** If/when git-backed persistence is desired, wairon currently has no first-class model for it, and we don't want to hard-couple wairon's core storage model to one git host (GitHub) on day one — GitLab, other git hosts, or entirely non-git backends (e.g. Notion) may be desirable later.
+
+**Request:** Treat wairon's own native on-disk (or hosted-instance-managed) storage as the primary source of truth, and treat git-host integration (GitHub, GitLab, etc.) or other external sync targets as **optional export/mirror/sync features** layered on top — e.g. a future `wairon sync --git <remote>` — rather than a required dependency for wairon to function at all.
+
+**Why:** Keeps wairon host-agnostic and avoids picking a single vendor's collaboration model (PRs, branch protection, etc.) as the only supported workflow.
+
+---
+
+## Explicitly out of scope / not being requested
+
+- Per-project MCP server process spawning (see #2).
+- A `wairon generate --target <specific-AI-platform>` "subagent" template for platforms that don't support isolated subagent dispatch the way Claude Code/Gemini CLI do — this pattern is only valuable where the host tool provides genuine context isolation for spawned subagents; generating a redundant role-description file for a platform without that mechanism (which we already read the underlying specs directly) adds no value and was considered and rejected during our own design process.
+- Full enterprise SSO/identity federation as a v1 requirement for the hosted MCP server.
+- `sdd_lock` (or any MCP tool) performing an actual merge/promotion to a production branch/state — this must remain a separately gated action.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wairon/cli",
-  "version": "5.1.1-dev.102",
+  "version": "5.1.1-dev.104",
   "description": "SYW Waffle AIron — CLI for managing AI coding agent topology across projects",
   "keywords": [
     "ai",
@@ -28,7 +28,9 @@
   "files": [
     "dist",
     "schemas",
-    "README.md"
+    "README.md",
+    "docs/*.md",
+    "docs/standards/**"
   ],
   "workspaces": [
     "sdk"