@bvdm/delano 0.2.3 → 0.2.5

package/.delano/viewer/server.js

@@ -12,7 +12,16 @@ const { spawn, spawnSync } = require('node:child_process');
 const repoRoot = path.resolve(process.env.DELANO_VIEWER_ROOT || path.resolve(__dirname, '..', '..'));
 const projectRoot = path.join(repoRoot, '.project');
 const publicRoot = path.join(__dirname, 'public');
-const port = Number(process.env.DELANO_VIEWER_PORT || process.env.PORT || 3977);
+const DEFAULT_PORT = 3977;
+const MAX_PORT = 65535;
+const MAX_PORT_ATTEMPTS = 100;
+const startPort = normalizePort(process.env.DELANO_VIEWER_PORT || process.env.PORT, DEFAULT_PORT);
+
+function normalizePort(value, fallback) {
+  const parsed = Number(value || fallback);
+  if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_PORT) return fallback;
+  return parsed;
+}
 
 function isInside(parent, child) {
   const rel = path.relative(parent, child);
@@ -332,6 +341,7 @@ function sendStatic(res, pathname) {
   const ext = path.extname(resolved).toLowerCase();
   const mimeMap = {
     '.js': 'text/javascript',
+    '.jsx': 'text/javascript',
     '.css': 'text/css',
     '.svg': 'image/svg+xml',
     '.png': 'image/png',
@@ -340,7 +350,7 @@ function sendStatic(res, pathname) {
     '.webp': 'image/webp',
     '.ico': 'image/x-icon',
   };
-  const isText = ext === '.js' || ext === '.css' || ext === '.svg' || ext === '' || ext === '.html';
+  const isText = ext === '.js' || ext === '.jsx' || ext === '.css' || ext === '.svg' || ext === '' || ext === '.html';
   const type = mimeMap[ext] || 'text/html';
   const headers = isText ? { 'content-type': `${type}; charset=utf-8` } : { 'content-type': type };
   res.writeHead(200, headers);
@@ -384,6 +394,37 @@ const server = http.createServer((req, res) => {
   }
 });
 
-server.listen(port, '127.0.0.1', () => {
-  console.log(`Delano read-only viewer: http://127.0.0.1:${port}`);
-});
+function listenWithPortFallback(server, firstPort, host = '127.0.0.1') {
+  let port = firstPort;
+  let attempts = 0;
+
+  const listen = () => {
+    server.once('error', onError);
+    server.listen(port, host);
+  };
+
+  const onError = (error) => {
+    if (error.code === 'EADDRINUSE' && port < MAX_PORT && attempts < MAX_PORT_ATTEMPTS) {
+      attempts += 1;
+      port += 1;
+      listen();
+      return;
+    }
+
+    console.error(`Failed to start Delano viewer on ${host}:${port}: ${error.message}`);
+    process.exitCode = 1;
+  };
+
+  const onListening = () => {
+    server.removeListener('error', onError);
+    const address = server.address();
+    const actualPort = typeof address === 'object' && address ? address.port : port;
+    const skipped = actualPort !== firstPort ? ` (${firstPort} was unavailable)` : '';
+    console.log(`Delano read-only viewer: http://${host}:${actualPort}${skipped}`);
+  };
+
+  server.on('listening', onListening);
+  listen();
+}
+
+listenWithPortFallback(server, startPort);

package/README.md

@@ -15,7 +15,7 @@ The npm package is intentionally thin. It distributes the approved runtime paylo
 ## Delano CLI
 
 - Package: `@bvdm/delano`
-- Current package version: `0.2.3`
+- Current package version: `0.2.4`
 - Binary: `delano`
 - Commands: `onboarding`, `install`, `viewer`, `init`, `validate`, `status`, `next`
 - Primary goal: bootstrap a repo safely, expose local delivery state clearly, and keep runtime gates verifiable
@@ -72,6 +72,8 @@ delano install --yes
 delano viewer
 delano validate
 delano init <slug> "<Project Name>" [owner] [lead]
+delano import-spec-kit <slug> <source-md> [--name <project-name>] [--owner <owner>] [--lead <lead>] [--json]
+delano research <project-slug> <research-slug> [--title <title>] [--question <question>] [--json]
 ```
 
 Command intent:
@@ -80,6 +82,8 @@ Command intent:
 - `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
+- `delano import-spec-kit` creates a planned Delano project from the first supported Spec Kit-style markdown fixture and then runs validation
+- `delano research` creates repo-native research intake files inside an existing Delano project and then runs validation
 
 `delano init` usage:
 
@@ -94,8 +98,36 @@ Notes:
 - `lead` defaults to `owner`
 - this is the right command for an agent to scaffold a new delivery project after `delano install`
 
+`delano import-spec-kit` usage:
+
+```bash
+delano import-spec-kit <slug> <source-md> [--name <project-name>] [--owner <owner>] [--lead <lead>] [--json]
+```
+
+Notes:
+
+- the source markdown must use the initial supported shape documented in `docs/spec-kit/import-contract.md`
+- agents should prefer named options over positional metadata, and `--json` when parsing the result
+- imported artifacts start in planned/ready states and still have to pass Delano validation, probe, and evidence gates
+- the command is additive and refuses to overwrite an existing `.project/projects/<slug>/` folder
+
+`delano research` usage:
+
+```bash
+delano research <project-slug> <research-slug> [--title <title>] [--question <question>] [--owner <owner>] [--json]
+```
+
+Notes:
+
+- use this before mutating `spec.md`, `plan.md`, workstreams, or tasks when intent is unclear
+- research files live under `.project/projects/<project-slug>/research/<research-slug>/`
+- agents should use `--json` when parsing the result
+- research findings must fold forward into canonical Delano artifacts or be explicitly closed as no-action
+
 ## How to use Delano after install
 
+For a fast guided path, start with [Delano in the First 15 Minutes](docs/first-15-minutes.md).
+
 Recommended first step:
 
 ```bash
@@ -111,6 +143,7 @@ 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 status --open --brief
 npx -y @bvdm/delano@latest next -- --all
 ```
 
@@ -121,8 +154,11 @@ delano onboarding
 delano viewer
 delano validate
 delano status
+delano status --open --brief
 delano next -- --all
 delano init <slug> "<Project Name>" [owner] [lead]
+delano import-spec-kit <slug> <source-md> --json
+delano research <project-slug> <research-slug> --title "Research title" --question "Primary question" --json
 ```
 
 The wrapper commands call the existing PM scripts under `.agents/scripts/pm/`. You can also run those scripts directly:
@@ -130,7 +166,9 @@ The wrapper commands call the existing PM scripts under `.agents/scripts/pm/`. Y
 ```bash
 bash .agents/scripts/pm/validate.sh
 bash .agents/scripts/pm/status.sh
+bash .agents/scripts/pm/status.sh --open --brief
 bash .agents/scripts/pm/next.sh --all
+bash .agents/scripts/pm/research.sh <project-slug> <research-slug> --title "Research title" --question "Primary question" --json
 ```
 
 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. It indexes `.project/context`, `.project/templates`, and `.project/projects`, then derives artifact roles, statuses, project outlines, task/workstream relationships, snippets, and rendered markdown for local inspection.
@@ -160,6 +198,28 @@ The CLI does not bundle its own shell or Python runtime.
 
 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 base install payload also includes `.codex/hooks.json`, a Codex `SessionStart` hook config that injects compact open-project context when Codex hooks are enabled. If a target repo already has `.codex/hooks.json`, `delano install` merges the Delano hook into the existing JSON instead of replacing it. Invalid or non-file hook configs are skipped without blocking the rest of the install.
+
+Codex hook activation is intentionally manual:
+
+1. Enable hooks for a session with `codex --enable hooks`, or persist the feature in `~/.codex/config.toml`:
+
+   ```toml
+   [features]
+   hooks = true
+   ```
+
+2. Start Codex in the repository and approve the project trust prompt for the repo-local `.codex/` layer. Codex records trusted projects in `~/.codex/config.toml`, for example:
+
+   ```toml
+   [projects."E:\\path\\to\\repo"]
+   trust_level = "trusted"
+   ```
+
+3. Approve the Delano `SessionStart` hook when Codex asks whether to trust it.
+
+Older docs and builds may refer to `[features].codex_hooks`; newer Codex builds warn that this key is deprecated in favor of `[features].hooks`.
+
 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`.
 
@@ -174,7 +234,7 @@ delano install --no-project-state --force --yes
 
 The interactive installer presents presets for updating the runtime while preserving project state, updating only skills and project templates, full install or repair, and custom category selection.
 
-Install categories are `agent-runtime`, `skills`, `viewer`, `project-context`, `project-templates`, `project-registry`, `project-projects`, `handbook`, and `legacy-installer`. The `--no-project-state` shortcut excludes `.project/context`, `.project/projects`, and `.project/registry`.
+Install categories are `agent-runtime`, `codex-hooks`, `skills`, `viewer`, `project-context`, `project-templates`, `project-registry`, `project-projects`, `handbook`, and `legacy-installer`. The `--no-project-state` shortcut excludes `.project/context`, `.project/projects`, and `.project/registry`.
 
 ## Optional AGENTS.md / CLAUDE.md snippet
 
@@ -254,7 +314,7 @@ Before the first Actions publish, configure npm trusted publishing for `@bvdm/de
 
 The package metadata must keep `repository.url` set to `https://github.com/MajesteitBart/delano`; npm validates that value against the GitHub Actions provenance bundle.
 
-After trusted publishing is configured, publish by pushing a matching version tag such as `v0.2.3`, or run the `Publish package to npm` workflow manually from `main`. The workflow rebuilds the package payload, checks manifest drift, runs tests, dry-runs the package contents, verifies the version is not already published, and then runs `npm publish --access public` from GitHub Actions using OIDC. A manual `dry_run` input is available to run the same checks without publishing.
+After trusted publishing is configured, publish by pushing a matching version tag such as `v0.2.4`, or run the `Publish package to npm` workflow manually from `main`. The workflow rebuilds the package payload, checks manifest drift, runs tests, dry-runs the package contents, verifies the version is not already published, and then runs `npm publish --access public` from GitHub Actions using OIDC. A manual `dry_run` input is available to run the same checks without publishing.
 
 If npm publish fails after the package checks pass, verify that the npm trusted publisher settings match the repository and workflow filename exactly, and that the workflow has `id-token: write`.
 

package/assets/install-manifest.json

@@ -4,8 +4,10 @@
     ".agents/README.md",
     ".agents/adapters/claude/README.md",
     ".agents/adapters/codex/README.md",
+    ".agents/adapters/manifest.schema.json",
     ".agents/adapters/opencode/README.md",
     ".agents/adapters/pi/README.md",
+    ".agents/adapters/spec-kit/adapter.json",
     ".agents/common/README.md",
     ".agents/common/log-safety.js",
     ".agents/eval-fixtures/skill-output/invalid/missing-evidence/output.json",
@@ -14,6 +16,7 @@
     ".agents/fixtures/linear/issue-snapshot.json",
     ".agents/hooks/README.md",
     ".agents/hooks/bash-worktree-fix.sh",
+    ".agents/hooks/codex-session-status.js",
     ".agents/hooks/post-tool-logger.js",
     ".agents/hooks/session-tracker.js",
     ".agents/hooks/user-prompt-logger.js",
@@ -87,8 +90,10 @@
     ".agents/scripts/pm/epic-list.sh",
     ".agents/scripts/pm/in-progress.sh",
     ".agents/scripts/pm/init.sh",
+    ".agents/scripts/pm/import-spec-kit.sh",
     ".agents/scripts/pm/next.sh",
     ".agents/scripts/pm/prd-list.sh",
+    ".agents/scripts/pm/research.sh",
     ".agents/scripts/pm/search.sh",
     ".agents/scripts/pm/standup.sh",
     ".agents/scripts/pm/status.sh",
@@ -155,6 +160,7 @@
     ".agents/validation-fixtures/strict/invalid/stale-context/context.md",
     ".agents/validation-fixtures/strict/manifest.json",
     ".agents/validation-fixtures/strict/valid/minimal-project/task.md",
+    ".codex/hooks.json",
     ".delano/README.md",
     ".delano/viewer/README.md",
     ".delano/viewer/server.js",
@@ -168,6 +174,7 @@
     ".project/registry/linear-map.json",
     ".project/registry/migration-map.json",
     ".project/templates/completion-summary.md",
+    ".project/templates/decisions.md",
     ".project/templates/plan.md",
     ".project/templates/progress-update.md",
     ".project/templates/spec.md",

package/assets/payload/.agents/adapters/manifest.schema.json

@@ -0,0 +1,103 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://delano.dev/schemas/adapter-manifest.schema.json",
+  "title": "Delano Adapter Manifest",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "name",
+    "type",
+    "owner",
+    "status",
+    "summary",
+    "commands",
+    "generated_files",
+    "validation",
+    "install",
+    "limits"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "type": {
+      "type": "string",
+      "enum": ["agent", "authoring-tool", "sync-tool", "workflow"]
+    },
+    "owner": {
+      "type": "string",
+      "minLength": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": ["proposed", "experimental", "stable", "deprecated"]
+    },
+    "summary": {
+      "type": "string",
+      "minLength": 1
+    },
+    "commands": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "description", "input", "output", "writes", "validation"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "input": { "type": "array", "items": { "type": "string" } },
+          "output": { "type": "array", "items": { "type": "string" } },
+          "writes": { "type": "array", "items": { "type": "string" } },
+          "validation": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    },
+    "generated_files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["path", "owner", "mode", "conflict_behavior", "fold_forward"],
+        "properties": {
+          "path": { "type": "string", "minLength": 1 },
+          "owner": { "type": "string", "minLength": 1 },
+          "mode": { "type": "string", "enum": ["create-only", "update-owned", "proposal-only", "never-overwrite"] },
+          "conflict_behavior": { "type": "string", "enum": ["abort", "diff-required", "operator-approval-required"] },
+          "fold_forward": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "validation": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["categories", "conflict_policy"],
+      "properties": {
+        "categories": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "conflict_policy": {
+          "type": "string",
+          "minLength": 1
+        }
+      }
+    },
+    "limits": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string" }
+    }
+  }
+}

package/assets/payload/.agents/adapters/spec-kit/adapter.json

@@ -0,0 +1,71 @@
+{
+  "id": "spec-kit",
+  "name": "Spec Kit Interop",
+  "type": "authoring-tool",
+  "owner": "delano-team",
+  "status": "experimental",
+  "summary": "Imports Spec Kit-style intent artifacts into Delano-governed delivery projects.",
+  "commands": [
+    {
+      "name": "delano import-spec-kit",
+      "description": "Create a planned Delano project from a supported Spec Kit-style markdown artifact.",
+      "input": ["slug", "source-md", "--name", "--owner", "--lead", "--json"],
+      "output": ["human summary", "JSON result with ok, command, project, source, validation"],
+      "writes": [".project/projects/<slug>/"],
+      "validation": ["delano validate"]
+    },
+    {
+      "name": "delano research",
+      "description": "Open repo-native research intake for unclear imported intent.",
+      "input": ["project-slug", "research-slug", "--title", "--question", "--json"],
+      "output": ["human summary", "JSON result with ok, command, project, research, files, validation"],
+      "writes": [".project/projects/<project-slug>/research/<research-slug>/"],
+      "validation": ["delano validate"]
+    }
+  ],
+  "generated_files": [
+    {
+      "path": ".project/projects/<slug>/spec.md",
+      "owner": "spec-kit adapter",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "canonical spec"
+    },
+    {
+      "path": ".project/projects/<slug>/plan.md",
+      "owner": "spec-kit adapter",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "canonical plan"
+    },
+    {
+      "path": ".project/projects/<slug>/tasks/*.md",
+      "owner": "spec-kit adapter",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "canonical tasks with evidence gates"
+    },
+    {
+      "path": ".project/projects/<project-slug>/research/<research-slug>/",
+      "owner": "research intake",
+      "mode": "create-only",
+      "conflict_behavior": "abort",
+      "fold_forward": "spec, plan, decisions, workstreams, tasks, or updates"
+    }
+  ],
+  "validation": [
+    "delano validate",
+    "npm run check:text-safety for Delano repo changes",
+    "fixture import smoke before release"
+  ],
+  "install": {
+    "categories": ["agent-runtime", "project-templates", "skills"],
+    "conflict_policy": "Use existing Delano install allowlist behavior; abort on generated project collisions unless an operator approves a diff-backed change."
+  },
+  "limits": [
+    "Does not replace Spec Kit.",
+    "Does not execute imported tasks automatically.",
+    "Does not write Linear or GitHub state directly.",
+    "Does not depend on Obsidian, OpenClaw, or private local paths."
+  ]
+}

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

@@ -7,5 +7,10 @@ Default hooks:
 - `post-tool-logger.js`
 - `user-prompt-logger.js`
 - `bash-worktree-fix.sh`
+- `codex-session-status.js`
 
-All hooks append JSONL records in `.agents/logs/`.
+The logging hooks append JSONL records in `.agents/logs/`.
+
+`codex-session-status.js` is used by the optional `.codex/hooks.json` SessionStart
+configuration. It emits `delano status --open --brief` context and fails open if
+the local runtime is not available.

package/assets/payload/.agents/hooks/codex-session-status.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+const { existsSync } = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+function findDelanoRoot(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (
+      existsSync(path.join(current, ".project", "projects")) &&
+      existsSync(path.join(current, ".agents", "scripts", "pm", "status.sh"))
+    ) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function toBashPath(filePath) {
+  return filePath.replace(/\\/g, "/");
+}
+
+function resolveBash() {
+  const candidates = [];
+
+  if (process.env.DELANO_BASH) {
+    candidates.push(process.env.DELANO_BASH);
+  }
+
+  if (process.platform === "win32") {
+    candidates.push(
+      "C:\\Program Files\\Git\\bin\\bash.exe",
+      "C:\\Program Files\\Git\\usr\\bin\\bash.exe"
+    );
+
+    const whereResult = spawnSync("where.exe", ["bash"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (whereResult.status === 0 && whereResult.stdout) {
+      candidates.push(...whereResult.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean));
+    }
+  } else {
+    const whichResult = spawnSync("which", ["bash"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (whichResult.status === 0 && whichResult.stdout.trim()) {
+      candidates.push(whichResult.stdout.trim());
+    }
+    candidates.push("/usr/bin/bash", "/bin/bash");
+  }
+
+  return candidates.find((candidate) => candidate && existsSync(candidate)) || null;
+}
+
+const root = findDelanoRoot(process.cwd());
+const bashPath = resolveBash();
+if (!root || !bashPath) {
+  process.exit(0);
+}
+
+const statusScript = toBashPath(path.join(root, ".agents", "scripts", "pm", "status.sh"));
+const result = spawnSync(bashPath, [statusScript, "--open", "--brief"], {
+  cwd: root,
+  encoding: "utf8",
+  timeout: 4500,
+  maxBuffer: 64 * 1024
+});
+
+if (result.error || result.status !== 0) {
+  process.exit(0);
+}
+
+const statusOutput = result.stdout.trim();
+if (!statusOutput) {
+  process.exit(0);
+}
+
+const additionalContext = formatStatusContext(statusOutput);
+
+console.log(JSON.stringify({
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext
+  }
+}));
+
+function formatStatusContext(rawStatusOutput) {
+  const lines = rawStatusOutput.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const projectLines = lines.filter((line) => (
+    !line.startsWith("Delano ") &&
+    !/^=+$/.test(line) &&
+    !line.startsWith("No open projects")
+  ));
+
+  if (projectLines.length === 0) {
+    return "Delano startup context. Open projects: none.";
+  }
+
+  const projects = projectLines.map(formatProjectLine);
+  return `Delano startup context. Open projects: ${projects.join("; ")}.`;
+}
+
+function formatProjectLine(line) {
+  const match = line.match(/^(\S+)\s+spec=(\S+)\s+plan=(\S+)\s+open_tasks=(\d+)\s+total_tasks=(\d+)$/);
+  if (!match) {
+    return line;
+  }
+
+  const [, slug, spec, plan, openTasks, totalTasks] = match;
+  return `${slug} (spec=${spec}, plan=${plan}, open_tasks=${openTasks}, total_tasks=${totalTasks})`;
+}
+
+module.exports = {
+  formatProjectLine,
+  formatStatusContext
+};

package/assets/payload/.agents/schemas/status-transitions.json

@@ -21,6 +21,41 @@
       "description": "A done task must not close over unresolved local dependencies.",
       "requires": ["all local depends_on task statuses are done"]
     },
+    {
+      "id": "progressed-task-requires-active-project",
+      "status": "in-progress|done",
+      "description": "A task must not start or complete while the parent project spec or plan is still planned.",
+      "requires": [
+        "spec.status is active or complete",
+        "plan.status is active or done"
+      ]
+    },
+    {
+      "id": "closed-task-set-requires-closed-project",
+      "status": "done|deferred",
+      "description": "A project with no open tasks must not remain open through stale spec or plan statuses.",
+      "requires": [
+        "spec.status is complete or deferred",
+        "plan.status is done or deferred"
+      ]
+    },
+    {
+      "id": "progressed-task-requires-active-workstream",
+      "status": "in-progress|done",
+      "description": "A task must not start or complete before its parent workstream has started.",
+      "requires": [
+        "in-progress tasks require workstream.status active",
+        "done tasks require workstream.status active or done"
+      ]
+    },
+    {
+      "id": "closed-task-set-requires-closed-workstream",
+      "status": "done|deferred",
+      "description": "A workstream with no open tasks must not remain open through a stale status.",
+      "requires": [
+        "workstream.status is done or deferred"
+      ]
+    },
     {
       "id": "blocked-owner-check-back",
       "status": "blocked",

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

@@ -11,7 +11,7 @@ Compatibility path: `.claude/scripts/...` when the mirror is present.
 Critical path:
 - `init.sh`
 - `validate.sh`
-- `status.sh`
+- `status.sh` (`--open` and `--brief` are available for compact startup context)
 - `next.sh`
 - `blocked.sh`