docs(spec): redefine processkit v1 from first principles

[projectious]

Objective

Define a coherent review baseline for a clean processkit v1.x implementation from first principles, updated for the accepted repository-scoped agent architecture. Existing v0 behavior and released v1-alpha code are implementation evidence and migration inputs rather than unreviewed normative constraints.

Work item: BACK-20260807_1003-WarmHawk-specify-processkit-v1-from-first-principles
Decision: DEC-20260807_1003-LucidGarnet-re-specify-and-reimplement-the-processkit

What changed

• define one repository and one authoritative processkit context as shared project memory for multiple human, permanent-agent, and ephemeral-agent participants
• retain the complete 89-concept T/P/D/C ontology as mandatory v1 scope
• specify Python 3.12+ with one application core shared by CLI, MCP, validation, lifecycle, events, indexing, migration, generation, and reconciliation
• define the standalone repository CLI, including generic entity, event, context, skill, handoff, package, index, migration, and lifecycle operations
• keep canonical state in human-readable Git files while treating SQLite, full-text, semantic, and vector indexes as disposable local projections
• clarify TeamMember as project-local participation state rather than private harness memory, credentials, or canonical global identity
• define repository authority, qualified cross-repository references, bounded handoffs, and Git-mediated collaboration without distributed transactions
• make skills canonical processkit packages and generate provenance-preserving harness-native projections through versioned adapters
• define declarative desired state for profiles, packages, skills, MCP capabilities, and harness targets, reconciled through reviewed plan and apply operations
• retain the efficient local MCP gateway daemon and stdio proxy alongside direct stdio, while binding the daemon to one repository, authenticated loopback clients, and the same application core
• simplify v1 to one standard profile, one runtime semantics, and no required sidecar, shared database, hosted service, remote daemon, or per-skill authority
• update security, verification, compatibility, migration, documentation, acceptance, performance, operational, and roadmap contracts accordingly

Central architecture

One Git repository represents one project or coordination scope and contains one authoritative processkit context. Multiple agents and humans work through ordinary clones, branches, reviews, and merges. Processkit governs the shared ontology and repository memory; the harness owns model execution, conversation memory, and heartbeat; Aibox may provide the secure execution environment; Kaits may consume processkit contracts for wider company orchestration without becoming product-repository authority.

The reference product is a Python application. CLI and MCP are adapters over the same operations. Direct stdio is the universal MCP baseline; a reusable authenticated loopback daemon and lightweight stdio proxy preserve the useful v0 efficiency topology without creating a second source of truth.

Skills have one harness-neutral canonical representation. Desired harness integrations are declared in project configuration. processkit plan reconcile, processkit apply --plan ..., and processkit verify provide an idempotent, machine-readable convergence contract suitable for later CI/CD or GitOps controllers without requiring such a controller in v1.

Important review boundaries

This remains a draft proposal and does not authorize destructive branch changes. Existing v1.x-dev, prerelease tags, and alpha support require an ancestry-preserving reconciliation decision after the specification is accepted.

The company-wide OpenSpec/processkit specification-location question also remains open. spec/doc/v1/ is a project-local baseline, not a company directory standard.

Validation

• scripts/validate-v1-spec.py: valid roadmap, links, dependency graph, and 378 unique normative requirements
• duplicate requirement-ID scan: no duplicates
• git diff --check: passed