Skip to content

Phase review: housekeeping + #174 subclass + Category B publish + docs reorg #196

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Argocyte wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Phase review: housekeeping + #174 subclass + Category B publish + docs reorg #196

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2682ef7
feat(orchestrator): refactor 361→313 lines + fix stale domain references
Argocyte Apr 12, 2026
0b26921
feat(clerk): add subclass field to log_labour — closes #174
Argocyte Apr 12, 2026
87555b5
docs: Category B publish + docs reorg + README repo structure update
Argocyte Apr 12, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 7 additions & 55 deletions .claude/skills/dev-orchestrator/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ version: 1.0.0

The dev-orchestrator convenes a **session cooperative** — a temporary S3 delegate
circle that forms at session start around the current drivers and dissolves at session
end. It reads state from all 7 persistent domain cooperatives, classifies felt
end. It reads state from all 10 persistent domain cooperatives, classifies felt
tensions, and facilitates a wave of steward convocations on behalf of the domain roles
that hold each driver. The result is a surface report carrying completed agreements,
blockers, decisions needing Lola's consent, lateral handoffs, and failed drivers.
Expand Down Expand Up @@ -69,12 +69,12 @@ skills; the orchestrator convenes them, it does not replicate them.

Vocabulary, roles, patterns, and what OpenClaw already provides live in
`references/cooperative-topology.md` — read it before drafting any brief. The
orchestrator is a **facilitator + secretary**; the 7 domain roles are double-linked
orchestrator is a **facilitator + secretary**; the 10 domain roles are double-linked
peers, each a member of the session cooperative and of their own persistent domain
cooperative. Drivers motivate action; tensions are felt gaps; agreements have review
dates. Four roles hold **standing paramount objection rights**: compliance on
security-affecting changes, review-desk on any merge to main, phase-b-architecture on
unconsented ADRs, governance-clerk on weakening S3 governance patterns. Any other
security-affecting changes, review-desk on any merge to main, architecture on
unconsented ADRs, governance on weakening S3 governance patterns. Any other
role may raise a one-off objection during the convening round.

---
Expand All @@ -86,7 +86,7 @@ procedure convene_session_cooperative(budget):
surface = UpstreamReport() # fed back to Lola via the project-cooperative link

# Session cooperative forms around current drivers.
# 7 domain representatives hold dual membership: session coop + their own domain coop.
# 10 domain representatives hold dual membership: session coop + their own domain coop.
session_coop = convene([
governance, compliance, infrastructure, operations,
architecture, review_desk, roles, researcher,
Expand Down Expand Up @@ -250,57 +250,9 @@ Primary drivers sourced from `references/cooperative-topology.md` §4. Old domai

---

## Hard Rules (Paste Into Every Brief)
## Hard Rules

```
## Iskander Invariants — DO NOT VIOLATE

1. Glass Box before every write — log to Glass Box in a separate step *before* the write
2. Agents draft, humans sign — no signing keys in agents, no auto-submit
3. Constitutional Core is immutable — no bypass for ICA principle checks
4. Tombstone-only lifecycle — mark tombstoned, never DELETE
5. Boundary layer sequential — 5 gates in order: Trust → Ontology → Governance → Causal → GBWrap
6. Self-responsibility — own ets mistakes openly without prior consent; mistakes stay on record

If any change would weaken, bypass, or reorder one of these, STOP and surface it.
Phantom invariants currently tracked: #147 (tombstone in decision-recorder),
#148 (manifest SHA-256 lock). Cite them if your scope touches them.

## Verification hook (answer before returning "done")
- [ ] Did this change touch a Glass Box gate, a signing path, a principle check,
a delete path, or the boundary layer?
- [ ] If yes — which invariant(s), and how is the change consistent with them?

## Data sovereignty rule (review-desk paramount objection scope, 2026-04-11)
External state changes (PR merges, issue filings, GitHub comments, discussions, posts,
external API writes) REQUIRE Lola's explicit consent. Drafts live in Et's sovereign
zone (memory + plan files + worktree files) until consent is given. The merge IS the
boundary between Et's local sovereignty and external commitment.

EXCEPTION (self-responsibility carve-out): apology comments and corrective notes for
Et's own past mistakes do NOT need prior consent. Test: would the action exist if Et
had not made the mistake? Yes = self-responsibility (no consent needed). No = new
external commitment (consent needed). See `cooperative-topology.md` §10.

## S3 vocabulary
Don't say: manager / task / assign / dispatch to / queue / worker / report to
Say instead: domain role / driver / accept driver / convene steward for /
backlog of drivers / lateral handoff / is double-linked with

## Agreement rule
Every agreement has a review date — no exceptions. An agreement without a review date
is invalid and will be rejected by the review-desk steward.

## Model rule
The model parameter on every dispatched subagent must be explicit. Never rely on
inheritance from the calling session.

## Confirmation protocol
Return a short confirmation — files touched with line ranges, test results,
invariant checklist, tensions raised to other domains. Do NOT return full file contents.
```

Full paste-box and verification hook sourced from `references/invariants-cheatsheet.md`.
**Read `references/invariants-cheatsheet.md` and paste its content into every brief.** The cheatsheet contains the 6 invariants, verification hook, data sovereignty rule, S3 vocabulary, agreement rule, model rule, and confirmation protocol. Do not inline them here — the cheatsheet is authoritative.

---

Expand Down
88 changes: 38 additions & 50 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -196,61 +196,49 @@ Every aspect of Iskander is designed around the seven cooperative principles:
```
iskander/
+-- README.md
+-- CLAUDE.md # Working conventions + invariants + how Et works
+-- CLAUDE.md # How Et works — cooperative governance + invariants
+-- CONTRIBUTING.md # Contribution guidelines
+-- SECURITY.md # Security policy
+-- .claude/skills/ # Et's fractal domain skills (10 domains + orchestrator)
| +-- dev-orchestrator/ # Session cooperative facilitator
| +-- governance/ # S3 facilitation, tensions, agreements, Clerk
| +-- compliance/ # Security + regulatory (was red-team)
| +-- infrastructure/ # Installer, Helm, supply chain
| +-- operations/ # Phase C.5 ops backbone
| +-- architecture/ # ADR stewardship
| +-- review-desk/ # PR review, merge gate
| +-- roles/ # Cooperative role coverage
| +-- researcher/ # Domain skill system self-improvement
| +-- historian/ # Session review, institutional memory
| +-- communications/ # Public voice, outreach
+-- docs/
| +-- roadmap.md # Phased project roadmap
| +-- overview.md # Non-technical overview for members
| +-- plan.md # Detailed technical plan (Route C -> B)
| +-- plan.md # Technical plan (Route C -> B)
| +-- roadmap.md # Phased project roadmap
| +-- white-paper.md # Technical and philosophical rationale
| +-- red-team-threat-model.md # Living development threat model
| +-- legacy-audit.md # Legacy module disposition
| +-- essays/ # Long-form cooperative-governance reflections
| +-- legacy-audit.md # Legacy backend module disposition (feeds #128)
| +-- archive/ # Archived design specs
+-- skills/ # Claude Code skill plugins
+-- src/
+-- IskanderOS/
| +-- openclaw/ # AI agent system
| | +-- openclaw.json # OpenClaw configuration
| | +-- agents/
| | | +-- orchestrator/ # Agent coordinator
| | | +-- clerk/ # Member-facing assistant (Loomio + Mattermost)
| | | +-- steward/ # Treasury monitor
| | +-- skills/
| | +-- loomio-bridge/ # Loomio API integration
| | +-- mattermost-bridge/ # Mattermost API integration
| | +-- document-collab/# AI-assisted document drafting
| | +-- values-reflection/
| | +-- glass-box/ # Audit trail
| | +-- treasury-monitor/
| | +-- membership/ # Join/leave/onboard
| +-- services/
| | +-- authentik/ # SSO identity provider
| | +-- loomio/ # Governance platform
| | +-- mattermost/ # Real-time team chat
| | +-- nextcloud/ # Files, calendar, email
| | +-- vaultwarden/ # Credential management
| | +-- backrest/ # Backup management
| | +-- beszel/ # System monitoring
| | +-- cloudflared/ # Tunnel for public access
| | +-- headscale/ # Mesh VPN for federation
| | +-- decision-recorder/ # Webhook service (FastAPI)
| | +-- website/ # Public cooperative website
| +-- infra/
| | +-- k3s/ # K3s manifests and Helm charts
| | +-- ansible/ # Installation playbooks
| | +-- decision_log.sql # Database schema
| +-- contracts/ # Solidity smart contracts
| | +-- src/
| | +-- Constitution.sol
| | +-- CoopIdentity.sol # ERC-4973 Soulbound Tokens
| | +-- governance/
| | +-- MACIVoting.sol # ZK secret ballot voting
| +-- scripts/
| | +-- install.sh # curl|sh entry point
| | +-- first-boot.py # Interactive setup wizard
| +-- docs/ # ICA reference documents
| +-- legacy/ # Archived: previous backend, frontend, agents
| +-- funding/ # NLnet application + funding materials
| +-- reference/ # ICA guidance, peer project analyses
| +-- templates/ # Governance templates (consent proposal, etc.)
| +-- whitepapers/ # Audience-specific whitepaper variants
| +-- archive/ # Pre-architecture design specs
+-- src/IskanderOS/
| +-- openclaw/ # AI agent system (Cooperative API)
| | +-- agents/{clerk,steward,sentry}/ # Runtime agents with SOUL.md
| | +-- tests/ # 15 passing tests
| +-- services/
| | +-- decision-recorder/ # Glass Box + governance state (FastAPI)
| | +-- provisioner/ # Membership provisioning
| +-- contracts/ # Solidity smart contracts
+-- infra/
| +-- helm/ # K3s Helm charts for all services
| +-- ansible/ # Installation playbooks
+-- install/ # curl|sh entry point
```

> **Note:** Hardware work (previously at `src/IskanderHearth/`) has moved to its own repository at [`Argocyte/IskanderHearth`](https://github.com/Argocyte/IskanderHearth) as of 2026-04-11. See the "Sibling repositories" section above for the three-repo public foundation.
> **Note:** Hardware work lives at [`Argocyte/IskanderHearth`](https://github.com/Argocyte/IskanderHearth). Legacy code archived to [`Argocyte/iskander-legacy`](https://github.com/Argocyte/iskander-legacy) (private). Data commons at [`Argocyte/Iskander-data`](https://github.com/Argocyte/Iskander-data).

---

Expand Down
Loading
Loading