@bvdm/delano 0.1.5 → 0.1.8

package/assets/payload/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,29 +642,30 @@ 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**
 
+- skill: `prototype-skill`
 - discovery artifacts from `spec.md`
 - targeted prototype commands or narrow experiments
 - `pm/validate.sh` if probe findings mutate contracts
 
 **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
 
@@ -656,7 +675,7 @@ This keeps rapid learning without weakening team governance.
 
 **Entry criteria**
 
-- `spec.md` approved
+- `spec.md` active
 
 **Primary components**
 
@@ -979,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
@@ -1171,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>
@@ -1222,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>
@@ -1277,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:
@@ -1424,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.1.5",
+  "version": "0.1.8",
   "description": "CLI for the Delano delivery runtime.",
   "license": "UNLICENSED",
   "bin": {
@@ -14,6 +14,7 @@
     "bin/",
     "src/",
     "assets/",
+    ".delano/",
     "README.md",
     "HANDBOOK.md",
     "install-delano.sh"
@@ -21,6 +22,34 @@
   "scripts": {
     "build:assets": "node scripts/build-npm-assets.mjs",
     "prepack": "npm run build:assets",
-    "test": "node --test"
+    "test": "node --test",
+    "viewer": "node .delano/viewer/server.js",
+    "check:package-manifest": "node scripts/check-package-manifest-drift.mjs",
+    "check:agent-entry-docs": "node scripts/check-agent-entry-docs.mjs",
+    "check:artifact-scope": "node scripts/check-artifact-scope.mjs",
+    "check:artifact-schemas": "node scripts/check-artifact-schemas.mjs",
+    "check:operating-modes": "node scripts/check-operating-modes.mjs",
+    "check:status-transitions": "node scripts/check-status-transitions.mjs",
+    "check:evidence-map": "node scripts/check-evidence-map.mjs",
+    "check:strict-fixtures": "node scripts/check-strict-fixtures.mjs",
+    "check:sync-schemas": "node scripts/check-sync-schemas.mjs",
+    "check:local-sync-map": "node scripts/read-local-sync-map.mjs",
+    "check:github-sync": "node scripts/check-github-sync.mjs",
+    "check:github-status": "node scripts/check-github-status-inspection.mjs",
+    "check:linear-inspection": "node scripts/check-linear-issue-inspection.mjs",
+    "check:drift-report": "node scripts/build-drift-report.mjs",
+    "check:repair-plan": "node scripts/plan-sync-repairs.mjs",
+    "check:lease-contracts": "node scripts/check-lease-contracts.mjs",
+    "check:lease-manager": "node scripts/lease-manager.mjs self-test",
+    "check:lease-conflicts": "node scripts/check-lease-conflicts.mjs --zone scripts/lease-manager.mjs --mode exclusive",
+    "check:next-task": "node scripts/select-next-task.mjs --project delano-multi-agent-execution --stream default",
+    "check:worktree-health": "node scripts/check-worktree-health.mjs",
+    "check:text-safety": "node scripts/check-text-safety.mjs",
+    "check:delivery-metrics": "node scripts/check-delivery-metrics.mjs",
+    "check:handoff-summaries": "node scripts/check-handoff-summaries.mjs --self-test",
+    "check:project-metrics": "node scripts/summarize-project-metrics.mjs --json",
+    "check:context-audit": "node scripts/check-context-audit.mjs",
+    "check:skill-output-evals": "node scripts/check-skill-output-evals.mjs",
+    "check:closeout-learning": "node scripts/propose-closeout-learning.mjs --json && node scripts/check-closeout-learning-proposals.mjs"
   }
 }

package/src/cli/commands/onboarding.js

@@ -0,0 +1,29 @@
+const { ANALYSIS_APPROVAL_FLAG, runOnboarding } = require("../lib/onboarding");
+
+function getOnboardingHelp() {
+  return [
+    "Usage:",
+    "  delano onboarding [options]",
+    "",
+    "Options:",
+    "  --target <dir>                 Analyze the nearest AGENTS.md starting from this directory.",
+    `  ${ANALYSIS_APPROVAL_FLAG}   Explicitly approve AGENTS.md analysis without an interactive prompt.`,
+    "  -h, --help                    Show command help.",
+    "",
+    "Behavior:",
+    "  - Finds AGENTS.md by searching upward from the target directory.",
+    "  - Requires explicit approval before analyzing the file.",
+    "  - Uses the packaged onboarding skill rubric to print recommendations.",
+    "  - Never edits AGENTS.md; changes remain a separate explicit approval step.",
+    "",
+    "Examples:",
+    "  delano onboarding",
+    `  delano onboarding ${ANALYSIS_APPROVAL_FLAG}`,
+    "  delano onboarding --target ../repo"
+  ].join("\n");
+}
+
+module.exports = {
+  getOnboardingHelp,
+  runOnboarding
+};

package/src/cli/commands/viewer.js

@@ -0,0 +1,81 @@
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const { CliError } = require("../lib/errors");
+const { findDelanoRoot, getPackageRoot } = require("../lib/runtime");
+
+function parseViewerArgs(args) {
+  const options = {
+    target: process.cwd()
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === "--target") {
+      index += 1;
+      if (!args[index]) {
+        throw new CliError("Missing value for --target.", 1);
+      }
+      options.target = args[index];
+      continue;
+    }
+
+    if (arg.startsWith("--target=")) {
+      options.target = arg.slice("--target=".length);
+      continue;
+    }
+
+    throw new CliError(`Unknown viewer option: ${arg}`, 1);
+  }
+
+  options.target = path.resolve(options.target);
+  return options;
+}
+
+function getViewerHelp() {
+  return [
+    "Usage:",
+    "  delano viewer [options]",
+    "",
+    "Options:",
+    "  --target <dir>   Delano repository to view (default: current directory)",
+    "  -h, --help       Show help",
+    "",
+    "Environment:",
+    "  DELANO_VIEWER_PORT or PORT overrides the default port 3977."
+  ].join("\n");
+}
+
+async function runViewer(args) {
+  const options = parseViewerArgs(args);
+  const delanoRoot = findDelanoRoot(options.target);
+  if (!delanoRoot) {
+    throw new CliError(
+      `Could not find a Delano repository from ${options.target}. Run 'delano install' first or pass --target.`,
+      1
+    );
+  }
+
+  const serverPath = path.join(getPackageRoot(), ".delano", "viewer", "server.js");
+  const result = spawnSync(process.execPath, [serverPath], {
+    cwd: delanoRoot,
+    stdio: "inherit",
+    env: {
+      ...process.env,
+      DELANO_VIEWER_ROOT: delanoRoot
+    }
+  });
+
+  if (result.error) {
+    throw new CliError(`Failed to launch Delano viewer: ${result.error.message}`, 1);
+  }
+
+  return typeof result.status === "number" ? result.status : 1;
+}
+
+module.exports = {
+  getViewerHelp,
+  parseViewerArgs,
+  runViewer
+};

package/src/cli/index.js

@@ -3,7 +3,9 @@ const path = require("node:path");
 
 const { CliError } = require("./lib/errors");
 const { getPackageRoot } = require("./lib/runtime");
+const { getOnboardingHelp, runOnboarding } = require("./commands/onboarding");
 const { runInstall, getInstallHelp } = require("./commands/install");
+const { runViewer, getViewerHelp } = require("./commands/viewer");
 const { createWrapperCommand } = require("./commands/wrapper");
 
 const wrapperCommands = {
@@ -14,11 +16,21 @@ const wrapperCommands = {
 };
 
 const commands = {
+  onboarding: {
+    description: "Analyze AGENTS.md with the approval-first onboarding skill.",
+    run: runOnboarding,
+    help: getOnboardingHelp
+  },
   install: {
     description: "Install the approved Delano runtime payload into a target repository.",
     run: runInstall,
     help: getInstallHelp
   },
+  viewer: {
+    description: "Launch the read-only Delano UI for a local repository.",
+    run: runViewer,
+    help: getViewerHelp
+  },
   init: wrapperCommands.init,
   validate: wrapperCommands.validate,
   status: wrapperCommands.status,
@@ -84,7 +96,9 @@ function getGeneralHelp() {
     "  delano <command> [options]",
     "",
     "Commands:",
+    "  onboarding Analyze AGENTS.md with the approval-first onboarding skill",
     "  install    Install the approved Delano runtime payload",
+    "  viewer     Launch the read-only local UI for .project contracts",
     "  init       Run .agents/scripts/pm/init.sh in the current Delano repo",
     "  validate   Run .agents/scripts/pm/validate.sh in the current Delano repo",
     "  status     Run .agents/scripts/pm/status.sh in the current Delano repo",
@@ -95,15 +109,21 @@ function getGeneralHelp() {
     "  -v, --version   Show version",
     "",
     "Examples:",
+    "  delano onboarding",
+    "  delano onboarding --approve-agents-analysis",
     "  delano --yes",
     "  delano --target ../my-repo --yes",
     "  npx -y @bvdm/delano@latest --yes",
+    "  delano viewer",
     "  delano validate",
     "  delano next -- --all",
     "",
     "Shorthand:",
     "  delano [install-options] is equivalent to delano install [install-options].",
     "",
+    "Recommended first step after install:",
+    "  Run 'delano onboarding' to review AGENTS.md. The command requires explicit approval before analysis.",
+    "",
     "Use 'delano <command> --help' for command-specific help."
   ].join("\n");
 }

package/src/cli/lib/install.js

@@ -251,6 +251,7 @@ function applyInstallPlan(plan, options) {
 
   console.log("");
   console.log(`Installed ${plan.items.length} files into ${options.target}.`);
+  console.log("Recommended next step: run 'delano onboarding' to review AGENTS.md. The command asks for explicit approval before analysis.");
 }
 
 function normalizeManifestEntries(rawManifest) {