dw-kit 1.4.0 → 1.7.0-rc.1

package/.dw/core/schemas/agent-claim.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/agent-claim.schema.json",
+  "title": "agent-claim@v1",
+  "description": "Agent OS claim file schema (ADR-0009 Round 2). Cooperative lock declaring ownership of subtasks + write_scope.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "claim_id",
+    "task_id",
+    "agent",
+    "subtasks",
+    "write_scope",
+    "lease_expires",
+    "lease_duration_seconds",
+    "status",
+    "created_at"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "agent-claim@v1",
+      "description": "Schema version. Bump rule: minor for additive fields, major for breaking changes."
+    },
+    "claim_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*-\\d{8}T\\d{6}Z(-[a-z0-9]+)?$",
+      "description": "Format: {task-id-slug}-{subtask-ids-joined}-{YYYYMMDDTHHMMSSZ}-{random4}. Random suffix prevents same-second collision. Never reused after release/expire."
+    },
+    "task_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9.-]{0,62}[a-z0-9])?$",
+      "description": "References .dw/tasks/{task_id}/task.md"
+    },
+    "agent": {
+      "type": "object",
+      "required": ["id", "vendor", "role"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "description": "Stable identifier for this agent instance (e.g., 'codex-1', 'claude-main')"
+        },
+        "vendor": {
+          "type": "string",
+          "enum": ["claude", "codex", "gemini", "human", "other"],
+          "description": "Agent vendor for adapter routing"
+        },
+        "role": {
+          "type": "string",
+          "enum": ["worker", "reader", "orchestrator", "reviewer"],
+          "description": "worker=writes files; reader=read-only research; orchestrator=splits work; reviewer=approves merge"
+        }
+      }
+    },
+    "subtasks": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^(ST|WS)-[0-9.]+$"
+      },
+      "minItems": 1,
+      "description": "Semantic ownership: subtask IDs from task.md Section 3 tracker. Empty array rejected per R2-7."
+    },
+    "write_scope": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "description": "Filesystem ownership: glob paths agent may modify. Empty array allowed only if role=reader."
+    },
+    "read_scope": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Optional: paths agent will read but not modify. Informational; not enforced."
+    },
+    "lease_expires": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "Wall-clock ISO UTC expiry. Per R2-9 used together with lease_duration_seconds via max()."
+    },
+    "lease_duration_seconds": {
+      "type": "integer",
+      "minimum": 60,
+      "maximum": 86400,
+      "description": "Relative lease length (1 min to 24 hours). Per R2-9 fallback if wall clock skewed."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["created", "active", "released", "expired", "invalidated"],
+      "description": "Lifecycle state per R2-1. created→active→released (clean) or →expired (lease passed) or →invalidated (orchestrator override)."
+    },
+    "created_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    },
+    "activated_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "When status transitioned created→active (first edit)"
+    },
+    "released_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "When status transitioned to released/expired/invalidated"
+    },
+    "release_reason": {
+      "type": "string",
+      "description": "Optional free-text reason for release/expire/invalidate"
+    },
+    "worktree_path": {
+      "type": "string",
+      "description": "If agent operates in a git worktree per R2-3, the worktree path. .dw/cache/worktrees/{agent-id}/"
+    }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "agent": { "properties": { "role": { "const": "reader" } } } } },
+      "then": { "properties": { "write_scope": { "maxItems": 0 } } },
+      "else": { "properties": { "write_scope": { "minItems": 1 } } }
+    }
+  ]
+}

package/.dw/core/schemas/agent-report.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/agent-report.schema.json",
+  "title": "agent-report@v1",
+  "description": "Agent OS report frontmatter schema (ADR-0009 Round 2). Each agent writes a markdown report file after work; this validates the frontmatter portion. Body is free-form markdown.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "task_id",
+    "agent_id",
+    "vendor",
+    "claim_id",
+    "status",
+    "created_at"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "agent-report@v1"
+    },
+    "task_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9.-]{0,62}[a-z0-9])?$"
+    },
+    "agent_id": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64
+    },
+    "vendor": {
+      "type": "string",
+      "enum": ["claude", "codex", "gemini", "human", "other"]
+    },
+    "claim_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]*-\\d{8}T\\d{6}Z(-[a-z0-9]+)?$",
+      "description": "Must reference an existing claim (active, released, expired, or invalidated)."
+    },
+    "status": {
+      "type": "string",
+      "enum": ["completed", "partial", "blocked", "needs-review", "abandoned"],
+      "description": "Report outcome. needs-review = flagged for human attention (e.g., edited outside write_scope)."
+    },
+    "subtasks_addressed": {
+      "type": "array",
+      "items": { "type": "string", "pattern": "^(ST|WS)-[0-9.]+$" }
+    },
+    "files_changed": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Paths (relative to repo root) that this agent modified during the claim."
+    },
+    "files_outside_scope": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Files agent edited that were NOT in declared write_scope. Triggers needs-review status."
+    },
+    "open_questions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "next_actions": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "created_at": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$"
+    }
+  }
+}

package/.dw/core/schemas/goal-frontmatter.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/goal-frontmatter.schema.json",
+  "title": "goal@v1",
+  "description": "Frontmatter schema for .dw/goals/{goal-id}/goal.md (ADR-0010 Goals Management Layer, v1.7).",
+  "type": "object",
+  "required": [
+    "goal_id",
+    "schema_version",
+    "created",
+    "last_updated",
+    "status",
+    "owner",
+    "goal_version"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "goal_id": {
+      "type": "string",
+      "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$",
+      "description": "Goal identifier. Format G-{slug}; uniqueness enforced via goals-index.json (W-1)."
+    },
+    "schema_version": {
+      "type": "string",
+      "const": "goal@v1",
+      "description": "Schema version. Upgrade path via `dw goal migrate --to goal@v2` (S-1)."
+    },
+    "created": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date YYYY-MM-DD"
+    },
+    "last_updated": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date YYYY-MM-DD"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["Draft", "Active", "Achieved", "Abandoned", "Pivoted"],
+      "description": "Q3 OKR-style lifecycle. Status transitions auto-bump goal_version (Q4/C-1)."
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Person responsible for shipping this goal."
+    },
+    "target_date": {
+      "type": ["string", "null"],
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$|^TBD$",
+      "description": "ISO date YYYY-MM-DD or 'TBD' or null."
+    },
+    "goal_version": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Q4/C-1: Bumped only on manual `dw goal bump --reason` or status transition (goal_status_changed event). Field edits (KR progress, summary) emit goal_field_updated event without counter increment."
+    },
+    "archived_at": {
+      "type": ["string", "null"],
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z$",
+      "description": "C-2: Soft-delete timestamp ISO UTC. null = active. Set automatically when status transitions to Abandoned or via `dw goal delete`."
+    },
+    "parent_goal_id": {
+      "type": ["string", "null"],
+      "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$|^none$",
+      "description": "Optional parent goal (for sub-goals). 'none' or null = top-level goal."
+    },
+    "summary": {
+      "type": ["string", "null"],
+      "maxLength": 1000,
+      "description": "≤1000-char short-form (agentchattr borrow). Mirrored to goals-index.json for O(1) portfolio reads + Tier 1 agent reaction."
+    },
+    "icon": {
+      "type": ["string", "null"],
+      "maxLength": 8,
+      "description": "Optional emoji/icon for visual differentiation in portfolio cards (bigokr borrow)."
+    },
+    "cycle": {
+      "type": ["string", "null"],
+      "maxLength": 32,
+      "description": "Optional temporal grouping label e.g. 'Q1 2026', 'v1.7-cycle', '2026 H1' (bigokr borrow). Portfolio groups goals by cycle."
+    }
+  }
+}

package/.dw/core/schemas/task-frontmatter.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dv-workflow/dv-workflow/blob/main/.dw/core/schemas/task-frontmatter.schema.json",
+  "title": "task-frontmatter",
+  "description": "Frontmatter schema for .dw/tasks/{name}/task.md (v3 task format per ADR-0008; v3.1 adds optional goal linkage + summary per ADR-0010)",
+  "type": "object",
+  "required": [
+    "task_id",
+    "created",
+    "last_updated",
+    "status",
+    "owner",
+    "depth",
+    "schema_version"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "task_id": {
+      "type": "string",
+      "pattern": "^[a-z0-9](?:[a-z0-9.-]{0,62}[a-z0-9])?$",
+      "description": "Kebab-case slug (dots allowed for version-like IDs e.g. sc-guard-v1.3.5); matches parent folder name in .dw/tasks/"
+    },
+    "created": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date YYYY-MM-DD"
+    },
+    "last_updated": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ISO date YYYY-MM-DD; updated by stop-check hook on session end"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "Draft",
+        "Approved",
+        "In Progress",
+        "Blocked",
+        "Paused",
+        "Done"
+      ],
+      "description": "Lifecycle status. Single-source-of-truth for task state."
+    },
+    "phase": {
+      "type": "string",
+      "description": "Free-form current phase description (e.g., 'WS-3 lint impl')"
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Person responsible for shipping this task"
+    },
+    "depth": {
+      "type": "string",
+      "enum": ["quick", "standard", "thorough"],
+      "description": "Workflow depth routing per dw config"
+    },
+    "related_adr": {
+      "type": ["string", "null"],
+      "pattern": "^(ADR-\\d{4}|none)$",
+      "description": "ADR reference (ADR-NNNN format) or 'none' or null"
+    },
+    "target_ship": {
+      "type": ["string", "null"],
+      "description": "Free-form target ship date or milestone (e.g., 'v1.5' or 'TBD')"
+    },
+    "schema_version": {
+      "type": "string",
+      "enum": ["v3.0", "v3.1"],
+      "description": "Frontmatter schema version. v3.1 adds optional parent_goal_id, contributing_goal_ids, summary per ADR-0010."
+    },
+    "blockers": {
+      "type": "string",
+      "description": "Current blockers in free-form text; use 'none' if unblocked"
+    },
+    "parent_goal_id": {
+      "type": ["string", "null"],
+      "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$|^none$",
+      "description": "v3.1 (ADR-0010 Q1): Primary goal this task contributes to. Single goal; ownership semantics. Format G-{slug} or 'none' or null."
+    },
+    "contributing_goal_ids": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "pattern": "^G-[A-Za-z0-9](?:[A-Za-z0-9.-]{0,31}[A-Za-z0-9])?$"
+      },
+      "uniqueItems": true,
+      "description": "v3.1 (ADR-0010 Q1): Optional secondary goals task contributes to. Informational only; no ownership/portfolio-placement effect."
+    },
+    "summary": {
+      "type": ["string", "null"],
+      "maxLength": 1000,
+      "description": "v3.1 (ADR-0010 + agentchattr borrow): ≤1000-char short-form for portfolio cards + Tier 1 agent reaction. Mirrored to goals-index.json/active-index when applicable."
+    }
+  }
+}

package/.dw/core/templates/v3/goal.md

@@ -0,0 +1,146 @@
+---
+goal_id: G-{slug}
+schema_version: goal@v1
+created: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+status: Draft
+owner: {name}
+target_date: {YYYY-MM-DD or TBD}
+goal_version: 1
+archived_at: null
+parent_goal_id: none
+icon: "🎯"
+cycle: "{Q1 2026 | v1.7-cycle | 2026 H1 | null}"
+summary: "{≤1000-char short-form for portfolio cards + agent reaction; mirrored to goals-index.json}"
+---
+
+# Goal: {Title}
+
+<!--
+Goals Management Layer (ADR-0010 Accepted Round 2, 2026-05-22).
+
+This template mirrors task.md v3 structure (dual-projection per ADR-0008) so
+agents and humans navigate goal.md and task.md with the same mental model.
+
+Status lives ONLY in Section 3 (Subtask/KR Tracker) — never in Section 2.
+Status transitions auto-bump goal_version per Q4/C-1; non-status field edits
+emit goal_field_updated event without counter increment.
+
+Sidecar SVG (timeline-goal.svg) auto-rendered by `dw goal render` once
+dw-kit-render `renderGoal()` ships (R-G6 telemetry-gated, post-P1).
+-->
+
+<!-- ![Goal Timeline](./goal.svg) -->
+
+## 1. Snapshot
+
+**Status:** {Draft | Active | Achieved | Abandoned | Pivoted}
+**Owner:** {name}
+**Target date:** {YYYY-MM-DD or TBD}
+**Goal version:** {1}
+**Last updated:** {YYYY-MM-DD}
+**Linked tasks:** {auto-populated from `dw goal lint` or `dw goal portfolio`}
+
+## 2. Statement
+
+<!--
+Section 2 is the stable intent contract. Per lint convention, status markers
+(✅, 🟡, dates) MUST NOT appear in Section 2 — those live exclusively in
+Section 3 (Tracker). Section 2 changes only when intent or scope genuinely
+changes (auto-bumps goal_version via `dw goal bump --reason`).
+-->
+
+### What
+
+{1-2 paragraphs — what outcome this goal is chasing. No background padding.}
+
+### Why Now
+
+{Forcing function: deadline, market signal, dependency, strategic bet.}
+
+### Out of Scope
+
+- {Explicit exclusions — prevents goal scope creep into Jira-lite territory (R-G1)}
+
+## 3. Key Results & Linked Tasks Tracker
+
+<!--
+SINGLE SOURCE OF TRUTH for KR status. This is the only section where status
+markers (⬜🟡✅🔴⏸) are allowed. KR progress is percentage 0-100% per Q2.
+Linked tasks auto-populated from frontmatter parent_goal_id / contributing_goal_ids
+in task.md v3.1.
+-->
+
+### Key Results
+
+| # | Key Result | Target | Current | Status | Notes |
+|---|-----------|--------|---------|--------|-------|
+| KR-001 | {measurable outcome} | {100%} | {0%} | ⬜ Pending | |
+| KR-002 | ... | ... | ... | ⬜ Pending | |
+
+Status legend: ⬜ Pending · 🟡 In Progress · ✅ Achieved · 🔴 Blocked · ⏸ Paused
+
+### Linked Tasks
+
+| Task | Role | KR | Status |
+|------|------|----|--------|
+| {auto-populated by `dw goal lint`} | primary/contributing | KR-N | ... |
+
+## 4. Timeline / Changelog
+
+<!--
+Reverse-chronological. Each pivot or material change = one heading. Section
+auto-rotates per goal_version bump (manual `dw goal bump --reason` or status
+transition). Field edits emit events to events-global.jsonl WITHOUT bumping
+this section (Q4/C-1 separation).
+-->
+
+```mermaid
+timeline
+    title Goal Lifecycle
+    {YYYY-MM-DD} : Drafted (v1)
+```
+
+### {YYYY-MM-DD} — Goal drafted (version 1)
+
+**Statement:**
+{snapshot of Section 2 at creation time for diff history}
+
+**Key Results defined:**
+- KR-001: ...
+- KR-002: ...
+
+**Initial target date:** {YYYY-MM-DD or TBD}
+
+## 5. Handoff & Annotations
+
+<!--
+Cross-session context for agents picking up work on this goal. Annotations
+(canvas-style sticky notes) live in peer file goal-annotations.md per Q6
+(ADR-0010 P6 scope).
+-->
+
+**For next session (or next agent):**
+
+- **Read first:** {related ADRs, parent goal if any, linked task.md files}
+- **Current state:** {phase, blocked-on, last decision}
+- **Don't do:** {anti-patterns specific to this goal}
+- **Watch out:** {strategic risks, dependencies, stakeholder commitments}
+
+### Friction Journal
+
+| Date | Friction | Component | Proposed fix |
+|------|----------|-----------|-------------|
+| {YYYY-MM-DD} | ... | ... | ... |
+
+## 6. Annexes
+
+<!--
+Free-form supplements. Recommended names:
+- baseline.md — initial metrics
+- pivot-r{N}.md — pivot rationale
+- goal-annotations.md — canvas annotations (P6+)
+- timeline-history.md — auto-rotated overflow
+-->
+
+- (none)