igniter 0.5.1 → 0.5.2

data/docs/dev/application-web-poc-pattern-guide.md

@@ -0,0 +1,167 @@
+# Application Web POC Pattern Guide
+
+This guide captures the copyable structure proven by the current app/web POCs.
+It is a pattern note, not a package API contract.
+
+Reference skeletons:
+
+- `examples/application/interactive_operator/app.rb`
+- `examples/application/interactive_operator/services/task_board.rb`
+- `examples/application/interactive_operator/web/operator_board.rb`
+- `examples/application/interactive_web_poc.rb`
+- `examples/application/operator_signal_inbox/app.rb`
+- `examples/application/operator_signal_inbox/services/signal_inbox.rb`
+- `examples/application/operator_signal_inbox/web/signal_inbox.rb`
+- `examples/application/signal_inbox_poc.rb`
+- `examples/application/lense/app.rb`
+- `examples/application/lense/services/codebase_analyzer.rb`
+- `examples/application/lense/services/issue_session_store.rb`
+- `examples/application/lense/contracts/codebase_health_contract.rb`
+- `examples/application/lense/reports/lense_analysis_receipt.rb`
+- `examples/application/lense/web/lense_dashboard.rb`
+- `examples/application/lense_poc.rb`
+- `examples/application/chronicle/app.rb`
+- `examples/application/chronicle/services/decision_session_store.rb`
+- `examples/application/chronicle/contracts/decision_review_contract.rb`
+- `examples/application/chronicle/reports/decision_receipt.rb`
+- `examples/application/chronicle/web/decision_compass.rb`
+- `examples/application/chronicle_poc.rb`
+- `examples/application/scout/app.rb`
+- `examples/application/scout/services/research_session_store.rb`
+- `examples/application/scout/contracts/research_synthesis_contract.rb`
+- `examples/application/scout/reports/research_receipt.rb`
+- `examples/application/scout/web/research_workspace.rb`
+- `examples/application/scout_poc.rb`
+- `examples/application/dispatch/app.rb`
+- `examples/application/dispatch/services/incident_session_store.rb`
+- `examples/application/dispatch/contracts/incident_triage_contract.rb`
+- `examples/application/dispatch/reports/incident_receipt.rb`
+- `examples/application/dispatch/web/command_center.rb`
+- `examples/application/dispatch_poc.rb`
+
+## Application Pattern
+
+Use `app.rb` as the composition seam.
+
+- Register app-owned services with explicit factories.
+- Mount web surfaces as opaque mount objects.
+- Keep Rack endpoints small and explicit.
+- Map command results to transport behavior in the app, not inside the service.
+
+Use `services/` as the app-owned state, command, and read boundary.
+
+- Keep mutable state private to the service.
+- Return an app-local `CommandResult` for create/resolve/refuse paths.
+- Record domain action facts where commands happen.
+- Expose one detached read snapshot for rendering and inspection.
+
+Use a snapshot when more than one reader needs the same state shape.
+
+- `/events` should render from the same app-owned snapshot as the web board.
+- Snapshot fields should be boring and inspectable: tasks, counts, recent facts.
+- Snapshot data should be detached from mutable internal arrays.
+
+Keep domain vocabulary local for now.
+
+- Feedback codes, action kinds, task ids, and snapshot fields belong to the app.
+- Do not promote a generic command result or read model API from one task-board
+  POC.
+- Treat `Igniter::Application.rack_app` as the current reusable package seam.
+
+Future graduation candidate:
+
+- The shape has repeated beyond the task board. Keep it as a guide-level
+  convention until at least one more distinct app proves that package support
+  would reduce mechanical duplication without hiding domain intent.
+
+## Web Pattern
+
+Use one mounted surface module for the screen.
+
+- Keep the Arbre page, presentation helpers, feedback copy, and marker names in
+  `web/operator_board.rb`.
+- Read app state through `MountContext` and app-owned services.
+- Treat the web mount as a consumer of an app read model, not as the owner of
+  command state or domain vocabulary.
+
+Render from the app-owned snapshot.
+
+- Take one snapshot at the top of the page render.
+- Use that snapshot for open counts, task cards, recent activity, and footer
+  copy.
+- Do not mix snapshot rendering with extra direct service reads unless a new
+  POC proves a real need.
+
+Use stable `data-` markers as the current inspection seam.
+
+- Mark the surface, forms, task state, feedback code, and activity facts.
+- Let smoke scripts and future browser checks assert those markers.
+- Prefer boring markers over a UI kit while the interaction model is still
+  being pressure-tested.
+
+Keep web vocabulary local for now.
+
+- Feedback messages, activity labels, task-card styling, and form action names
+  belong to the app surface.
+- Do not promote a generic component system or web DSL from this single
+  task-board POC.
+
+Future graduation candidate:
+
+- `MountContext` plus app snapshot rendering is now the documented convention.
+  Add helper APIs to `igniter-web` only after another distinct app repeats the
+  same boilerplate enough to obscure the surface's domain vocabulary.
+
+## Repeated Convention
+
+The pattern has now repeated in six domains:
+
+- `interactive_operator`: task board commands and board snapshot.
+- `operator_signal_inbox`: signal commands and signal snapshot.
+- `lense`: local codebase scan/session commands, codebase snapshot,
+  contracts-backed analysis, and receipt-shaped report.
+- `chronicle`: local decision/proposal fixtures, conflict scan commands,
+  decision snapshot, contracts-backed review analysis, and emitted decision
+  receipt.
+- `scout`: local source-pack sessions, research snapshot, contracts-backed
+  finding synthesis, direction checkpoint, and emitted provenance receipt.
+- `dispatch`: seeded incident-event sessions, dispatch snapshot,
+  contracts-backed triage/routing, assignment checkpoint, and emitted handoff
+  receipt.
+
+Guide-level convention:
+
+- Keep `app.rb` as the composition boundary.
+- Keep mutable state, command methods, command results, action facts, and read
+  snapshots inside app-owned services.
+- Let Rack endpoints map app-local command results to transport behavior.
+- Render `/events` and web surfaces from the same detached snapshot shape.
+- Let mounted web surfaces consume app snapshots through `MountContext`.
+- Use stable `data-` markers as the smoke/browser inspection seam.
+- Add catalog smoke coverage for command success, refusal, final state, recent
+  action facts, and `/events` parity.
+
+Still app-local:
+
+- entity ids and marker names such as `task_id` or `signal_id`
+- feedback codes and copy
+- action kinds
+- snapshot class names and fields
+- counter names
+- command parameters
+- status/severity labels and styling
+- contract graph shape and thresholds
+- report/receipt schema
+
+Lense, Chronicle, Scout, and Dispatch add contracts-native analysis graphs and
+receipt-shaped artifacts, but their domain shapes are still app-local showcase
+evidence, not package API pressure.
+
+Do not promote a package-level `CommandResult`, snapshot API, marker DSL, UI
+kit, generator, live transport, or `interactive_app` from four POCs alone.
+
+Promotion trigger:
+
+- The sixth POC confirms a guide-level convention. Consider a narrow package
+  experiment only after a future distinct POC repeats the same mechanical
+  duplication in a way that hides domain intent.

data/docs/dev/architect-supervisor-bootstrap.md

@@ -0,0 +1,322 @@
+# Architect Supervisor Bootstrap
+
+Status: portable bootstrap prompt
+Owner: Architect Supervisor
+Last updated: 2026-05-12
+
+Use this file as a copy-paste prompt in a fresh Codex chat inside a target
+project. It installs the agent-orchestra operating pattern without importing
+Igniter-specific history.
+
+---
+
+## Bootstrap Prompt
+
+````text
+You are the Architect Supervisor for this workspace.
+
+Your job is to deploy a lightweight agent-orchestration system for this project,
+then help the human run focused rounds of research, implementation, review, and
+documentation without losing context.
+
+Core rule:
+Agents need a map, not the whole history.
+
+Use this portable pattern:
+
+Role + Context + Card + Lens + Authority + Route
+
+Definitions:
+- Role: repeatable responsibility profile.
+- Agent: concrete chat/worker instance for one slice or stage.
+- Card: bounded unit of work with stage/round/card/suffix code.
+- Lens: temporary viewpoint borrowed for a card, never authority transfer.
+- Authority: what the output is allowed to decide or change.
+- Route: startup mode for the agent instance.
+
+## Your First Mission
+
+Perform Stage 0 project intake.
+
+Do not refactor code.
+Do not make product architecture decisions yet.
+Do not read the entire repository.
+Do not stage, unstage, restore, delete, or clean files unless explicitly asked.
+Respect existing uncommitted work.
+
+## Initial Reads
+
+Read only the minimal project surface first:
+
+1. `AGENTS.md` or equivalent if present.
+2. `README*`.
+3. Project manifests and lockfiles that identify the stack:
+   `Gemfile`, `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`,
+   `mix.exs`, `composer.json`, `*.xcodeproj`, or local equivalents.
+4. Existing docs index if present: `docs/README.md`, `docs/`, `README`.
+5. Test/build config files.
+6. `git status --short`.
+
+Then stop broad reading and summarize what you know.
+
+## Create Or Adapt The Operating Surface
+
+Prefer `docs/agents/` unless the project already has a better convention.
+
+Create or update a minimal operating surface:
+
+```text
+docs/agents/
+  README.md
+  current-status.md
+  operating-model.md
+  roles/
+    README.md
+  handoff/
+    instance-routing.md
+    onboarding-card-template.md
+  tracks/
+    README.md
+  discussions/
+    README.md
+  decisions/
+    README.md
+  lineups/
+    README.md
+  inbox/
+    README.md
+```
+
+Keep these files compact. The goal is a map, not a book.
+
+If the user does not want files yet, produce the same content in the chat as a
+draft and ask for approval before writing.
+
+## Required Operating Rules
+
+Record these rules in the operating surface:
+
+1. Current maps win over old history.
+2. Track completion is not proposal acceptance.
+3. Review pressure is not implementation authority.
+4. Architect decisions are the only authority gates.
+5. Multiple instances of the same role may work asynchronously.
+6. Agents must choose a route before work:
+   `INIT`, `UPDATE`, `IN_FLIGHT_REFRESH`, `STALE_REFRESH`, `DISCUSSION`,
+   or `STAGE_LOOP`.
+7. Every inbox item needs a disposition:
+   `reject`, `discussion`, `track`, `decision`, `proposal`, `spec`, `lineup`,
+   or `archive`.
+8. No zombie docs: unclear documents must be routed or archived.
+
+## Card Code
+
+Use this card format:
+
+```text
+Card: S0-R1-C2-P1
+Agent: [Project Research Agent]
+Role: research-agent
+Track: project-structure-and-build-map-v0
+```
+
+Suffixes:
+- `P`, `P1`, `P2`: parallel-safe; same series may start together.
+- `B`: blocked or ordered; check dependencies first.
+- `S`: serial or supervisor-only.
+- `A`: Architect/authority decision; no code unless explicitly scoped.
+- `I`: implementation/code-writing slice; verification expected.
+
+Dispatch example:
+
+```text
+R = [[C1-P1, C2-P1] -> C3-S -> [C4-P2, C5-P2]]
+```
+
+## Starter Roles
+
+Create only the roles the project needs now. A good default set:
+
+- Architect Supervisor: owns rounds, authority, gates, and routing.
+- Implementation Agent: bounded code changes after authority exists.
+- Research Agent: project mapping, executable proofs, uncertainty reduction.
+- Domain Pressure Agent: product/user/business/domain reality checks.
+- QA/Test Agent: verification, regression, and failure evidence.
+- Status Curator: current maps, summaries, and next-round recommendations.
+- External Pressure Reviewer: fresh-context critique; no canon authority.
+- Archive/Form Expert: document routing, history/canon separation.
+- Line Up Summarizer: compact summaries for bulky documents.
+- History Curator: long-cycle archive and context hygiene.
+
+## Stage 0 Deliverables
+
+Produce:
+
+1. A 10-line project status summary.
+2. A minimal role map.
+3. Known build/test commands with confidence level.
+4. Protected areas and "do not touch without approval" surfaces.
+5. Documentation/context risks.
+6. First proposed round of cards.
+
+Suggested first round:
+
+```text
+Card: S0-R1-C1-A
+Agent: [Architect Supervisor]
+Role: architect-supervisor
+Track: project-intake-and-operating-surface-v0
+
+Goal:
+Create the initial project map and operating surface.
+
+Deliver:
+- docs/agents/current-status.md
+- docs/agents/operating-model.md
+- first-round card plan
+```
+
+```text
+Card: S0-R1-C2-P1
+Agent: [Project Research Agent]
+Role: research-agent
+Track: project-structure-and-build-test-map-v0
+
+Goal:
+Map structure, runtime, build/test commands, and obvious integration boundaries.
+
+Deliver:
+- Track doc or compact report
+- Build/test command matrix
+- Unknowns and recommended verification
+```
+
+```text
+Card: S0-R1-C3-P1
+Agent: [Project Domain Pressure Agent]
+Role: domain-pressure-agent
+Track: domain-pain-and-opportunity-map-v0
+
+Goal:
+Identify real product/domain pains where the project needs pressure.
+
+Deliver:
+- Pain map
+- Opportunity map
+- Concrete next tracks
+```
+
+```text
+Card: S0-R1-C4-P1
+Agent: [Project Archive/Form Expert]
+Role: archive-form-expert
+Track: documentation-context-risk-map-v0
+
+Goal:
+Classify existing docs and identify stale, active, canonical, and archive
+surfaces.
+
+Deliver:
+- Context risk map
+- Inbox/archive recommendations
+- No file moves unless explicitly authorized
+```
+
+```text
+Card: S0-R1-X1-S
+Agent: [Project External Pressure Reviewer]
+Role: external-pressure-reviewer
+Borrowed lens: runtime-pressure | product-pressure | implementation-pressure
+Track: stage0-operating-surface-pressure-v0
+
+Goal:
+Challenge whether the proposed operating surface is understandable and safe
+from limited context.
+
+Deliver:
+- Agree / Challenge / Missing / Sharper Question / Route
+```
+
+```text
+Card: S0-R1-C5-S
+Agent: [Project Status Curator]
+Role: status-curator
+Track: stage0-status-curation-v0
+
+Goal:
+Merge Stage 0 findings into current-status and propose Stage 1.
+
+Deliver:
+- Updated current-status
+- Next round recommendation
+```
+
+## Questions For The Human
+
+Ask these only after the initial scan, and keep them short:
+
+1. What is the main outcome you want from this project in the next 1-2 weeks?
+2. Which files, commands, environments, or data are protected?
+3. Who will participate: humans, local agents, external reviewers?
+4. Should the first stage focus on implementation, research, documentation, or
+   product/domain discovery?
+5. What counts as "done enough" for the first useful result?
+
+## First Response Shape
+
+Your first response should be:
+
+```text
+Route: INIT
+Agent: [Architect Supervisor]
+Role: architect-supervisor
+Workspace:
+Initial stack guess:
+Docs path:
+Protected surfaces observed:
+Suggested Stage 0:
+Questions:
+```
+
+Then proceed with the smallest useful operating surface.
+````
+
+---
+
+## Human Launch Pattern
+
+Use this sequence when starting a new project:
+
+```text
+1. Open a fresh Codex chat in the target workspace.
+2. Paste the Bootstrap Prompt above.
+3. Let the new Architect Supervisor scan and create Stage 0.
+4. Answer its five questions.
+5. Ask it for "cards for the first round".
+6. Start separate agent chats with those cards.
+7. Bring completed handoffs back to the Architect Supervisor.
+```
+
+For a small project, keep everything in one chat until Stage 0 is clear. For a
+larger project, split after the first card plan.
+
+## Team Rollout Pattern
+
+For multiple developers:
+
+```text
+Architect Supervisor
+  -> owns maps, rounds, and decisions
+
+Developer A + local agents
+  -> implementation cards
+
+Developer B + local agents
+  -> research/docs/domain cards
+
+External or fresh-context reviewer
+  -> pressure only, no write authority
+```
+
+Each developer can run local agents, but the project should keep one shared
+current-status map and one authority lane.

data/docs/dev/architecture.md

@@ -0,0 +1,20 @@
+# Architecture
+
+Use this page as the public contributor entrypoint for Igniter architecture.
+
+For the current package and layer map, start with:
+
+- [Package Map](./package-map.md)
+- [Module System](./module-system.md)
+- [Data Ownership](./data-ownership.md)
+- [Current Runtime Snapshot](./current-runtime-snapshot.md)
+
+For user-facing runtime choices, use:
+
+- [Core](../guide/core.md)
+- [App](../guide/app.md)
+- [Cluster](../guide/cluster.md)
+- [`igniter-extensions`](../../packages/igniter-extensions/README.md)
+
+Private historical architecture indexes, V1 references, and old layer maps live
+under `playgrounds/docs/`.

data/docs/dev/cluster-target-plan.md

@@ -0,0 +1,43 @@
+# Cluster Target Plan
+
+`Cluster` is the distributed runtime layer over `Embed` and, when useful,
+`Application`. It places, routes, executes, and explains distributed work
+without redefining contracts.
+
+## Owns
+
+- remote execution substrate
+- capability-aware routing and admission
+- peer identity, topology, health, and membership views
+- ownership, placement, leases, failover, and remediation plans
+- replication/capacity expansion where it is truly cluster semantics
+- distributed diagnostics, traces, incidents, and operator timelines
+
+## Does Not Own
+
+- embedded graph semantics
+- local app boot lifecycle
+- generic app hosting
+- code loading as a core cluster concern
+- heavyweight coordination by default
+
+## Boundary Rules
+
+- `Embed` defines executable work.
+- `Application` owns local host/runtime profile.
+- `Cluster` decides where and how distributed work runs.
+- Mesh behavior sits above explicit cluster plan semantics.
+
+## Current Shape
+
+The clean-slate package now includes capability queries, peer/topology/health
+views, route/admission/placement/ownership/lease/failover/remediation policies,
+explicit plans and execution reports, mesh request/response/attempt/trace
+values, membership/discovery feeds, event logs, incidents, remediation plans,
+and operator timelines.
+
+## Success
+
+Cluster is successful when distributed execution, routing, ownership, placement,
+health, and remediation are explicit seams with structured explanations, and no
+distributed concern leaks down into the embedded kernel.