dxcomplete 0.1.0 → 0.2.0

package/src/validate.ts

@@ -19,6 +19,7 @@ const docs = [
   "cost-model.md",
   "glossary.md",
   "model.md",
+  "operating-guide.md",
   "roles.md",
   "taxonomy.md",
   "workflows.md",
@@ -85,6 +86,7 @@ function packageRequiredFiles(): string[] {
     path.join("api", "dxcomplete-service.js"),
     path.join("api", "auth", "callback", "google.js"),
     path.join("dxcomplete", "workspace.json"),
+    path.join("templates", "AGENTS.md"),
     path.join("scripts", "check-env-surface.mjs"),
     path.join("scripts", "smoke-mcp-http.mjs"),
     path.join("scripts", "dogfood-work-order.mjs"),

package/templates/AGENTS.md

@@ -0,0 +1,30 @@
+# DX Complete Guidance
+
+This project uses DX Complete.
+
+Before making DX Complete process changes, read:
+
+- `dxcomplete/docs/operating-guide.md`
+- `dxcomplete/docs/codex-integration.md`
+
+## Role Context
+
+When acting as Codex, assume you are assisting the `Engineer` unless the user explicitly assigns another role.
+
+Engineer/Codex default path:
+
+```text
+Requirement -> Task
+```
+
+Use:
+
+- `Task` for ordinary implementation work.
+- `Decision` for meaningful choices between alternatives.
+- `Risk` for uncertainty or exposure.
+- `Journal` only for relevant context with no better dedicated record home.
+- `Change` only for a discrete alteration to the running service.
+
+Do not create ITSM-style records merely because development work is happening. `Change` is the run-side control record for a discrete service alteration. `Incident` is for a specific service-impacting occurrence. `Problem` is for an underlying or recurring cause evidenced by incidents.
+
+Keep public documentation user-facing. Website copy should speak to people using DX Complete, not to maintainers building the package.

package/templates/process/controls.yml

@@ -73,7 +73,7 @@ controls:
 
   - id: release_readiness
     name: Release readiness
-    draft_purpose: Confirm change scope, risk, rollback, notice, veto, emergency posture, and required evidence before release.
+    draft_purpose: Confirm change type, scope, risk, rollback, notice, veto, and required evidence before release.
     applies_to:
       - Change
       - Release
@@ -99,15 +99,19 @@ controls:
     open_questions:
       - Which deployment evidence is automatically available?
 
-  - id: incident_response_record
-    name: Incident response record
-    draft_purpose: Preserve response details for service-impacting events.
+  - id: service_impact_response_evidence
+    name: Service-impact response evidence
+    draft_purpose: Preserve response details for service-impacting events through Incident entries.
     applies_to:
-      - Incident
+      - DX Complete Ticket
+      - Risk
+      - Task
+      - Change
+      - Decision
     draft_evidence:
       - Timeline.
       - Impact.
       - Actions taken.
       - Resolution and follow-up links.
     open_questions:
-      - Which support tickets should be promoted to incidents?
+      - Which service-impact signals should later become Incident records if Incident is promoted?

package/templates/process/diagrams/01-intake-triage.mmd

@@ -1,20 +1,20 @@
 %% Draft intake and triage workflow.
 flowchart TD
   Signal[Incoming signal] --> Source{Likely source?}
-  Source -->|Client or user| SupportSignal[Support Ticket draft]
+  Source -->|Client or user| SupportSignal[Support Request draft]
   Source -->|Product idea| Feedback[Feedback draft]
   Source -->|Authority or commitment| AuthoritySignal[Authoritative Request draft]
-  Source -->|Service health| Incident[Incident draft]
+  Source -->|Service health| ServiceImpact[Service-impact signal]
   SupportSignal --> Triage[Triage]
   Feedback --> Triage
   AuthoritySignal --> Triage
-  Incident --> Triage
+  ServiceImpact --> Triage
   Triage --> OwnerRoute[Route to Owner]
   Triage --> OpsRoute[Route to Operator]
   Triage --> DecisionRoute[Route for authority decision]
   ProductRoute --> RequirementCandidate[Requirement candidate]
-  OpsRoute --> IncidentOrProblem[Incident or Problem candidate]
+  OpsRoute --> ServiceFollowUp[Risk, Task, Change, or Decision candidate]
   DecisionRoute --> Decision[Decision or priority]
   RequirementCandidate --> OpenQuestions[Capture open questions]
-  IncidentOrProblem --> OpenQuestions
+  ServiceFollowUp --> OpenQuestions
   Decision --> OpenQuestions

package/templates/process/diagrams/02-product-definition.mmd

@@ -1,6 +1,6 @@
 %% Draft product definition workflow.
 flowchart TD
-  SourceObject[Feedback / Feature Request / Authoritative Request / Problem] --> Clarify[Clarify desired outcome]
+  SourceObject[Feedback / Feature Request / Authoritative Request / Recurring issue] --> Clarify[Clarify desired outcome]
   Clarify --> Statement[Capture User Statement]
   Statement --> Expectation[Restate Expected Result]
   Expectation --> Requirement[Draft Requirement]

package/templates/process/diagrams/06-change-release-control.mmd

@@ -1,16 +1,14 @@
 %% Draft change and release control workflow.
 flowchart TD
-  Change[Create Change record] --> Plan[Record change plan]
+  Change[Create Change record] --> Type[Classify standard, normal, or emergency]
+  Type --> Plan[Record change plan]
   Plan --> Execution[Record execution steps]
   Execution --> Rollback[Record rollback plan]
-  Rollback --> RiskImpact[Record risk and impact]
+  Rollback --> RiskImpact[Record risk, impact, and downstream impact]
   RiskImpact --> Notice[Append notice event]
   Notice --> Veto{Veto recorded?}
   Veto -->|Yes| VetoEvent[Append veto event]
   Veto -->|No| Decision[Append decision event]
   VetoEvent --> Decision
-  Decision --> Emergency{Emergency path?}
-  Emergency -->|Yes| EmergencyEvent[Append importance and immediacy]
-  Emergency -->|No| Release[Prepare release or deployment]
-  EmergencyEvent --> Release
-  Release --> Result[Append result or recovery event]
+  Decision --> Release[Prepare release or deployment]
+  Release --> Result[Append result or recovery event with optional Git reference]

package/templates/process/diagrams/07-deployment-operations.mmd

@@ -6,8 +6,8 @@ flowchart TD
   Registry --> Monitor[Monitor service health]
   Monitor --> Healthy{Healthy?}
   Healthy -->|Yes| Operate[Operate service]
-  Healthy -->|No| Incident[Create or update Incident]
-  Incident --> Response[Incident response]
+  Healthy -->|No| ServiceSignal[Record service-impact signal]
+  ServiceSignal --> Response[Operator response]
   Response --> Rollback{Rollback needed?}
   Rollback -->|Yes| RollbackAction[Rollback or mitigation]
   Rollback -->|No| ContinueMonitor[Continue monitoring]

package/templates/process/diagrams/08-support-incident-management.mmd

@@ -1,15 +1,16 @@
 %% Draft support and incident management workflow.
 flowchart TD
-  UserSignal[End User signal] --> Ticket[Support Ticket]
+  UserSignal[End User signal] --> Ticket[Support Request]
   Ticket --> Classify{Classify}
   Classify -->|Question or request| SupportResponse[Support Agent response]
   Classify -->|Outcome signal| Feedback[Feedback]
-  Classify -->|Service impact| Incident[Incident]
-  Classify -->|Recurring issue| ProblemCandidate[Problem candidate]
+  Classify -->|Service impact| Incident[Create Incident]
+  Classify -->|Recurring issue| Problem[Create Problem]
   Incident --> Operator[Operator response]
+  Incident --> Problem
   Operator --> UserComms[Support Agent communicates status]
   Feedback --> Owner[Owner triage]
-  ProblemCandidate --> ProblemReview[Problem review]
+  Problem --> ProblemReview[Risk, Decision, Requirement, Change, or Task review]
   SupportResponse --> CloseTicket[Close or update ticket]
   UserComms --> CloseTicket
   Owner --> CloseTicket

package/templates/process/diagrams/09-problem-improvement.mmd

@@ -1,11 +1,12 @@
 %% Draft problem and improvement workflow.
 flowchart TD
-  Signal[Incident / Support Ticket / QA defect / Operator finding] --> Problem[Problem draft]
-  Problem --> Investigate[Investigate likely cause]
+  Signal[Incident / ticket / repeated service signal] --> Problem[Create Problem]
+  Problem --> Investigate[Append investigation entry]
   Investigate --> CauseKnown{Cause known?}
   CauseKnown -->|No| MoreEvidence[Collect more evidence]
   MoreEvidence --> Investigate
-  CauseKnown -->|Yes| Improvement{Improvement needed?}
+  CauseKnown -->|Yes| RootCause[Append root-cause or known-error entry]
+  RootCause --> Improvement{Improvement needed?}
   Improvement -->|Requirement| Requirement[Create Requirement]
   Improvement -->|Service change| Change[Create Change]
   Improvement -->|No action| Decision[Record decision]

package/templates/process/diagrams/10-risk-control-management.mmd

@@ -1,11 +1,13 @@
 %% Draft risk and control management workflow.
 flowchart TD
-  RiskSignal[Risk signal] --> Risk[Risk draft]
-  Risk --> Assess[Assess likelihood, impact, and owner]
+  RiskSignal[Risk signal] --> Risk[Create Risk ledger]
+  Risk --> Identify[Append identified entry]
+  Identify --> Assess[Append assessment entry]
   Assess --> Treatment{Treatment}
-  Treatment -->|Accept| Decision[Record acceptance decision]
+  Treatment -->|Accept| Owner[Owner formal acceptance]
+  Owner --> Decision[Record acceptance decision]
   Decision -. informed_by .-> Risk
-  Treatment -->|Mitigate| Control[Define Control]
+  Treatment -->|Mitigate| Control[Append treatment entry]
   Treatment -->|Avoid or defer| Requirement[Create or revise Requirement]
   Control --> EvidenceNeed[Define evidence need]
   EvidenceNeed --> LinkedObjects[Link Requirement / Release / Deployment]

package/templates/process/diagrams/11-audit-evidence-capture.mmd

@@ -1,6 +1,6 @@
 %% Draft audit and evidence capture workflow.
 flowchart TD
-  LifecycleObject[Requirement / Task / Change / Release / Deployment / Incident / Control] --> EvidenceNeed{Evidence needed?}
+  LifecycleObject[Requirement / Task / Change / Incident / Problem / Decision / Risk / Control] --> EvidenceNeed{Evidence needed?}
   EvidenceNeed -->|No| Note[Record no evidence required decision if useful]
   EvidenceNeed -->|Yes| Capture[Capture or link evidence]
   Capture --> ResponsiblePerson[Record responsible person and timestamp]

package/templates/process/taxonomy.yml

@@ -14,14 +14,19 @@ current_lifecycle_hypothesis:
     - Journal
     - Environment
     - Component
+    - Maintenance Schedule
     - Expectation
     - Requirement
     - Estimate
     - Benefits
+    - Value Realization
     - Commitment
     - Deferral
     - Task
     - Change
+    - Incident
+    - Problem
+    - Support Request
     - Decision
     - Risk
   upstream_decision_basis_objects:
@@ -30,14 +35,12 @@ current_lifecycle_hypothesis:
     - Requirement
     - Estimate
     - Benefits
+    - Value Realization
     - Decision
   lifecycle_concepts_not_runtime_records:
     - Feedback
     - Authoritative Request
     - Feature Request
-    - Incident
-    - Problem
-    - Support Ticket
     - Release
     - Deployment
     - Control
@@ -91,7 +94,7 @@ objects:
       - Task
       - Decision
       - Risk
-      - Support Ticket
+      - Support Request
 
   - id: journal
     name: Journal
@@ -163,6 +166,26 @@ objects:
       - Decision
       - Risk
 
+  - id: maintenance_schedule
+    name: Maintenance Schedule
+    draft_definition: A recurring operational hygiene record with cadence, start date, rationale, and derived due state.
+    draft_fields:
+      - name
+      - kind
+      - cadence
+      - start_date
+      - rationale
+      - notes
+      - version_history
+    rules:
+      - Maintenance Schedule is for recurring service hygiene, not one-off work.
+      - Due state is derived from cadence and linked completed Changes or Tasks.
+      - Maintenance Schedule edits should preserve prior versions.
+    possible_links:
+      - Change
+      - Task
+      - Decision
+
   - id: estimate
     name: Estimate
     draft_definition: An itemized cost record used during Weigh, linked to the requirements or expectations it covers.
@@ -194,6 +217,20 @@ objects:
       - Commitment
       - Decision
 
+  - id: value_realization
+    name: Value Realization
+    draft_definition: A measured before-and-after value record for expectations, requirements, or commitments.
+    rules:
+      - Value Realization metrics have a baseline, unit, direction, and optional actual value.
+      - Metrics without actual values remain open.
+      - Comparisons are derived from baseline and actual values.
+      - Value Realization edits should preserve prior versions.
+    possible_links:
+      - Expectation
+      - Requirement
+      - Commitment
+      - Decision
+
   - id: feedback
     name: Feedback
     status: lifecycle_concept
@@ -364,48 +401,76 @@ objects:
       - Operator
       - Incident
     draft_fields:
+      - change_type
       - change_plan
       - execution_steps
       - rollback_plan
       - risk_impact
+      - impact_grade
+      - emergency_importance
+      - emergency_immediacy
       - planned_for
       - events
     rules:
       - Change is not a standing Operations Plan.
       - DX Complete records the change; it does not perform or enforce the operation.
       - The original plan sections should remain as the baseline.
-      - Notice, veto, emergency posture, decision, result, recovery, notes, and plan revisions should be appended as immutable events.
-      - Emergency changes should record both importance and immediacy.
+      - Risk and impact should include downstream impact where known: what else may be affected and what depends on what is changing.
+      - Change type is standard, normal, or emergency.
+      - Notice, veto, decision, result, recovery, notes, and plan revisions should be appended as immutable events.
+      - Result and recovery events may include optional Git commit references for each execution attempt or rollback; these are references only and should not require Git validation.
+      - Emergency changes should record both importance and immediacy where available; missing rationale remains visible.
       - Owner or Engineer may record a veto, but the veto does not mechanically stop the Operator.
     possible_links:
       - Requirement
       - Release
       - Deployment
       - Risk
+      - Component
+      - Incident
       - Control
 
   - id: incident
     name: Incident
-    status: lifecycle_concept
-    draft_definition: A service-impacting or potentially service-impacting event requiring response.
+    status: current_runtime_record
+    draft_definition: A specific service-impacting or potentially service-impacting occurrence requiring response.
+    draft_fields:
+      - description
+      - entries
+      - current_status
+      - current_severity
+    rules:
+      - Current status and severity derive from ordered entries.
+      - Use Incident for a specific occurrence, not for an underlying cause.
+      - Link affected Components with affects.
     likely_sources:
       - Operator
       - Support Agent
       - Monitoring
       - End User
     possible_links:
-      - Support Ticket
+      - Support Request
       - Problem
       - Change
+      - Component
       - Risk
 
   - id: problem
     name: Problem
-    status: lifecycle_concept
-    draft_definition: An underlying cause or recurring issue that may require investigation and improvement work.
+    status: current_runtime_record
+    draft_definition: An underlying or recurring cause evidenced by one or more incidents.
+    draft_fields:
+      - description
+      - entries
+      - current_status
+      - current_root_cause
+    rules:
+      - Current status and root cause derive from ordered entries.
+      - Link incidents that evidence the problem with evidenced_by.
+      - Link affected Components with affects when useful.
     likely_sources:
       - Incident
-      - Support Ticket
+      - Support Request
       - Operator
       - Tester
     possible_links:
@@ -413,15 +478,24 @@ objects:
       - Risk
       - Decision
 
-  - id: support_ticket
-    name: Support Ticket
-    status: lifecycle_concept
-    draft_definition: A user-facing support interaction, request, or issue report.
+  - id: support_request
+    name: Support Request
+    status: current_runtime_record
+    draft_definition: A shared support ledger for a user-facing reported experience, question, request, or issue.
+    draft_fields:
+      - reporter
+      - kind
+      - reported_experience
+      - entries
+      - current_status
+    rules:
+      - Current status derives from ordered entries.
+      - Escalated support entries can link to an Incident.
+      - Use DX Complete Ticket for private communication with DX Complete, not shared support follow-up.
     likely_sources:
       - End User
       - Support Agent
     possible_links:
-      - Feedback
       - Incident
       - Problem
       - Requirement

package/templates/process/workflows.yml

@@ -39,7 +39,7 @@ workflows:
 
   - id: intake_triage
     name: Intake and triage
-    draft_purpose: Decide whether a signal should become feedback, feature request, requirement, incident, problem, or another lifecycle object.
+    draft_purpose: Decide whether a signal should become a ticket, statement, requirement, task, risk, decision, change, journal note, or another matching lifecycle concept.
     likely_roles:
       - Owner
       - Support Agent
@@ -108,7 +108,7 @@ workflows:
 
   - id: change_release_control
     name: Change and release control
-    draft_purpose: Record a discrete service change, including plan, execution, rollback, notice, veto, emergency posture, and result.
+    draft_purpose: Record a discrete service change, including change type, plan, execution, rollback, notice, veto, and result.
     likely_roles:
       - Operator
       - Owner
@@ -118,7 +118,8 @@ workflows:
       - Record the Change baseline.
       - Confirm required evidence and notice.
       - Assess risk, impact, and rollback.
-      - Append notice, veto, emergency, decision, result, recovery, note, or revision events as they occur.
+      - Classify the change as standard, normal, or emergency.
+      - Append notice, veto, decision, result, recovery, note, or revision events as they occur.
       - Link release or deployment evidence where needed.
 
   - id: deployment_operations
@@ -134,7 +135,7 @@ workflows:
       - Monitor service health.
       - Update Environment and Component records when operational inventory changes.
       - Record deployment evidence.
-      - Route issues to incident or support workflows.
+      - Route issues to tickets, risks, tasks, changes, decisions, requirements, or journal notes as appropriate.
 
   - id: operational_registry
     name: Operational Registry maintenance
@@ -151,7 +152,7 @@ workflows:
 
   - id: support_incident_management
     name: Support and incident management
-    draft_purpose: Handle user-facing issues and service-impacting events.
+    draft_purpose: Handle user-facing issues and service-impacting events, using Incident when a specific occurrence needs response history.
     likely_roles:
       - Support Agent
       - Operator
@@ -159,14 +160,14 @@ workflows:
       - Engineer
     draft_steps:
       - Capture user or monitoring signal.
-      - Classify as ticket, incident, feedback, or problem candidate.
+      - Classify as ticket, statement, incident, problem, risk, task, change, decision, requirement, or journal note.
       - Communicate status to affected users where needed.
       - Resolve or route.
       - Link follow-up objects.
 
   - id: problem_improvement
     name: Problem and improvement management
-    draft_purpose: Convert recurring or root-cause issues into durable improvements.
+    draft_purpose: Convert recurring or root-cause signals into durable improvements through Problem records and linked follow-up.
     likely_roles:
       - Operator
       - Engineer
@@ -174,8 +175,8 @@ workflows:
       - Support Agent
     draft_steps:
       - Identify recurring issue or root cause.
-      - Record problem.
-      - Decide whether improvement requires a requirement or Change.
+      - Capture the underlying or recurring cause through Problem when incidents or operational evidence support it.
+      - Decide whether improvement requires a Requirement, Task, Risk, Decision, or Change.
       - Track corrective action.
       - Capture outcome and evidence.
 

package/website/flow.html

@@ -23,6 +23,7 @@
           <a class="nav-link" href="./flow.html">Flow</a>
           <a class="nav-link" href="./objects.html">Records</a>
           <a class="nav-link" href="./roles.html">Roles</a>
+          <a class="nav-link" href="./operating-guide.html">Operating Guide</a>
           <a class="nav-link" href="./glossary.html">Glossary</a>
         </nav>
       </aside>