diff --git a/README.md b/README.md index fee08758..a22147b7 100644 --- a/README.md +++ b/README.md @@ -168,6 +168,7 @@ messages, and screenshots for organization identifiers before it pushes. Nothing ## Going deeper +- [`docs/README.md`](./docs/README.md) — documentation by audience and purpose - [`docs/getting-started.md`](./docs/getting-started.md) — first run, end to end - [`cli/README.md`](./cli/README.md) — the `qm` CLI and the deployment directory contract - [`docs/deploy-directory.md`](./docs/deploy-directory.md) — the deployment directory in full diff --git a/adrs/README.md b/adrs/README.md new file mode 100644 index 00000000..3f5758b6 --- /dev/null +++ b/adrs/README.md @@ -0,0 +1,14 @@ +# Change proposals and decision records + +This directory is the contribution path described in [`CONTRIBUTING.md`](../CONTRIBUTING.md). +An informal, human-written `.txt` or `.md` proposal is welcome and does not need to use +a template. + +A file's presence here does not prove that its proposal is accepted or implemented. +When a change needs a durable architectural decision record, use the +[`ADR template`](../docs/templates/adr.md), assign the next four-digit sequence, and keep +its status current. Accepted records capture rationale and consequences; current code, +tests, and normative contracts remain the evidence for implemented behavior. + +Name structured records `NNNN-short-decision.md`. Mark rejected and superseded records +rather than deleting them so later readers can understand why the decision changed. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..9fa7f435 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,65 @@ +# Documentation + +This page is the entry point for QM and Agent Squad Workspace documentation. Each +document should identify whether it describes current behavior, a proposal, or a +reusable template. Code and tests remain the final evidence for implemented behavior. + +## Product users + +- [QM overview](../README.md) describes the current product and its supported surfaces. +- [Deploy QM for an organization](./getting-started.md) gives the current deployment + starting point. +- [Security policy](../SECURITY.md) states the current trust boundaries, operator + assumptions, and known limitations. +- [Agent Squad Workspace](./agent-squad-workspace/README.md) describes a planned QM + extension. It is not a list of currently available capabilities. + +## Contributors + +- [Repository working rules](../AGENTS.md) define the required development and review + practices. +- [Contributing](../CONTRIBUTING.md) explains how to propose a change. +- [CLI end-to-end tests](../cli/test/e2e/README.md) describe the deployment CLI test + harness. +- [Documentation policy](./documentation-policy.md) defines document ownership, + status, naming, links, and update triggers. + +The root `package.json` is the source for local commands. The normal documentation-only +check is: + +```bash +npm run format:check +``` + +The repository pins Node and npm versions in `.node-version` and `package.json`. + +## Platform operators + +- [Deployment workflow](../deployment.md) points to the authoritative generated + runbook. +- [Deployment directory contract](./deploy-directory.md) is the normative deployment + schema and lifecycle contract. +- [QM CLI](../cli/README.md) lists current commands and package behavior. +- [Deployment templates](../deploy/README.md) explains the shipped service topology and + fixtures. +- [Organization layers](../deploy/layers/README.md) defines the private-fork boundary. +- [Slack surface](../src/slack/README.md) covers Slack setup and behavior. + +Plugin-specific setup and contracts live beside each plugin: + +- [Admin](../plugins/admin/README.md) +- [Authentication broker](../plugins/auth/README.md) +- [Onboarding](../plugins/onboarding/README.md) +- [Portal](../plugins/portal/README.md) +- [Web UI](../plugins/web-ui/README.md) + +## Maintainers + +- [Documentation audit](./documentation-audit-2026-08-02.md) records the current + inventory, gaps, and prioritized follow-up work. +- [ADR template](./templates/adr.md) +- [Feature specification template](./templates/feature-spec.md) +- [API and message protocol template](./templates/api-message-protocol.md) +- [Runbook template](./templates/runbook.md) +- [Test plan template](./templates/test-plan.md) +- [Acceptance record template](./templates/acceptance-record.md) diff --git a/docs/agent-squad-workspace/README.md b/docs/agent-squad-workspace/README.md new file mode 100644 index 00000000..387061d0 --- /dev/null +++ b/docs/agent-squad-workspace/README.md @@ -0,0 +1,119 @@ +# Agent Squad Workspace + +**Status: Proposed.** Agent Squad Workspace is a planned extension of QM. Unless a +statement links to current QM code, tests, or an accepted decision, it is a target and +not an available product capability. + +## Intended audience and outcome + +This section is the shared starting point for product owners, contributors, quality +reviewers, security reviewers, and operators designing a bounded multi-agent workspace. +The intended outcome is a team-oriented environment in which specialized agents divide +work, communicate, review results, and produce verifiable delivery evidence without +bypassing identity, permission, audit, or sandbox boundaries. + +## Current foundation and planned extension + +| Area | Current QM evidence | Proposed Agent Squad extension | +| ---------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------- | +| Identity and access | `src/identity/`, `src/acl/`, `SECURITY.md` | AgentProfile configuration, validated Agent principal semantics, and delegation checks | +| Durable execution | `src/runs/`, `src/tasks/`, `src/persistence/` | Task/TaskAttempt separation, dependency-aware coordination, and resumable workflows | +| Isolated work | `src/sandbox/`, `src/resolution/` | Per-agent execution context with authorized shared project resources | +| Projects and artifacts | `src/projects/`, `src/files/` | Structured task inputs, outputs, artifacts, and acceptance evidence | +| Audit and policy | `src/audit/`, `src/policy/` | Initiator, executor, delegation chain, approval, and review attribution | +| Surfaces | `plugins/web-ui/`, `src/slack/` | Squad configuration, goal submission, progress, review, and approval views | + +The current directories show reusable QM foundations, not proof that the proposed +multi-agent behaviors already exist. The accepted planning baseline keeps Project as the +MVP Workspace compatibility anchor and keeps Run/Worker/Orchestrator/Harness/Sandbox as +the execution data plane; Squad, Task DAG, Delegation, and acceptance are a new control +plane. + +## Shared terminology + +These are the accepted planning terms from the project architecture baseline. They +remain proposed repository contracts until implemented and recorded in accepted ADRs: + +- **Workspace**: an authorized project collaboration boundary containing resources, + tasks, artifacts, and policy. The MVP maps this boundary to the existing QM Project + rather than introducing a second identity domain. +- **Squad / SquadMember**: a Workspace-scoped orchestration template whose members + reference AgentProfiles and define leader, responsibilities, and versioned routing + rules. +- **AgentProfile**: an organization-level reusable configuration for role, prompt, + approved harness/model, skills, tool policy, and budget ceiling. It does not hold Task + state. +- **Task**: an accountable unit of work with an owner, inputs, outputs, state, and + acceptance criteria. +- **TaskAttempt**: one execution attempt with an AgentProfile/Squad configuration + snapshot, related Run IDs, cost, sandbox route, and termination reason. A retry creates + a new Attempt instead of overwriting history. +- **Dependency**: a prerequisite relationship that constrains when a Task may run. +- **Delegation**: an attributed transfer of bounded work and authority from one actor to + another. +- **Message**: a structured collaboration record such as delegation, question, + progress, review feedback, or result. +- **Artifact / TaskArtifact**: a durable output plus its input, output, or evidence + relationship to a Task, retaining producer Attempt, hash, and visible scope. +- **Review / Check / AcceptanceDecision**: reviewer opinion, machine evidence, and the + decision that satisfies a Task's delivery gate. A successful Run or an Agent's + completion claim alone is not acceptance. + +## Required invariants + +The extension design must preserve these current QM boundaries unless an accepted ADR +explicitly changes them with migration and security review: + +- Core, not model output or sandbox code, enforces identity, scope, grants, delivery, + and deterministic effect gates. +- Delegation cannot grant authority the delegator does not hold. +- Durable tasks, messages, approvals, audit records, and recoverable workflow state do + not rely on one process's memory. +- Shared conclusions and artifacts are authorized explicitly; private process context + does not become squad-visible by default. +- Every high-risk action has an attributable initiator, executor, delegation chain, and + approval result where required. +- Completion requires specified evidence such as tests, review, or human approval. +- A Run completion ends an Attempt; it does not directly accept a Task. +- Planned security controls do not erase the limitations documented in + [`SECURITY.md`](../../SECURITY.md). + +## Documentation set and readiness gates + +Create these documents only when they contain reviewable substance: + +| Path | Minimum content before implementation depends on it | Accountable role | +| ----------------------------- | -------------------------------------------------------------------------------------------- | ------------------ | +| `domain-model.md` | Entity identity, ownership, state, lifecycle, durability, and relationships | Architecture owner | +| `architecture.md` | Current flow, extension boundaries, data ownership, integration points, and ADR links | Architecture owner | +| `api-and-message-protocol.md` | Schemas, authorization, ordering, idempotency, errors, retries, versioning, and examples | Owning developer | +| `permissions-and-audit.md` | Principal/action/resource matrix, delegation constraints, approvals, and audit events | Security owner | +| `failure-recovery.md` | Failure taxonomy, retry ownership, cancellation, compensation, resume, and operator recovery | Platform operator | +| `testing-and-acceptance.md` | Success, error, permission, concurrency, idempotency, recovery, and regression evidence | Quality owner | + +Use the templates listed in the [documentation index](../README.md#maintainers) and +follow the [`documentation policy`](../documentation-policy.md). A future implementation +PR must update affected current-state documents and remove or revise superseded proposal +text. + +## Known open decisions + +- Whether an Agent is a non-human principal, an AgentProfile attached to an existing + principal, or both; this requires a threat-model spike before sharing credentials. +- The authoritative Task state machine and dependency scheduling semantics. The current + recommendation is `draft -> ready -> running -> awaiting_review -> accepted`, plus + `blocked`, `failed`, and `cancelled`, with only accepted dependencies becoming ready. +- How delegation narrows permissions, budget, time, tools, and resource scope. +- Message delivery guarantees, ordering, deduplication, retention, and visibility. +- Artifact ownership and merge behavior across isolated execution environments. +- Required Review, Check, AcceptanceDecision, and human approval gates. +- Cancellation, partial failure, retries, compensation, and orphan recovery. + +The recommended first vertical slice is one existing QM Project as the Workspace, one +fixed Squad, a Leader producing two schema-validated dependent Tasks, TaskAttempts backed +by existing Runs, Artifact and Check evidence, independent Review and AcceptanceDecision, +then a Leader summary using only accepted outputs. Dynamic routing, automatic merging, +and a second workflow engine remain out of scope until this slice is verified. + +Resolve these through feature specifications and ADRs before describing their behavior +as current. diff --git a/docs/documentation-audit-2026-08-02.md b/docs/documentation-audit-2026-08-02.md new file mode 100644 index 00000000..64917bee --- /dev/null +++ b/docs/documentation-audit-2026-08-02.md @@ -0,0 +1,118 @@ +# Documentation audit: 2026-08-02 + +**Status: Current audit.** This report describes the repository at the audited revision. +It does not claim that planned Agent Squad Workspace capabilities exist. + +**Audited revision:** `7f2c916` + +## Scope and method + +The audit covered repository Markdown, root and package scripts, CI workflow, API route +layout, and the directories that own identity, ACL, audit, tasks, runs, projects, +workspaces, and persistence. Generated skill content and third-party reference material +under `skills-seed/` were classified as product assets rather than maintainer +documentation. + +Claims were checked against repository paths. Commands were taken from `package.json`, +package-level manifests, or the CLI documentation. This audit did not deploy QM or +exercise provider-specific infrastructure. + +## Inventory + +| Area | Existing source | Assessment | +| --------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | +| Product overview | `README.md` | Strong current overview, architecture sketch, security posture, deployment entry, and links | +| First deployment | `docs/getting-started.md` | Accurate but narrowly focused on organization deployment; not a contributor quick start | +| Deployment contract | `docs/deploy-directory.md`, `cli/README.md` | Detailed and partly executable through `test/deploy-directory-doc.test.ts` | +| Operator workflow | `deployment.md`, `cli/templates/deployment/`, `deploy/README.md` | Clear authority chain, but information is distributed across template and provider references | +| Configuration | `.env.example`, deployment contract, plugin READMEs | Names are documented near owners; no unified configuration index by audience | +| Contribution | `AGENTS.md`, `CONTRIBUTING.md` | Strong repository rules and proposal path; no concise environment setup or change-to-test matrix | +| Architecture | `README.md` and module layout | Only a high-level diagram; no maintained component, data, or request-flow architecture document | +| Decisions | `adrs/` | No decision records existed; `CONTRIBUTING.md` routes proposals there, but status and decision lifecycle were unspecified | +| HTTP API | `src/api/routes/`, plugin READMEs | Route behavior exists in code and scattered module docs; no API index, schema catalog, compatibility policy, or error model | +| Agent protocol | `src/api/agent-api-catalog.ts`, `src/api/contract.ts` | Implementation exists; no audience-facing protocol contract | +| Permissions and audit | `SECURITY.md`, `src/acl/`, `src/audit/`, related tests | Threat model is strong; principal/action/resource mapping and audit event catalog are absent | +| Testing | Root and package scripts, `.github/workflows/cicd.yml`, `cli/test/e2e/README.md` | Broad automated coverage; no test strategy, test-data guide, or acceptance evidence format | +| Operations | Generated deployment runbook and provider references | Deployment is detailed; incident triage, backup/restore drills, degraded-mode behavior, and service-level runbooks are fragmented or absent | +| Plugins and Slack | `plugins/*/README.md`, `src/slack/README.md` | Useful local contracts, but style, prerequisites, and freshness signals vary | +| Agent Squad Workspace | None before this change | Product intent, current/planned boundary, domain terms, protocols, delegation, review, and recovery need dedicated documentation | + +## Findings + +### High priority + +1. There was no repository-wide documentation entry point. Readers had to infer the + route from the root README and directory names. `docs/README.md` now provides the + audience-based navigation. +2. Current QM behavior and the planned Agent Squad Workspace extension had no explicit + separation. The new extension landing page uses current/planned labels and reserves + the required domain, protocol, security, audit, recovery, and testing documents. +3. API and agent-message contracts are not documented as contracts. Future protocol + work needs request/response schemas, authorization, idempotency, ordering, errors, + compatibility, and audit effects before implementation can be independently tested. +4. There is no maintained detailed architecture source. A checked-in architecture + baseline must establish component ownership, durable data, execution boundaries, and + request/task flows before an accepted Agent Squad design depends on them. +5. Documentation ownership and update triggers were absent. The new policy assigns + accountable roles without inventing people or a `CODEOWNERS` configuration. + +### Medium priority + +1. A contributor can find commands in manifests but not a single environment setup and + affected-test guide. Add a contributor development guide after verifying the minimal + local services and credentials. +2. Deployment documentation is intentionally layered but repeats entry instructions. + Keep `docs/deploy-directory.md` normative, the generated template operational, and + other pages as links plus context. +3. Tests are extensive but acceptance evidence is not standardized. The test-plan and + acceptance-record templates provide a starting format without replacing executable + tests. +4. Security documentation describes threats and limitations but not an authorization + matrix or audit event catalog. Agent delegation must not ship until those extension + contracts are explicit and tested negatively. +5. Runbooks cover deployment better than incidents and recovery. Per-service symptoms, + diagnostics, mitigation, rollback, data safety, escalation, and post-recovery checks + remain to be written. + +### Specific stale or unverifiable content + +- `plugins/web-ui/README.md` cited `ADR-0003 D2/D4`, but no such record exists in + `adrs/` or elsewhere in the repository. This change removes the unresolved citation; + current behavior remains testable in `test/file-channel-share.test.ts`. +- Plugin READMEs use references such as `spec section` without a checked-in spec. Treat + those labels as historical context, not navigable evidence, until the source document + is restored or the references are replaced with current contracts. +- Several operational claims require cloud accounts, credentials, or live services. + They are documented but were not independently exercised in this audit. + +## Target information architecture + +| Reader | Start | Next authoritative sources | +| ---------------------------- | ------------------------ | -------------------------------------------------------------------------------- | +| Product user | `README.md` | Current surface guide, security policy, deployment start | +| Contributor | `docs/README.md` | `AGENTS.md`, contributor setup, architecture, ADRs, API contracts, test strategy | +| Platform operator | `deployment.md` | Generated runbook, deployment contract, service runbooks, recovery procedures | +| Security reviewer | `SECURITY.md` | Permission matrix, audit catalog, protocol authorization, negative tests | +| Product and quality reviewer | Agent Squad landing page | Feature specs, test plans, acceptance records, known limitations | + +The detailed placement and single-source rules are in +[`documentation-policy.md`](./documentation-policy.md). + +## Prioritized roadmap + +| Priority | Deliverable | Owner | Exit evidence | +| -------- | ----------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- | +| P0 | QM architecture baseline and Agent Squad extension boundary | Architecture owner | Current flow and data claims cite code/tests; proposed changes are separate | +| P0 | First vertical-slice feature specification and ADR set | Product and architecture owners | Scope, alternatives, permission boundaries, failure states, and acceptance criteria approved | +| P0 | API/message and delegation protocol contract | Owning developer and security owner | Schemas, authorization, audit, idempotency, ordering, retries, and compatibility are testable | +| P1 | Contributor development and test guide | Developer and quality owner | Clean checkout can run documented focused checks with stated prerequisites | +| P1 | Permission matrix and audit event catalog | Security owner | Positive and negative access cases map to tests and recorded events | +| P1 | Failure recovery and operator runbooks | Platform operator | Failure drills include safe diagnosis, mitigation, rollback, and verification | +| P1 | Test strategy and release acceptance record | Quality owner | CI/local gates and evidence ownership are explicit | +| P2 | Automated internal-link and documentation freshness checks | Documentation steward | CI detects broken relative links and stale generated contracts | + +The project architecture baseline completed during this audit. Its accepted planning +terms are reflected in the Agent Squad landing page: Project-compatible Workspace, +AgentProfile, Task/TaskAttempt, Delegation, Message, Artifact/TaskArtifact, and +Review/Check/AcceptanceDecision. A checked-in architecture document remains P0 because +the project issue is not a durable repository source of truth. diff --git a/docs/documentation-policy.md b/docs/documentation-policy.md new file mode 100644 index 00000000..4a5def28 --- /dev/null +++ b/docs/documentation-policy.md @@ -0,0 +1,109 @@ +# Documentation policy + +This policy keeps product, implementation, operations, and validation material from +competing as sources of truth. + +## Status and evidence + +Every new design or product document must state one of these statuses near its title: + +- **Current**: verified against the referenced code, test, configuration, or released + behavior. +- **Proposed**: a decision or capability that is not yet implemented or accepted. +- **Template**: a reusable structure with no behavioral claim. +- **Historical**: retained for context and not a description of current behavior. + +Do not infer implementation from a roadmap, issue, mockup, or proposed ADR. Statements +about current behavior should cite the owning code path, executable check, or normative +contract. If evidence is unavailable, label the statement `To verify` and name the +verification needed. + +## Sources of truth + +| Subject | Primary source | Supporting material | +| ---------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------- | +| Current product scope | `README.md` | Plugin READMEs | +| Runtime behavior | `src/`, `plugins/`, `cli/src/` | Tests beside the owning package | +| Local commands and prerequisites | `package.json`, package-level `package.json` files, `.node-version` | Contributor guides | +| Deployment directory and lifecycle | `docs/deploy-directory.md` | `cli/README.md`, generated `deployment.md` | +| Configuration names | Schemas and `.env.example` | Deployment and plugin guides | +| Security and trust boundaries | `SECURITY.md` and authorization code/tests | Feature specifications and ADRs | +| Architectural rationale | Accepted records in `adrs/` | Current architecture documents | +| Agent Squad Workspace scope | `docs/agent-squad-workspace/README.md` | Accepted ADRs and implemented feature specifications | +| Test and acceptance evidence | Executable tests and CI workflow | Dated test plans and acceptance records | + +When two documents repeat a fact, one must name the primary source and the other should +link to it instead of maintaining a second copy. Generated deployment runbooks are an +intentional exception: their template is authoritative, and generated copies are bound +to the CLI version that created them. + +## Information architecture + +Use these locations for new material: + +```text +README.md current public product overview +docs/README.md documentation navigation +docs/agent-squad-workspace/ planned and current extension documentation +docs/templates/ reusable document templates +adrs/ change proposals and accepted decision records +cli/README.md CLI-specific user contract +plugins//README.md plugin-specific behavior and setup +deploy/**/README.md deployment template and fixture boundaries +``` + +Agent Squad Workspace documents should use the following paths when the corresponding +work begins. Do not create a placeholder that could be mistaken for an implemented +contract: + +```text +docs/agent-squad-workspace/domain-model.md +docs/agent-squad-workspace/architecture.md +docs/agent-squad-workspace/api-and-message-protocol.md +docs/agent-squad-workspace/permissions-and-audit.md +docs/agent-squad-workspace/failure-recovery.md +docs/agent-squad-workspace/testing-and-acceptance.md +``` + +## Naming and links + +- Use lowercase kebab-case Markdown filenames. ADRs additionally use a four-digit + sequence: `NNNN-short-decision.md`. +- Use relative repository links and descriptive labels. Do not link to runtime-local + paths. +- Link to a directory only when it contains a `README.md`; otherwise link to a file. +- Prefer stable headings over line-number links. +- Keep one H1 per standalone document and use sentence-case headings. +- Put commands in fenced blocks and state their working directory and prerequisites + when those are not obvious. + +## Ownership and update triggers + +Ownership is role-based until the repository adds a `CODEOWNERS` policy. + +| Material | Accountable role | Required update trigger | +| ---------------------------------- | --------------------- | -------------------------------------------------------------------------- | +| Product overview and feature specs | Product owner | User-visible scope or workflow changes | +| Architecture and ADRs | Architecture owner | Boundary, dependency, data model, or trade-off changes | +| API and message protocols | Owning developer | Route, schema, state, compatibility, or error changes | +| Deployment and runbooks | Platform operator | Config, prerequisite, topology, recovery, or command changes | +| Permissions, audit, and security | Security owner | Principal, grant, approval, secret, trust-boundary, or audit-event changes | +| Test plans and acceptance records | Quality owner | Acceptance criteria, test matrix, or release-gate changes | +| Navigation and templates | Documentation steward | New, moved, superseded, or removed documents | + +The implementation owner updates affected documents in the same pull request. The +accountable role verifies behavioral claims; the documentation steward verifies status, +placement, links, and readability. High-risk security or operational changes require the +corresponding owner even when the text change is small. + +## Review checklist + +- The audience, status, prerequisites, scope, and out-of-scope behavior are explicit. +- Current claims have repository evidence; proposals are not written in the present + tense. +- Commands and paths exist and use repository-pinned tooling. +- Permissions, audit effects, errors, rollback, and failure recovery are covered when + applicable. +- Related navigation and cross-links are updated. +- `npm run format:check` passes; affected contract tests run when a normative document + is executable test input. diff --git a/docs/templates/acceptance-record.md b/docs/templates/acceptance-record.md new file mode 100644 index 00000000..6afaae88 --- /dev/null +++ b/docs/templates/acceptance-record.md @@ -0,0 +1,37 @@ +# Acceptance record: Delivery title + +**Status: Passed | Failed | Blocked** + +**Date:** YYYY-MM-DD + +**Reviewer:** [Independent reviewer] + +**Revision:** [Immutable commit or artifact] + +**Criteria source:** [Accepted specification and test plan] + +## Decision + +[State the acceptance outcome and release consequence.] + +## Evidence + +| Criterion | Result | Evidence | Notes | +| -------------- | ----------------- | ------------------------------- | --------- | +| [Criterion ID] | Pass/Fail/Blocked | [Test, CI, review, or artifact] | [Context] | + +## Findings + +| Severity | Finding | Reproduction | Owner | Disposition | +| ---------- | ------------------- | ------------ | ------- | ------------------------------- | +| [Severity] | [Observed behavior] | [Steps] | [Owner] | [Block/follow-up/accepted risk] | + +## Environment limitations + +[State which evidence was not collected and why. Do not convert missing evidence into a +pass.] + +## Follow-up and revalidation + +[List fixes, approval requirements, expiry of accepted risk, and the exact revalidation +scope.] diff --git a/docs/templates/adr.md b/docs/templates/adr.md new file mode 100644 index 00000000..dea2b1c6 --- /dev/null +++ b/docs/templates/adr.md @@ -0,0 +1,38 @@ +# ADR NNNN: Short decision title + +**Status: Proposed | Accepted | Superseded by ADR NNNN | Rejected** + +**Date:** YYYY-MM-DD + +**Owners:** [Accountable roles] + +**Related:** [Issue, feature specification, implementation, or prior ADR] + +## Context + +[Describe the current facts, constraints, forces, and decision deadline. Separate +verified behavior from assumptions.] + +## Decision + +[State the decision precisely, including scope and boundaries.] + +## Alternatives considered + +| Alternative | Benefits | Costs and risks | Reason not selected | +| ----------- | ---------- | --------------- | ------------------- | +| [Option] | [Benefits] | [Costs] | [Reason] | + +## Consequences + +[List intended outcomes, trade-offs, compatibility impact, security impact, operational +impact, and follow-up work.] + +## Verification + +[Name the tests, metrics, review, migration check, or operational exercise that proves +the decision was implemented safely.] + +## Reversal or supersession + +[Describe how to reverse the decision and what evidence would require reconsideration.] diff --git a/docs/templates/api-message-protocol.md b/docs/templates/api-message-protocol.md new file mode 100644 index 00000000..32c79a0d --- /dev/null +++ b/docs/templates/api-message-protocol.md @@ -0,0 +1,53 @@ +# API or message protocol: Short title + +**Status: Proposed | Current | Historical** + +**Owner:** [Owning module or role] + +**Version:** [Version and compatibility policy] + +**Related:** [Feature specification, ADR, implementation, and tests] + +## Purpose and boundaries + +[Describe callers, consumers, transport, trust boundary, and non-goals.] + +## Authorization and audit + +| Operation | Principal | Required scope/grant | Audit event | Denied behavior | +| ----------- | ----------- | -------------------- | ----------- | --------------- | +| [Operation] | [Principal] | [Requirement] | [Event] | [Response] | + +## Envelope or endpoint + +```json +{ + "id": "example-id", + "type": "example.type", + "version": 1, + "payload": {} +} +``` + +[Define fields, types, required/optional status, bounds, sensitive data, and examples.] + +## State and delivery semantics + +[Define ordering, idempotency key, deduplication window, concurrency control, retries, +timeouts, cancellation, retention, and acknowledgement.] + +## Responses and errors + +| Code or type | Meaning | Retryable | Caller action | +| ------------ | --------- | --------- | ------------- | +| [Value] | [Meaning] | Yes/No | [Action] | + +## Compatibility and migration + +[Define additive and breaking changes, negotiation, rollout order, old-reader behavior, +and data migration.] + +## Verification + +[Link contract tests, authorization-negative tests, idempotency/concurrency tests, and +live verification.] diff --git a/docs/templates/feature-spec.md b/docs/templates/feature-spec.md new file mode 100644 index 00000000..435ad4b8 --- /dev/null +++ b/docs/templates/feature-spec.md @@ -0,0 +1,53 @@ +# Feature specification: Short title + +**Status: Proposed | Accepted | Implemented | Historical** + +**Audience:** [Users and operators affected] + +**Owner:** [Accountable role] + +**Related:** [Issue, ADRs, protocols, designs, and tests] + +## Problem and outcome + +[State the user problem and the observable outcome.] + +## Scope + +### In scope + +- [Behavior] + +### Out of scope + +- [Explicit boundary] + +## Actors and permissions + +| Actor | Preconditions | Allowed actions | Denied actions | +| ------- | ------------- | --------------- | ------------------- | +| [Actor] | [State/grant] | [Actions] | [Negative boundary] | + +## User flow and states + +[Describe entry, success, empty, loading, blocked, denied, failure, retry, cancellation, +review, and completion states that apply.] + +## Data and contracts + +[Link the domain entities, API/message protocol, persistence rules, audit events, and +compatibility requirements.] + +## Failure and recovery + +[Define ownership of retry, timeout, partial failure, compensation, resume, and operator +intervention.] + +## Acceptance criteria + +- [Observable, independently testable criterion] + +## Verification and rollout + +[List test commands, required evidence, migration/rollout stages, monitoring, rollback, +and known residual risks.] diff --git a/docs/templates/runbook.md b/docs/templates/runbook.md new file mode 100644 index 00000000..183592ac --- /dev/null +++ b/docs/templates/runbook.md @@ -0,0 +1,40 @@ +# Runbook: Service or operation + +**Status: Current | Historical** + +**Owner:** [On-call or accountable role] + +**Last verified:** YYYY-MM-DD against [revision/environment] + +**Risk:** [User, data, security, cost, and availability impact] + +## Preconditions and safety + +[Required access, tools, environment, backups, approvals, and actions that must not be +taken.] + +## Symptoms and signals + +| Symptom | Signal or query | Likely scope | +| --------- | ----------------- | ------------ | +| [Symptom] | [Safe diagnostic] | [Scope] | + +## Diagnosis + +1. [Read-only check with expected result] + +## Mitigation + +1. [Bounded action, expected result, and stop condition] + +## Recovery or rollback + +1. [Recovery step, data-safety constraint, and rollback command] + +## Verification + +- [Health, behavior, data-integrity, permission, and audit checks] + +## Escalation and follow-up + +[Escalation owner, evidence to preserve, incident record, and permanent-fix trigger.] diff --git a/docs/templates/test-plan.md b/docs/templates/test-plan.md new file mode 100644 index 00000000..1af023f0 --- /dev/null +++ b/docs/templates/test-plan.md @@ -0,0 +1,42 @@ +# Test plan: Short title + +**Status: Proposed | Active | Complete | Historical** + +**Owner:** [Independent quality owner] + +**Scope revision:** [Commit or PR] + +**Related:** [Feature specification, ADRs, protocols, and implementation] + +## Objectives and exclusions + +[State what confidence this plan provides and what it does not cover.] + +## Environment and data + +[List prerequisites, services, credentials, fixtures, isolation, cleanup, and sensitive +data restrictions.] + +## Test matrix + +| ID | Scenario | Level | Preconditions | Expected evidence | Blocking | +| ----- | ----------------------------- | ----------- | ------------- | ------------------------ | -------- | +| T-001 | Success path | Integration | [State] | [Assertion/artifact] | Yes | +| T-002 | Permission denied | Integration | [State] | [No side effect + audit] | Yes | +| T-003 | Concurrent or duplicate input | Integration | [State] | [Idempotent result] | Yes | +| T-004 | Partial failure and recovery | End to end | [State] | [Recoverable result] | Yes | + +## Commands + +```bash +[Repository-verified command] +``` + +## Entry and exit criteria + +[Define required implementation state, allowed test limitations, severity thresholds, +and evidence required to pass.] + +## Residual risk + +[List untested behavior, environment limitations, non-blocking defects, and owners.] diff --git a/plugins/README.md b/plugins/README.md new file mode 100644 index 00000000..178b11a4 --- /dev/null +++ b/plugins/README.md @@ -0,0 +1,14 @@ +# Plugins + +Plugins provide optional QM surfaces and services over the headless core. Each plugin +owns its setup, runtime behavior, and package checks: + +- [`admin`](./admin/README.md) provides the administrative governance surface. +- [`auth`](./auth/README.md) provides the built-in email sign-in broker. +- [`onboarding`](./onboarding/README.md) provides first-run onboarding. +- [`portal`](./portal/README.md) provides the public SSO front door. +- [`web-ui`](./web-ui/README.md) provides the browser application. + +`chassis` is shared plugin-to-core plumbing and has no standalone user surface. Follow +the repository boundaries in [`AGENTS.md`](../AGENTS.md) before changing shared plugin +behavior. diff --git a/plugins/web-ui/README.md b/plugins/web-ui/README.md index 0dacefaa..2bd1d608 100644 --- a/plugins/web-ui/README.md +++ b/plugins/web-ui/README.md @@ -110,7 +110,7 @@ and `CORE_SIGNING_SECRET` (same value as the core when source-auth is enabled). (`GET /api/files/:id/content`, streamed binary). Image files (`image/*`) show an inline thumbnail rendered straight from that same `/content` stream. Backed by a durable, owner-scoped registry — NOT a transcript scan. Delivered/uploaded files are owned at the initiator's personal scope so - they surface here, and auto-shared with the conversation (ADR-0003 D2/D4): a public-channel file + they surface here, and auto-shared with the conversation: a public-channel file gets an `org:` read grant so every member sees it under "Shared with you"; private-channel per-member grants are sequencing-gated (off until enabled), so those stay owner-only until then. - **Connectors** — per-provider OAuth status with Connect / Reconnect / Disconnect. The server