@bvdm/delano 0.1.7 → 0.2.0

package/HANDBOOK.md

@@ -2,8 +2,8 @@
 
 ## First Edition, v3
 
-Version: 3.1  
-Last updated: 2026-04-03
+Version: 3.2
+Last updated: 2026-05-04
 
 ---
 
@@ -56,7 +56,7 @@ Its core objective is:
 
 ### 1.1 Primary flow
 
-**Outcome -> Draft Spec -> Probe Decision -> Approved Spec -> Delivery Project -> Workstreams -> Tasks -> Linear Issues -> PRs -> Release -> Learnings**
+**Outcome -> Planned Spec -> Probe Decision -> Active Spec -> Delivery Project -> Workstreams -> Tasks -> Linear Issues -> PRs -> Release -> Learnings**
 
 ### 1.2 Design principles
 
@@ -201,7 +201,7 @@ Recommended naming:
 
 Operational rule:
 
-- Every task issue must carry one workstream identifier.
+- Every task issue must carry one workstream identifier in task frontmatter (`workstream: WS-A`) and the corresponding Linear workstream label (`ws-a`).
 
 #### 4.2.5 Task -> Issue
 
@@ -296,7 +296,7 @@ A coding agent is Delano-compatible if it can:
 name: <project-name>
 slug: <kebab-case>
 owner: <person-or-team>
-status: draft|approved|active|complete|canceled
+status: planned|active|complete|deferred
 created: <ISO8601 UTC>
 updated: <ISO8601 UTC>
 outcome: <measurable target>
@@ -325,13 +325,13 @@ Required sections:
 
 ```yaml
 name: <project-name>
-status: planned|in-progress|done|canceled
+status: planned|active|done|deferred
 lead: <person>
 created: <ISO8601 UTC>
 updated: <ISO8601 UTC>
 linear_project_id: <id>
 risk_level: low|medium|high
-spec_status_at_plan_time: approved|active
+spec_status_at_plan_time: planned|active|complete|deferred
 ```
 
 Required sections:
@@ -351,7 +351,8 @@ Required sections:
 ```yaml
 id: T-001
 name: <task-title>
-status: backlog|ready|in-progress|review|done|blocked|canceled
+status: ready|in-progress|blocked|done|deferred
+workstream: WS-A
 created: <ISO8601 UTC>
 updated: <ISO8601 UTC>
 linear_issue_id: <id-or-empty>
@@ -360,8 +361,8 @@ github_pr: <url-or-empty>
 depends_on: []
 conflicts_with: []
 parallel: true|false
-priority: low|medium|high|urgent
-estimate: XS|S|M|L|XL
+priority: low|medium|high
+estimate: S|M|L|XL
 ```
 
 Required sections:
@@ -376,7 +377,7 @@ Required sections:
 
 - `created` immutable
 - `updated` real UTC system timestamp
-- probe decision explicit before spec approval
+- probe decision explicit before spec activation
 - dependency graph acyclic before execution
 - no absolute path leakage in shared output
 
@@ -384,66 +385,71 @@ Required sections:
 
 ## 7) Status models and transition policy
 
-### 7.1 Why expanded task states exist
+### 7.1 Why compact runtime states exist
 
-Expanded states solve execution ambiguity:
+The v0.2 runtime uses compact status sets that are enforced by schemas and validation:
 
-- `backlog` vs `ready` separates unsized ideas from executable work
-- `review` enforces handoff before closure
-- `blocked` exposes dependency constraints explicitly
+- `planned` means a spec, plan, or workstream is defined but not actively being executed.
+- `ready` means a task is executable and should not carry unresolved local dependencies.
+- `in-progress` means implementation has started.
+- `blocked` exposes dependency constraints explicitly.
+- `done` and `complete` are terminal success states for delivery plans/tasks and specs respectively.
+- `deferred` is the terminal non-completion state for postponed or canceled work.
+
+Idea triage belongs outside executable task files. Review is a gate recorded in evidence, updates, quality notes, or PR state; it is not a canonical v0.2 task status.
 
 ### 7.2 Lifecycle definitions
 
 #### Spec
 
-`draft -> approved -> active -> complete`  
-optional terminal: `canceled`
+`planned -> active -> complete`  
+optional terminal: `deferred`
 
-Probe decision rule while spec is `draft`:
+Probe decision rule while spec is `planned`:
 
-- `probe_required: false` allows approval once other discovery gates pass
-- `probe_required: true` requires a Prototype Probe and recorded findings before approval
+- `probe_required: false` allows activation once other discovery gates pass.
+- `probe_required: true` requires a Prototype Probe and recorded findings before activation.
 
 #### Delivery Project
 
-`planned -> in-progress -> done`  
-optional terminal: `canceled`
+`planned -> active -> done`  
+optional terminal: `deferred`
 
 #### Task
 
-`backlog -> ready -> in-progress -> review -> done`  
-optional branches: `blocked`, `canceled`
+`ready -> in-progress -> done`  
+optional branches: `blocked`, `deferred`
 
 ### 7.3 Transition policy
 
-- No `in-progress` with unmet hard dependencies.
+- No `ready`, `in-progress`, or `done` transition with unmet local dependencies.
 - No `done` without evidence completion.
 - No project `done` with unresolved required tasks.
-- No spec `approved` without explicit probe decision fields.
-- No spec `approved` with unresolved required probe findings.
+- No spec `active` without explicit probe decision fields.
+- No spec `active` with unresolved required probe findings.
 - No spec `complete` without outcome review.
 
+Current artifact scans and proposed transitions are strict for local task dependencies: `ready`, `in-progress`, and `done` tasks fail validation when they depend on unresolved local tasks.
+
 ### 7.4 Review semantics
 
-`review` may include one or more:
+Review is a quality gate before closure. It may include one or more:
 
 - code review
 - quality gate verification
 - product acceptance for user-visible changes
 
-Teams must define exact review semantics in local policy.
+Teams must define exact review semantics in local policy and record the result in evidence, updates, or PR state.
 
 ### 7.5 Explicit Delano -> Linear status mapping
 
 | Delano task status | Preferred Linear state |
 |---|---|
-| backlog | Triage or Backlog |
 | ready | Todo |
 | in-progress | In Progress |
-| review | In Review |
 | done | Done |
 | blocked | Blocked (if exists) or Todo + blocked relation/label |
-| canceled | Canceled |
+| deferred | Canceled, Icebox, or Backlog depending on team policy |
 
 If team workflow names differ, maintain this semantic mapping in sync rules.
 
@@ -458,6 +464,17 @@ If team workflow names differ, maintain this semantic mapping in sync rules.
 - **Rules**: constraints and policy
 - **Hooks**: runtime tracking and guardrails
 
+### 8.8 v0.2 runtime foundation
+
+v0.2 adds enforceable local runtime surfaces around the handbook process:
+
+- **Operating modes**: Mode 0 patch, Mode 1 scoped change, Mode 2 feature, Mode 3 uncertain feature, and Mode 4 multi-stream. Modes are additive hints for task depth and required proof, not a reason to skip safety gates.
+- **Contract validation**: schemas and validators cover artifact scope, schema shape, operating modes, status transitions, evidence maps, strict fixtures, sync scaffolding, leases, metrics, text safety, context audit, and skill-output evals.
+- **Evidence expectations**: done tasks need checked acceptance criteria plus implementation or validation evidence. v0.2 evidence mapping remains markdown-based; full criterion-to-ledger instance validation is a later maturity gate.
+- **Dry-run sync**: GitHub and Linear sync surfaces inspect, classify drift, and produce repair plans without remote mutation unless a future explicit apply gate is approved.
+- **Lease semantics**: multi-agent work uses leases with conflict zones, lifecycle state, and handoff summaries. Conflict checks must run before overlapping work proceeds.
+- **Release gates**: `npm run build:assets`, package-manifest drift checks, PM validation, and `npm test` are the local release baseline. Formal CI publishing, enterprise state-machine orchestration, and non-mocked Linear behavior remain later maturity gates.
+
 ### 8.2 Skill contract standard
 
 Each skill must define:
@@ -476,7 +493,7 @@ Each skill must define:
 
 ```yaml
 name: breakdown-skill
-intent: decompose approved plan into atomic tasks
+intent: decompose active plan into atomic tasks
 inputs:
   - spec_path
   - plan_path
@@ -549,6 +566,7 @@ script_hooks:
 | `query-log.sh` | query change stream |
 | `test-and-log.sh` | capture test execution logs |
 | `check-path-standards.sh` | path/privacy enforcement |
+| `check-text-safety.mjs` | hidden/bidirectional Unicode control enforcement |
 | `fix-path-standards.sh` | path normalization |
 | `git-sparse-download.sh` | sparse external resource retrieval |
 
@@ -598,7 +616,7 @@ This keeps rapid learning without weakening team governance.
 
 **Goal**
 
-- define a measurable outcome, draft the Spec, and make the probe decision explicit
+- define a measurable outcome, create the planned Spec, and make the probe decision explicit
 
 **Entry criteria**
 
@@ -611,7 +629,7 @@ This keeps rapid learning without weakening team governance.
 
 **Exit artifacts**
 
-- drafted `spec.md` with uncertainty and probe decision recorded
+- planned `spec.md` with uncertainty and probe decision recorded
 
 **Gate**
 
@@ -624,11 +642,11 @@ This keeps rapid learning without weakening team governance.
 
 **Goal**
 
-- retire or bound material uncertainty before spec approval
+- retire or bound material uncertainty before spec activation
 
 **Entry criteria**
 
-- `spec.md` is still `draft`
+- `spec.md` is still `planned`
 - `probe_required: true`
 
 **Primary components**
@@ -640,14 +658,14 @@ This keeps rapid learning without weakening team governance.
 
 **Exit artifacts**
 
-- updated draft `spec.md`
-- probe findings and approval recommendation
+- updated planned `spec.md`
+- probe findings and activation recommendation
 
 **Gate**
 
 - probe findings recorded
 - touched surfaces and footguns explicit
-- approval recommendation clear
+- activation recommendation clear
 
 ### Stage C: Planning
 
@@ -657,7 +675,7 @@ This keeps rapid learning without weakening team governance.
 
 **Entry criteria**
 
-- `spec.md` approved
+- `spec.md` active
 
 **Primary components**
 
@@ -980,6 +998,7 @@ Every update should answer:
 - immutable creation timestamps
 - UTC timestamp policy
 - path privacy enforcement
+- hidden/bidirectional Unicode control enforcement
 - GitHub remote safety checks
 
 ### 14.2 Default team policy pack
@@ -1172,7 +1191,7 @@ This section is designed for live planning and execution meetings.
 name: <project-name>
 slug: <kebab-case>
 owner: <person-or-team>
-status: draft
+status: planned
 created: <ISO8601 UTC>
 updated: <ISO8601 UTC>
 outcome: <measurable target>
@@ -1223,7 +1242,7 @@ created: <ISO8601 UTC>
 updated: <ISO8601 UTC>
 linear_project_id:
 risk_level: <low|medium|high>
-spec_status_at_plan_time: <approved|active>
+spec_status_at_plan_time: <planned|active|complete|deferred>
 ---
 
 # Delivery Plan: <project-name>
@@ -1278,6 +1297,7 @@ updated: <ISO8601 UTC>
 id: T-001
 name: <task-title>
 status: ready
+workstream: WS-A
 created: <ISO8601 UTC>
 updated: <ISO8601 UTC>
 linear_issue_id:
@@ -1425,7 +1445,7 @@ For each active epic scope:
 
 #### Step 4: map statuses
 
-- `open` -> `backlog` or `ready` depending on readiness
+- `open` -> `ready` when executable, or `deferred` when not actionable in the current delivery scope
 - `in-progress` -> `in-progress`
 - `closed` -> `done`
 

package/README.md

@@ -10,13 +10,13 @@ Delano is an agent-agnostic delivery runtime. It keeps planning, execution, and
 - `.claude/` is a compatibility mirror of `.agents/`, not a second runtime.
 - `.delano/` is an optional UI layer.
 
-The npm package is intentionally thin. It distributes the approved runtime payload and wraps the existing shell-based PM scripts. It does not replace the handbook, the file contracts, or the underlying bash/Python execution layer.
+The npm package is intentionally thin. It distributes the approved runtime payload, includes the read-only viewer UI, and wraps the existing shell-based PM scripts. It does not replace the handbook, the file contracts, or the underlying bash/Python execution layer.
 
 ## Delano CLI
 
 - Package: `@bvdm/delano`
 - Binary: `delano`
-- Commands: `onboarding`, `install`, `init`, `validate`, `status`, `next`
+- Commands: `onboarding`, `install`, `viewer`, `init`, `validate`, `status`, `next`
 - Primary v1.1 goal: bootstrap a repo safely, then stay out of the way
 
 ## One-command bootstrap
@@ -59,6 +59,7 @@ Typical flow in a repository:
 ```bash
 cd /path/to/repo
 delano install --yes
+delano viewer
 delano validate
 delano init <slug> "<Project Name>" [owner] [lead]
 ```
@@ -66,6 +67,7 @@ delano init <slug> "<Project Name>" [owner] [lead]
 Command intent:
 
 - `delano install` bootstraps the Delano runtime into the current repository
+- `delano viewer` launches the read-only local UI for `.project` contracts
 - `delano validate` checks whether the runtime and required assets are in place
 - `delano init` creates a delivery project inside a repository that already has Delano installed
 
@@ -96,6 +98,7 @@ If you bootstrap with one-shot `npx`, keep using `npx` for wrapper commands:
 
 ```bash
 npx -y @bvdm/delano@latest onboarding --approve-agents-analysis
+npx -y @bvdm/delano@latest viewer
 npx -y @bvdm/delano@latest validate
 npx -y @bvdm/delano@latest status
 npx -y @bvdm/delano@latest next -- --all
@@ -105,6 +108,7 @@ If the package is installed locally or globally, run these inside the target rep
 
 ```bash
 delano onboarding
+delano viewer
 delano validate
 delano status
 delano next -- --all
@@ -119,6 +123,8 @@ bash .agents/scripts/pm/status.sh
 bash .agents/scripts/pm/next.sh --all
 ```
 
+The viewer is packaged with `@bvdm/delano` and serves the selected repository's `.project` files read-only. It defaults to `http://127.0.0.1:3977`; set `DELANO_VIEWER_PORT` or `PORT` to use another port.
+
 ## Required dependencies
 
 Delano v1.1 assumes these tools are available:
@@ -142,6 +148,7 @@ The CLI does not bundle its own shell or Python runtime.
 - it does not install or overwrite repo-root Git config files such as `.gitignore` or `.gitattributes`
 
 The base install payload intentionally excludes top-level adapter entry docs such as `AGENTS.md`, `CLAUDE.md`, `CODEX.md`, `OPENCODE.md`, and `PI.md`. Those remain opt-in only.
+The base install payload includes `.delano/`, including the read-only viewer UI.
 The installable `.project/context/` pack is seeded from generic templates during packaging; it does not ship Delano's own repo-specific context files into consumer repositories.
 After install, the recommended first step is `delano onboarding`, which requires explicit approval before it reviews `AGENTS.md`.
 
@@ -164,6 +171,7 @@ When working in this repository:
 - use the Delano status model and evidence discipline from `HANDBOOK.md`
 - keep sync and quality gates aligned with the handbook
 - use `delano init <slug> "<Project Name>" [owner] [lead]` to scaffold a new delivery project when needed
+- use `delano viewer` to inspect `.project/` through the read-only local UI
 ```
 
 ## v1.1 boundaries

package/assets/install-manifest.json

@@ -1,32 +1,88 @@
 {
   "version": 2,
   "files": [
+    ".agents/README.md",
     ".agents/adapters/claude/README.md",
     ".agents/adapters/codex/README.md",
     ".agents/adapters/opencode/README.md",
     ".agents/adapters/pi/README.md",
     ".agents/common/README.md",
+    ".agents/common/log-safety.js",
+    ".agents/eval-fixtures/skill-output/invalid/missing-evidence/output.json",
+    ".agents/eval-fixtures/skill-output/valid/summary/output.json",
+    ".agents/fixtures/github/status-snapshot.json",
+    ".agents/fixtures/linear/issue-snapshot.json",
+    ".agents/hooks/README.md",
     ".agents/hooks/bash-worktree-fix.sh",
     ".agents/hooks/post-tool-logger.js",
-    ".agents/hooks/README.md",
     ".agents/hooks/session-tracker.js",
     ".agents/hooks/user-prompt-logger.js",
     ".agents/logs/.gitkeep",
+    ".agents/logs/delivery-metrics.md",
     ".agents/logs/schema.md",
-    ".agents/README.md",
+    ".agents/rules/README.md",
     ".agents/rules/agent-coordination.md",
     ".agents/rules/datetime.md",
+    ".agents/rules/delivery-modes.md",
     ".agents/rules/frontmatter-operations.md",
     ".agents/rules/github-operations.md",
     ".agents/rules/path-standards.md",
-    ".agents/rules/README.md",
     ".agents/rules/test-execution.md",
     ".agents/rules/worktree-operations.md",
+    ".agents/schemas/README.md",
+    ".agents/schemas/artifact-scope.json",
+    ".agents/schemas/artifacts/context.schema.json",
+    ".agents/schemas/artifacts/decision_log.schema.json",
+    ".agents/schemas/artifacts/evidence.schema.json",
+    ".agents/schemas/artifacts/plan.schema.json",
+    ".agents/schemas/artifacts/spec.schema.json",
+    ".agents/schemas/artifacts/task.schema.json",
+    ".agents/schemas/artifacts/update.schema.json",
+    ".agents/schemas/artifacts/workstream.schema.json",
+    ".agents/schemas/evidence-map.json",
+    ".agents/schemas/learning/closeout-learning-proposal.schema.json",
+    ".agents/schemas/learning/delivery-metric-event.schema.json",
+    ".agents/schemas/leases/lease.schema.json",
+    ".agents/schemas/metrics/delivery-event.schema.json",
+    ".agents/schemas/metrics/delivery-events.schema.json",
+    ".agents/schemas/operating-modes.json",
+    ".agents/schemas/status-transitions.json",
+    ".agents/schemas/sync/drift-report.schema.json",
+    ".agents/schemas/sync/drift-taxonomy.json",
+    ".agents/schemas/sync/sync-map.schema.json",
+    ".agents/scripts/README.md",
+    ".agents/scripts/audit-context-files.mjs",
+    ".agents/scripts/audit-context-scoring.mjs",
+    ".agents/scripts/build-drift-report.mjs",
+    ".agents/scripts/check-artifact-schemas.mjs",
+    ".agents/scripts/check-closeout-learning-proposals.mjs",
+    ".agents/scripts/check-context-audit.mjs",
+    ".agents/scripts/check-delivery-metric-events.mjs",
+    ".agents/scripts/check-delivery-metrics.mjs",
+    ".agents/scripts/check-evidence-map.mjs",
+    ".agents/scripts/check-github-status-inspection.mjs",
+    ".agents/scripts/check-github-sync.mjs",
+    ".agents/scripts/check-handoff-summaries.mjs",
+    ".agents/scripts/check-lease-conflicts.mjs",
+    ".agents/scripts/check-lease-contracts.mjs",
+    ".agents/scripts/check-linear-issue-inspection.mjs",
+    ".agents/scripts/check-local-sync-map.mjs",
+    ".agents/scripts/check-log-safety.sh",
+    ".agents/scripts/check-operating-modes.mjs",
     ".agents/scripts/check-path-standards.sh",
+    ".agents/scripts/check-skill-output-evals.mjs",
+    ".agents/scripts/check-status-transitions.mjs",
+    ".agents/scripts/check-strict-fixtures.mjs",
+    ".agents/scripts/check-sync-schemas.mjs",
+    ".agents/scripts/check-text-safety.mjs",
+    ".agents/scripts/check-worktree-health.mjs",
     ".agents/scripts/fix-path-standards.sh",
     ".agents/scripts/git-sparse-download.sh",
+    ".agents/scripts/inspect-github-sync.mjs",
+    ".agents/scripts/lease-manager.mjs",
     ".agents/scripts/log-event.js",
     ".agents/scripts/log-event.sh",
+    ".agents/scripts/plan-sync-repairs.mjs",
     ".agents/scripts/pm/blocked.sh",
     ".agents/scripts/pm/epic-list.sh",
     ".agents/scripts/pm/in-progress.sh",
@@ -37,56 +93,87 @@
     ".agents/scripts/pm/standup.sh",
     ".agents/scripts/pm/status.sh",
     ".agents/scripts/pm/validate.sh",
+    ".agents/scripts/propose-closeout-learning.mjs",
     ".agents/scripts/query-log.sh",
-    ".agents/scripts/README.md",
+    ".agents/scripts/read-local-sync-map.mjs",
+    ".agents/scripts/select-next-task.mjs",
+    ".agents/scripts/summarize-project-metrics.mjs",
     ".agents/scripts/test-and-log.sh",
     ".agents/skills/.gitkeep",
-    ".agents/skills/breakdown-skill/references/runbook.md",
+    ".agents/skills/README.md",
     ".agents/skills/breakdown-skill/SKILL.md",
+    ".agents/skills/breakdown-skill/references/runbook.md",
     ".agents/skills/breakdown-skill/templates/ambiguity-report.md",
     ".agents/skills/breakdown-skill/templates/task-batch-summary.md",
-    ".agents/skills/closeout-skill/references/runbook.md",
     ".agents/skills/closeout-skill/SKILL.md",
+    ".agents/skills/closeout-skill/references/runbook.md",
     ".agents/skills/closeout-skill/templates/closure-checklist.md",
+    ".agents/skills/closeout-skill/templates/learning-proposal.md",
+    ".agents/skills/closeout-skill/templates/learning-proposals.md",
     ".agents/skills/closeout-skill/templates/outcome-review.md",
-    ".agents/skills/manage-context/references/context-audit-checklist.md",
-    ".agents/skills/manage-context/references/runbook.md",
-    ".agents/skills/manage-context/SKILL.md",
-    ".agents/skills/manage-context/templates/context-debt-report.md",
-    ".agents/skills/manage-context/templates/context-refresh-summary.md",
-    ".agents/skills/onboarding/references/agents-md-best-practices.md",
-    ".agents/skills/onboarding/SKILL.md",
-    ".agents/skills/discovery-skill/references/runbook.md",
     ".agents/skills/discovery-skill/SKILL.md",
+    ".agents/skills/discovery-skill/references/runbook.md",
     ".agents/skills/discovery-skill/templates/clarification-questions.md",
     ".agents/skills/discovery-skill/templates/discovery-summary.md",
-    ".agents/skills/prototype-skill/references/probe-design-checklist.md",
-    ".agents/skills/prototype-skill/references/runbook.md",
-    ".agents/skills/prototype-skill/SKILL.md",
-    ".agents/skills/prototype-skill/templates/probe-approval-recommendation.md",
-    ".agents/skills/prototype-skill/templates/probe-findings.md",
-    ".agents/skills/execution-skill/references/runbook.md",
     ".agents/skills/execution-skill/SKILL.md",
+    ".agents/skills/execution-skill/references/runbook.md",
     ".agents/skills/execution-skill/templates/blocker-update.md",
     ".agents/skills/execution-skill/templates/stream-update.md",
-    ".agents/skills/learning-skill/references/runbook.md",
     ".agents/skills/learning-skill/SKILL.md",
+    ".agents/skills/learning-skill/references/runbook.md",
     ".agents/skills/learning-skill/templates/improvement-backlog.md",
     ".agents/skills/learning-skill/templates/retrospective.md",
-    ".agents/skills/planning-skill/references/runbook.md",
+    ".agents/skills/manage-context/SKILL.md",
+    ".agents/skills/manage-context/references/context-audit-checklist.md",
+    ".agents/skills/manage-context/references/runbook.md",
+    ".agents/skills/manage-context/templates/context-debt-report.md",
+    ".agents/skills/manage-context/templates/context-refresh-summary.md",
+    ".agents/skills/onboarding/SKILL.md",
+    ".agents/skills/onboarding/references/agents-md-best-practices.md",
     ".agents/skills/planning-skill/SKILL.md",
+    ".agents/skills/planning-skill/references/runbook.md",
     ".agents/skills/planning-skill/templates/architecture-decision.md",
     ".agents/skills/planning-skill/templates/workstream-definition.md",
-    ".agents/skills/quality-skill/references/runbook.md",
+    ".agents/skills/prototype-skill/SKILL.md",
+    ".agents/skills/prototype-skill/references/probe-design-checklist.md",
+    ".agents/skills/prototype-skill/references/runbook.md",
+    ".agents/skills/prototype-skill/templates/probe-approval-recommendation.md",
+    ".agents/skills/prototype-skill/templates/probe-findings.md",
     ".agents/skills/quality-skill/SKILL.md",
+    ".agents/skills/quality-skill/references/runbook.md",
     ".agents/skills/quality-skill/templates/gate-decision.md",
     ".agents/skills/quality-skill/templates/quality-evidence.md",
-    ".agents/skills/README.md",
-    ".agents/skills/sync-skill/references/runbook.md",
     ".agents/skills/sync-skill/SKILL.md",
+    ".agents/skills/sync-skill/references/runbook.md",
     ".agents/skills/sync-skill/templates/conflict-resolution-actions.md",
     ".agents/skills/sync-skill/templates/drift-report.md",
+    ".agents/validation-fixtures/strict/invalid/broken-dependencies/dependency.md",
+    ".agents/validation-fixtures/strict/invalid/broken-dependencies/task.md",
+    ".agents/validation-fixtures/strict/invalid/invalid-transition/task.md",
+    ".agents/validation-fixtures/strict/invalid/missing-evidence/task.md",
+    ".agents/validation-fixtures/strict/invalid/path-leak/task.md",
+    ".agents/validation-fixtures/strict/invalid/stale-context/context.md",
+    ".agents/validation-fixtures/strict/manifest.json",
+    ".agents/validation-fixtures/strict/valid/minimal-project/task.md",
     ".delano/README.md",
+    ".delano/viewer/README.md",
+    ".delano/viewer/server.js",
+    ".delano/viewer/public/app.js",
+    ".delano/viewer/public/explorer.svg",
+    ".delano/viewer/public/index.html",
+    ".delano/viewer/public/markdown.svg",
+    ".delano/viewer/public/vscode.svg",
+    ".delano/viewer/public/styles.css",
+    ".project/projects/.gitkeep",
+    ".project/registry/linear-map.json",
+    ".project/registry/migration-map.json",
+    ".project/templates/completion-summary.md",
+    ".project/templates/plan.md",
+    ".project/templates/progress-update.md",
+    ".project/templates/spec.md",
+    ".project/templates/task.md",
+    ".project/templates/workstream.md",
+    "HANDBOOK.md",
     {
       "source": "assets/templates/context/gui-testing.md",
       "target": ".project/context/gui-testing.md"
@@ -127,16 +214,6 @@
       "source": "assets/templates/context/tech-context.md",
       "target": ".project/context/tech-context.md"
     },
-    ".project/projects/.gitkeep",
-    ".project/registry/linear-map.json",
-    ".project/registry/migration-map.json",
-    ".project/templates/completion-summary.md",
-    ".project/templates/plan.md",
-    ".project/templates/progress-update.md",
-    ".project/templates/spec.md",
-    ".project/templates/task.md",
-    ".project/templates/workstream.md",
-    "HANDBOOK.md",
     "install-delano.sh"
   ]
 }

package/assets/payload/.agents/README.md

@@ -2,11 +2,36 @@
 
 Canonical shared runtime for Delano.
 
-- `scripts/`, `rules/`, `hooks/`, `skills/`, `logs/` -> shared Delano runtime assets
-- `adapters/claude/` -> Claude adapter notes
-- `adapters/codex/` -> Codex adapter notes
-- `adapters/opencode/` -> OpenCode adapter notes
-- `adapters/pi/` -> Pi adapter notes
-- `common/` -> shared adapter docs/policies
+## Source-of-truth map
+
+- Root agent workflow and boundaries: `AGENTS.md`
+- Process and operator handbook: `HANDBOOK.md`
+- Delivery contracts and evidence: `.project/`
+- Runtime scripts: `.agents/scripts/`
+- Shared rules: `.agents/rules/`
+- Hooks: `.agents/hooks/`
+- Skills: `.agents/skills/`
+- Logs: `.agents/logs/`
+- Shared adapter utilities: `.agents/common/`
+- Agent-specific adapter notes: `.agents/adapters/<agent>/`
 
 The compatibility path `.claude/` may mirror this runtime for agents that still expect Claude-style paths.
+
+## Required first-turn behavior
+
+Every adapter should start from `AGENTS.md`, inspect the relevant `.project` contract and current git state, then use the adapter note only for runtime-specific differences.
+
+## Core validation commands
+
+- `bash .agents/scripts/pm/validate.sh`
+- `npm test`
+- `npm run build:assets`
+- `npm run check:package-manifest`
+
+## Completion rule
+
+Do not report a task as done until the change is present, evidence is recorded, validation has passed or been explicitly marked not run, and blockers are named.
+
+## Safety boundaries
+
+Keep logs privacy-safe, avoid absolute path leaks in docs/contracts/hook output, and do not perform destructive git or remote-write operations without an explicit task instruction.

package/assets/payload/.agents/adapters/claude/README.md

@@ -1,5 +1,24 @@
 # Claude adapter
 
-- Start from `AGENTS.md`
-- Shared runtime is in `.agents/` (available at `.claude/` via symlink)
-- Keep Claude-specific behavior in `CLAUDE.md` and this adapter folder
+## Start here
+
+1. Read root `AGENTS.md` first.
+2. Use this note only for Claude-specific path behavior.
+3. Inspect `git status --short --branch` and the assigned `.project` contract before editing.
+
+## Runtime paths
+
+- Canonical runtime: `.agents/`
+- Claude compatibility path: `.claude/` mirrors `.agents/` where available
+- Delivery contracts: `.project/`
+
+## Commands
+
+- `bash .agents/scripts/pm/validate.sh`
+- `npm test`
+- `npm run build:assets`
+- `npm run check:package-manifest`
+
+## Completion and safety
+
+Record evidence in the task or update log before marking work done. Do not rely on `.claude/` as a separate source of truth, do not commit unsafe logs, and do not leak local absolute paths in output.