dxcomplete 0.2.2 → 0.3.0

package/README.md

@@ -1,55 +1,63 @@
 # DX Complete
 
-DX Complete installs a process, documentation, and MCP route scaffold into a Next.js workspace so a service can track decisions, requirements, tasks, changes, incidents, support, operations, and measurement over time.
+DX Complete installs the workspace-side documentation, process files, and MCP route needed for a service to use the hosted DX Complete record system.
 
-This public package is the workspace installer and client-side MCP surface. It does not include the central DX Complete service that stores records, manages OAuth, checks workspace membership, assigns readable IDs, or executes MCP tools. Installed workspaces connect to that hosted service with provisioned workspace credentials.
+This npm package is the installer for a client workspace. It is not the central DX Complete service. The hosted service stores records, manages Google OAuth, checks workspace membership, assigns readable IDs, and executes MCP tools. An installed workspace must be provisioned in DX Complete and configured with its service URL, client ID, and client secret before its MCP route can be used.
 
-## Quick Start
+Create those credentials by signing in at `https://dxcomplete.directeddomains.com/account.html`. Store the secret in the client workspace hosting environment; it is shown once.
 
-Install the scaffold into the current Next.js project:
+For the full DX Complete method and browser documentation, see `https://dxcomplete.directeddomains.com`.
+
+## Install A Workspace
+
+1. Create or open the Next.js project repo that will expose the DX Complete route for this service.
+
+2. Install DX Complete into that project:
 
 ```sh
 npx dxcomplete init
 ```
 
-The command creates editable DX Complete documentation and process files under `dxcomplete/`, installs Next.js route wrappers under `pages/api/`, writes `vercel.json` compatibility settings, and creates `dxcomplete/workspace.json` as the workspace identity for that service.
+3. Sign in at `https://dxcomplete.directeddomains.com/account.html`.
 
-Before the hosted MCP route can be used, the workspace must be provisioned in DX Complete and given its workspace service URL, client ID, and client secret.
+4. Create a workspace for the service.
 
-The broader product premise is:
+5. Replace the generated `dxcomplete/workspace.json` with the workspace JSON shown by the account page.
 
-```text
-DX Complete = Decision Basis + Complete Engineering + Operations Measurement
+6. Store the service values shown by the account page in the client workspace hosting environment:
+
+```sh
+DXC_SERVICE_URL=https://dxcomplete.directeddomains.com
+DXC_SERVICE_CLIENT_ID=...
+DXC_SERVICE_CLIENT_SECRET=...
 ```
 
-The scaffold is intended to help a team describe and revise a full engineering and service lifecycle model. It deliberately does not present the current model as decided. Roles, workflows, object taxonomy, and diagrams are draft material that should be edited as the operating model becomes clearer.
+7. Deploy the workspace app and verify its MCP route at `/api/mcp`.
 
-## Product Outcome
+The init command creates editable DX Complete documentation and process files under `dxcomplete/`, installs Next.js route wrappers under `pages/api/`, writes Vercel compatibility settings, and creates an initial `dxcomplete/workspace.json` file. The hosted account page is the source of the provisioned workspace JSON and one-time service secret.
 
-Running `dxcomplete init` in a Next.js project creates an editable starting point for process documentation, Mermaid diagrams, taxonomy files, decision-basis templates, cost-model templates, workflow templates, placeholder controls, evidence folders, workspace configuration, Next-compatible MCP route wrappers, and optional GitHub workflow checks.
+`DXC_SERVICE_URL` is environment-specific, `DXC_SERVICE_CLIENT_ID` is a provisioning detail, and `DXC_SERVICE_CLIENT_SECRET` is a secret. Workspace deployments do not need database credentials, OAuth provider secrets, or central-service provisioning secrets.
 
-The current draft model covers:
+## What It Installs
 
-- Direction
-- Product definition
-- Engineering execution
-- Engineer implementation, including Codex-assisted work where appropriate
-- QA verification
-- Product validation
-- Change and release control
-- Deployment
-- Operation
-- User support
-- Administration as part of operation
-- Audit and evidence
+DX Complete adds a workspace-side scaffold for one service scope:
 
-## Current Framing
+- Editable process documentation under `dxcomplete/docs/`.
+- Editable process data under `dxcomplete/process/`.
+- Workspace identity in `dxcomplete/workspace.json`.
+- Install metadata in `dxcomplete/.install-manifest.json`.
+- Next.js route wrappers under `pages/api/`.
+- Vercel compatibility settings in `vercel.json`.
+- An optional basic GitHub workflow.
+- A root `AGENTS.md` only when the target project does not already have one.
 
-The working hypothesis is that DX Complete describes a full decision-basis, engineering, and service lifecycle, not only software development. It includes cost and benefit reasoning before engineering begins, both build/change responsibilities and run/service responsibilities, and actual measurement after delivery where available.
+The documentation and process files are intentionally local to the installed workspace. Teams can adapt them to match how their service is actually governed, built, released, operated, supported, and measured.
 
-The current role model includes Owner, Engineer, Tester, Operator, Support Agent, and End User. The model keeps outcome authority, requirements, product validation, and risk acceptance visible inside Owner; implementation responsibilities inside Engineer; and administration responsibilities inside Operator.
+## Current Record Set
 
-Current runtime records include Workspace, Statement, Journal, Environment, Component, Maintenance Schedule, Expectation, Requirement, Estimate, Benefits, Value Realization, Commitment, Deferral, Task, Change, Incident, Problem, Support Request, Decision, Risk, and DX Complete Ticket. Other lifecycle concepts such as Feedback, Feature Request, Release, Deployment, Control, and Evidence remain useful language but are not all current records. They are represented in editable YAML and Markdown so the model can evolve deliberately.
+The hosted DX Complete runtime stores records for the service lifecycle. Current runtime records include Workspace, Statement, Journal, Environment, Component, Maintenance Schedule, Expectation, Requirement, Estimate, Benefits, Value Realization, Commitment, Deferral, Task, Change, Incident, Problem, Support Request, Decision, Risk, and DX Complete Ticket.
+
+Workspace-scoped lifecycle records receive readable references such as `REQ-0001` while UUID remains the primary key and link target. DX Complete keeps ledger-style records appendable where history matters, and state-style records versioned where the current shape matters.
 
 ## Usage
 
@@ -89,14 +97,19 @@ Validate the scaffold shape:
 npx dxcomplete validate
 ```
 
-By default, the scaffold is written to `dxcomplete/` and a placeholder workflow is written to `.github/workflows/dxcomplete.yml`. Existing files are not overwritten unless `--force` is provided.
+By default, the scaffold is written to `dxcomplete/` and a basic workflow is written to `.github/workflows/dxcomplete.yml`. Existing files are not overwritten unless `--force` is provided.
+
+If the target project does not already have a root `AGENTS.md`, `dxcomplete init` writes a small Codex guidance file that points future engineering agents to `dxcomplete/docs/operating-guide.md` and `dxcomplete/docs/codex-integration.md`. If a root `AGENTS.md` already exists, it is skipped. `dxcomplete upgrade` does not overwrite a user-owned `AGENTS.md`.
 
-If the target project does not already have a root `AGENTS.md`, `dxcomplete init` also writes a small Codex guidance file that points future engineering agents to `dxcomplete/docs/operating-guide.md` and `dxcomplete/docs/codex-integration.md`. If a root `AGENTS.md` already exists, it is skipped. `dxcomplete upgrade` does not overwrite a user-owned `AGENTS.md`.
+`dxcomplete upgrade` previews by default. It manages the installed route wrappers, Vercel compatibility configuration, and `dxcomplete/.install-manifest.json`. It does not overwrite `dxcomplete/workspace.json`. It reports drift in `dxcomplete/docs` and `dxcomplete/process` because those files become user-owned after installation.
 
-`dxcomplete upgrade` previews by default. It manages the installed route wrappers, Vercel compatibility configuration, and `dxcomplete/.install-manifest.json`. It does not overwrite `dxcomplete/workspace.json`. It reports drift in `dxcomplete/docs` and `dxcomplete/process` because those files are expected to become user-owned after installation.
 Run `dxcomplete init` before `dxcomplete upgrade`; upgrade refuses targets that do not already have `dxcomplete/workspace.json`.
 
-The installed MCP route wrappers are written under `pages/api/` so the workspace can remain a normal Next.js app on Vercel:
+## Workspace Runtime and MCP
+
+The installed workspace exposes a Model Context Protocol route for that workspace. The route does not open the database directly and does not run the hosted DX Complete service. It proxies auth and MCP requests to the hosted service. Access is scoped by the installed repo's `dxcomplete/workspace.json`, authenticated actor identity, and workspace membership.
+
+The installed route wrappers are written under `pages/api/` so the workspace can remain a normal Next.js app on Vercel:
 
 ```text
 pages/api/mcp.js
@@ -105,37 +118,17 @@ pages/api/dxcomplete/[...path].js
 pages/api/auth/callback/google.js
 ```
 
-The workspace identity is written to `dxcomplete/workspace.json` inside the installed project. That file belongs to the workspace app repo, not to the central DX Complete repo.
-
-## Package and Compatibility Versioning
-
-DX Complete uses one package version, one workspace compatibility gate, and one surface fingerprint:
-
-- `packageVersion` is the npm package release version from `package.json`.
-- `workspaceCompatibility` is the installed workspace compatibility gate. It changes only when an installed workspace must update its route/proxy surface to keep talking safely to the hosted DX Complete service.
-- `surfaceFingerprint` is an automatic hash of the live MCP tools, tool schemas, process guide, and on-demand doc references. It can change without requiring a package release or workspace upgrade.
-
-The MCP `surfaceVersion` field is a stable surface identifier. Use `surfaceFingerprint` for exact surface reconciliation and `workspaceCompatibility` for upgrade decisions.
-
-## Workspace Runtime and MCP
-
-The documentation scaffold is the first milestone. The runtime layer treats Workspace as the boundary for one service scope.
-
-The default MCP deployment model is one endpoint per workspace. A Next.js project repo installs DX Complete and exposes an MCP route for that workspace. That workspace route does not open the database directly and does not run the hosted DX Complete service. It proxies auth and MCP requests to that service. Access is scoped by the installed repo's `dxcomplete/workspace.json`, authenticated actor identity, and workspace membership. Do not use a workspace environment variable for this boundary.
+Hosted MCP is exposed in the installed workspace app at `/api/mcp`. The workspace route uses Streamable HTTP, advertises OAuth metadata for remote MCP clients, proxies OAuth through the hosted DX Complete service, and returns DX Complete bearer tokens scoped to the configured workspace. The installed repo supplies workspace identity through `dxcomplete/workspace.json`; the hosted service stores workspace memberships and executes MCP tools.
 
-For a workspace MCP deployment, provide only the hosted-service connection:
+The hosted DX Complete service uses Google OAuth for account sign-in. Its Google OAuth callback URL is:
 
-```sh
-DXC_SERVICE_URL=https://dxcomplete.directeddomains.com
-DXC_SERVICE_CLIENT_ID=...
-DXC_SERVICE_CLIENT_SECRET=...
+```text
+https://dxcomplete.directeddomains.com/api/dxcomplete/web/auth/google/callback
 ```
 
-`DXC_SERVICE_URL` is environment-specific, `DXC_SERVICE_CLIENT_ID` is a provisioning detail, and `DXC_SERVICE_CLIENT_SECRET` is a secret. Workspace MCP deployments must not require database credentials, OAuth provider secrets, or central-service provisioning secrets.
-
-Once connected, the hosted DX Complete service stores records for the workspace. The first runtime collections cover workspaces, statements, journal entries, environments, components, estimates, benefits, expectations, requirements, commitments, deferrals, tasks, changes, decisions, and risks. Use the MCP tools to create and link those records inside the intended workspace. Workspace-scoped lifecycle records receive a human-readable reference such as `REQ-0001` while UUID remains the primary key and link target.
+On Vercel, `vercel.json` must include `dxcomplete/workspace.json` in the API function bundle. The scaffold includes this by default with `functions["pages/api/**/*.js"].includeFiles`. Vercel reserves `/.well-known`, so the installed Next app rewrites the OAuth discovery metadata paths to the DX Complete route wrapper.
 
-Environment and Component records form the Operational Registry. The registry is an inventory of operational state: what exists in each environment, where it lives, and which secret names or locations are relevant. It is not monitoring, diagnostics, a secret vault, an event log, or a runbook engine. Secret pointers should identify stores and keys only; do not record secret values.
+## MCP Tools
 
 Useful MCP tools include:
 
@@ -160,17 +153,21 @@ Useful MCP tools include:
 - `link_records` and `unlink_records` for explicit relationships when a typed tool does not already create or remove the link.
 - `archive_record` for cleanup without deleting evidence.
 
-Hosted MCP is exposed in the installed workspace app at `/api/mcp`. The workspace route uses Streamable HTTP, advertises OAuth metadata for remote MCP clients, proxies OAuth through the hosted DX Complete service, and returns DX Complete bearer tokens scoped to the configured workspace. The installed repo supplies workspace identity through `dxcomplete/workspace.json`; the hosted service stores workspace memberships and executes MCP tools.
+A DX Complete Ticket is the private place for an MCP client user to raise a question, report, request, correction, or follow-up with DX Complete. It has an ID and can receive appended entries over time. The durable content is the title plus entries; summary is optional and is not generated automatically. DX Complete replies can be tracked as unread or read by the submitting actor. Formal shared work should be created or linked separately when someone decides the ticket needs process follow-up.
 
-Use `runtime_status` to reconcile the MCP-facing contract. `surfaceFingerprint` is the single client-facing identity for the tools, tool schemas, process guide, and on-demand doc references together. `get_process_guide` and `get_doc` return the same `surfaceVersion` and `surfaceFingerprint`, so an MCP client can treat a mismatch as a stale or inconsistent surface and refresh before continuing.
+The Journal is shared workspace context, not a private ticket. It is for useful notes that do not already belong in a dedicated record such as Statement, Expectation, Requirement, Decision, Risk, Change, or Task. Journal content that becomes load-bearing should be promoted to the appropriate record and linked back where useful.
 
-On Vercel, `vercel.json` must include `dxcomplete/workspace.json` in the API function bundle. The scaffold includes this by default with `functions["pages/api/**/*.js"].includeFiles`. Vercel reserves `/.well-known`, so the installed Next app rewrites the OAuth discovery metadata paths to the DX Complete route wrapper.
+The Operating Guide explains record routing by role. Engineer/Codex work defaults to Requirement -> Task. Tester evidence usually belongs in Task entries, review notes, Risk, Decision, or Journal. Operator work uses Change for run-side alterations, Incident for specific service-impacting occurrences, Problem for underlying or recurring causes, and Environment or Component for operational inventory. Support Agent work starts with DX Complete Ticket, then promotes to shared records only when needed.
 
-A DX Complete Ticket is the private place for an MCP client user to raise a question, report, request, correction, or follow-up with DX Complete. It has an ID and can receive appended entries over time. The durable content is the title plus entries; summary is optional and is not generated automatically. DX Complete replies can be tracked as unread or read by the submitting actor. The unread list identifies tickets that need attention; reading the ticket opens the full content and marks addressed replies read. A ticket does not ingest files or assets, and does not automatically create a requirement, task, incident, or decision. Formal shared work should be created or linked separately when someone decides the ticket needs process follow-up.
+## Package and Compatibility Versioning
 
-The Journal is shared workspace context, not a private ticket. It is for useful notes that do not already belong in a dedicated record such as Statement, Expectation, Requirement, Decision, Risk, Change, or Task. The routing test is: will another record reference or depend on this? If yes, prefer a dedicated record. Journal content that becomes load-bearing should be promoted to the appropriate record and linked back where useful. Journal entries are append-only and can be linked as decision inputs or provenance. The default journal read returns the hot tier: active summaries plus active raw notes. Summary entries point back to covered raw notes, and covered notes are archived out of the hot read without being deleted.
+DX Complete uses one package version, one workspace compatibility gate, and one surface fingerprint:
 
-The Operating Guide explains record routing by role. Engineer/Codex work defaults to Requirement -> Task. Tester evidence usually belongs in Task entries, review notes, Risk, Decision, or Journal. Operator work uses Change for run-side alterations, Incident for specific service-impacting occurrences, Problem for underlying or recurring causes, and Environment or Component for operational inventory. Support Agent work starts with DX Complete Ticket, then promotes to shared records only when needed.
+- `packageVersion` is the npm package release version from `package.json`.
+- `workspaceCompatibility` is the installed workspace compatibility gate. It changes only when an installed workspace must update its route/proxy surface to keep talking safely to the hosted DX Complete service.
+- `surfaceFingerprint` is an automatic hash of the live MCP tools, tool schemas, process guide, and on-demand doc references. It can change without requiring a package release or workspace upgrade.
+
+The MCP `surfaceVersion` field is a stable surface identifier. Use `surfaceFingerprint` for exact surface reconciliation and `workspaceCompatibility` for upgrade decisions. `runtime_status`, `get_process_guide`, and `get_doc` return the same `surfaceVersion` and `surfaceFingerprint`, so an MCP client can refresh when the surface is stale or inconsistent.
 
 ## Repository Structure
 
@@ -178,10 +175,6 @@ The Operating Guide explains record routing by role. Engineer/Codex work default
 docs/                 Installed DX Complete documentation
 templates/process/    Installed editable process files
 templates/next/       Installed Next.js route wrappers
-templates/github/     Optional GitHub workflow placeholder
+templates/github/     Optional basic GitHub workflow
 dist/                 Published CLI and workspace MCP proxy handler
 ```
-
-## Design Principle
-
-Use the scaffold to preserve the current thinking without freezing it. Prefer explicit draft status, open questions, TODOs, and editable configuration over hardcoded claims about how the model must work.

package/dist/cli.js

@@ -34,7 +34,7 @@ async function main(argv) {
         console.log(`Initialized DX Complete scaffold in ${result.targetDir}`);
         printList("Written", result.written);
         printList("Skipped existing", result.skipped);
-        console.log("Review dxcomplete/docs/open-questions.md before treating the draft model as policy.");
+        console.log("Next: sign in at https://dxcomplete.directeddomains.com/account.html, create the workspace, replace dxcomplete/workspace.json with the returned workspace JSON, and store the service values in the hosting environment.");
         return;
     }
     if (args.command === "upgrade") {
@@ -164,7 +164,7 @@ Usage:
   dxcomplete validate [--target <dir>]
 
 Commands:
-  init            Install the editable draft scaffold into a project.
+  init            Install the editable DX Complete workspace scaffold into a project.
   upgrade         Preview or apply compatibility-critical scaffold updates.
   validate        Validate the expected scaffold file shape.
 

package/docs/cost-model.md

@@ -1,4 +1,4 @@
-# Draft Cost Model
+# Cost Model
 
 Cost modeling is first-class in DX Complete. Do not reduce the top-level model to OPEX. OPEX/CAPEX-like categories may exist inside the cost model, but the top-level concept should remain Cost Model / Decision Basis.
 
@@ -27,7 +27,7 @@ The structured `Estimate` record is cost-only. It keeps one-time and recurring c
 
 Expected value belongs in `Benefits`. Benefits may include quantified items with amounts, or qualitative items that are complete without an amount.
 
-## Draft Cost Objects
+## Cost Records
 
 Current-state cost context should be attempted where relevant. It may be complete, partial, unavailable, or limited by disclosure, but it is no longer a separate runtime record in the current model.
 

package/docs/decision-basis.md

@@ -1,14 +1,8 @@
-# Draft Decision Basis
+# Decision Basis
 
-DX Complete should be modeled as:
+A DX effort implies a decision to improve or create a digital capability with some expected business benefit. DX Complete therefore keeps cost and benefit reasoning before engineering work begins, plus actual measurement after delivery where possible.
 
-```text
-Decision Basis + Complete Engineering + Operations Measurement
-```
-
-This is a working hypothesis, but the need is first-class. A DX effort implies a decision to improve or create a digital capability with some expected business benefit. The model therefore needs cost and benefit reasoning before engineering work begins, plus actual measurement after delivery where possible.
-
-## Draft Purpose
+## Purpose
 
 The decision basis explains whether there is enough reason and confidence to commit after expectations and the requirement set have been elicited, or whether the work should be deferred until named conditions are addressed.
 
@@ -34,7 +28,7 @@ Actual cost and benefit measurements should be captured after launch where avail
 
 Weigh should preserve the Owner outcome: a Commitment if the work moves forward, or a Deferral if conditions must be addressed first. Decision records can still preserve decision entries, loose argument entries, notes, and linked inputs where a separate decision trail is useful. DX Complete should not require numeric weights or treat the recorded rationale as proof that the choice was objectively correct.
 
-## Draft Decision Basis Flow
+## Decision Basis Flow
 
 1. Statement capture
 2. Capture statement and expectations
@@ -54,4 +48,4 @@ Weigh should preserve the Owner outcome: a Commitment if the work moves forward,
 
 The decision basis should not pretend that every DX effort has clean financial data. It should create visibility into what is known, estimated, unavailable, or deliberately undisclosed.
 
-The terms and object names are draft. The concepts are important.
+The workspace process files can adapt the terms and local guidance, but the decision basis should keep cost, benefit, risk, confidence, and the Owner outcome visible.

package/docs/diagrams.md

@@ -1,6 +1,6 @@
-# Draft Diagrams
+# Diagrams
 
-The Mermaid diagrams are draft visualizations. They should be revised as roles, workflows, and object relationships change.
+The Mermaid diagrams visualize the current DX Complete workflow and record relationships. Revise them when local role, workflow, or record decisions change.
 
 Installed diagram files:
 
@@ -20,7 +20,7 @@ Installed diagram files:
 
 ## Diagram Policy
 
-Each diagram should stay editable in plain Mermaid. Avoid diagrams that imply the model is final unless the related Markdown and YAML have been updated to match that decision.
+Each diagram should stay editable in plain Mermaid. Keep related Markdown, YAML, and Mermaid files aligned when a workspace policy changes.
 
 ## Revision Questions
 

package/docs/index.md

@@ -1,61 +1,47 @@
-# DX Complete Draft Scaffold
+# DX Complete Workspace Docs
 
 ## Goal
 
-Build a Node package that installs a reusable DX Complete documentation and scaffold kit into a project.
+These files describe how this workspace uses DX Complete to decide what is worth doing, deliver it with control, run it safely, and learn from the results.
 
-## Important Context
+DX Complete is installed into a service repo as workspace-owned documentation, process files, and route wrappers. The hosted DX Complete service stores records, manages sign-in, checks workspace membership, assigns readable IDs, and executes MCP tools.
 
-This is exploratory design work. The product goal is stable, but the engineering/service model, roles, workflows, object taxonomy, and diagrams are still being discovered.
+## Install And Provisioning Context
 
-Do not treat the current model as final. Preserve it as draft material and make it easy to revise.
+The npm package installs the workspace-side files. It does not install the hosted DX Complete service.
 
-## Core Product Outcome
+For a new workspace:
 
-The package should initialize a repo with process documentation, Mermaid diagrams, taxonomy files, decision-basis templates, cost-model templates, workflow templates, and placeholder configuration for a full end-to-end DX engineering and service control model.
+1. Run `npx dxcomplete init` in the Next.js project repo.
+2. Sign in at `https://dxcomplete.directeddomains.com/account.html`.
+3. Create a workspace for the service.
+4. Replace `dxcomplete/workspace.json` with the workspace JSON shown by the account page.
+5. Store `DXC_SERVICE_URL`, `DXC_SERVICE_CLIENT_ID`, and `DXC_SERVICE_CLIENT_SECRET` in the workspace app hosting environment.
+6. Deploy the workspace app and verify the MCP route at `/api/mcp`.
 
-The broader product premise is:
+The service secret is shown once by the account page. Store it in the hosting environment, not in the repo.
 
-```text
-DX Complete = Decision Basis + Complete Engineering + Operations Measurement
-```
+## Current Product Model
 
-Command target:
-
-```sh
-npx dxcomplete init
-```
-
-## Scope Of The Draft Model
-
-The installed scaffold should help describe and evolve a model covering:
+The installed model covers:
 
 - Workspace and service context
 - Statement capture
 - Shared Journal context
-- Current-state cost context attempts
-- Itemized cost estimates
-- Benefits
+- Cost context, itemized estimates, benefits, and measured value
 - Decision basis for Weigh
-- Weigh outcomes with Commitment or Deferral records, plus decisions with linked inputs where useful
-- Direction
-- Product definition
-- Engineering execution
-- Engineer implementation, including Codex-assisted work where appropriate
-- QA verification
-- Product validation
+- Weigh outcomes with Commitment or Deferral records
+- Decisions with linked inputs where useful
+- Direction and product definition
+- Engineering execution and task work
+- QA verification and product validation
 - Change and release control
-- Deployment
-- Operation
-- User support
+- Deployment and operation
+- User support, incidents, and problems
 - Administration as part of operation
-- Audit and evidence
-- Actual cost / benefit measurement where available
-- Estimate refinement for future projects
+- Audit, evidence, risk, and measurement
 - Role-by-role operating guidance
 
 ## How To Read These Docs
 
-These documents record the current working hypotheses. They are not requirements for how every organization must operate.
-
-Use `operating-guide.md` to see how each role should choose records in normal work. Use `open-questions.md` to capture uncertain areas before turning them into policy. Use the YAML files in `templates/process/` as the editable source for roles, objects, workflows, and controls.
+Use `operating-guide.md` to see how each role should choose records in normal work. Use `taxonomy.md` to understand the current record set. Use `open-questions.md` for genuine unresolved policy questions. Use the YAML files in `dxcomplete/process/` as editable workspace process data.

package/docs/model.md

@@ -1,16 +1,10 @@
-# Draft Model
+# DX Complete Model
 
-## Working Hypothesis
+## Current Model
 
 The model is a full DX lifecycle, not merely a software development workflow.
 
-The broader product premise is:
-
-```text
-DX Complete = Decision Basis + Complete Engineering + Operations Measurement
-```
-
-It should include cost and benefit reasoning before engineering begins, both build/change roles and run/service roles, and actual measurement after delivery where available.
+It includes cost and benefit reasoning before engineering begins, both build/change roles and run/service roles, and actual measurement after delivery where available.
 
 The current runtime scope decision is `Workspace`: the hosted-record container for one service scope. The default MCP deployment model is one endpoint per workspace. Each installed project repo carries its workspace identity in editable DX Complete config and exposes one MCP route for that workspace.
 
@@ -18,21 +12,19 @@ Workspace MCP deployments are not database runtimes and do not install the hoste
 
 Workspace carries the service identity through its name, summary, and mode when useful. A separate service charter record is not part of the current model; if a presentation summary is needed, it should be derived from the workspace and current expectations.
 
-The current decision-basis hypothesis is that `Statement`, `Expectation`, `Requirement`, `Estimate`, `Benefits`, and `Decision` sit upstream of Build inside the Workspace. Statements, expectations, dependencies, constraints, unknowns, and requirements should be elicited before useful estimates are generated. Current-state cost context should be attempted where relevant, an itemized cost `Estimate` should be generated by default from the elicited requirement set where cost reasoning is needed, expected `Benefits` should be recorded where possible, and Weigh should bridge into Build through a Commitment or keep the path visible through a Deferral. A Decision can preserve ordered rationale entries and records that informed the Owner's judgment.
+The current decision-basis model is that `Statement`, `Expectation`, `Requirement`, `Estimate`, `Benefits`, and `Decision` sit upstream of Build inside the Workspace. Statements, expectations, dependencies, constraints, unknowns, and requirements should be elicited before useful estimates are generated. Current-state cost context should be attempted where relevant, an itemized cost `Estimate` should be generated by default from the elicited requirement set where cost reasoning is needed, expected `Benefits` should be recorded where possible, and Weigh should bridge into Build through a Commitment or keep the path visible through a Deferral. A Decision can preserve ordered rationale entries and records that informed the Owner's judgment.
 
-The current early lifecycle hypothesis is `Statement -> Expectation -> Requirement -> Commitment`, with `Deferral` as the alternate Weigh outcome that can resolve into a Commitment. `Statement` preserves the user's own words before interpretation as a runtime record. `Expectation` is tracked as a runtime record and restates the expected result and how success will be recognized in user-facing language. The MCP client should confirm captured wording before recording it on a user's behalf. Separate authority approval, usually by Owner, can be tracked when it reduces risk. `Requirement` is the team-owned commitment that translates expectations into something buildable and verifiable. Statements, expectations, and requirements should keep prior versions when their current wording changes. `Commitment` records the Owner moving requirements or expectations into Build. `Task` is a cross-cutting execution object that can be created whenever a phase needs concrete action. `Journal` is cross-cutting shared workspace context for relevant notes that do not have a dedicated record home.
+The current early lifecycle is `Statement -> Expectation -> Requirement -> Commitment`, with `Deferral` as the alternate Weigh outcome that can resolve into a Commitment. `Statement` preserves the user's own words before interpretation as a runtime record. `Expectation` is tracked as a runtime record and restates the expected result and how success will be recognized in user-facing language. The MCP client should confirm captured wording before recording it on a user's behalf. Separate authority approval, usually by Owner, can be tracked when it reduces risk. `Requirement` is the team-owned commitment that translates expectations into something buildable and verifiable. Statements, expectations, and requirements should keep prior versions when their current wording changes. `Commitment` records the Owner moving requirements or expectations into Build. `Task` is a cross-cutting execution object that can be created whenever a phase needs concrete action. `Journal` is cross-cutting shared workspace context for relevant notes that do not have a dedicated record home.
 
 A separate technical specification object is not part of the current model. Implementation and verification detail should live inside a Requirement as optional requirement detail until the need for an independent object is proven.
 
-The current engineering lifecycle hypothesis is that the main end-to-end engineering object may be `Requirement`. Requirements are shaped during elicitation, committed or deferred during Weigh, and refined into requirement detail and tasks during Build once covered by a Commitment. Task is a cross-cutting execution record with ordered entries and a current status derived from the latest status-change entry. The Engineer works primarily on Tasks and may use coding-capable tools such as Codex where appropriate. Incident and Problem are now run-side records: Incident records a specific service-impacting occurrence, and Problem records an underlying or recurring cause evidenced by incidents. Feature Request, Feedback, Authoritative Request, Release, Deployment, and Control remain useful lifecycle concepts, but they are not separate runtime records in the current model.
-
-The current review-note hypothesis is that Engineer input on Expectations or Requirements should be preserved as append-only free text. A review note can be marked important to draw attention, but it does not block progress, create a severity state, or require an Owner response.
+The current engineering lifecycle uses `Requirement` as the main end-to-end engineering object. Requirements are shaped during elicitation, committed or deferred during Weigh, and refined into requirement detail and tasks during Build once covered by a Commitment. Task is a cross-cutting execution record with ordered entries and a current status derived from the latest status-change entry. The Engineer works primarily on Tasks and may use coding-capable tools such as Codex where appropriate. Incident and Problem are run-side records: Incident records a specific service-impacting occurrence, and Problem records an underlying or recurring cause evidenced by incidents. Feature Request, Feedback, Authoritative Request, Release, Deployment, and Control remain useful lifecycle concepts, but they are not separate runtime records in the current model.
 
-The current checkpoint hypothesis is that approval and similar confirmation points are advisory risk checkpoints, not blockers. A checkpoint can be approved, formally accepted as risk by the Owner, or proceeded past with the open risk still visible. Proceeding past an open checkpoint does not close or accept the risk.
+Engineer input on Expectations or Requirements is preserved as append-only free text. A review note can be marked important to draw attention, but it does not block progress, create a severity state, or require an Owner response.
 
-The current decision rationale hypothesis is that DX Complete should preserve the matter being decided, ordered decision entries, loose argument and note entries, and the records that informed the choice. The current decision is derived from the latest decision entry while earlier decisions remain visible. DX Complete should not require numeric weights or attempt to prove that the decision was objectively correct. Authority can make a poor or unreasonable decision; the system's role is to keep the decision trail visible for accountability, review, audit, and learning.
+Approval and similar confirmation points are advisory risk checkpoints, not blockers. A checkpoint can be approved, formally accepted as risk by the Owner, or proceeded past with the open risk still visible. Proceeding past an open checkpoint does not close or accept the risk.
 
-This is a draft. The primary lifecycle object, object boundaries, role ownership, and lifecycle links may change.
+DX Complete preserves the matter being decided, ordered decision entries, loose argument and note entries, and the records that informed the choice. The current decision is derived from the latest decision entry while earlier decisions remain visible. DX Complete does not require numeric weights or attempt to prove that the decision was objectively correct. Authority can make a poor or unreasonable decision; the system's role is to keep the decision trail visible for accountability, review, audit, and learning.
 
 ## Model Layers
 
@@ -70,7 +62,7 @@ Operations measurement captures actual cost and benefit observations where avail
 
 Decision rationale captures ordered entries for the matter being decided, including decision entries, argument entries, and notes without forcing those arguments into weighted or directional scoring. Decision inputs link the Decision to the records that informed it, so the trail can be followed from the choice back to its basis.
 
-## Draft Relationship Shape
+## Relationship Shape
 
 ```mermaid
 flowchart LR
@@ -105,6 +97,6 @@ flowchart LR
   Decision -. informed_by .-> Change
 ```
 
-## Revision Principle
+## Adaptation Principle
 
-Keep the model editable. If a team discovers that `Change`, `Requirement`, or another object should be the central lifecycle object, update the docs and YAML files before treating the scaffold as operating policy.
+Keep the workspace process files editable. If a team makes a local policy decision that changes how it uses `Change`, `Requirement`, or another record, update the Markdown, YAML, and Mermaid files together so the workspace guidance stays consistent.

package/docs/open-questions.md

@@ -1,6 +1,6 @@
 # Open Questions
 
-Use this file to keep uncertainty visible. The package should preserve draft thinking without making the model appear decided.
+Use this file to keep genuine unresolved policy questions visible. When a question is answered, update the related Markdown, YAML, and Mermaid files together.
 
 ## Model
 

package/docs/taxonomy.md

@@ -1,8 +1,8 @@
-# Draft Taxonomy
+# DX Complete Records
 
-The object taxonomy is draft material. Use it to preserve the current working model, not to declare final truth.
+The record set describes the current DX Complete runtime model for one workspace.
 
-## Current Runtime Record Hypothesis
+## Current Runtime Records
 
 - Workspace
 - DX Complete Ticket
@@ -39,7 +39,7 @@ These concepts remain useful, but they are not separate runtime records in the c
 - Evidence
 - Estimate Refinement
 
-## Current Lifecycle Hypothesis
+## Current Lifecycle Model
 
 `Workspace` is the runtime scope object. It contains one service scope and is the boundary for hosted DX Complete records. The default MCP deployment model is one endpoint per installed workspace, with workspace identity coming from DX Complete config and access constrained by authenticated actor plus workspace authorization.
 
@@ -67,7 +67,7 @@ Workspace-scoped lifecycle records use UUIDs as primary keys and links, while al
 
 `ReviewNote` is not a separate collection. Expectations and Requirements can carry append-only review notes. A note can be marked important, but it does not create a severity state, block progress, or require an Owner response.
 
-The main engineering object may be `Requirement`. Requirements translate expectations into team-owned commitments that are shaped during elicitation, weighed by the Owner, and refined during Build once covered by a Commitment. When a requirement changes, prior versions should be kept so the current commitment remains reconstructable.
+The main engineering object is `Requirement`. Requirements translate expectations into team-owned commitments that are shaped during elicitation, weighed by the Owner, and refined during Build once covered by a Commitment. When a requirement changes, prior versions should be kept so the current commitment remains reconstructable.
 
 `Commitment` is the Owner's point-in-time authority record that moves named requirements or expectations into Build. It can include reservations: concerns the Owner is moving forward despite.
 
@@ -89,9 +89,8 @@ Decision inputs use the `informed_by` relationship from a Decision to the record
 
 The installed scaffold includes `dxcomplete/process/taxonomy.yml`. Treat that file as the editable taxonomy source for a project.
 
-## Taxonomy Questions
+## Open Taxonomy Questions
 
-- Is `Requirement` the main lifecycle object, or should the center be `Change`, `Feature Request`, or another object?
 - Is `Workspace` sufficient as the service-scope boundary, or will related workspaces need a stronger grouping model?
 - Should future work need a grouping model above Workspace, or is Workspace sufficient as the service scope?
 - Should decision arguments remain embedded text, or should they become first-class records after repeated use?

package/docs/workflows.md

@@ -1,6 +1,6 @@
-# Draft Workflows
+# Workflows
 
-These workflows are editable drafts. They describe likely lifecycle paths without declaring them final.
+These workflows describe the current DX Complete lifecycle paths. Adapt the workspace-owned process files when a local policy decision changes how the team works.
 
 ## Current Workflow Areas
 
@@ -26,7 +26,7 @@ These workflows are editable drafts. They describe likely lifecycle paths withou
 - Actual cost / benefit observations
 - Estimate refinement
 
-## Draft End-To-End Flow
+## End-To-End Flow
 
 1. A signal enters through feedback, authoritative request, support ticket, service-impact event, recurring issue, or strategic direction.
 2. Statement capture preserves the user's own words and links the work to the Workspace context.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dxcomplete",
-  "version": "0.2.2",
-  "description": "Install a Next.js workspace scaffold for DX Complete process records, MCP routes, and service lifecycle documentation.",
+  "version": "0.3.0",
+  "description": "Install the DX Complete workspace-side docs, process files, and MCP route for the hosted record service.",
   "type": "module",
   "keywords": [
     "dxcomplete",

package/templates/process/README.md

@@ -1,19 +1,19 @@
 # DX Complete Process Scaffold
 
-This directory is an editable draft scaffold for a DX Complete model.
+This directory contains editable process files for this DX Complete workspace.
 
-The current model is not final. Update these files as the decision-basis, engineering, service, roles, workflows, object taxonomy, and controls become clearer.
+Update these files when the workspace makes local decisions about decision-basis, engineering, service operation, roles, workflows, records, and controls.
 
 The current scope commitment is that a Workspace contains one service scope. Statements, journal entries, decisions, requirements, work, cost, benefit, support, operations, and measurement records should be understood inside that workspace unless a project explicitly decides otherwise. The default runtime shape is one MCP endpoint for that installed workspace, with workspace identity coming from DX Complete config and access constrained by authenticated actor identity plus workspace authorization.
 
 ## Files
 
-- `decision-basis.yml` stores draft decision-basis templates and Commitment-or-Deferral framing.
-- `cost-model.yml` stores draft current-state cost context, estimate, and actuals concepts.
-- `roles.yml` stores draft role responsibilities.
-- `taxonomy.yml` stores draft lifecycle objects and relationships.
-- `workflows.yml` stores draft workflow templates.
-- `controls.yml` stores placeholder controls and evidence expectations.
+- `decision-basis.yml` stores decision-basis templates and Commitment-or-Deferral framing.
+- `cost-model.yml` stores current-state cost context, estimate, and actuals concepts.
+- `roles.yml` stores role responsibilities.
+- `taxonomy.yml` stores lifecycle records and relationships.
+- `workflows.yml` stores workflow templates.
+- `controls.yml` stores controls and evidence expectations.
 - `diagrams/` stores editable Mermaid diagrams.
 - `evidence/` stores captured evidence or pointers to evidence.
 - `decisions/` stores decision records.
@@ -21,7 +21,7 @@ The current scope commitment is that a Workspace contains one service scope. Sta
 
 ## Editing Guidance
 
-Prefer explicit draft language until a decision is made. When a decision is made, capture the decision record and update the relevant YAML, Markdown, and Mermaid files together.
+When a decision changes the workspace process, capture the decision record and update the relevant YAML, Markdown, and Mermaid files together.
 
 ## Suggested First Pass
 
@@ -35,4 +35,4 @@ Prefer explicit draft language until a decision is made. When a decision is made
 8. Keep `Requirement` as the main engineering lifecycle object unless the model proves otherwise.
 9. Remove objects that are too heavy for the current context.
 10. Add evidence expectations only where they are useful.
-11. Review open questions before turning placeholders into policy.
+11. Review open questions before turning local process changes into policy.