dw-kit 1.3.6 → 1.6.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/task-frontmatter.schema.json

@@ -0,0 +1,78 @@
+{
+  "$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)",
+  "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",
+      "const": "v3.0",
+      "description": "Frontmatter schema version. Bumped only on breaking schema change."
+    },
+    "blockers": {
+      "type": "string",
+      "description": "Current blockers in free-form text; use 'none' if unblocked"
+    }
+  }
+}

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

@@ -0,0 +1,188 @@
+---
+task_id: {task-name}
+created: {YYYY-MM-DD}
+last_updated: {YYYY-MM-DD}
+status: Draft
+phase: {free-form phase description}
+owner: {name}
+depth: quick | standard | thorough
+related_adr: {ADR-NNNN | none}
+target_ship: {milestone or TBD}
+schema_version: v3.0
+blockers: none
+---
+
+# Timeline: {Task Title}
+
+<!--
+Section 1 (Snapshot) is the always-on, ≤15-line header for fast human scan and
+GitHub-rendered preview. The image reference below is auto-generated by the
+pre-commit / stop-check hook via dw-kit-render. Leave it as-is — do NOT edit
+timeline.svg by hand; it regenerates on commit.
+
+If dw-kit-render is not installed, the SVG reference renders as a broken image
+in some viewers. Run `npm install -g dw-kit-render` to enable full preview,
+or fall back to Mermaid blocks (see Section 4 example).
+-->
+
+![Timeline](./timeline.svg)
+
+<!--
+The line below is the auto-generated SVG preview. It is INJECTED by `dw task render`
+or by the pre-commit / stop-check hook the first time the task is rendered.
+Until the SVG exists, the image is suppressed by commenting it out.
+
+To enable visual preview now, run: `dw task render <task-name>`
+or commit task.md changes (hook will regenerate).
+
+After rendering, the comment markers can be removed and the image will display
+inline on GitHub PR view + IDE markdown preview.
+-->
+<!-- ![Timeline](./timeline.svg) -->
+
+## 1. Snapshot
+
+**Phase:** {current phase}
+**Status:** {Draft | Approved | In Progress | Blocked | Paused | Done}
+**Next milestone:** {date or deliverable}
+**Owner:** {name}
+**Blockers:** {none | description}
+**Last updated:** {YYYY-MM-DD}
+
+## 2. Intent & Scope
+
+<!--
+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 (Subtask Tracker). Section 2 changes only when intent or scope
+genuinely changes.
+-->
+
+### Intent
+
+{1-2 paragraphs — what and why. No background padding.}
+
+### Why Now
+
+{Forcing function: deadline, incident, dependency, opportunity.}
+
+### Subtasks (in scope)
+
+**ST-1: {Subtask name}**
+- {Concrete action}
+- Acceptance: {verifiable criterion}
+
+**ST-2: {Subtask name}**
+- ...
+
+### Out of Scope
+
+- {Explicit exclusions — prevents scope creep}
+
+### Success Criteria
+
+Measurable outcomes (not vibes):
+
+- [ ] {Numeric threshold, e.g., "p95 latency <100ms"}
+- [ ] {Binary gate, e.g., "passes smoke test"}
+
+### Dependencies
+
+- {Upstream blockers}
+- {External systems}
+
+### Risk Register (optional, recommended for thorough depth)
+
+| ID | Risk | Severity | Mitigation | Owner |
+|----|------|----------|-----------|-------|
+| R-1 | ... | HIGH/MED/LOW | ... | ... |
+
+## 3. Subtask Tracker
+
+<!--
+SINGLE SOURCE OF TRUTH for subtask status. This is the only section where
+status markers (⬜🟡✅🔴⏸) are allowed.
+-->
+
+| # | Subtask | Status | Date | Notes |
+|---|---------|--------|------|-------|
+| ST-1 | ... | ⬜ Pending | — | |
+| ST-2 | ... | ⬜ Pending | — | |
+
+Status legend: ⬜ Pending · 🟡 In Progress · ✅ Done · 🔴 Blocked · ⏸ Paused
+
+## 4. Timeline / Changelog
+
+<!--
+Reverse-chronological. Each session = one heading. Section auto-rotates to
+timeline-history.md when total > 400 lines (stop-check hook). Older entries
+remain accessible via the history file.
+
+Optional Mermaid block at top for GitHub-native timeline render (used as
+fallback if dw-kit-render is absent — graceful degradation).
+-->
+
+```mermaid
+timeline
+    title Task Lifecycle
+    {YYYY-MM-DD} : Created
+    {YYYY-MM-DD} : {next event}
+```
+
+### {YYYY-MM-DD} — {Session / commit title}
+
+**Actions taken:**
+- ...
+
+**Decisions made:**
+- ...
+
+**Pain points logged:**
+- ...
+
+**Open items for next session:**
+- [ ] ...
+
+## 5. Handoff & Friction
+
+**For next session (or next agent):**
+
+- **Read first:** {files / ADRs}
+- **Current state:** {phase, subtask}
+- **Don't do:** {anti-patterns}
+- **Watch out:** {risks, gotchas}
+
+### Friction Journal
+
+<!--
+Log friction encountered while working on this task. Feeds dw-kit improvement
+backlog. Keep entries short.
+-->
+
+| Date | Friction | Component | Proposed fix |
+|------|----------|-----------|-------------|
+| {YYYY-MM-DD} | ... | ... | ... |
+
+## 6. Annexes
+
+<!--
+Free-form supplements. Indexer ignores files here; lint warns on generic names.
+Recommended names: baseline.md, experiment-{id}.md, debate-r{N}.md,
+timeline-history.md (auto-rotated).
+-->
+
+- (none)
+
+## 7. Debate Log (optional, thorough depth only)
+
+<!--
+Adversarial review (red-bot / blue-bot) findings. Keep last round only;
+overflow into debate-r{N}.md annexes.
+-->
+
+### {YYYY-MM-DD} — {Context}
+
+**Red-bot findings:** ...
+**Blue-bot suggestions:** ...
+**Incorporated:** ...
+**Deferred:** ...

package/CLAUDE.md

@@ -3,7 +3,7 @@
 Workflow toolkit codebase. Rules live in `.claude/rules/` (auto-loaded).
 
 **v2.0 direction:** Context-First SDLC Governance Layer (5 pillars — see `.dw/core/PILLARS.md`)
-**Current:** v1.3.6 (released 2026-05-14) · ADR-0001 active · ADR-0005 + ADR-0006 Accepted (Supply-Chain Guard 3-pillar AI-Native; sunset review 2026-08-12 per pillar) · v1.4 cuts pending telemetry
+**Current:** v1.3.6 (released 2026-05-14) · ADR-0001 active · ADR-0005 + ADR-0006 Accepted (Supply-Chain Guard 3-pillar AI-Native; sunset review 2026-08-12 per pillar) · v1.4 cuts pending telemetry · **ADR-0008 Accepted (task docs v3 = 1-file `task.md` + 3-tier auto-sync sidecar)** shipped v1.5 (commit 2030dd2) · **ADR-0009 Accepted Round 2 (Agent OS multi-agent orchestration)** — execution task `agent-os-orchestration` shipping v1.6 (rc.1 candidate)
 
 ---
 
@@ -27,7 +27,7 @@ src/
 .dw/
   core/       WORKFLOW · THINKING · QUALITY · ROLES · PILLARS · templates/
   decisions/  ADRs (Records pillar)
-  tasks/      Active + archive/ (Bridges pillar — via tracking.md)
+  tasks/      Active + archive/ (Bridges pillar — via task.md v3 / tracking.md v2)
   metrics/    Local telemetry (events.jsonl)
   config/     dw.config.yml
   security/   IoC namespace fixture (Guards pillar — ADR-0005)