diff --git a/CHANGELOG.md b/CHANGELOG.md index b3a4a08d..91922803 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,12 @@ Versions follow [Semantic Versioning](https://semver.org/). ## Unreleased +### Added + +- Add a from-scratch processkit v1.x product specification, implementation + language assessment, normative requirement set, executable roadmap schema, + and phased roadmap for review. + ## [v1.0.0-alpha.5] - 2026-07-31 v1.0.0-alpha.5 completes the extracted issue #135 follow-up tracks for trusted diff --git a/README.md b/README.md index 89e3efc1..0d8a6fd7 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,10 @@ > > The current v1 release is `v1.0.0-alpha.5`. Its published native executable > supports Linux ARM64 GNU only. +> +> A [from-scratch replacement v1 product specification](spec/doc/v1/README.md) +> is proposed for review. Until accepted and implemented, it describes planned +> behavior and does not replace the alpha.5 contracts documented below. --- diff --git a/scripts/validate-v1-spec.py b/scripts/validate-v1-spec.py new file mode 100755 index 00000000..d9b003a7 --- /dev/null +++ b/scripts/validate-v1-spec.py @@ -0,0 +1,155 @@ +#!/usr/bin/env -S uv run --script +# /// script +# requires-python = ">=3.12" +# dependencies = [ +# "jsonschema>=4.0", +# "pyyaml>=6.0", +# ] +# /// + +"""Validate the processkit v1 specification's executable contracts.""" + +from __future__ import annotations + +import json +import re +from pathlib import Path + +import jsonschema +import yaml + + +ROOT = Path(__file__).resolve().parents[1] +SCHEMA_PATH = ROOT / "spec/schemas/v1/roadmap.schema.json" +ROADMAP_PATH = ROOT / "spec/doc/v1/roadmap.yaml" +DOC_ROOT = ROOT / "spec/doc/v1" +REQUIREMENT_RE = re.compile(r"\b(PK-[A-Z]+-[0-9]{3})\b") +MARKDOWN_LINK_RE = re.compile(r"\[[^]]+\]\(([^)]+)\)") +INVALID_ROADMAP_ROOT = ROOT / "spec/tests/v1/roadmap" + + +def validate_roadmap( + roadmap: dict[str, object], + validator: jsonschema.Draft202012Validator, + *, + check_note_paths: bool, +) -> None: + validator.validate(roadmap) + + groups = roadmap["groups"] + group_ids = [group["id"] for group in groups] + duplicate_groups = sorted( + group_id + for group_id in set(group_ids) + if group_ids.count(group_id) > 1 + ) + if duplicate_groups: + raise ValueError(f"duplicate roadmap group IDs: {duplicate_groups}") + + items = [item for group in groups for item in group["items"]] + item_ids = [item["id"] for item in items] + duplicates = sorted( + item_id for item_id in set(item_ids) if item_ids.count(item_id) > 1 + ) + if duplicates: + raise ValueError(f"duplicate roadmap IDs: {duplicates}") + + known = set(item_ids) + broken = sorted( + (item["id"], dependency) + for item in items + for dependency in item["dependencies"] + if dependency not in known + ) + if broken: + raise ValueError(f"unknown roadmap dependencies: {broken}") + + dependencies = { + item["id"]: set(item["dependencies"]) + for item in items + } + pending = set(known) + while pending: + ready = { + item_id + for item_id in pending + if not (dependencies[item_id] & pending) + } + if not ready: + raise ValueError( + f"cyclic roadmap dependencies: {sorted(pending)}" + ) + pending -= ready + + if check_note_paths: + for item in items: + if item["status"] == "shipped": + note = ROOT / item["devNote"] + if not note.is_file(): + raise ValueError( + f"{item['id']} references absent development note: " + f"{note}" + ) + + +def main() -> None: + schema = json.loads(SCHEMA_PATH.read_text(encoding="utf-8")) + roadmap = yaml.safe_load(ROADMAP_PATH.read_text(encoding="utf-8")) + + jsonschema.Draft202012Validator.check_schema(schema) + validator = jsonschema.Draft202012Validator( + schema, + format_checker=jsonschema.Draft202012Validator.FORMAT_CHECKER, + ) + validate_roadmap(roadmap, validator, check_note_paths=True) + + for invalid_path in sorted(INVALID_ROADMAP_ROOT.glob("invalid-*.yaml")): + invalid = yaml.safe_load(invalid_path.read_text(encoding="utf-8")) + try: + validate_roadmap(invalid, validator, check_note_paths=False) + except (jsonschema.ValidationError, ValueError): + continue + raise ValueError( + f"expected roadmap validation to fail: {invalid_path}" + ) + + requirement_sources: dict[str, list[str]] = {} + for document in sorted(DOC_ROOT.glob("*.md")): + text = document.read_text(encoding="utf-8") + for requirement_id in REQUIREMENT_RE.findall(text): + requirement_sources.setdefault(requirement_id, []).append( + document.name + ) + + for target in MARKDOWN_LINK_RE.findall(text): + if "://" in target or target.startswith("#"): + continue + path_part = target.split("#", 1)[0] + linked_path = (document.parent / path_part).resolve() + if path_part and not linked_path.exists(): + raise ValueError( + f"broken local link in {document.name}: {target}" + ) + + duplicates = { + requirement_id: sources + for requirement_id, sources in requirement_sources.items() + if len(sources) > 1 + } + if duplicates: + raise ValueError(f"duplicate normative requirement IDs: {duplicates}") + + if len(requirement_sources) < 100: + raise ValueError( + "unexpectedly small normative requirement inventory: " + f"{len(requirement_sources)}" + ) + + print( + "processkit v1 specification contracts are valid " + f"({len(requirement_sources)} normative requirements)" + ) + + +if __name__ == "__main__": + main() diff --git a/spec/doc/v1/01-product-definition.md b/spec/doc/v1/01-product-definition.md new file mode 100644 index 00000000..ff9dd6b5 --- /dev/null +++ b/spec/doc/v1/01-product-definition.md @@ -0,0 +1,158 @@ +# Product definition + +## Purpose + +processkit is a local-first, provider-neutral AI-agent context and memory +management system for humans and agents working in Git repositories. It turns +repository text files into durable, typed, inspectable memory and provides the +shared ontology through which humans and agents describe work, knowledge, +decisions, evidence, organizations, capabilities, and processes in +conversation. + +One processkit installation belongs to one Git repository representing one +project or coordination scope. Its `context/` is the authoritative shared +process memory of that scope, not the private memory of one agent. Any number +of human, permanent-agent, and ephemeral-agent TeamMembers may participate by +working with ordinary clones, branches, reviews, and merges. + +Human-readable Git files are always canonical. Local databases, full-text +indexes, and embedding/vector entries augment retrieval and context assembly, +but remain disposable client-side projections that can be rebuilt from the +repository. processkit also installs, versions, discovers, and governs skills +and MCP servers that let agents understand and safely operate on this context. + +The product answers these questions without depending on replay of a chat +history or one model provider's private memory: + +1. What project and organizational context should an agent know now? +2. Which durable memories, decisions, evidence, relationships, and history + support that context? +3. How can a human and an agent express new information in the same ontology? +4. What state are process entities in, and which transitions are valid? +5. Which skill, MCP tool, or process capability should an agent use next? + +## Users + +- A project owner installs and upgrades a coherent process capability set. +- A human contributor reads and reviews canonical state in Git. +- An AI agent retrieves bounded relevant context, queries durable memory, and + records or mutates project state through validated tools. +- A process author creates reusable skills, schemas, state machines, and + process definitions. +- A harness or orchestrator integrates through stable MCP and machine + contracts without becoming a processkit dependency. +- A portfolio coordinator links work and evidence across repositories without + treating any single repository as a global mutable database. + +## Goals + +- **PK-PROD-001:** canonical project process state MUST remain human-readable, + Git-compatible, and usable without a hosted processkit service. +- **PK-PROD-002:** normal agent writes MUST pass through validated operations + that enforce schemas, lifecycle rules, ownership, and event recording. +- **PK-PROD-003:** the same public process semantics MUST be available to every + supported harness through provider-neutral contracts. +- **PK-PROD-004:** installation, upgrade, verification, and removal MUST + preserve project-owned changes or stop with an explicit conflict. +- **PK-PROD-005:** shipped content and runtime behavior MUST be versioned, + locally testable, and independently verifiable from release artifacts. +- **PK-PROD-006:** processkit MUST support one repository as one concern while + allowing explicit references and handoffs between independently owned + repositories. +- **PK-PROD-017:** one repository MUST have at most one active processkit + installation and one authoritative context root; nested Git repositories or + submodules are independent roots and MUST NOT be absorbed implicitly. +- **PK-PROD-018:** a processkit root MUST support multiple human and AI + participants and MUST NOT imply one repository or one processkit + installation per agent. +- **PK-PROD-019:** every reference runtime MUST operate locally against one + selected working copy. A long-lived local MCP daemon MAY serve several + authorized clients for that working copy, but it is not shared repository + authority or a second project database. Git synchronization and review + transfer accepted state between working copies. +- **PK-PROD-007:** project state MUST remain authoritative when indexes, + caches, generated references, or harness projections are absent. +- **PK-PROD-008:** v1 MUST provide the complete 89-concept T/P/D/C ontology + defined in the conceptual-model chapter so users can express broad process, + organizational, evidence, planning, and agentic-work concepts without + overloading a reduced set of generic records. +- **PK-PROD-009:** processkit MUST assemble bounded, attributable agent context + from canonical entities and verified derived indexes without treating model + conversation history as authoritative project memory. +- **PK-PROD-016:** skills and MCP servers MUST be managed as versioned, + inspectable capabilities with ownership, discovery, configuration, + compatibility, and verification contracts. + +## Non-goals + +- **PK-PROD-010:** processkit MUST NOT run language models, own an agent loop, + schedule autonomous teams, or replace a harness or orchestrator. +- **PK-PROD-011:** processkit MUST NOT replace Git hosting, issue trackers, + code review, CI systems, chat, secrets managers, or artifact stores. +- **PK-PROD-012:** processkit MUST NOT require a central database, cloud + account, projectious.work service, aibox, or a specific AI provider. +- **PK-PROD-013:** processkit MUST NOT encode a single scaling framework, + organizational method, or model vendor as its universal ontology. +- **PK-PROD-014:** processkit MUST NOT make every Markdown file an entity or + claim that unstructured documentation has lifecycle semantics. +- **PK-PROD-015:** processkit v1 MUST NOT provide portfolio-wide distributed + transactions or pretend cross-repository operations are atomic. +- **PK-PROD-028:** processkit MUST NOT create branches, commits, pull + requests, issues, discussions, merges, pushes, or fetches as implicit side + effects. Humans, agents, harnesses, and forge adapters own those workflows. + +## Product boundary + +processkit owns: + +- contracts for process entities, relations, transitions, and events; +- reusable process content and its packaging metadata; +- local installation and reconciliation of processkit-owned files; +- validated CLI and MCP operations; +- derived local indexes and generated harness projections; +- context discovery, retrieval, ranking, and bounded context assembly; +- local full-text and embedding/vector projections derived from canonical + repository content; +- versioned skills and MCP server capability manifests, installation, and + verification; +- compatibility, migration, verification, and diagnostic behavior. + +The consuming repository owns: + +- its entities and their meaning within the declared contracts; +- local policies, extensions, accepted overrides, and private content; +- Git history, review, retention, backup, and publication; +- authorization to mutate the repository; +- credentials and external-system integrations. + +The harness or orchestrator owns agent identity bootstrap, model execution, +prompts outside shipped skills, conversation and runtime memory, heartbeat, +task scheduling, agent isolation, cost control, and cross-agent coordination. +Company modelling, teams-of-teams orchestration, simulation, message delivery, +and portfolio views belong to products such as Kaits, which consume +processkit contracts without becoming repository authority. + +## Required user journeys + +- **PK-PROD-020:** a new user MUST be able to install a pinned release into a + disposable Git repository, verify it, start MCP, and create/read/transition + a WorkItem without aibox. +- **PK-PROD-021:** an existing project MUST be able to preview an update, + inspect every planned file action and conflict, apply it atomically within + documented limits, and verify the result. +- **PK-PROD-022:** an agent MUST be able to discover an applicable skill, + query the relevant entities, perform an allowed mutation, and observe the + resulting event without raw filesystem discovery. +- **PK-PROD-023:** a maintainer MUST be able to rebuild all derived indexes + and projections from canonical files. +- **PK-PROD-024:** a project with local extensions MUST be able to distinguish + upstream-owned, locally modified, project-owned, and generated paths. +- **PK-PROD-025:** a failed or interrupted mutation MUST leave either the + previous valid state or explicit recovery evidence; it MUST NOT claim + transactionality beyond what was achieved. +- **PK-PROD-026:** a project MUST be able to export a sanitized, bounded + handoff bundle and record an external reference without surrendering local + ownership or exposing private context by default. +- **PK-PROD-027:** a user MUST be able to validate, create or compose, query, + relate, and inspect every applicable concept in the complete v1 ontology + through its declared schema and interfaces. diff --git a/spec/doc/v1/02-conceptual-model.md b/spec/doc/v1/02-conceptual-model.md new file mode 100644 index 00000000..bf9a8cb6 --- /dev/null +++ b/spec/doc/v1/02-conceptual-model.md @@ -0,0 +1,152 @@ +# Conceptual model and ontology + +## Design rule + +The complete v1 ontology is a primary product capability, not an experiment or +optional extension. processkit v0 already demonstrated that a smaller +Git-native process model and validated agent operations work in principle. +v1 adds the semantic breadth required to express processes, organizations, +evidence, plans, communication, resources, and agentic work without forcing +unrelated concepts into generic tags or records. + +The ontology remains framework-neutral. Domain packages may compose and extend +it, but MUST NOT redefine its canonical concepts or their class semantics. + +The ontology is applied recursively at different organizational levels. A +deliverable repository may use it to govern product work, while a coordinating +repository may use the same concepts for strategy, portfolio goals, standards, +or cross-project decisions. This semantic consistency does not create a global +database: each repository remains authoritative only for the entities it owns. + +## T/P/D/C class system + +| Class | Count | Contract | +|---|---:|---| +| T — foundational concept | 19 | Reusable schema and lifecycle mechanic without independent persistence. | +| P — primitive | 22 | Atomic persistent entity family with identity, schema, storage, lifecycle, and interfaces. | +| D — discriminator | 24 | Closed typed variant of a parent primitive that inherits its storage and lifecycle. | +| C — composition | 24 | Named concept assembled from primitives and foundational fragments, with a generated schema and declared lifecycle. | +| **Total** | **89** | Complete mandatory v1 ontology. | + +- **PK-MODEL-000:** the v1 ontology MUST contain exactly the 89 canonical + concepts named below: 19 T, 22 P, 24 D, and 24 C concepts. +- **PK-MODEL-008:** a product profile MAY expose a smaller operational tool + surface, but the standard v1 distribution MUST install and validate the + complete ontology. Profile selection MUST NOT change concept meaning. + +## Canonical ontology inventory + +### T — foundational concepts (19) + +State, Transition, StateMachine, Lifecycle, Constraint, Guard, Identity, +Versioning, Ownership, Immutability, Schema, Composition, Inheritance, +Uniqueness, Interface, ValidationMode, Provenance, Visibility, and +Cardinality. + +### P — atomic primitives (22) + +Actor, Artifact, Binding, Capability, Channel, Command, Container, Event, +Gate, Location, Note, Outcome, Policy, Proposition, Queue, Record, Recurrence, +Resource, Role, Skill, Specification, and WorkItem. + +### D — discriminator variants (24) + +| Parent primitive | Discriminators | +|---|---| +| Proposition | Risk, Belief, WorldFact, WSJFEstimate, Assumption | +| Location | GeographicRegion, Site, Coordinate, LogicalRegion, Timezone | +| Capability | Disposition | +| Container | Portfolio, ValueStream, ART, Team, Project, Scope | +| Binding | Hierarchy, Position, ProvenanceLink, Correlation, Dependency, OwnershipLink, RelatedTo | + +### C — compositions (24) + +TeamMember, DecisionRecord, LogEntry, Measurement, Archive, +ProcessSpecification, GoalSpecification, Service, RoleSpecification, +GateSpecification, SchemaSpecification, ScheduleSpecification, +TestSpecification, ChannelSpecification, QueueSpecification, WorkItemTemplate, +Migration, ScopePlan, Roadmap, ProgramIncrement, Iteration, Release, +Discussion, and EvaluationRun. + +- **PK-MODEL-009:** canonical names, classes, parent primitives, and + composition membership MUST be represented in one versioned ontology + registry from which schemas, references, query metadata, and coverage + reports are generated or mechanically checked. + +## Common envelope + +- **PK-MODEL-001:** every entity MUST declare a contract version, entity type, + stable ID, creation time, and typed specification. +- **PK-MODEL-002:** mutable entities SHOULD declare an update time and MUST + declare lifecycle state when their EntityType has a state machine. +- **PK-MODEL-003:** unknown fields MUST fail strict validation unless the + owning schema explicitly declares an extension map. +- **PK-MODEL-004:** extension fields MUST be namespaced and MUST NOT redefine + kernel or EntityType fields. +- **PK-MODEL-005:** IDs MUST be unique within a repository context and remain + stable across path changes. +- **PK-MODEL-006:** references MUST use typed IDs or declared external + references; filenames and Markdown links alone are not durable identity. +- **PK-MODEL-007:** a schema MUST distinguish absent, null, empty, and default + values whenever they have different semantics. + +## Lifecycle and mutation + +- **PK-MODEL-010:** every state transition MUST name its source, destination, + applicable guards, authority requirement, and emitted event. +- **PK-MODEL-011:** terminal-state mutation MUST be prohibited unless the + EntityType defines an explicit correction or supersession operation. +- **PK-MODEL-012:** historical decisions and events MUST be superseded or + corrected through traceable records, not silently rewritten. +- **PK-MODEL-013:** mutating operations MUST validate the complete resulting + entity before replacing canonical state. +- **PK-MODEL-014:** successful mutations MUST emit their required domain event + in the same operation boundary. +- **PK-MODEL-015:** failed validation or authorization MUST leave canonical + files and derived indexes unchanged. + +## Relations and interfaces + +- **PK-MODEL-020:** relations MUST declare type, subject, target, and optional + scope or validity bounds. +- **PK-MODEL-021:** relation types MUST define direction, cardinality, + endpoint constraints, inverse behavior, and deletion semantics. +- **PK-MODEL-022:** interfaces MAY group EntityTypes by capability, such as + `Record`, `Assignable`, or `Versioned`, but MUST NOT hide incompatible + lifecycle semantics. +- **PK-MODEL-023:** querying by interface MUST return the concrete EntityType + and contract version of every result. +- **PK-MODEL-024:** cross-repository references MUST carry repository identity, + object identity, and observed revision where reproducibility matters. +- **PK-MODEL-025:** unresolved external references MUST remain visible and + MUST NOT be treated as validated local relations. +- **PK-MODEL-027:** every persistent entity MUST have exactly one authoritative + repository context. Other contexts MUST use qualified references, imported + evidence, or explicitly non-authoritative projections rather than competing + writable copies. +- **PK-MODEL-028:** authority MUST be scoped to a decision surface. A + coordinating repository MAY own broader intent, policy, dependencies, and + coordination processes, but MUST NOT thereby acquire implicit write + authority over participant repositories. +- **PK-MODEL-029:** organizational structure MAY form a multi-level graph of + coordinating and participating repositories. Where authority overlaps, the + applicable contract MUST define precedence or require explicit resolution. + +## Events + +- **PK-MODEL-030:** LogEntry is the canonical append-only event record. +- **PK-MODEL-031:** an event MUST identify event type, time, actor or system + authority, subject, outcome, and structured details appropriate to its type. +- **PK-MODEL-032:** event vocabulary and detail schemas MUST be versioned. +- **PK-MODEL-033:** operational logs MUST NOT be inserted into the domain + event stream merely because they are available. +- **PK-MODEL-034:** corrections append new evidence and preserve original + content or its cryptographic digest according to retention policy. + +## Extensibility test + +- **PK-MODEL-026:** additions beyond the canonical 89-concept v1 ontology MUST + demonstrate reusable meaning across at least two unrelated product domains, + declare whether they are T, P, D, or C, and provide compatibility and + migration treatment. Otherwise they belong in a package or project + namespace. diff --git a/spec/doc/v1/03-project-storage-and-ownership.md b/spec/doc/v1/03-project-storage-and-ownership.md new file mode 100644 index 00000000..39ad61f8 --- /dev/null +++ b/spec/doc/v1/03-project-storage-and-ownership.md @@ -0,0 +1,130 @@ +# Project storage and ownership + +## Canonical layout + +- **PK-STORE-000:** the processkit root is the selected repository root. The + default context directory is `/context/`. A project MAY + configure another contained context directory before installation. Both the + repository identity and contained context path are recorded in processkit + state and cannot change implicitly. + +```text +context/ + entities//... + schemas/... + state-machines/... + processes/... + skills/... + packages/... + policy/... + generated/... + .processkit/... +``` + +Exact sharding beneath an EntityType is declared by its storage contract. +Index databases, journals, locks, ownership manifests, and installed-release +metadata live below `.processkit/` and are not domain entities. + +- **PK-STORE-000A:** root discovery MUST resolve exactly one repository and + one contained context directory. It MUST reject ambiguous nested roots, + context paths outside the selected repository, and attempts to combine + several repositories into one invocation. +- **PK-STORE-000B:** each clone or worktree MAY maintain its own runtime locks + and disposable indexes. Those derived stores do not coordinate Git branches + and MUST never be treated as shared authority between working copies. + +## Sources of truth + +- **PK-STORE-006:** v1 MUST preserve the product principle of Git-backed, + human-readable canonical entities while defining their formats anew from + this specification. Existing file shapes are migration inputs, not v1 + format authority. +- **PK-STORE-001:** canonical entities, accepted project policy, and local + extensions MUST be ordinary files suitable for Git review. +- **PK-STORE-002:** SQLite databases, full-text indexes, embedding/vector + indexes and entries, caches, rendered indexes, and harness projections MUST + be rebuildable derived state. None may become the only copy of project + context or memory. +- **PK-STORE-007:** SQLite with FTS MUST remain the default derived index + adapter, reimplemented behind the repository query port. Existing index + schemas and code are evidence only and MUST NOT constrain canonical storage + or public query semantics. +- **PK-STORE-008:** embedding text, vectors, chunk metadata, and similarity + indexes MUST identify the canonical source ID, source revision or digest, + projection version, embedding model contract, and generation. Stale or + untraceable entries MUST NOT contribute to a complete or verified result. +- **PK-STORE-009:** deleting every derived database and embedding entry MUST + lose no canonical information; `rebuild` MUST reproduce functionally + equivalent indexes from Git-backed files and declared local configuration. +- **PK-STORE-003:** generated schemas MAY be committed for review, but their + generator inputs and generation metadata MUST identify the authoritative + source and support a drift check. +- **PK-STORE-004:** release payload content and consuming-project state MUST + have distinct ownership; dogfood project entities MUST NOT enter a release. +- **PK-STORE-005:** processkit MUST NOT require users to commit caches, locks + used only for concurrency, or machine-specific paths. + +## File contract + +- **PK-STORE-010:** text contracts MUST use UTF-8, LF on serialization, and a + deterministic documented serialization policy. +- **PK-STORE-011:** entity bodies MAY use Markdown, but structural semantics + MUST remain in validated frontmatter or another declared structured region. +- **PK-STORE-012:** parsers MUST support the complete declared YAML subset and + MUST NOT locate frontmatter with ambiguous delimiter heuristics. +- **PK-STORE-013:** paths derived from IDs or user input MUST be normalized, + checked for containment, and rejected on traversal, symlink escape, special + files, or normalization collision. +- **PK-STORE-014:** writes MUST use temporary files in the destination + filesystem, flush as required by the durability profile, and replace + atomically where the platform supports it. +- **PK-STORE-015:** multi-file operations MUST use a journal and publish their + achieved guarantees; processkit MUST NOT label a sequence atomic when a + crash can expose an intermediate state. + +## Ownership classes + +Every managed path is classified as one of: + +- `release-owned`: exact bytes supplied by a pinned package; +- `mergeable`: upstream baseline with supported project customization; +- `project-owned`: created and controlled by the consuming project; +- `generated`: reproducible from declared inputs; or +- `runtime`: local cache, lock, journal, or index. + +- **PK-STORE-020:** installation manifests MUST record path, ownership class, + source package, source digest, installed digest, and applicable merge rule. +- **PK-STORE-021:** update MUST use recorded base, incoming release, and local + content for three-way reconciliation of mergeable files. +- **PK-STORE-022:** an unresolved semantic or textual conflict MUST stop before + canonical mutation and appear in both human and machine plans. +- **PK-STORE-023:** uninstall MUST remove only paths whose ownership and + unchanged state processkit can prove; modified or project-owned paths remain. +- **PK-STORE-024:** processkit MUST NOT silently overwrite an unknown existing + path, adopt it as owned, or delete an untracked path. + +## Concurrency and recovery + +- **PK-STORE-030:** mutating commands MUST acquire a root-scoped operation lock + with owner, process, start time, and safe stale-lock diagnostics. +- **PK-STORE-031:** concurrent reads MAY proceed from canonical files; index + readers MUST detect generation changes or use a consistent snapshot. +- **PK-STORE-032:** interruption MUST preserve a recovery journal until the + operation is completed, rolled back, or explicitly abandoned. +- **PK-STORE-033:** recovery MUST revalidate source hashes and current paths; + it MUST NOT replay stale operations onto changed content. +- **PK-STORE-034:** `verify` and `doctor` MUST distinguish invalid canonical + state, stale derived state, interrupted mutation, and benign local changes. +- **PK-STORE-035:** processkit MAY inspect Git root, tracked state, ignore + rules, and cleanliness for safety evidence but MUST NOT commit, merge, + rebase, push, fetch, switch branches, or modify Git configuration as an + implicit side effect of a lifecycle or entity operation. +- **PK-STORE-038:** processkit MUST report the selected repository identity, + working-copy revision, context path, and relevant worktree state in plans + and machine results whenever they affect reproducibility or mutation safety. +- **PK-STORE-036:** a command requiring a clean worktree MUST report the exact + relevant dirty paths and allow no blanket assumption that unrelated changes + belong to processkit. +- **PK-STORE-037:** generated ignore-file updates are planned, bounded to a + marked processkit block, idempotent, and preserve surrounding project-owned + content. diff --git a/spec/doc/v1/04-content-packages-and-extensions.md b/spec/doc/v1/04-content-packages-and-extensions.md new file mode 100644 index 00000000..30d8b2af --- /dev/null +++ b/spec/doc/v1/04-content-packages-and-extensions.md @@ -0,0 +1,132 @@ +# Content, packages, and extensions + +## Content types + +processkit distributes process capability as independently inspectable files: + +- EntityType schemas and state machines; +- skills containing instructions, tools, configuration, and references; +- ProcessSpecifications; +- templates and maintained examples; +- policies and validation rules; +- harness-neutral capability metadata; +- harness projections generated from that metadata; and +- documentation tied to the owning content. + +## Package manifest + +- **PK-PKG-001:** every package MUST have a versioned manifest declaring name, + version, processkit compatibility, contents, dependencies, conflicts, + ownership classes, capabilities, and digests. +- **PK-PKG-002:** package dependency resolution MUST be deterministic for a + pinned release and MUST fail on cycles, absent dependencies, incompatible + ranges, duplicate ownership, or ambiguous capability providers. +- **PK-PKG-003:** profiles MUST be named selections of packages; they MUST NOT + duplicate package contents or alter package semantics implicitly. +- **PK-PKG-004:** v1 MUST publish one complete `standard` profile. Additional + profiles MAY select different packages, but are not separate v1 conformance + targets and MUST publish an exact resolved manifest when supplied. +- **PK-PKG-005:** package and profile selection MUST be previewable without + filesystem mutation. + +## Skills + +A skill has one canonical processkit representation. It is not authored once +per harness. Its package contains a harness-neutral manifest and instruction +document plus any declared references, templates, assets, scripts, and MCP +capabilities. Harness-native files are disposable projections of that source. + +- **PK-PKG-010:** a skill MUST declare stable identity, version, purpose, + triggers, inputs, outputs, owned capabilities, dependencies, side effects, + safety constraints, and progressive-disclosure resources. +- **PK-PKG-011:** skill instructions MUST be provider-neutral; provider or + harness adapters MAY project them into native discovery formats without + changing their semantics. +- **PK-PKG-012:** a skill that exposes MCP tools MUST declare those tools in a + machine-readable capability manifest whose schemas match runtime discovery. +- **PK-PKG-013:** skills MUST declare whether operations are read-only, + project-mutating, externally mutating, privileged, or destructive. +- **PK-PKG-014:** extension skills MUST NOT impersonate a reserved processkit + identity or override a core capability without explicit policy. +- **PK-PKG-015:** a canonical skill MUST declare which parts are normative + semantics and which are explanatory text. A harness adapter MUST preserve + purpose, triggers, inputs, outputs, safety, side effects, required tools, and + progressive-disclosure order; formatting and invocation syntax MAY differ. +- **PK-PKG-016:** scripts and MCP tools remain separately executable declared + capabilities. Project text or generated prompt files MUST NOT silently gain + executable authority. + +## Processes + +- **PK-PKG-020:** a ProcessSpecification MUST declare ordered or branching + steps, + entry conditions, completion conditions, required capabilities, evidence, + failure behavior, and resumability. +- **PK-PKG-021:** ProcessSpecifications describe coordination semantics; they + MUST NOT embed arbitrary executable code. +- **PK-PKG-022:** starting a durable process MUST create a declared execution + record composed from the canonical ontology, or a declared set of linked + WorkItems, so execution state is inspectable. +- **PK-PKG-023:** process overrides MUST identify the upstream definition and + compatibility range they replace. + +## Extension model + +- **PK-PKG-030:** projects MAY add namespaced EntityTypes, relation types, + skills, processes, policies, and packages under project-owned paths. +- **PK-PKG-031:** extensions MUST validate against published extension + metaschemas and MUST declare their namespace owner. +- **PK-PKG-032:** extension loading order MUST be deterministic and explicit; + directory traversal order MUST NOT affect behavior. +- **PK-PKG-033:** processkit MUST offer conformance commands that validate an + extension without installing it into a real project. +- **PK-PKG-034:** extension failures MUST be isolated and attributed; one + invalid optional extension MUST NOT silently disable unrelated core checks. +- **PK-PKG-035:** executable plugins are outside the default v1 extension + model. If introduced later, they require a separate trust, sandbox, signing, + and compatibility contract. + +## Harness projections + +A harness adapter maps the canonical skill and capability catalogs to one +documented harness contract: discovery paths, instruction wrappers, command +aliases, MCP configuration, and supported metadata. Adapters do not own skill +semantics. + +- **PK-PKG-040:** one canonical capability catalog MUST generate supported + harness configuration and command/skill projections. +- **PK-PKG-041:** projection generation MUST preserve user-owned configuration + or stop with a conflict; generated files MUST carry provenance. +- **PK-PKG-042:** harness absence MUST NOT prevent package installation, + verification, CLI use, or manual MCP configuration. +- **PK-PKG-043:** adding a harness adapter MUST NOT change core entity or + process semantics. +- **PK-PKG-044:** each adapter MUST publish a support matrix. If a harness + cannot represent a required skill constraint, generation MUST report the + loss and verification MUST fail when that projection is required by policy. +- **PK-PKG-045:** `init` MAY detect supported harnesses and include their + projections in its installation plan, but MUST NOT install every known + adapter implicitly. Explicitly configured or selected targets take + precedence over detection. +- **PK-PKG-046:** one plan MAY contain several harness targets. Applying it + MUST generate all selected projections from the same canonical catalog and + record adapter versions and source digests, allowing one repository to + support several harnesses without maintaining several skill sources. +- **PK-PKG-047:** selected harness targets and adapter options MUST be + declarative desired state in project configuration. Projection files and + merged harness MCP configuration are observed state; deleting or changing + them creates detectable drift rather than changing the desired catalog. + +## Future organizational distributions + +Organizations may eventually publish a governed processkit adaptation that +preselects or adds mandatory profiles, processes, policies, skills, prompts, +and MCP capabilities for their developers. The organization-specific +distribution is not part of the v1 contract. + +Its future design must preserve upstream processkit identity and provenance, +distinguish upstream and organization-owned content, support private +distribution and authenticated installation, declare compatibility with an +exact upstream range, and provide a continuous update and conflict-resolution +path. A downstream Git fork requiring indefinite manual merges is one option +to evaluate, not the assumed product model. diff --git a/spec/doc/v1/05-application-and-lifecycle.md b/spec/doc/v1/05-application-and-lifecycle.md new file mode 100644 index 00000000..bb90c82f --- /dev/null +++ b/spec/doc/v1/05-application-and-lifecycle.md @@ -0,0 +1,177 @@ +# Application and lifecycle + +## Distribution + +The reference implementation is installed as a Python application with +`uv tool install processkit==` or an equivalent isolated Python +application installer. Releases publish a wheel, source distribution, source +archive, checksums, SBOM, and signature or attestation material. + +- **PK-CLI-000:** the installed CLI is `processkit`; `pk` MAY be supplied as a + documented alias. All repository commands accept `--root`, where root means + exactly one repository working copy rather than its `context/` directory. + +## Command surface + +| Command | Purpose | +|---|---| +| `processkit version` | Report product, source, runtime, and contract versions. | +| `processkit help` | Show stable command help. | +| `processkit list KIND` | List installed `skills`, `ontology`, `packages`, `profiles`, `mcp-servers`, `harness-adapters`, or another declared catalog kind. | +| `processkit show KIND NAME` | Describe one catalog entry and its source, version, compatibility, and enabled state. | +| `processkit init [--harness TARGET...]` | Convenience form of `plan install` for an uninitialized repository; it creates a reviewable plan and does not apply it. | +| `processkit plan OPERATION` | Preview install, update, reconcile, profile, adapter, or removal changes. | +| `processkit apply --plan PLAN` | Apply an exact reviewed plan. | +| `processkit verify` | Verify ownership, contracts, projections, and derived state. | +| `processkit doctor [--reconcile]` | Diagnose and optionally apply bounded safe repairs. | +| `processkit migrate plan|apply|verify` | Operate an explicit contract or data migration through reviewed phases. | +| `processkit index status|rebuild` | Inspect or rebuild disposable lexical, semantic, and vector indexes. | +| `processkit generate TARGET` | Regenerate declared schemas, documentation, or manifests that do not require installation reconciliation. | +| `processkit entity get ID` | Read one canonical entity by typed ID or exact repository-relative path. | +| `processkit entity list [TYPE]` | List entities with state, scope, relation, and pagination filters. | +| `processkit entity search QUERY` | Run lexical, semantic, or hybrid retrieval with explicit method and filters. | +| `processkit entity create TYPE` | Create an entity from structured input through its declared operation. | +| `processkit entity update ID` | Update fields allowed by the entity contract. | +| `processkit entity transition ID STATE` | Apply a declared lifecycle transition. | +| `processkit entity link SUBJECT RELATION TARGET` | Create a validated relation or Binding. | +| `processkit entity supersede OLD NEW` | Supersede historical state without silent rewriting. | +| `processkit entity archive ID` | Apply the entity's declared archival operation. | +| `processkit event list` | Query canonical domain events by subject, actor, type, outcome, and time. | +| `processkit context assemble` | Assemble bounded attributed context from one repository for a supplied task. | +| `processkit skill find|route` | Find an applicable skill or route a task through installed policy. | +| `processkit harness detect|verify` | Detect applicable harnesses and verify generated projections; the general catalog lists adapters. | +| `processkit handoff export|import` | Export or import a bounded cross-repository handoff without remote mutation. | +| `processkit mcp serve --stdio` | Serve the configured MCP capability set over standard input/output. | +| `processkit mcp serve --http` | Run the same repository-bound MCP application as a long-lived authenticated loopback daemon. | +| `processkit mcp proxy` | Bridge a harness's stdio connection to the configured local daemon. | +| `processkit package validate` | Validate a package or extension in isolation. | + +- **PK-CLI-009:** the generic entity, event, context, skill, and handoff + command groups are mandatory v1 surfaces. EntityType- and skill-specific + convenience aliases MAY be added after their contracts are stable, but use + the same application services and machine envelopes. +- **PK-CLI-013:** `list` MUST be read-only and return canonical identity, + version, source package, installation status, enabled state where + applicable, and compatibility metadata in text and versioned machine form. +- **PK-CLI-014:** listable kinds MUST derive from the installed ontology and + capability catalogs. The CLI MUST NOT maintain a second hard-coded catalog + that can drift from MCP discovery or package manifests. +- **PK-CLI-015:** products exposing a local MCP server MUST use the common + command shape ` mcp serve --stdio`. Product-specific root and + capability options MAY extend this shape without renaming the command. +- **PK-CLI-016:** CLI and MCP need not use identical names, but every + repository read or mutation available through both adapters MUST resolve to + the same application operation and produce equivalent outcomes, events, + authorization checks, and recovery behavior. +- **PK-CLI-017:** structured input MUST be accepted from a versioned JSON or + YAML document through an explicit file or standard input. Repeated `--set` + flags MAY support simple interactive use but MUST NOT define a second data + model or silently coerce ambiguous values. +- **PK-CLI-018:** every data-bearing command MUST support a versioned machine + result. Text output is a human projection and MUST NOT be the only way to + recover IDs, revisions, diagnostics, events, or recovery state. +- **PK-CLI-019:** entity mutation commands modify only the selected working + copy. They MUST NOT stage, commit, branch, merge, push, open a pull request, + or contact a Git forge unless a separately named future adapter command is + explicitly invoked. +- **PK-CLI-027:** stdio is the universal v1 MCP baseline. V1 also supports an + optional local daemon over authenticated loopback HTTP and a lightweight + stdio proxy. Remote, unauthenticated, and hosted endpoints are outside v1. +- **PK-CLI-028:** harness projection changes use the ordinary lifecycle: + `processkit plan adapter --harness TARGET...` followed by + `processkit apply --plan PLAN`. `TARGET` is data resolved through the adapter + catalog; v1 MUST NOT add a different top-level command per harness. +- **PK-CLI-029:** `processkit init --harness detected` MAY include every + confidently detected supported harness in the initial plan. With no harness + selection it MUST leave projections unconfigured and report the exact plan + command to add them later. +- **PK-CLI-030:** `processkit plan reconcile` MUST compare the complete + declared repository configuration with observed installed packages, + profiles, harness adapters, generated projections, ownership state, and + derived-state generations. Applying its reviewed plan converges only those + processkit-owned or mergeable surfaces whose preconditions still match. +- **PK-CLI-031:** `processkit plan adapter --harness TARGET...` MAY propose + both the declarative configuration change and its resulting projections. + Once accepted configuration names those targets, ordinary `plan reconcile`, + `apply`, and `verify` MUST be sufficient for later automation; callers do + not need harness-specific imperative commands. + +## Lifecycle requirements + +- **PK-CLI-001:** lifecycle plans MUST bind root identity, operation, release, + profile, adapters, current ownership state, input digests, and expiration. +- **PK-CLI-002:** apply MUST refuse a plan when any bound input or relevant + target path changed after planning. +- **PK-CLI-003:** destructive changes require an explicit plan and confirmation; + non-interactive confirmation requires both `--non-interactive` and `--yes`. +- **PK-CLI-004:** `init`, `plan`, `verify`, and doctor without `--reconcile` + MUST be read-only with respect to canonical project state. +- **PK-CLI-005:** `doctor --reconcile` MAY repair only registered, + deterministic, idempotent, locally contained derived or processkit-owned + state. +- **PK-CLI-006:** doctor MUST NOT rewrite project entities, accept policy, + install runtimes, fetch releases, or resolve semantic conflicts. +- **PK-CLI-007:** migration MUST separate analysis, plan, application, and + verification and MUST preserve a recovery record. +- **PK-CLI-008:** all mutating commands MUST support interruption and report + whether rollback completed, recovery is required, or no mutation occurred. + +## Exit categories + +| Code | Category | +|---:|---| +| 0 | Success or completed diagnostic with no blocking finding. | +| 2 | Invalid invocation or malformed input. | +| 3 | Contract, policy, or compatibility refusal. | +| 4 | Conflict or stale plan. | +| 5 | Dependency or environment unavailable. | +| 6 | Operation failed with canonical state preserved. | +| 7 | Recovery or manual inspection required. | +| 130 | Interrupted by SIGINT where supported. | + +- **PK-CLI-010:** exit meanings MUST remain stable within v1.x. +- **PK-CLI-011:** commands MUST NOT use success for skipped required work, + unresolved conflicts, or unavailable checks that determine correctness. +- **PK-CLI-012:** cancellation and termination handling MUST be tested on every + supported operating system, with platform differences documented. + +## Supported environments + +- **PK-CLI-020:** v1 supports CPython 3.12 and later minor versions explicitly + listed in release metadata. +- **PK-CLI-021:** v1 targets current supported Linux, macOS, and Windows on + x86-64 and ARM64 where CPython and uv support are available; each release + MUST state its actually tested matrix. +- **PK-CLI-022:** default operation MUST be local and offline after application + and package installation; network access requires an explicit command or + authorized configuration. +- **PK-CLI-023:** no command may assume a shell, GNU userland, writable home + directory, or ambient Git credentials. +- **PK-CLI-024:** root selection resolves an explicit `--root`, then + `PROCESSKIT_ROOT`, then the nearest ancestor containing `processkit.toml` or + processkit installed-state metadata; otherwise it uses the current directory + only for `init` and fails for commands requiring an installation. +- **PK-CLI-025:** root discovery MUST NOT search configured root lists, cross a + filesystem boundary implicitly, select a descendant, or choose between + multiple repositories by basename. +- **PK-CLI-026:** an invocation MUST report an error when `--root` names the + context directory instead of the repository root unless the implementation + can unambiguously normalize it to the owning repository and reports the + normalized root before mutation. + +## Post-v1 CLI directions + +These directions are intentionally outside the v1.0.0 release gate and need +separate accepted contracts before implementation: + +- harness conversation-memory review or synchronization; repository entity + archival is already part of the v1 entity surface; +- company-specific processkit distributions carrying organization-wide + processes, policy, skills, prompts, profiles, and MCP capabilities. + +Memory lifecycle design MUST first distinguish durable repository memory from +harness conversation/session context and analyze overlap with harnesses such +as tau. Company-distribution design MUST compare upstream package composition, +private distributions, overlays, and downstream forks, and define provenance, +trust, naming, compatibility, update cadence, and continuous upstream +reconciliation. No particular adaptation mechanism is selected by v1. diff --git a/spec/doc/v1/06-agent-protocol-and-query-surface.md b/spec/doc/v1/06-agent-protocol-and-query-surface.md new file mode 100644 index 00000000..09a14a78 --- /dev/null +++ b/spec/doc/v1/06-agent-protocol-and-query-surface.md @@ -0,0 +1,147 @@ +# Agent protocol and query surface + +## MCP role + +MCP is processkit's primary agent-facing protocol. The CLI and MCP adapters +invoke the same application services and enforce identical validation, +authority, mutation, event, and recovery semantics. + +The MCP server serves one explicitly selected repository root. It may be +launched by Airunner, Tau, another harness, an IDE, or a human-operated shell, +but the launcher does not change repository authority. The reference profile +runs locally inside the contributor's execution environment against that +contributor's working copy. + +The runtime exposes one repository's configured capability catalog. It may be +an on-demand stdio process or one long-lived local daemon reused through +direct HTTP clients and lightweight stdio proxies. Both execute the same +application core and enforce the same repository root, policy, locking, +transactions, events, and result contracts. + +- **PK-MCP-006:** behavior from the existing gateway and domain tools MAY be + reused only when new v1 conformance fixtures approve it. Existing tool + implementations and observed behavior are not normative. +- **PK-MCP-007:** semantics currently distributed across Python per-skill + servers MUST be consolidated into the shared application core. Legacy + per-domain servers are migration inputs, not an additional v1 runtime model. + +## Discovery + +- **PK-MCP-001:** runtime discovery MUST expose tool name, version, description, + input schema, output schema, side-effect class, owning capability, and + deprecation state. +- **PK-MCP-002:** discovered schemas MUST match the schemas used for runtime + validation and generated reference documentation. +- **PK-MCP-003:** tool names MUST be stable and collision-free; aliases MUST + declare their canonical replacement and removal horizon. +- **PK-MCP-004:** a configured capability absent at runtime is a startup or + verification failure, not a silently omitted tool. +- **PK-MCP-005:** list/read/search tools MUST be clearly distinguishable from + project-mutating and externally mutating tools. +- **PK-MCP-008:** discovery MUST expose the selected repository identity, + context path, working-copy revision, read/write capability, and index + freshness without exposing ambient credentials. + +## Core read surface + +The standard profile provides operations equivalent to: + +```text +get_entity(id | path) +list_entities(type?, state?, scope?, limit?, cursor?) +search_entities(text, filters?, limit?, cursor?) +semantic_search_entities(text, filters?, limit?, cursor?) +hybrid_search_entities(text, filters?, limit?, cursor?) +query_by_interface(interface, filters?, limit?, cursor?) +traverse_relations(subject, relation?, direction?, depth?) +events_for_subject(subject, after?, limit?, cursor?) +find_skill(task_description) +route_task(task_description, constraints?) +get_effective_configuration() +assemble_context(task, constraints?, token_budget?, provenance?) +``` + +- **PK-MCP-010:** reads MUST come from canonical files or a verified index + generation and MUST report index staleness when freshness cannot be proven. +- **PK-MCP-011:** pagination order and cursors MUST be deterministic for a + stable generation. +- **PK-MCP-012:** search ranking MAY evolve compatibly, but filters, result + identity, and completeness claims MUST be explicit. +- **PK-MCP-013:** a query MUST not expose private entity bodies or sensitive + fields beyond the caller's configured local policy. +- **PK-MCP-014:** semantic and hybrid search MUST return canonical entity IDs, + source digests, ranking method, and index generation. Similarity is a + retrieval signal, not evidence that a proposition is true or current. +- **PK-MCP-015:** context assembly MUST be bounded by explicit size or token + limits, preserve source attribution, report omissions and stale indexes, and + prefer canonical relationships and policy over embedding similarity alone. +- **PK-MCP-016:** every context result MUST remain reproducible enough to fetch + its canonical source records without relying on an embedding database row. + +## Mutation surface + +EntityTypes own typed create, update, transition, link, supersede, and archive +operations as applicable. + +The generic CLI entity commands and typed MCP tools are projections of these +same operations. The ontology and capability registries, not adapter-specific +hard-coded lists, determine which operations apply to each EntityType. + +- **PK-MCP-020:** mutating tools MUST accept structured requests and return a + versioned result containing outcome, affected IDs, emitted event IDs, + warnings, and recovery state. +- **PK-MCP-021:** tools MUST re-read and validate relevant state immediately + before commit; read-time observations are not mutation preconditions unless + bound by revision or digest. +- **PK-MCP-022:** optimistic concurrency MUST be available through an expected + revision or content digest. +- **PK-MCP-023:** partial multi-entity success MUST be prohibited unless the + operation contract explicitly defines partial outcomes and compensation. +- **PK-MCP-024:** idempotency keys SHOULD be supported for operations likely to + be retried by orchestrators. +- **PK-MCP-025:** authorization is local policy plus host-process authority; + MCP connectivity alone MUST NOT grant permission to bypass policy. +- **PK-MCP-026:** a successful mutation changes canonical files only in the + selected working copy. It MUST NOT imply that the change was staged, + committed, reviewed, merged, pushed, or accepted by another clone. + +## Runtime and transports + +- **PK-MCP-030:** stdio MUST be supported for local harness integration and + started with `processkit mcp serve --stdio`. +- **PK-MCP-031:** `processkit mcp serve --http` MAY run as a long-lived daemon + bound to loopback for exactly one repository root. It MUST require + per-client authentication, publish health and catalog-generation metadata, + and reject a request attempting to select another root. +- **PK-MCP-032:** requests MUST have size and concurrency limits, cancellation, + timeouts, and bounded error payloads. +- **PK-MCP-033:** the server MUST isolate request context and correlation data; + concurrent responses MUST not leak data or diagnostics between requests. +- **PK-MCP-034:** graceful shutdown MUST stop accepting work, complete or + cancel active operations according to contract, flush evidence, and release + locks. +- **PK-MCP-035:** `processkit mcp proxy` MUST be a bounded transport bridge; it + MUST NOT load tools, reinterpret schemas, weaken authentication, select a + different root, or acquire independent mutation authority. +- **PK-MCP-036:** daemon reuse MUST invalidate or atomically refresh its + capability catalog and derived indexes when the installed manifest, + configuration, canonical generation, or adapter plan changes. A stale + catalog MUST be reported rather than silently served as current. +- **PK-MCP-037:** processkit provides a foreground daemon process and health + contract, not a cross-platform service manager. Aibox, an operating-system + supervisor, or another authorized runtime MAY own start, restart, and stop. + +## Cross-repository coordination + +- **PK-MCP-040:** processkit MAY expose export/import and external-reference + operations, but each call remains scoped to one explicitly selected root + and returns a bundle for transport by Git, a forge, a harness, or Kaits. +- **PK-MCP-041:** a cross-repository handoff MUST identify source repository, + source revision, owning entity, requested outcome, and sanitized evidence. +- **PK-MCP-042:** receiving a handoff MUST create local project-owned state; + it MUST NOT mutate the source repository or claim distributed completion. +- **PK-MCP-043:** portfolio orchestration remains a consumer of processkit + contracts and is outside the processkit agent runtime. +- **PK-MCP-044:** processkit v1 MUST NOT poll repositories, route messages, + retry remote delivery, manage forge issues or discussions, or run + cross-repository heartbeats. Those are adapter or orchestration concerns. diff --git a/spec/doc/v1/07-configuration-output-and-evidence.md b/spec/doc/v1/07-configuration-output-and-evidence.md new file mode 100644 index 00000000..8fb10c84 --- /dev/null +++ b/spec/doc/v1/07-configuration-output-and-evidence.md @@ -0,0 +1,103 @@ +# Configuration, output, and evidence + +## Configuration hierarchy + +Configuration resolves from lower to higher precedence: + +```text +compiled defaults +→ system configuration +→ user configuration +→ project policy +→ environment variables +→ command-line or MCP invocation +``` + +- **PK-CONFIG-000:** the application MAY omit a system layer on platforms + without an appropriate location but MUST NOT reorder layers. + +- **PK-CONFIG-001:** configuration files MUST use a closed, versioned schema. +- **PK-CONFIG-002:** environment variables use the `PROCESSKIT_` prefix. +- **PK-CONFIG-003:** relative paths resolve against the file declaring them or + another explicitly documented anchor, never an accidental working directory. +- **PK-CONFIG-004:** project policy MUST NOT select executables, add + credentials, weaken user/system security, enable network listeners, or + redirect state outside allowed roots without higher-authority approval. +- **PK-CONFIG-005:** processkit MUST expose deterministic redacted effective + configuration with winning and overridden sources and rejected settings. +- **PK-CONFIG-006:** invocation overrides are ephemeral unless a dedicated + write command explicitly changes project-owned configuration. +- **PK-CONFIG-007:** project configuration is + `/processkit.toml` by + default; project policy and mutable operational state MUST NOT share one + file. +- **PK-CONFIG-008:** system and user files use the operating system's published + application configuration locations and are reported by `doctor` and the + effective-configuration result even when absent. +- **PK-CONFIG-009:** environment and invocation layers MUST NOT change the + selected root after root discovery has loaded project policy; root selection + is resolved before other project configuration. +- **PK-CONFIG-010:** project configuration MUST declare the desired profile, + packages, skills, MCP capabilities, and harness-adapter targets needed for + deterministic reconciliation. Machine-local daemon addresses, credentials, + and supervisor state MUST remain in higher-authority local configuration. + +## Result envelope + +Every machine result uses a closed versioned envelope containing: + +```text +apiVersion, command, outcome, result, diagnostics, correlationId +``` + +`outcome` distinguishes `succeeded`, `refused`, `failed`, `cancelled`, +`timed_out`, `partial`, and `recovery_required` where applicable. + +- **PK-OUTPUT-001:** JSON stdout MUST contain exactly one declared result + object and no logs, progress, banners, or child output. +- **PK-OUTPUT-002:** requested human results go to stdout and diagnostics to + stderr; non-interactive output is plain and colorless by default. +- **PK-OUTPUT-003:** result schemas, examples, and negative fixtures MUST cover + every command and outcome category. +- **PK-OUTPUT-004:** unknown fields and unsupported result API versions MUST + fail strict consumers. +- **PK-OUTPUT-005:** `version` output MUST report product version, source + commit, build/package provenance, Python runtime, platform, and supported + entity, package, plan, event, and machine-result contract versions. +- **PK-OUTPUT-006:** repository-scoped results MUST identify the normalized + repository root, context path, observed Git revision when available, and + canonical or index generation relevant to the operation. + +## Operational logging + +- **PK-LOG-001:** logs are structured semantic events rendered to configured + sinks after redaction. +- **PK-LOG-002:** events SHOULD include time, level, name, component, operation, + correlation ID, outcome, duration, and attributed dependency. +- **PK-LOG-003:** default level is `warning`; verbosity changes operational + detail, not result semantics. +- **PK-LOG-004:** file and network sinks require authorized configuration and + declare rotation, retention, failure, and privacy behavior. +- **PK-LOG-005:** sink failure MUST be surfaced without corrupting requested + output or canonical domain evidence. + +## Domain evidence + +- **PK-EVIDENCE-001:** entity events, migration journals, ownership manifests, + release records, and accepted gate results are durable evidence, not logs. +- **PK-EVIDENCE-002:** evidence retention and deletion follow project policy; + rotating logs MUST NOT erase authoritative evidence. +- **PK-EVIDENCE-003:** evidence must distinguish observed facts, user claims, + inferred conclusions, skipped checks, and unavailable dependencies. +- **PK-EVIDENCE-004:** export requires an explicit selection and redaction + policy; private context is excluded by default. + +## Redaction + +- **PK-REDACT-001:** secrets, secret-shaped values, personal data, sensitive + paths, and project-declared protected fields MUST be redacted before any + renderer, buffer, log sink, response, telemetry, or test artifact. +- **PK-REDACT-002:** redaction MUST cover structured values, free text, chunks, + exception chains, and concurrent streams. +- **PK-REDACT-003:** raw modes require explicit invocation and MUST still block + known secrets; their residual risk is documented. diff --git a/spec/doc/v1/08-security-and-trust.md b/spec/doc/v1/08-security-and-trust.md new file mode 100644 index 00000000..c7062bfc --- /dev/null +++ b/spec/doc/v1/08-security-and-trust.md @@ -0,0 +1,109 @@ +# Security and trust + +## Assets and boundaries + +Protected assets include project entities, unpublished discussions and notes, +credentials referenced by integrations, Git history, release packages, +ownership manifests, migration evidence, harness configuration, and generated +agent instructions. Derived embedding text and vectors are protected at the +highest sensitivity of their canonical sources because they may reveal source +meaning even when the original text is absent. + +Trust boundaries exist between: + +- release publisher and installer; +- processkit-owned and project-owned content; +- project policy and user/system authority; +- MCP clients and the local runtime; +- canonical files and untrusted indexes or caches; +- package instructions and executable tools; +- one repository and external repositories or services. +- one clone or worktree and another clone or worktree of the same repository. + +## Release trust + +- **PK-SEC-001:** installers MUST verify package integrity and authenticated + release provenance before mutation when signature material is supplied. +- **PK-SEC-002:** trust anchors MUST be configured independently of the + untrusted release being verified. +- **PK-SEC-003:** a checksum downloaded from the same unauthenticated location + as an artifact proves integrity in transit only, not publisher identity. +- **PK-SEC-004:** package manifests MUST bind every installed file digest, + ownership class, contract version, and dependency. +- **PK-SEC-005:** downgrade, prerelease adoption, and trust-anchor replacement + require explicit policy and confirmation. + +## Input and filesystem safety + +- **PK-SEC-010:** parsers MUST bound document size, nesting, collection counts, + string lengths, archive expansion, and decompression ratio. +- **PK-SEC-011:** archives MUST reject absolute paths, traversal, duplicate + normalized paths, symlink/hardlink escape, devices, sockets, and unsupported + metadata before extraction. +- **PK-SEC-012:** filesystem checks MUST be race-aware and repeated at commit + boundaries; validation of a path string alone is insufficient. +- **PK-SEC-013:** processkit MUST preserve restrictive permissions for private + runtime state and MUST not broaden permissions silently. +- **PK-SEC-014:** subprocesses, when unavoidable, use argument arrays, + controlled working directories, allowlisted environment, bounded IO, + timeout, and cancellation; shell evaluation is prohibited by default. + +## MCP and instruction safety + +- **PK-SEC-020:** stdio is the universal local transport. The optional v1 HTTP + daemon MUST bind to loopback, authenticate every client using credentials + kept outside project-controlled files, enforce origin and request-isolation + controls applicable to the selected MCP transport, and disclose residual + same-host risks. Non-loopback binding is outside v1. +- **PK-SEC-028:** daemon and proxy diagnostics MUST redact bearer material and + MUST NOT place credentials in command arguments, repository configuration, + generated skill projections, or MCP discovery responses. Credential files + require owner-only permissions where the platform supports them. +- **PK-SEC-021:** mutating and destructive capabilities MUST be labeled for + harness policy and independently checked by processkit. +- **PK-SEC-022:** content from packages, entities, external references, and + imported bundles is untrusted data; it MUST NOT silently acquire executable + or higher-authority semantics because an agent reads it. +- **PK-SEC-023:** imported skills and processes remain disabled until package + trust and project policy accept them. +- **PK-SEC-024:** diagnostics MUST not recommend bypassing containment, + signature, validation, approval, or recovery checks. +- **PK-SEC-025:** repository content, including processkit entities changed by + another participant, MUST be treated as untrusted input until normal project + review and validation policy accepts it. A valid schema does not establish + the truth, authorization, or safety of its claims. +- **PK-SEC-026:** processkit MUST NOT infer caller identity or mutation + authority solely from mutable TeamMember files, Git author metadata, harness + prompts, or environment variables. Authority-sensitive operations require an + authenticated runtime principal or an explicit local policy decision. +- **PK-SEC-027:** project TeamMember records MUST NOT be used as storage for + model-provider credentials, harness session secrets, or private conversational + memory. + +## Dependencies and privacy + +- **PK-SEC-030:** every direct runtime dependency MUST have a documented + purpose and reviewed license, maintenance, provenance, and transitive cost. +- **PK-SEC-031:** dependency and application lockfiles are committed and release + builds fail on unresolved or mutable dependency inputs. +- **PK-SEC-032:** default operation emits no telemetry and performs no network + egress. +- **PK-SEC-033:** tests use synthetic data, reserved domains, temporary roots, + and no ambient credentials or user configuration. +- **PK-SEC-034:** security defects add permanent negative regression coverage + and follow coordinated disclosure without moving published tags. +- **PK-SEC-035:** embedding generation and semantic retrieval MUST run locally + by default. Sending source text or derived representations to a remote model + or vector service requires explicit configuration, disclosure of affected + data classes and destination, and project policy authorization. +- **PK-SEC-036:** private or excluded canonical content MUST remain excluded + from embedding, similarity search, context assembly, logs, and exports unless + the same caller is explicitly authorized for that content. + +## Threat-driven acceptance + +- **PK-SEC-040:** the release suite MUST include adversarial archives, symlink + races where the platform permits testing, malformed YAML/JSON, oversized + inputs, untrusted Markdown instructions, MCP request flooding, stale plans, + interrupted writes, signature failures, malicious package paths, and + redaction boundary cases. diff --git a/spec/doc/v1/09-architecture-and-language.md b/spec/doc/v1/09-architecture-and-language.md new file mode 100644 index 00000000..e0fc89e1 --- /dev/null +++ b/spec/doc/v1/09-architecture-and-language.md @@ -0,0 +1,127 @@ +# Architecture and language assessment + +## Decision drivers + +The implementation language is evaluated against the product defined here, +not against prior sunk cost. Highest-weight drivers are: + +1. correctness of schema, file, lifecycle, and reconciliation behavior; +2. speed of evolving process contracts before v1 stability; +3. MCP and AI-tooling ecosystem fit; +4. cross-platform installation and isolated dependency management; +5. testability of filesystems, failures, and protocol boundaries; +6. maintainer accessibility and extension authoring; +7. startup and memory efficiency; and +8. supply-chain surface and release complexity. + +## Assessment + +| Driver | Python | Go | Rust | +|---|---|---|---| +| Contract iteration and schema tooling | Strong | Good | Adequate | +| MCP and agent ecosystem integration | Strong | Good | Developing | +| Safe high-level YAML/Markdown processing | Strong | Good | Good but costly | +| Single native executable | Weak | Strong | Strong | +| Transactional filesystem implementation | Good with disciplined design | Strong | Strong | +| Extension and contributor accessibility | Strong | Good | Adequate | +| Cross-platform packaging | Strong with uv/PyPI | Strong | Strong | +| Runtime performance | Adequate | Strong | Strongest | +| Implementation complexity for this product | Lowest | Medium | Highest | + +Python wins because processkit is primarily a contract, content, filesystem, +and integration product whose model will continue to evolve through v1 +prereleases. Its performance requirements are modest and IO-bound. `uv tool +install` provides an isolated, reproducible application installation path, so +the absence of one native executable is not decisive. + +Go would be preferred if the dominant product requirement were a native, +dependency-free executable or a long-running high-concurrency service. Rust +would be preferred for a smaller security-critical native installer with +strict resource or embedded constraints. Neither is the primary v1 product. + +The earlier Rust CLI plus Python MCP split is not an implementation baseline. +No module, architecture boundary, API, or behavior is inherited merely because +it exists in that implementation. It may supply adversarial fixtures and +evidence for transaction, archive, trust, migration, and recovery requirements +only after those fixtures are reviewed against this specification. v1 uses a +new one-language implementation unless measured evidence later justifies a +narrow native component. + +## Reference architecture + +- **PK-ARCH-001:** the reference implementation MUST use Python 3.12 or later + as its sole required application language. +- **PK-ARCH-002:** the CLI, MCP server, validation, reconciliation, indexing, + migration, and generation surfaces MUST share one application core. +- **PK-ARCH-003:** public behavior MUST be defined by versioned schemas and + conformance fixtures, not Python module layout or implementation classes. +- **PK-ARCH-004:** the core MUST use explicit ports for filesystem, clock, + process, network, terminal, and index dependencies so tests can control them. +- **PK-ARCH-005:** a future native component requires measured need, a narrow + versioned boundary, independent fixtures, failure isolation, and an accepted + architecture decision. +- **PK-ARCH-006:** implementation MUST begin from the accepted specification + and conformance fixtures, not by porting or adapting modules from the prior + Rust v1 implementation. Reuse requires an explicit file-level review proving + conformance and must not import prior architecture by default. +- **PK-ARCH-007:** the Rust installer MUST be replaced. Its adversarial + transaction, interruption, archive, and recovery cases SHOULD be extracted + as implementation-independent fixtures before replacement where they remain + applicable to the accepted contracts. +- **PK-ARCH-008:** the reference runtime is an on-demand CLI or MCP process, + or an optional long-lived local MCP daemon, bound to one repository working + copy. A sidecar, shared database, remote daemon, or hosted processkit service + MUST NOT be required for v1. +- **PK-ARCH-009:** the Python application MUST remain useful without Aibox, + Airunner, Tau, Kaits, or a Git forge. Those products may launch or consume + it through the documented CLI, MCP, file, and handoff contracts. + +## Component boundaries + +```text +CLI / MCP adapters + ↓ +application services + ↓ +domain model and policies + ↓ +ports: repository, lexical index, semantic index, package, clock, process, + network, rendering + ↓ +local adapters: filesystem, SQLite/FTS, embedding/vector index, + uv/Python packaging, MCP stdio and loopback HTTP +``` + +Each running application instance binds the repository port to one working +copy and the index ports to disposable state derived from that copy. Separate +agents normally have separate clones and index generations; Git review and +merge, not shared index state, reconcile their accepted work. + +- **PK-ARCH-010:** domain behavior MUST not depend on CLI parsing, MCP SDK + objects, SQLite rows, or ambient process globals. +- **PK-ARCH-011:** canonical repository mutation MUST have one implementation + path shared by CLI, MCP, migration, and reconciliation. +- **PK-ARCH-012:** SQLite with FTS is the default derived query adapter; a + different adapter MAY be added without changing canonical storage semantics. +- **PK-ARCH-015:** embedding generation and vector search MUST be behind + replaceable local ports. Their model, dimensions, chunking, distance metric, + and projection version are adapter metadata and MUST NOT enter canonical + entity semantics. +- **PK-ARCH-013:** Pydantic or equivalent typed boundary models MAY be used, + but published JSON Schemas and fixtures remain the interoperability contract. +- **PK-ARCH-014:** network release resolution and external connectors are + optional adapters and MUST not enter the local domain core. +- **PK-ARCH-016:** Git and forge automation MAY be implemented later as + explicit adapters over proposed changes and handoff bundles. It MUST NOT be + embedded in entity application services or make GitHub-specific concepts + part of the ontology. + +## Dependency posture + +- **PK-ARCH-020:** the initial implementation SHOULD prefer maintained focused + libraries for CLI, MCP, YAML, JSON Schema, models, and platform directories. +- **PK-ARCH-021:** it SHOULD use the standard library for hashing, archives + where safely sufficient, atomic file operations, subprocess control, + logging foundations, and SQLite. Dependency selection is finalized during + implementation planning with locked versions and contract tests; this + specification does not bless a library by name. diff --git a/spec/doc/v1/10-verification-strategy.md b/spec/doc/v1/10-verification-strategy.md new file mode 100644 index 00000000..a40c9e89 --- /dev/null +++ b/spec/doc/v1/10-verification-strategy.md @@ -0,0 +1,99 @@ +# Verification strategy + +## Principles + +Default checks are offline, deterministic, credential-free, parallel-safe, +locale-independent, and isolated from real home directories and repositories. +Tests assert observable contracts and failure behavior, not only code paths. + +## Layers + +| Layer | Required evidence | +|---|---| +| Unit | Domain invariants, merge decisions, lifecycle guards, parsing, rendering, redaction. | +| Component | Repository transactions, indexes, package resolution, configuration, migration, MCP dispatch. | +| Contract | Schemas, positive/negative fixtures, CLI/MCP envelopes, generated-reference drift. | +| Black box | Installed CLI and MCP workflows in temporary repositories. | +| Integration | Supported Python, OS, filesystem, terminal, uv, Git, and harness adapters. | +| Disposable end to end | Signed artifact install, first workflow, update conflict, recovery, removal, and published-artifact verification. | + +## Required suites + +- **PK-TEST-001:** schema metaschema tests and positive/negative fixtures MUST + cover every public contract and format assertion. +- **PK-TEST-002:** every EntityType MUST test create, read, valid transition, + invalid transition, unknown field, malformed reference, concurrency conflict, + emitted event, and terminal behavior as applicable. +- **PK-TEST-003:** mutation tests MUST inject failures before and after each + durability boundary and assert canonical files, journals, indexes, and + reported recovery state. +- **PK-TEST-004:** install/update tests MUST cover clean install, idempotence, + unchanged update, local modification, compatible merge, conflict, stale plan, + interruption, recovery, downgrade refusal, and conservative uninstall. +- **PK-TEST-005:** MCP tests MUST compare runtime discovery with published + schemas and execute requests over stdio and the authenticated daemon/proxy + path, including concurrency, cancellation, bounds, malformed input, + authentication refusal, catalog refresh, root isolation, and shutdown. +- **PK-TEST-015:** every application operation exposed through both CLI and + MCP MUST have adapter-equivalence tests for successful, refused, stale, + invalid, interrupted, and recovery-required outcomes. +- **PK-TEST-006:** query tests MUST compare indexed results with a canonical + scan across randomized create/update/archive sequences. +- **PK-TEST-014:** semantic and hybrid retrieval tests MUST cover deterministic + fixture embeddings or a controlled fake adapter, source attribution, + sensitivity filters, stale projections, model changes, complete rebuild, + bounded context assembly, and operation with semantic indexing disabled. +- **PK-TEST-007:** security suites MUST exercise every threat-driven case in + the security chapter and verify refusal plus redaction. +- **PK-TEST-008:** documentation examples and generated references MUST be + executed or schema-validated and checked for drift. +- **PK-TEST-009:** confirmed defects MUST gain permanent regression coverage at + the narrowest useful layer and at a public boundary when user-visible. +- **PK-TEST-013:** applicable signed-release, interrupted-installation, and + recovery cases from prior implementations MUST be adapted to the Python + artifacts and the new ownership contract. Passing an old implementation's + test unchanged is not evidence when its asserted contract differs from v1. +- **PK-TEST-016:** multi-participant tests MUST use independent clones or + worktrees with separate indexes, integrate canonical changes through Git, + and prove that no local lock, cache, or database is mistaken for + cross-working-copy authority. +- **PK-TEST-017:** each supported harness adapter MUST project one canonical + fixture skill, MCP capability, and safety constraint; tests MUST verify + provenance, conflict preservation, idempotence, support-matrix reporting, + and equivalence across all generated harness forms. + +## Property and fuzz testing + +- **PK-TEST-010:** property tests SHOULD cover serialization round trips, path + containment, three-way reconciliation invariants, state-machine + reachability, relation inverse rules, deterministic plans, and index + equivalence. Fuzz smoke tests cover structured parsers, frontmatter + boundaries, archives, machine envelopes, and MCP requests with bounded + resource use. + +## Platform matrix + +Every supported Python minor and release operating system is represented in +pre-release evidence. Filesystem-sensitive behavior is tested on case-sensitive +and case-insensitive filesystems where supported. Windows path, locking, +replacement, signal, and terminal differences receive explicit black-box +tests rather than being inferred from Linux success. + +## Gates + +- **Local fast:** formatting, lint, type check, unit/component subset, + contract fixtures, affected docs. +- **Change risk:** local fast plus selected migration, concurrency, fuzz, + security, compatibility, performance, and platform checks. +- **Pre-release:** complete matrix, dependency/license/vulnerability/secret + review, generated drift, docs, packages, clean-room extension conformance. +- **Release candidate:** exact wheel/source/archive verification and installed + black-box journeys. +- **Published release:** download, integrity/authenticity verification, + isolated installation, `version`, `help`, MCP startup, and first workflow. + +- **PK-TEST-020:** unexplained skips fail required gates. +- **PK-TEST-021:** flaky tests are defects; quarantine requires owner, issue, + scope, and expiry. +- **PK-TEST-022:** coverage is reviewed by risk and MUST NOT be substituted for + behavioral evidence or set as a context-free universal percentage. diff --git a/spec/doc/v1/11-compatibility-migration-and-release.md b/spec/doc/v1/11-compatibility-migration-and-release.md new file mode 100644 index 00000000..ef811749 --- /dev/null +++ b/spec/doc/v1/11-compatibility-migration-and-release.md @@ -0,0 +1,121 @@ +# Compatibility, migration, and release + +## Version axes + +processkit versions these axes independently: + +- product release SemVer; +- entity API; +- package manifest; +- lifecycle plan and journal; +- machine result; +- event vocabulary; +- skill and ProcessSpecification contracts; and +- extension metaschemas. + +The proposed v1 identifiers are: + +| Contract | Identifier | +|---|---| +| Entity envelope and standard EntityTypes | `processkit.projectious.work/entity/v1` | +| Package and profile manifests | `processkit.projectious.work/package/v1` | +| Lifecycle plans and journals | `processkit.projectious.work/plan/v1` | +| Machine results | `processkit.projectious.work/result/v1` | +| Event vocabulary | `processkit.projectious.work/event/v1` | +| Application configuration | `processkit.projectious.work/config/v1` | +| Extension metadata | `processkit.projectious.work/extension/v1` | + +- **PK-COMPAT-000:** contract identifiers MUST include their semantic surface + and version. The previous unqualified `processkit.projectious.work/v2` + Entity API is a migration source, not the identifier for the clean v1 + contract family. + +- **PK-COMPAT-001:** `processkit version --format json` MUST report supported + versions for every public contract axis. +- **PK-COMPAT-002:** each contract MUST define unknown-version, unknown-field, + supported-window, deprecation, migration, and rollback behavior. +- **PK-COMPAT-003:** persisted data MUST NOT be silently reinterpreted under + changed semantics. +- **PK-COMPAT-004:** stricter validation, changed defaults, ordering changes, + new authority requirements, and performance-guarantee changes MUST be + classified for compatibility even when schema shape is unchanged. + +## Compatibility policy + +- **PK-COMPAT-005:** before v1.0.0, prereleases MAY make breaking changes with + migration notes and fixture updates. From v1.0.0 through v1.x: + +- additive optional fields and commands may be minor changes; +- bug fixes preserving declared semantics may be patches; +- removal, required-field addition, semantic reinterpretation, incompatible + validation, or persisted-layout break requires v2 unless an already-declared + v1 migration boundary permits it; +- deprecated public names remain for at least one minor release and six months, + unless a security issue requires faster removal. + +## Migration + +- **PK-MIG-001:** migration is an explicit source-contract to target-contract + transformation with preconditions, operations, expected hashes, validation, + evidence, and rollback limits. +- **PK-MIG-002:** analysis and planning MUST be read-only and available in the + machine result contract. +- **PK-MIG-003:** application MUST operate on a clean Git worktree or create a + complete contained backup, unless the user explicitly accepts a narrower + documented recovery boundary. +- **PK-MIG-004:** migrations MUST preserve unknown project-owned extensions or + stop; they MUST NOT drop fields to make data validate. +- **PK-MIG-005:** append-only events are not rewritten. Identity changes use + aliases, successor/predecessor relations, and new correction events. +- **PK-MIG-006:** v0 and earlier-v1-alpha importers are compatibility adapters, + not sources of v1 semantics. Each has representative golden corpora and a + field-level preservation report. +- **PK-MIG-008:** maintained v0 and released v1-alpha corpora MUST be preserved + as immutable migration fixtures and compatibility evidence. Fixture + preservation does not grandfather their schemas, ontology, or behavior. +- **PK-MIG-007:** an unsupported or ambiguous transformation produces a manual + action and blocks completion; migration MUST NOT guess intent. + +## Release topology + +The v1 line follows the company version-line standard: + +```text +v1.x-dev → v1.x-pre-release → v1.x-release → main +``` + +Topic branches target `v1.x-dev`. Promotion branches are fast-forward-only +pointers and receive no unique commits. Because earlier experimental v1 +history already exists, adoption of this specification requires a separate +reviewed branch-reconciliation decision; this PR does not authorize rewriting +or force-updating a protected branch. + +## Artifacts and provenance + +- **PK-REL-001:** releases originate from a clean worktree and exact annotated, + preferably signed tag. +- **PK-REL-002:** publish wheel, source distribution, source archive, resolved + package manifests, schemas and fixtures, checksums, SBOMs, curated notes, + installation guidance, and signatures or attestations required by policy. +- **PK-REL-003:** build metadata MUST identify source commit, Python and uv + versions, dependency lock digest, supported contract versions, and platform + scope. +- **PK-REL-004:** candidate artifacts MUST be installed and tested without + repository-relative imports or undeclared network access. +- **PK-REL-005:** published artifacts MUST be downloaded and independently + verified before publication is considered complete. +- **PK-REL-006:** tags and artifacts are immutable; corrections use a new + version. + +## v1 acceptance sequence + +- `alpha`: the complete 89-concept ontology registry and generated contracts, + repository transactions, install/verify, and MCP workflow proven. +- `beta`: standard profile, harness-adapter and extension conformance, + migration corpus, complete + security and platform matrices proven; feature freeze begins. +- `rc`: documentation, compatibility, performance, package set, and exact + candidate journeys complete with no unexplained skips. +- final: every normative requirement classified, all blockers closed, stable + tag and artifacts independently verified, and migration/support policy + published. diff --git a/spec/doc/v1/12-documentation-and-acceptance.md b/spec/doc/v1/12-documentation-and-acceptance.md new file mode 100644 index 00000000..f9d5dd89 --- /dev/null +++ b/spec/doc/v1/12-documentation-and-acceptance.md @@ -0,0 +1,108 @@ +# Documentation and acceptance + +## Documentation system + +- **PK-DOC-001:** public documentation MUST describe shipped behavior for the + selected version line and label planned behavior explicitly. +- **PK-DOC-002:** source, schemas, examples, CLI/MCP reference, and development + notes MUST evolve in the same change as the behavior they describe. +- **PK-DOC-003:** CLI, MCP, configuration, schema, package, and event references + MUST be generated or mechanically checked against canonical contracts. +- **PK-DOC-004:** the documentation site MUST build locally and publish static + output from `gh-pages` without project-authored GitHub Actions. +- **PK-DOC-005:** versioned documentation MUST preserve supported v0 material + during v1 development and clearly distinguish stable from prerelease lines. +- **PK-DOC-006:** maintained examples are product contracts and MUST run or + validate in release gates. +- **PK-DOC-007:** existing public documentation MUST be retained in its + applicable versioned archive. v1 documentation MUST be rewritten from the + accepted specification and shipped behavior, not edited as though historical + pages already described the new product. + +The public information architecture covers overview, getting started, +concepts, how-to guides, reference, troubleshooting, roadmap, releases and +migration, contributing, and security. The README remains a concise entry +point, not a second specification. + +## Development evidence + +- **PK-DOC-010:** every non-trivial roadmap phase maintains a development note + recording implementation, boundaries, decisions, deviations, tests, + security, compatibility, documentation, and owned follow-up work. +- **PK-DOC-011:** `roadmap.yaml` is the canonical roadmap and validates against + the company-compatible roadmap schema. +- **PK-DOC-012:** an item becomes `shipped` only when it names a release and + development note and its conformance evidence is accepted. + +## Specification conformance + +Implementation follows the company spec-driven development-cycle standard. +The accepted baseline consists of every file in this directory, its schemas, +examples, governing decisions, and applicable company standards. + +- **PK-ACCEPT-001:** planning MUST inventory every normative requirement and + map it to implementation work, tests, documentation, and evidence. +- **PK-ACCEPT-002:** an independent reviewer MUST review both the plan and the + integrated result against every applicable requirement and executable + contract. +- **PK-ACCEPT-003:** specification defects stop affected implementation and + require an explicit corrective amendment and plan revision. +- **PK-ACCEPT-004:** implementation convenience MUST NOT silently redefine the + contract, and existing behavior MUST NOT be grandfathered without an + explicit compatibility decision. +- **PK-ACCEPT-005:** final conformance classifies every requirement as + satisfied, accepted not-applicable, authorized deferral, or blocker; unknown + and partially satisfied are not completion. + +## Final acceptance journeys + +1. Install an exact authenticated release into an empty temporary repository + on every supported platform. +2. Verify the installed profile and inspect effective configuration. +3. Start MCP over stdio, then reuse the same capability catalog through an + authenticated local daemon and stdio proxy; prove equivalent operations, + root isolation, refresh, and shutdown behavior. +4. List installed skills, ontology concepts, packages, profiles, and MCP + servers in both text and machine form and reconcile the result with package + manifests and MCP discovery. +5. Create, query, transition, relate, and supersede representative entities; + verify equivalent CLI and MCP outcomes, events, and index state without an + implicit Git commit. +6. Generate and validate coverage for all 89 canonical ontology concepts, + exercise every persistent P and C schema, every D discriminator, and every + T fragment through at least one consuming contract. +7. Assemble bounded, attributed agent context through lexical, semantic, and + hybrid retrieval; delete every derived index, rebuild it from canonical Git + files, and obtain functionally equivalent sources without memory loss. +8. Install one canonical skill and MCP capability, project them into two + supported harness formats in one reviewed adapter plan, and prove equivalent + discovery, safety metadata, invocation, provenance, and conflict handling. +9. Run a durable process with a gate, evidence, interruption, and resumption. +10. Add and validate a namespaced extension package without core modification. +11. Preview and apply an update with unchanged, locally modified, mergeable, + conflicting, generated, and project-owned files. +12. Recover from injected interruption at each mutation boundary. +13. Import representative v0 and earlier-v1-alpha corpora with preservation + reports and explicit manual blockers. +14. Export a sanitized cross-repository handoff and receive it as local state. +15. Conservatively uninstall processkit while preserving modified and + project-owned content. +16. Build documentation and verify the exact published release artifacts. +17. Run two independently indexed clones as different TeamMembers, integrate + their proposed context changes through an ordinary reviewed Git merge, + rebuild both indexes, and verify that canonical state converges without a + shared processkit database. +18. Confirm that one repository supports human, permanent-agent, and + ephemeral-agent participants while TeamMember state remains project-local + and runtime memory remains outside canonical entities. +19. Add a newly installed harness target to declarative project configuration, + preview and apply the adapter reconciliation, verify convergence, and then + obtain an empty plan from the same desired state without a harness-specific + imperative command. + +## Definition of v1.0.0 complete + +v1.0.0 is complete only when all normative requirements and acceptance +journeys are evidenced; security, migration, compatibility, documentation, +and platform support are published; no required check has an unexplained skip; +and the exact release artifacts pass independent post-publication verification. diff --git a/spec/doc/v1/13-standard-entity-types.md b/spec/doc/v1/13-standard-entity-types.md new file mode 100644 index 00000000..ff488daf --- /dev/null +++ b/spec/doc/v1/13-standard-entity-types.md @@ -0,0 +1,187 @@ +# Ontology contracts + +This chapter refines high-use ontology concepts and defines the conformance +contract for the complete inventory in the conceptual-model chapter. The +named refinements below do not reduce v1 scope: every one of the 89 canonical +concepts is a release requirement. + +## Complete-ontology requirements + +- **PK-ENTITY-000:** the release MUST publish a machine-readable ontology + registry containing every canonical concept, its T/P/D/C class, description, + owner, interfaces, dependencies, and schema or fragment location. +- **PK-ENTITY-004:** every P primitive and C composition MUST have a closed + entity schema, storage declaration, identity policy, interface metadata, + lifecycle declaration where mutable, and positive and negative fixtures. +- **PK-ENTITY-005:** every D discriminator MUST be a closed variant of its + declared parent P schema, inherit the parent's lifecycle and storage rules, + and publish fixtures proving both valid specialization and invalid mixing. +- **PK-ENTITY-006:** every T foundational concept MUST have one canonical + schema fragment or registry contract and MUST be exercised by at least one + generated P or C schema. +- **PK-ENTITY-007:** ontology generation MUST fail on an unknown class, + duplicate canonical name, missing parent, dependency cycle, unconsumed T + concept, uncovered discriminator, or composition with unresolved parts. +- **PK-ENTITY-008:** a release coverage report MUST prove 19/19 T, 22/22 P, + 24/24 D, and 24/24 C concepts complete. Partial ontology coverage prevents + v1.0.0 release. + +## Work and reasoning + +### WorkItem + +- **PK-ENTITY-001:** WorkItem MUST record title, type, lifecycle state, + priority, description or acceptance outcome, and optional assignee, parent, + scope, dependencies, blockers, and governing decisions. +- **PK-ENTITY-002:** standard WorkItem types are `task`, `story`, `bug`, + `epic`, `spike`, and `chore`; extensions use namespaced values. +- **PK-ENTITY-003:** the default lifecycle is + `backlog → in_progress → review → done`, with explicit `blocked`, + `cancelled`, reopen, and correction paths. Terminal completion records + completion time and evidence where required. + +### DecisionRecord + +- **PK-ENTITY-010:** DecisionRecord MUST contain title, state, context, + decision, rationale, alternatives, consequences, deciders, and decision time + when accepted. +- **PK-ENTITY-011:** its lifecycle is `proposed → accepted → superseded` or + `proposed → rejected`; accepted history is not edited to represent a new + decision. +- **PK-ENTITY-012:** supersession MUST link both records and preserve the old + rationale independently of the new record. + +### Discussion + +- **PK-ENTITY-020:** Discussion MUST contain a driving question, state, + participants or audience, related subjects, and chronological contributions + or a durable body representing the inquiry. +- **PK-ENTITY-021:** discussion outcomes reference accepted DecisionRecords, + created WorkItems, promoted Artifacts, or an explicit no-decision result. +- **PK-ENTITY-022:** closing a Discussion MUST NOT imply agreement unless an + accepted outcome says so. + +### Note + +- **PK-ENTITY-030:** Note captures bounded uncommitted information as one of + `fleeting`, `insight`, `question`, or `reference`, with title, body, source, + tags, and optional review time. +- **PK-ENTITY-031:** promotion creates or links a durable target; it does not + silently mutate a Note into a different EntityType. + +## Evidence and governance + +### Artifact + +- **PK-ENTITY-040:** Artifact identifies a durable deliverable or external + pointer with name, kind, location or body, format, version, ownership, + producer, digest where reproducibility matters, and related subjects. +- **PK-ENTITY-041:** registration does not assert that an external location is + available or trusted; verification state and observed revision remain + explicit. + +### Gate + +- **PK-ENTITY-050:** Gate defines a stable check with description, kind, + validator contract, required authority, blocking behavior, and evidence + requirement. +- **PK-ENTITY-051:** evaluations are append-only events referencing the Gate; + a Gate definition MUST NOT be mutated after evaluation history in a way that + changes the meaning of past results. +- **PK-ENTITY-052:** outcomes are `passed`, `failed`, or `waived`; waiver + requires authority, reason, scope, and expiry or review condition. + +### Scope + +- **PK-ENTITY-060:** Scope defines a bounded project, release, milestone, + sprint, quarter, or namespaced interval with goals, optional parent, time + bounds, and lifecycle. +- **PK-ENTITY-061:** closing Scope MUST evaluate required completion gates and + record unresolved owned work rather than implying it disappeared. + +### Migration + +- **PK-ENTITY-070:** Migration records source/target contracts, state, + preconditions, operations, affected paths or entities, evidence, progress, + and applied or rejection outcome. +- **PK-ENTITY-071:** migration lifecycle and semantics follow the migration + requirements in the compatibility chapter and cannot embed arbitrary code. + +### LogEntry + +- **PK-ENTITY-080:** LogEntry uses the event contract from the conceptual model + and is append-only after successful creation. +- **PK-ENTITY-081:** event types have a registered owner and schema; unknown + event details MUST NOT be interpreted as a known event type. + +## People, teams, and relations + +### Actor + +- **PK-ENTITY-090:** Actor represents a human, AI agent, service, or + organization with display identity, active status, optional contact or + handle, declared capabilities, and privacy classification. +- **PK-ENTITY-091:** provider credentials, secret model identifiers, and + mutable runtime session state MUST NOT be stored in ordinary Actor entities. + +### Role + +- **PK-ENTITY-100:** Role defines provider-neutral responsibilities, required + capabilities or skills, and default scope; a Role is not a person or model. +- **PK-ENTITY-101:** changing the meaning of a Role with historical bindings + requires versioning or supersession rather than silent reinterpretation. + +### TeamMember + +- **PK-ENTITY-110:** TeamMember is the selected repository's local + representation of a human, permanent-agent, or ephemeral-agent participant. + It composes an Actor or qualified Actor reference with project-facing role + defaults, persona projection, capability references, engagement class, and + lifecycle. +- **PK-ENTITY-111:** a project TeamMember MUST NOT silently become the + canonical cross-repository identity, private memory store, credential store, + or Airunner session record for that participant. Credentials and runtime + working state remain outside ordinary project entities and exports. +- **PK-ENTITY-112:** TeamMember identity remains provider-neutral; runtime + model selection is a policy or Binding resolved at invocation time. +- **PK-ENTITY-113:** permanent and ephemeral participation MUST be explicit. + Ephemeral engagement may declare an end condition and narrower authority but + uses the same Actor, Role, Binding, event, and evidence contracts. +- **PK-ENTITY-114:** one TeamMember may hold a scoped team-leader Role without + becoming a different Actor kind. Human companion agents remain AI Actors and + may exercise human authority only through an explicit scoped Binding. +- **PK-ENTITY-115:** resolution of a company-wide canonical identity and its + projection into Airunner is an external identity contract in v1. A project + MAY use a revision-bound qualified reference and retain only locally owned + membership, role, and participation state. + +### Binding + +- **PK-ENTITY-120:** Binding is the canonical scoped or time-bounded relation + entity and contains relation type, subject, target, optional scope, + validity, conditions, and description. +- **PK-ENTITY-121:** Binding validation enforces the relation registry's + endpoint, cardinality, inverse, and temporal rules. + +## Durable execution record + +- **PK-ENTITY-130:** a durable execution record binds an exact + ProcessSpecification version to a project root, Scope, initiator, inputs, + ordered state, produced entities, evidence, and completion or recovery + Outcome. +- **PK-ENTITY-131:** a durable execution record MUST expose the current + actionable step and MUST distinguish waiting, blocked, failed, cancelled, + and completed. +- **PK-ENTITY-132:** process execution may coordinate external work but records + observed handoffs and results; it MUST NOT claim external completion without + evidence from the owning system or repository. + +## Schema acceptance + +- **PK-ENTITY-140:** every persistent P or C concept MUST publish a closed + schema, state machine where applicable, storage declaration, relation + constraints, event vocabulary, and valid/invalid fixtures. +- **PK-ENTITY-141:** schemas MUST reuse one versioned common envelope and + fragments without generating divergent copies of shared semantics. +- **PK-ENTITY-142:** generated schemas are release artifacts and MUST match + generator inputs byte-for-byte under the deterministic generation command. diff --git a/spec/doc/v1/14-performance-and-operations.md b/spec/doc/v1/14-performance-and-operations.md new file mode 100644 index 00000000..45af8af6 --- /dev/null +++ b/spec/doc/v1/14-performance-and-operations.md @@ -0,0 +1,86 @@ +# Performance and operations + +processkit is local tooling, not a high-throughput distributed database. +Performance requirements protect interactive agent use and bound resource +exhaustion without allowing caches to redefine correctness. + +## Scale profile + +The v1 reference profile is one repository containing up to: + +- 100,000 canonical entities; +- 1,000,000 LogEntries; +- 10,000 relations returned by an explicitly bounded traversal; +- 1 GiB total structured context excluding externally referenced artifacts; +- 500 installed skills and ProcessSpecifications; and +- 16 concurrent read requests with one serialized root mutation. + +This is a per-working-copy profile. Multiple agents may operate independent +clones of the same repository; processkit does not coordinate their local +locks or indexes. Git integration detects and resolves concurrent proposed +changes at branch and review boundaries. + +- **PK-PERF-000:** larger repositories MAY work but are outside the v1 + performance guarantee. + +## Interactive budgets + +- **PK-PERF-001:** after warm startup and with a verified index, single-entity + lookup and bounded metadata listing SHOULD complete within 100 ms at the + reference scale on the published reference machine. +- **PK-PERF-002:** bounded full-text search SHOULD return its first page within + 500 ms at the reference scale. +- **PK-PERF-003:** ordinary single-entity validation and mutation excluding + lock wait SHOULD complete within 500 ms and MUST not rebuild the full index. +- **PK-PERF-004:** CLI help and version SHOULD complete within 300 ms warm and + one second cold on the reference machine. +- **PK-PERF-005:** MCP stdio startup SHOULD advertise capabilities within two + seconds with installed dependencies and no network access. +- **PK-PERF-006:** a warm local daemon SHOULD avoid repeated application and + tool-catalog import cost across client connections and report startup, + catalog-load, refresh, request, and proxy overhead separately. + +These are release objectives, not semantic timeouts. A slower correct result +must report measurement and remain cancellable; it must not bypass validation. + +## Bounds and degradation + +- **PK-PERF-010:** list, search, event, and traversal operations MUST require or + apply documented result limits and stable pagination. +- **PK-PERF-011:** relation traversal MUST bound depth, visited nodes, returned + edges, and execution time and report truncation explicitly. +- **PK-PERF-012:** index rebuild MUST stream or batch input and MUST NOT require + all entity bodies in memory simultaneously. +- **PK-PERF-013:** when an index is absent or stale, processkit MAY fall back to + bounded canonical scans but MUST identify degraded completeness or latency. +- **PK-PERF-014:** corrupted indexes are quarantined and rebuilt; they MUST NOT + cause canonical entity deletion or mutation. +- **PK-PERF-015:** request and parser limits are configurable only within + system/user authority bounds; project policy cannot disable protection. + +## Operational behavior + +- **PK-OPS-001:** `doctor` reports runtime, contract support, root identity, + lock and journal state, canonical validation, ownership drift, projection + drift, index generation, package consistency, and configured MCP readiness. +- **PK-OPS-006:** status and diagnostic output MUST distinguish repository + root, context directory, Git revision, canonical generation, and local index + generation so an agent cannot mistake a stale clone or index for current + accepted state. +- **PK-OPS-002:** health output MUST distinguish `healthy`, `degraded`, + `blocked`, and `recovery_required`; unavailable optional checks are not + successes. +- **PK-OPS-003:** every finding has a stable code, severity, scope, evidence, + next action, and optional registered reconciler. +- **PK-OPS-004:** diagnostic collection MUST be available as a sanitized local + bundle with an explicit manifest and exclusion report. +- **PK-OPS-005:** processkit MUST expose its effective resource limits and + current derived-state generations in machine-readable diagnostics. + +## Benchmarks + +Pre-release evidence records reference hardware, operating system, Python +version, filesystem, corpus generator seed and digest, cold/warm state, sample +count, percentiles, and variance. Performance regression thresholds compare +like-for-like profiles and require review rather than silently updating a +golden number. diff --git a/spec/doc/v1/15-review-decisions.md b/spec/doc/v1/15-review-decisions.md new file mode 100644 index 00000000..7dc82a33 --- /dev/null +++ b/spec/doc/v1/15-review-decisions.md @@ -0,0 +1,193 @@ +# Review decisions + +This draft is internally coherent but intentionally does not manufacture +approval for consequential choices. Review must accept, amend, or reject each +item before the specification becomes the implementation baseline. + +## D1 — Complete 89-concept ontology in v1 + +**Accepted:** ship the complete 89-concept T/P/D/C ontology as mandatory v1 +scope and a v1.0.0 release gate. processkit v0 is sufficient proof that the +Git-native, validated process model works; v1 does not need another +reduced-scope product experiment. + +**Reason:** a principal value of v1 is enough semantic breadth to express the +processes, artifacts, organizational structures, evidence, resources, and +agentic-work concepts users may need without misusing generic records or tags. + +**Impact:** all 19 T, 22 P, 24 D, and 24 C concepts require registry coverage, +schema or fragment treatment, query metadata, fixtures, documentation, and +release evidence. Delivery may be phased, but v1.0.0 cannot omit concepts. + +## D2 — Python as the sole required implementation language + +**Proposal:** implement CLI, MCP, domain services, reconciliation, migrations, +generation, and indexing in Python 3.12+, installed as an isolated application +with uv or an equivalent tool. + +**Reason:** Python narrowly outranks Go for this contract- and integration-heavy +product once uv weakens the native single-executable advantage. Rust does not +justify its additional delivery cost for the specified workload. + +**Impact:** the Rust installer is replaced, but its security, transaction, and +recovery fixtures remain implementation evidence. A native component requires +a later measured justification and versioned boundary. + +## D3 — One application core + +**Proposal:** CLI and MCP become adapters over one application and domain core. +Earlier per-skill servers are migration evidence, not another v1 runtime. + +**Reason:** one mutation, validation, event, and recovery path prevents the +current split authority from recurring. + +**Impact:** module and process boundaries may change substantially even when a +public tool name survives. + +## D4 — Compatibility posture + +**Proposal:** support explicit migrations from maintained v0 corpora and +released earlier-v1-alpha corpora, while refusing to preserve alpha behavior +that conflicts with the accepted new contract. + +**Reason:** users deserve preservation and transparent incompatibility, not an +assumption that prerelease implementation details define the replacement. + +**Impact:** each source line needs golden corpora, field-level preservation +reports, manual-blocker behavior, and migration documentation. + +## D5 — Existing v1 branch reconciliation + +**Proposal:** keep this specification PR non-destructive. After acceptance, +prepare a separate reviewed reconciliation plan for the existing `v1.x-dev` +history and promotion branches. + +The plan must identify whether implementation proceeds by removing/replacing +experimental files through ordinary commits, introducing a new version line, +or another ancestry-preserving method. Force-push, tag movement, and unique +commits on promotion branches remain prohibited. + +**Reason:** accepting a new product baseline does not authorize rewriting +published alpha history or protected branches. + +**Impact:** implementation cannot begin until the target branch and handling of +existing alpha support are explicit. + +## D6 — Specification artifact location + +**Proposal:** use `spec/doc/v1/` and `spec/schemas/v1/` for this baseline while +the company discussion on OpenSpec, specifications, and processkit remains +open. Treat this as a project-local choice, not a company-wide directory +standard. + +**Reason:** the implementation needs a bounded reviewable baseline now, while +the broader question of representing specifications as processkit artifacts is +still unresolved. + +**Impact:** a later accepted company model may migrate these files without +changing their normative meaning or history. + +## D7 — Contract namespaces + +**Proposal:** use surface-qualified identifiers such as +`processkit.projectious.work/entity/v1` and +`processkit.projectious.work/result/v1` instead of continuing the old +unqualified `processkit.projectious.work/v2` value. + +**Reason:** product release, entities, packages, machine results, plans, +events, configuration, and extensions have independent compatibility +lifecycles. One unqualified counter cannot express or evolve those contracts +safely. + +**Impact:** existing `processkit.projectious.work/v2` entities require an +explicit source adapter. The apparent numeric move from `v2` to a qualified +`entity/v1` is a namespace change, not a claim that old data has been silently +downgraded. + +## D8 — Repository-scoped process memory + +**Accepted company architecture:** one repository represents one project or +coordination scope and contains one authoritative processkit context. The +context is shared project memory for any number of human and AI participants, +not an agent-private memory repository. + +**Reason:** the repository already supplies the authority, deliverable, +history, collaboration, and review boundary. Agents can use ordinary clones +and branches while processkit gives their shared context typed semantics and +validated operations. + +**Impact:** root means repository root; local indexes are per working copy; +TeamMember is project-local participation state; and processkit does not own +Airunner runtime memory, heartbeat, Git synchronization, or Kaits company +orchestration. + +## D9 — Python command surface + +**Proposal:** ship one Python application with lifecycle, catalog, entity, +event, context, skill, handoff, index, generation, package, and MCP command +groups. CLI and MCP are adapters over identical application operations; typed +MCP tools and optional convenience commands do not create separate semantics. + +**Reason:** humans, scripts, harnesses, and conformance tests need the same +repository capabilities without reproducing validation in shell scripts or +requiring MCP for local administration. Namespaced generic commands avoid a +flat CLI containing one command for every EntityType and skill. + +**Impact:** generic entity and retrieval commands move into mandatory v1 +scope. The tool changes only one selected working copy and never implies Git +commit, review, push, or cross-repository acceptance. + +## D10 — Canonical skills with generated harness adapters + +**Proposal:** processkit continues to own and version skills. Each skill has +one harness-neutral source contract; versioned adapters generate native +discovery files, command aliases, and MCP configuration for selected harnesses. +Initialization may detect and propose supported targets, while the ordinary +plan/apply lifecycle performs changes. There is no top-level command per +harness and no implicit installation of all known adapters. + +**Reason:** harnesses differ in file locations, metadata, invocation syntax, +and MCP configuration, but those differences do not justify divergent copies +of a skill's purpose, safety rules, inputs, or outputs. A generated projection +keeps processkit authoritative while making loss of semantics visible. + +**Impact:** skill authoring and harness projection are v1 capabilities rather +than post-v1 ideas. The release requires adapter support matrices, provenance, +idempotent regeneration, conflict preservation, and cross-harness conformance +fixtures. + +## D11 — Retain the efficient local MCP daemon + +**Proposal:** support both an on-demand stdio server and the useful v0-style +long-lived local gateway daemon with lightweight stdio proxies. The v1 daemon +executes the unified application core directly, serves exactly one repository +root, binds only to loopback, authenticates every client, and refreshes its +catalog safely. Process supervision remains external. + +**Reason:** repeated interpreter startup and registration of a large tool +catalog is avoidable overhead, especially when several harness sessions use +the same working copy. Removing the daemon would discard a proven operational +benefit merely to obtain a smaller topology diagram. + +**Impact:** daemon and proxy are v1 surfaces with root-isolation, credential, +catalog-refresh, concurrency, health, shutdown, and adapter-equivalence tests. +They do not restore per-skill runtime authority, create a shared project +database, or make a hosted service necessary. + +## D12 — Declarative harness reconciliation + +**Proposal:** desired profiles, packages, skills, MCP capabilities, and harness +targets live in versioned project configuration. `plan reconcile` computes the +drift and `apply --plan` converges it. `plan adapter --harness ...` is an +onboarding convenience that proposes the desired-state change as well as the +projection actions. + +**Reason:** adding Tau or another harness later should use the same reviewed, +idempotent plan/apply model as installation and upgrade. A declarative source +also permits future CI/CD or GitOps controllers to run reconciliation without +embedding a separate imperative command sequence. + +**Impact:** v1 does not need to ship a controller, Argo CD integration, or +continuous reconciler. It must provide stable desired-state, plan, machine +result, drift, idempotence, and verification contracts from which those +systems can be built. diff --git a/spec/doc/v1/README.md b/spec/doc/v1/README.md new file mode 100644 index 00000000..80bb1e70 --- /dev/null +++ b/spec/doc/v1/README.md @@ -0,0 +1,53 @@ +# processkit v1.x product specification + +Status: **draft for review** + +This directory defines the proposed normative baseline for a clean processkit +v1.x implementation. Existing v0 code, the earlier v1 alpha implementation, +and its Rust/Python architecture are evidence only. They do not define this +contract unless a requirement below deliberately preserves their behavior. + +Normative terms `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` have the +meanings defined by RFC 2119 and RFC 8174. + +## Reading order + +1. [Product definition](01-product-definition.md) +2. [Conceptual model and ontology](02-conceptual-model.md) +3. [Project storage and ownership](03-project-storage-and-ownership.md) +4. [Content, packages, and extensions](04-content-packages-and-extensions.md) +5. [Application and lifecycle](05-application-and-lifecycle.md) +6. [Agent protocol and query surface](06-agent-protocol-and-query-surface.md) +7. [Configuration, output, and + evidence](07-configuration-output-and-evidence.md) +8. [Security and trust](08-security-and-trust.md) +9. [Architecture and language](09-architecture-and-language.md) +10. [Verification strategy](10-verification-strategy.md) +11. [Compatibility, migration, and + release](11-compatibility-migration-and-release.md) +12. [Documentation and acceptance](12-documentation-and-acceptance.md) +13. [Ontology contracts](13-standard-entity-types.md) +14. [Performance and operations](14-performance-and-operations.md) +15. [Review decisions](15-review-decisions.md) +16. [Roadmap](roadmap.yaml) + +## Contract hierarchy + +Where documents disagree, executable schemas and fixtures govern structural +shape, numbered normative requirements govern semantics, and explanatory prose +provides intent. A contradiction is a specification defect and requires an +explicit baseline amendment before affected implementation continues. + +## Product profiles + +processkit is a composite product with these company-standard profiles: + +- CLI application; +- local per-repository MCP process; +- schema, protocol, and process package; +- Python library for internal composition and tested extension points; and +- documentation website. + +The v1 implementation follows the company standards for configuration, +application output and logging, compatibility, security, verification, +roadmaps, documentation, branching, and spec-driven development. diff --git a/spec/doc/v1/roadmap.yaml b/spec/doc/v1/roadmap.yaml new file mode 100644 index 00000000..58b4bbf3 --- /dev/null +++ b/spec/doc/v1/roadmap.yaml @@ -0,0 +1,93 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: foundation + title: Product and contract foundation + items: + - id: PK1-P0 + title: Accept the v1 product baseline + summary: >- + Establish one coherent normative product contract and reconcile the + existing experimental branch without inheriting accidental design. + status: in_progress + dependencies: [] + decisions: + - "DEC-20260807_1003-LucidGarnet-re-specify-and-\ + reimplement-the-processkit" + issues: + - "BACK-20260807_1003-WarmHawk-specify-processkit-v1-from-\ + first-principles" + - id: PK1-P1 + title: Implement the complete ontology and transaction model + summary: >- + Deliver the versioned registry and all 89 T/P/D/C concepts with + generated contracts, safe canonical storage, lifecycle enforcement, + events, query metadata, fixtures, and deterministic recovery. + status: planned + dependencies: [PK1-P0] + - id: PK1-P2 + title: Deliver the standalone repository tool + summary: >- + Let users install, inspect, query, mutate, index, verify, recover, + and conservatively remove an exact release against one repository + working copy without aibox, a harness, or a shared service. + status: planned + dependencies: [PK1-P1] + - id: agent-surface + title: Agent and authoring surface + items: + - id: PK1-P3 + title: Deliver equivalent CLI and agent workflows + summary: >- + Provide lexical, semantic, and hybrid retrieval, bounded attributed + context assembly, polymorphic ontology query, validated mutation, + events, configuration inspection, generic CLI commands, stdio MCP, + and an authenticated reusable local daemon/proxy path from one + application core. + status: planned + dependencies: [PK1-P1, PK1-P2] + - id: PK1-P4 + title: Stabilize skills, MCP servers, packages, and extensions + summary: >- + Ship the standard profile, canonical provider-neutral skills and + processes, versioned MCP manifests, conformance tooling, and + provenance-preserving declarative harness adapters with explicit + support matrices and plan/apply reconciliation. + status: planned + dependencies: [PK1-P3] + - id: PK1-P5 + title: Prove migration and Git-mediated collaboration + summary: >- + Preserve representative v0 and alpha corpora, converge independent + agent clones through reviewed Git changes, and exchange bounded + handoffs without distributed ownership claims. + status: planned + dependencies: [PK1-P3, PK1-P4] + - id: release + title: Stabilization and release + items: + - id: PK1-P6 + title: Complete beta conformance + summary: >- + Pass full 89-concept coverage plus the contract, security, extension, + migration, platform, documentation, and package matrices and enter + feature freeze. + status: planned + dependencies: [PK1-P5] + - id: PK1-P7 + title: Verify release candidates + summary: >- + Prove every acceptance journey using exact candidate artifacts with + no unexplained skips. + status: planned + dependencies: [PK1-P6] + - id: PK1-P8 + title: Publish and verify processkit v1.0.0 + summary: >- + Publish the accepted stable commit and independently verify + installation, MCP, migration, documentation, and first-use behavior. + status: planned + dependencies: [PK1-P7] diff --git a/spec/schemas/v1/roadmap.schema.json b/spec/schemas/v1/roadmap.schema.json new file mode 100644 index 00000000..c8fa5f8b --- /dev/null +++ b/spec/schemas/v1/roadmap.schema.json @@ -0,0 +1,78 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.projectious.work/processkit/v1/roadmap.schema.json", + "title": "processkit v1 roadmap", + "type": "object", + "additionalProperties": false, + "required": ["apiVersion", "kind", "metadata", "groups"], + "properties": { + "apiVersion": {"const": "roadmap.projectious.work/v1"}, + "kind": {"const": "ProductRoadmap"}, + "metadata": { + "type": "object", + "additionalProperties": false, + "required": ["project", "versionLine"], + "properties": { + "project": {"const": "processkit"}, + "versionLine": {"const": "v1.x"} + } + }, + "groups": { + "type": "array", + "minItems": 1, + "items": {"$ref": "#/$defs/group"} + } + }, + "$defs": { + "id": {"type": "string", "pattern": "^[A-Z][A-Z0-9]+(?:-[A-Z0-9]+)+$"}, + "group": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "items"], + "properties": { + "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]+$"}, + "title": {"type": "string", "minLength": 1}, + "items": { + "type": "array", + "minItems": 1, + "items": {"$ref": "#/$defs/item"} + } + } + }, + "item": { + "type": "object", + "additionalProperties": false, + "required": ["id", "title", "summary", "status", "dependencies"], + "properties": { + "id": {"$ref": "#/$defs/id"}, + "title": {"type": "string", "minLength": 1}, + "summary": {"type": "string", "minLength": 1}, + "status": {"enum": ["idea", "planned", "in_progress", "shipped", "cancelled"]}, + "target": {"type": "string", "minLength": 1}, + "dependencies": { + "type": "array", + "items": {"$ref": "#/$defs/id"}, + "uniqueItems": true + }, + "issues": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "uniqueItems": true + }, + "decisions": { + "type": "array", + "items": {"type": "string", "minLength": 1}, + "uniqueItems": true + }, + "devNote": {"type": "string", "minLength": 1}, + "release": {"type": "string", "minLength": 1} + }, + "allOf": [ + { + "if": {"properties": {"status": {"const": "shipped"}}}, + "then": {"required": ["devNote", "release"]} + } + ] + } + } +} diff --git a/spec/tests/v1/roadmap/invalid-broken-dependency.yaml b/spec/tests/v1/roadmap/invalid-broken-dependency.yaml new file mode 100644 index 00000000..916b7131 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-broken-dependency.yaml @@ -0,0 +1,14 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: Broken dependency + summary: References an absent roadmap item. + status: planned + dependencies: [PK1-MISSING] diff --git a/spec/tests/v1/roadmap/invalid-cycle.yaml b/spec/tests/v1/roadmap/invalid-cycle.yaml new file mode 100644 index 00000000..3dd13bef --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-cycle.yaml @@ -0,0 +1,19 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: First cyclic item + summary: Depends on the second cyclic item. + status: planned + dependencies: [PK1-BAD2] + - id: PK1-BAD2 + title: Second cyclic item + summary: Depends on the first cyclic item. + status: planned + dependencies: [PK1-BAD1] diff --git a/spec/tests/v1/roadmap/invalid-duplicate-id.yaml b/spec/tests/v1/roadmap/invalid-duplicate-id.yaml new file mode 100644 index 00000000..bf050f82 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-duplicate-id.yaml @@ -0,0 +1,19 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: First duplicate + summary: Uses a duplicated roadmap ID. + status: planned + dependencies: [] + - id: PK1-BAD1 + title: Second duplicate + summary: Uses the same roadmap ID. + status: planned + dependencies: [] diff --git a/spec/tests/v1/roadmap/invalid-shipped-evidence.yaml b/spec/tests/v1/roadmap/invalid-shipped-evidence.yaml new file mode 100644 index 00000000..d4631aa6 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-shipped-evidence.yaml @@ -0,0 +1,14 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: Shipped without evidence + summary: Omits the required release and development note. + status: shipped + dependencies: [] diff --git a/spec/tests/v1/roadmap/invalid-status.yaml b/spec/tests/v1/roadmap/invalid-status.yaml new file mode 100644 index 00000000..9bdfa1e6 --- /dev/null +++ b/spec/tests/v1/roadmap/invalid-status.yaml @@ -0,0 +1,14 @@ +apiVersion: roadmap.projectious.work/v1 +kind: ProductRoadmap +metadata: + project: processkit + versionLine: v1.x +groups: + - id: invalid + title: Invalid + items: + - id: PK1-BAD1 + title: Unknown status + summary: Uses a status outside the standard vocabulary. + status: almost_done + dependencies: []