@bvdm/delano 0.2.5 → 0.2.7

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.4`
+- Current package version: `0.2.7`
 - 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

package/assets/install-manifest.json

@@ -120,6 +120,10 @@
     ".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/research-skill/SKILL.md",
+    ".agents/skills/research-skill/references/runbook.md",
+    ".agents/skills/research-skill/templates/fold-forward-checklist.md",
+    ".agents/skills/research-skill/templates/research-summary.md",
     ".agents/skills/execution-skill/SKILL.md",
     ".agents/skills/execution-skill/references/runbook.md",
     ".agents/skills/execution-skill/templates/blocker-update.md",

package/assets/payload/.agents/scripts/pm/validate.sh

@@ -147,6 +147,7 @@ fi
 # Required skill contracts
 required_skills=(
   discovery-skill
+  research-skill
   prototype-skill
   planning-skill
   breakdown-skill

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

@@ -5,6 +5,7 @@ Handbook-aligned skill contracts.
 Core workflow skills:
 
 - `discovery-skill`
+- `research-skill`
 - `prototype-skill`
 - `planning-skill`
 - `breakdown-skill`

package/assets/payload/.agents/skills/research-skill/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: research-skill
+description: Open and run repo-native research intake before mutating canonical delivery artifacts. Use when a Delano request has unclear intent, unresolved options, external evidence needs, or material uncertainty that should be investigated before changing spec, plan, workstreams, or tasks.
+---
+
+# research-skill
+
+## Trigger context
+- delivery intent is unclear enough that direct changes to `spec.md`, `plan.md`, workstreams, or tasks would be speculative
+- options, constraints, risks, or external evidence need investigation before planning or execution
+- imported or user-provided material needs synthesis into Delano's canonical project artifacts
+- a previous `planning_with_files` style briefing would have been useful, but the work must stay inside the Delano repo
+
+## Non-triggers
+- obvious implementation tasks with accepted scope
+- simple bug fixes or one-file edits
+- work that already has an approved spec, plan, and ready tasks
+- personal Obsidian briefing or vault-based planning
+
+## Required inputs
+- project_slug
+- research_slug
+- research_title
+- primary_question
+- owner
+- known_constraints
+
+## Output schema
+- `.project/projects/<slug>/research/<research-slug>/task_plan.md`
+- `.project/projects/<slug>/research/<research-slug>/findings.md`
+- `.project/projects/<slug>/research/<research-slug>/progress.md`
+- folded-forward updates to `spec.md`, `plan.md`, `decisions.md`, workstreams, tasks, or update notes when conclusions are durable
+- explicit no-action closeout when research does not change canonical artifacts
+
+## Quality checks
+- research question is specific enough to answer
+- findings cite inspected files, commands, sources, or artifacts
+- progress log records actions, validation, blockers, and closeout
+- durable conclusions are folded into canonical Delano project artifacts
+- research files do not contain secrets, credentials, private machine paths, or Obsidian vault paths
+- research output is not treated as executable task truth until folded forward
+
+## Failure behavior
+- stop if project slug does not exist
+- return a narrower research question when the current question is too broad
+- document evidence gaps before recommending artifact changes
+- leave canonical project files unchanged when findings are weak or unresolved
+
+## Allowed side effects
+- create a research intake folder under `.project/projects/<slug>/research/<research-slug>/`
+- update `task_plan.md`, `findings.md`, and `progress.md` during investigation
+- update canonical Delano artifacts only after evidence supports the change
+- run Delano validation after creating or folding forward research
+
+## Script hooks
+- `bash .agents/scripts/pm/research.sh <project-slug> <research-slug> --title "<Research Title>" --question "<Primary Question>" --owner <owner> --json`
+- `bash .agents/scripts/pm/validate.sh`
+- `bash .agents/scripts/pm/status.sh`
+
+## Lineage
+This skill adapts Bart's `planning_with_files` pattern to Delano. Keep the useful three-file working state and closeout discipline, but do not use Obsidian, `BartsVault`, or external briefing folders. Delano research belongs inside the project repository.
+
+## Execution assets
+- `references/runbook.md`
+- `templates/research-summary.md`
+- `templates/fold-forward-checklist.md`

package/assets/payload/.agents/skills/research-skill/references/runbook.md

@@ -0,0 +1,59 @@
+# research-skill runbook
+
+Use research intake as Delano's repo-native version of file-based planning for unclear work. It gives agents durable working state without moving the source of truth out of the repository.
+
+## 1. Decide whether research is needed
+
+Open research when the next canonical artifact change would otherwise be a guess. Good triggers include unclear imported requirements, competing implementation options, missing evidence, uncertain user intent, and questions that need investigation before delivery planning.
+
+Skip research when the work is already decided and executable. Use `execution-skill`, `planning-skill`, or `quality-skill` directly instead.
+
+## 2. Open the intake
+
+Run:
+
+```bash
+bash .agents/scripts/pm/research.sh <project-slug> <research-slug> \
+  --title "<Research Title>" \
+  --question "<Primary Question>" \
+  --owner <owner> \
+  --json
+```
+
+The command creates:
+- `task_plan.md`
+- `findings.md`
+- `progress.md`
+
+under:
+- `.project/projects/<project-slug>/research/<research-slug>/`
+
+Do not create Obsidian briefings for Delano research.
+
+## 3. Work inside the intake
+
+Use `task_plan.md` for phase state, `findings.md` for evidence and conclusions, and `progress.md` for chronological actions, tests, blockers, and handoff notes.
+
+Keep entries concise and evidence-led. Cite local files, commands, issue references, PRs, docs, or external sources that were actually inspected.
+
+## 4. Fold forward
+
+Research is not done just because the three files exist. Durable conclusions must be folded into canonical Delano artifacts:
+- `spec.md`
+- `plan.md`
+- `decisions.md`
+- `workstreams/*.md`
+- `tasks/*.md`
+- `updates/*.md`
+
+If the answer is no-action, record why in `progress.md` and keep canonical files unchanged.
+
+## 5. Validate and report
+
+Run validation after creating intake files and again after folding conclusions forward:
+
+```bash
+bash .agents/scripts/pm/validate.sh
+```
+
+Report the research path, conclusion, folded-forward files, validation result, and remaining open items.

package/assets/payload/.agents/skills/research-skill/templates/fold-forward-checklist.md

@@ -0,0 +1,9 @@
+# Fold-forward Checklist
+
+- [ ] Research question answered or explicitly narrowed
+- [ ] Evidence and gaps recorded in `findings.md`
+- [ ] Actions, validation, and blockers recorded in `progress.md`
+- [ ] Durable conclusions copied into canonical Delano artifacts
+- [ ] No secrets, credentials, private machine paths, or Obsidian vault paths included
+- [ ] `bash .agents/scripts/pm/validate.sh` run after changes
+- [ ] No-action closeout recorded if canonical artifacts stayed unchanged

package/assets/payload/.agents/skills/research-skill/templates/research-summary.md

@@ -0,0 +1,21 @@
+# Research Summary
+
+## Question
+
+<primary research question>
+
+## Evidence Inspected
+
+- <file, command, source, issue, PR, or artifact>
+
+## Findings
+
+- <finding tied to evidence>
+
+## Recommendation
+
+<recommended Delano artifact change or no-action decision>
+
+## Confidence
+
+<high|medium|low> because <reason>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "CLI for the Delano delivery runtime.",
   "license": "MIT",
   "repository": {

package/src/cli/lib/project-state.js

@@ -472,12 +472,56 @@ function applyTaskRollups({ project, task, action, previousStatus, timestamp, ch
     promoteWorkstreamToActive(project, workstream, timestamp, changes);
   }
 
+  if (action === "close") {
+    openDependencyReadyTasks(project, task, timestamp, changes);
+  }
+
   if (["close", "defer"].includes(action)) {
     closeWorkstreamIfDone(project, workstream, timestamp, changes);
     closeProjectIfDone(project, timestamp, changes);
   }
 }
 
+function openDependencyReadyTasks(project, completedTask, timestamp, changes) {
+  const completedTaskId = String(completedTask.frontmatter.id || "").trim();
+  if (!completedTaskId) {
+    return;
+  }
+
+  for (const candidate of project.tasks) {
+    if (candidate === completedTask || !isDependencyOnlyBlockedTask(project, candidate, completedTaskId)) {
+      continue;
+    }
+
+    setFrontmatter(candidate, "status", "ready");
+    setFrontmatter(candidate, "updated", timestamp);
+    removeFrontmatter(candidate, "blocked_owner");
+    removeFrontmatter(candidate, "blocked_check_back");
+    appendEvidence(candidate, timestamp, `Opened automatically because dependencies are done after ${completedTaskId} closed.`);
+    changes.push(`${relativeProjectPath(project, candidate.path)} status -> ready`);
+  }
+}
+
+function isDependencyOnlyBlockedTask(project, task, completedTaskId) {
+  if ((task.frontmatter.status || "") !== "blocked") {
+    return false;
+  }
+
+  const dependencies = parseInlineList(task.frontmatter.depends_on || "[]");
+  if (!dependencies.includes(completedTaskId)) {
+    return false;
+  }
+  if (!dependencies.every((dependencyId) => findTask(project, dependencyId)?.frontmatter.status === "done")) {
+    return false;
+  }
+
+  const owner = String(task.frontmatter.blocked_owner || "").trim().toLowerCase();
+  if (!owner) {
+    return true;
+  }
+  return ["dependency", "dependencies", "delano", "delano-cli", "system", "auto", "automation"].includes(owner);
+}
+
 function assertTaskWorkstreamExists(project, task, action) {
   const workstreamId = String(task.frontmatter.workstream || "").trim();
   if (!workstreamId) {