docs(spec): add early Kaits v1 discussion baseline

AGENTS.md

@@ -3,16 +3,24 @@
 ## Purpose and scope
 
 kaits is the application that lets a principal run and supervise an AI-agent
-team. It owns the product UI, local application state, and the agent
-orchestration runtime. Keep changes focused on that product boundary.
+team. It owns the product UI, portfolio and organization state, and
+cross-product orchestration. Keep changes focused on that product boundary.
 
-- **airunner** owns the general-purpose agent execution/runtime surface; do
-  not duplicate its portable runtime concerns here.
+- **airunner** owns the independently usable agent execution/runtime surface;
+  Kaits may register, assign, and supervise Airunner instances but does not
+  duplicate their portable loop, checkpoint, or heartbeat implementation.
 - **processkit** owns reusable, provider-neutral process primitives and skills;
   kaits may consume them but does not define their canonical schemas or
   workflows.
 - **aibox** owns the development environment and workspace tooling; do not put
   product behavior or product configuration in it.
+- **ainfra** owns independently usable infrastructure provisioning and its
+  result artifacts; Kaits coordinates it through public contracts.
+
+The intentionally incomplete v1 discussion baseline lives under
+`spec/doc/v1/`. Where older product documentation assumes that Kaits itself
+implements the portable agent loop, treat that material as implementation
+evidence pending explicit reconciliation with the v1 boundary.
 
 ## Working agreement
 

spec/doc/v1/01-product-boundary.md

@@ -0,0 +1,51 @@
+# Product boundary
+
+## Purpose
+
+Kaits lets a principal operate and supervise an AI-first organization or team.
+It owns portfolio-level intent, organization and participation views,
+cross-repository coordination, resource demand, assignments, schedules,
+presence, and orchestration records.
+
+- **KAITS-PROD-001:** Kaits MUST treat ainfra, Aibox, Processkit, and Airunner
+  as independently usable products with independently versioned contracts.
+- **KAITS-PROD-002:** Kaits MUST call ainfra directly when it needs
+  independently usable infrastructure to be created or scaled.
+- **KAITS-PROD-003:** Kaits MUST call Aibox directly when it needs an agent box
+  deployed on a local, existing, managed-container, or ainfra-produced target.
+- **KAITS-PROD-004:** an Aibox environment MAY contain Processkit, Airunner,
+  both, or neither as standard Features or native image content.
+- **KAITS-PROD-005:** Kaits determines that an agent is available only from an
+  Airunner or harness registration/health contract, not merely because Aibox
+  reports a running container.
+- **KAITS-PROD-006:** Kaits MUST preserve participant-repository authority. A
+  portfolio view, policy, or assignment does not grant implicit write authority
+  over a product repository.
+
+## Non-goals established so far
+
+- **KAITS-NONGOAL-001:** Kaits is not an infrastructure provisioner.
+- **KAITS-NONGOAL-002:** Kaits is not a container or development-environment
+  manager.
+- **KAITS-NONGOAL-003:** Kaits does not implement a portable model/tool loop,
+  checkpoint engine, or harness runtime owned by Airunner.
+- **KAITS-NONGOAL-004:** Kaits does not redefine Processkit's repository-local
+  entity schemas, state machines, or canonical project memory.
+- **KAITS-NONGOAL-005:** Kaits does not create a distributed transaction across
+  repositories or product APIs.
+- **KAITS-NONGOAL-006:** Kaits v1 is not yet specified as a universal
+  organization ontology or generic workflow engine.
+
+## Product result pattern
+
+Kaits owns an orchestration result for the coordination it performs. That
+result references immutable ainfra infrastructure results, Aibox environment
+results, and Airunner registration or run results without copying or extending
+their schemas.
+
+- **KAITS-PROD-010:** Kaits MUST NOT append organization or agent state to an
+  ainfra, Aibox, Processkit, or Airunner result artifact.
+- **KAITS-PROD-011:** partial completion MUST remain explicit; Kaits MUST NOT
+  report orchestration success when infrastructure or a box exists but the
+  requested agent has not become available.
+

spec/doc/v1/02-orchestration-and-contracts.md

@@ -0,0 +1,113 @@
+# Orchestration and product contracts
+
+## Initial scaling scenario
+
+```text
+principal or Kaits policy requests more agent capacity
+        |
+        +--> ainfra plan/apply --> infrastructure result
+        |
+        +--> Aibox plan/apply on selected target --> environment result
+                                                |
+                                                +-- Processkit Feature
+                                                +-- Airunner Feature
+                                                        |
+                                                        +--> registers with Kaits
+```
+
+Kaits may skip ainfra when it already has a suitable target. It may also ask
+Aibox to use a managed-container adapter where capacity allocation and workload
+creation are one atomic Aibox operation.
+
+## Minimal cross-product fields
+
+The first contract does not require a global identity envelope. Each product
+owns its resource IDs and authenticates Kaits according to its own policy.
+Kaits maintains the relationship between:
+
+- orchestration and assignment IDs;
+- ainfra operation, deployment, target, and result references when applicable;
+- Aibox operation, environment, workload, and result references; and
+- Airunner agent-instance and registration references when applicable.
+
+- **KAITS-CONTRACT-001:** calls to ainfra and Aibox SHOULD carry an opaque
+  Kaits correlation ID for evidence lookup and an idempotency key for retry
+  safety.
+- **KAITS-CONTRACT-002:** correlation IDs MUST NOT grant authority, select
+  credentials, or replace product-owned resource identity.
+- **KAITS-CONTRACT-003:** Kaits MUST authenticate and receive authorization at
+  each product boundary; successful authorization at one boundary MUST NOT be
+  forwarded as implicit authority at another.
+- **KAITS-CONTRACT-004:** Kaits MUST accept versioned product results through
+  compatibility adapters and retain their immutable identity or digest.
+
+## Compensation, not distributed rollback
+
+Kaits coordinates durable operations that can succeed or fail independently.
+It records partial state and offers explicit next actions. Cleanup is a new
+authorized product operation, not rollback of a global transaction.
+
+- **KAITS-CONTRACT-010:** every orchestration step MUST expose pending,
+  running, succeeded, failed, cancelled, ambiguous, and recovery-required
+  states where applicable.
+- **KAITS-CONTRACT-011:** retries MUST reuse or deliberately replace the prior
+  idempotency key and MUST NOT silently duplicate infrastructure, boxes, or
+  agent registrations.
+- **KAITS-CONTRACT-012:** Kaits MUST retain product-specific error and evidence
+  references rather than flattening failures into generic prose.
+
+## Organization and work graphs
+
+Kaits treats graph engineering as an orchestration discipline, not a database
+selection. A relatively stable organization graph describes participating
+agents, routers, human gates, owned domains, supervision, and permitted
+handoffs. An ephemeral work graph describes assignments, dependencies,
+parallel branches, joins, retries, fallbacks, escalation, cancellation, and
+completion propagation for one bounded outcome.
+
+- **KAITS-CONTRACT-020:** graph nodes MUST declare stable type, owning
+  authority, accepted inputs and outputs, required capabilities, lifecycle,
+  and failure boundary rather than relying on prompt prose alone.
+- **KAITS-CONTRACT-021:** graph edges MUST declare permitted source and target
+  types, handoff contract, carried state and evidence, authorization,
+  cardinality, timeout, retry, fallback, cancellation, and failure-propagation
+  semantics as applicable.
+- **KAITS-CONTRACT-022:** organization-graph identity and policy MUST remain
+  distinct from the work-graph execution records created for one outcome.
+- **KAITS-CONTRACT-023:** dynamic work-graph expansion or removal MUST be
+  attributable, bounded by policy and budget, and represented as durable
+  orchestration events; model output alone MUST NOT gain scheduling authority.
+- **KAITS-CONTRACT-024:** joins MUST define required and optional predecessors,
+  partial-success behavior, evidence aggregation, timeout, and cancellation of
+  work that is no longer needed.
+
+## Agent2Agent communication edges
+
+Kaits may use [Agent2Agent (A2A) 1.0][a2a] as a client when delegating to an
+Airunner or another compatible agent. It may also authorize and observe a work
+edge whose messages flow directly between two agents. A2A is the optional
+communication protocol for that edge; Kaits remains the owner of scheduling,
+budget, supervision, and work-graph policy.
+
+- **KAITS-CONTRACT-030:** Kaits MUST keep its assignment identity and lifecycle
+  distinct from A2A Task and context identities and the remote agent's own run
+  identity, with explicit versioned correlation mappings.
+- **KAITS-CONTRACT-031:** A2A Agent Cards MAY contribute discovery and
+  compatibility claims but MUST NOT establish Kaits registration, presence,
+  readiness, lease, ownership, budget, or assignment authority.
+- **KAITS-CONTRACT-032:** Kaits MUST NOT require all peer messages to transit
+  Kaits. A direct A2A edge MAY be used when both agents are authenticated and
+  policy authorizes the source, target, capability, data scope, budget,
+  concurrency, delegation depth, and evidence obligations.
+- **KAITS-CONTRACT-033:** direct communication MUST emit or reconcile enough
+  durable status and result evidence for Kaits to supervise the work graph;
+  missing or conflicting peer status becomes explicit ambiguous or
+  recovery-required state rather than assumed success.
+- **KAITS-CONTRACT-034:** A2A task, message, and artifact semantics MUST NOT
+  replace Kaits joins, retries, fallbacks, escalation, cancellation
+  propagation, leases, or compensation contracts.
+- **KAITS-CONTRACT-035:** Kaits SHOULD use an official conformant A2A client
+  implementation and MUST preserve protocol-version and capability negotiation
+  rather than depending on one Airunner-specific wire behavior.
+
+[a2a]: https://a2a-protocol.org/v1.0.0/specification/

spec/doc/v1/03-architecture-and-data-authority.md

@@ -0,0 +1,44 @@
+# Architecture and data authority
+
+## Authority map
+
+| Authority | Owner |
+|---|---|
+| Company and portfolio intent, organization participation, assignments, orchestration records | Kaits |
+| Infrastructure deployment and infrastructure result | ainfra |
+| Agent-box deployment and environment result | Aibox |
+| Repository-local process memory and validated project entities | Processkit in the owning repository |
+| Portable agent loop, runtime state, checkpoints, heartbeat, and agent-run result | Airunner or another harness |
+| Git history and accepted repository changes | Owning repository and its review process |
+
+- **KAITS-ARCH-001:** Kaits MUST integrate through public product contracts,
+  not another product's database, cache, internal module, or generated files.
+- **KAITS-ARCH-002:** Kaits MAY keep projections for portfolio views, but they
+  MUST be rebuildable or reconcilable and MUST name their source authority and
+  observed revision.
+- **KAITS-ARCH-003:** Kaits MUST NOT require Processkit in every repository or
+  Airunner in every agent box merely to represent an external participant.
+- **KAITS-ARCH-004:** orchestration logic, UI, and adapters SHOULD remain
+  separable so another interface can exercise the same application use cases.
+- **KAITS-ARCH-005:** Kaits owns its organization and work graph semantics but
+  MUST NOT infer ownership of ainfra, Aibox, Processkit, or Airunner resources
+  merely because their results or participants appear as graph nodes.
+- **KAITS-ARCH-006:** persistence selection follows accepted graph contracts
+  and measured access patterns. This draft does not require a graph database;
+  any projection or specialized index MUST retain source authority and
+  generation metadata.
+- **KAITS-ARCH-007:** A2A is an optional adapter at an agent communication
+  edge, not Kaits' canonical organization, policy, identity, scheduling, or
+  persistence model.
+
+## Intentionally unresolved
+
+This draft does not decide:
+
+- the implementation language or framework for Kaits v1;
+- whether the existing application is evolved or replaced;
+- the canonical company/organization model;
+- the assignment, scheduling, queue, message, or resource schemas;
+- the external API or agent protocol;
+- persistence technology, topology, or deployment modes; or
+- whether Kaits itself exposes MCP, another protocol, or several adapters.

spec/doc/v1/04-security-evidence-and-standards.md

@@ -0,0 +1,56 @@
+# Security, evidence, and company standards
+
+## Initial security posture
+
+- **KAITS-SEC-001:** Kaits MUST use least-privilege, separately revocable
+  credentials for ainfra, Aibox, Airunner, repositories, model providers, and
+  other external systems.
+- **KAITS-SEC-002:** secrets MUST be references in committed configuration and
+  MUST NOT enter product results, orchestration evidence, logs, prompts, or
+  user-visible diagnostics.
+- **KAITS-SEC-003:** natural-language intent, agent confidence, or successful
+  planning MUST NOT authorize infrastructure creation, workload deployment,
+  destructive cleanup, spend, or privilege escalation.
+- **KAITS-SEC-004:** resource, spend, concurrency, time, and permission limits
+  MUST be explicit policy inputs before unattended scaling ships.
+- **KAITS-SEC-005:** imported product output and agent messages are untrusted
+  data. They MUST NOT become executable instructions or authorization policy.
+
+## Evidence
+
+Kaits produces a Kaits-owned orchestration result containing its request,
+policy and approval references, stable product-result references, timestamps,
+step outcomes, agent registration outcome, cleanup state, and limitations.
+
+- **KAITS-EVIDENCE-001:** evidence MUST distinguish facts observed directly by
+  Kaits from claims imported from another product.
+- **KAITS-EVIDENCE-002:** an optional correlation ID aids lookup but MUST remain
+  distinct from product resource IDs and authenticated principals.
+
+## Applicable company baseline
+
+The following company standards apply unless a later reviewed Kaits decision
+documents a necessary deviation:
+
+- Git branching and release promotion;
+- application configuration;
+- application output, logging, and evidence;
+- application profiles where deployment profiles are introduced;
+- compatibility and machine interfaces;
+- security and software supply chain;
+- software verification and release engineering;
+- product roadmap and development evidence;
+- spec-driven development;
+- open-source documentation; and
+- AI-agent accessibility and generative discovery.
+
+- **KAITS-STD-001:** Kaits MUST use the company CLI/MCP output and error
+  conventions for any interfaces it later adopts, deviating only for a
+  documented product-specific reason.
+- **KAITS-STD-002:** project-authored GitHub Actions remain prohibited; build,
+  test, release, and publication procedures are documented and run from an
+  authorized local environment.
+
+Host-gated execution and human-controlled host phases become applicable only
+if a future Kaits release requires host-only credentials or publication steps.
+

spec/doc/v1/05-open-questions.md

@@ -0,0 +1,32 @@
+# Open questions
+
+This list intentionally prevents the early draft from manufacturing answers.
+
+1. What is the smallest valuable Kaits user journey before autonomous scaling?
+2. Which existing Kaits concepts and UI evidence should survive into v1?
+3. What company, organization, team, role, membership, and participation model
+   is canonical, and which standard vocabularies are worth reusing?
+4. How does a principal approve intent, budgets, policies, and exceptions?
+5. How are assignments, leases, queues, schedules, presence, and messages
+   modeled without duplicating Airunner or Processkit?
+6. How does Airunner register, advertise capability, heartbeat, drain, and
+   terminate while remaining independently usable?
+7. Which ainfra and Aibox versions and capabilities form the first compatible
+   orchestration profile?
+8. What is the smallest secure local deployment before remote or multi-user
+   Kaits operation?
+9. Which UI journeys define the recognizable Kaits product experience?
+10. Which end-to-end external scenario is sufficient evidence for the broader
+    Projectious stack promise?
+11. What is the minimum stable organization graph, and which participants are
+    external references rather than Kaits-owned identities?
+12. What is the minimum ephemeral work graph, including branch, join, retry,
+    fallback, escalation, cancellation, and partial-success semantics?
+13. Which measured queries or scheduling loads, if any, would justify a
+    specialized graph store rather than ordinary transactional persistence?
+14. Which first assignment should use Kaits as an A2A client, and which first
+    peer edge should communicate directly without Kaits relaying messages?
+15. How does Kaits reconcile A2A polling, streaming, push notifications, and
+    incomplete message history into durable assignment and recovery state?
+16. Which registration directory binds a live participant to its verified
+    A2A Agent Card, endpoint, supported version, lease, and current readiness?

spec/doc/v1/README.md

@@ -0,0 +1,37 @@
+# Kaits v1 draft product specification
+
+| Field | Value |
+|---|---|
+| Status | Early discussion baseline; intentionally incomplete |
+| Product line | Kaits v1 |
+| Normative scope | Only requirements explicitly marked `KAITS-*` |
+| Implementation authority | None; this draft does not authorize a rewrite |
+
+Kaits is the portfolio and organization control surface through which a human
+principal forms, observes, directs, and supervises teams of human and AI
+participants. It coordinates independently owned products and repositories; it
+does not absorb their domain state into one inner platform.
+
+This first draft records only boundaries already established in company
+architecture discussions. It deliberately leaves product journeys, detailed
+organization semantics, implementation architecture, user experience,
+commercial posture, and release scope open for future review.
+
+## Documents
+
+- [Product boundary](01-product-boundary.md)
+- [Orchestration and product contracts](02-orchestration-and-contracts.md)
+- [Architecture and data authority](03-architecture-and-data-authority.md)
+- [Security, evidence, and company standards](04-security-evidence-and-standards.md)
+- [Open questions](05-open-questions.md)
+- [Discussion roadmap](roadmap.yaml)
+
+## Interpretation
+
+- Existing Kaits code and documentation are evidence, not automatic normative
+  constraints for this draft.
+- Requirements outside the few settled boundaries remain proposals.
+- `idea` roadmap items are discussion prompts, not commitments.
+- Product-specific results prove only operations owned by the producing
+  product.
+