@bvdm/delano 0.2.4 → 0.2.6

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

@@ -0,0 +1,296 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  research.sh <project-slug> <research-slug> [options]
+
+Creates a repo-native Delano research intake folder for a project.
+
+Required arguments:
+  project-slug          Existing Delano project slug
+  research-slug         Research folder slug in kebab-case
+
+Options:
+  --title <title>        Human-readable research title
+  --question <question>  Primary research question
+  --owner <owner>        Research owner, defaults to team
+  --no-validate          Create artifacts without running Delano validation
+  --json                 Print a single machine-readable JSON result
+  -h, --help             Show this help
+
+Agent notes:
+  - Use this before mutating spec/plan/tasks when intent is unclear.
+  - Update findings.md and progress.md during investigation.
+  - Fold durable conclusions forward into spec.md, plan.md, decisions.md, workstreams, tasks, or updates.
+  - Research files are supporting discovery state, not executable task truth.
+USAGE
+}
+
+resolve_python() {
+  if command -v python3 >/dev/null 2>&1 && python3 -c "import sys" >/dev/null 2>&1; then
+    PYTHON_CMD=(python3)
+  elif command -v py >/dev/null 2>&1 && py -3 -c "import sys" >/dev/null 2>&1; then
+    PYTHON_CMD=(py -3)
+  elif command -v python >/dev/null 2>&1 && python -c "import sys" >/dev/null 2>&1; then
+    PYTHON_CMD=(python)
+  else
+    echo "Error: Python runtime not found. Install python3, python, or py -3." >&2
+    exit 1
+  fi
+}
+
+resolve_python
+
+json_escape() {
+  "${PYTHON_CMD[@]}" -c 'import json,sys; print(json.dumps(sys.stdin.read().rstrip("\n")))'
+}
+
+if [[ "${1:-}" == "" || "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+  usage
+  exit 0
+fi
+
+if [[ "${2:-}" == "" ]]; then
+  usage
+  exit 1
+fi
+
+project_slug="$1"
+research_slug="$2"
+shift 2
+
+title=""
+question=""
+owner="team"
+validate="true"
+json="false"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --title)
+      title="${2:-}"
+      if [[ -z "$title" ]]; then echo "Error: --title requires a value"; exit 1; fi
+      shift 2
+      ;;
+    --question)
+      question="${2:-}"
+      if [[ -z "$question" ]]; then echo "Error: --question requires a value"; exit 1; fi
+      shift 2
+      ;;
+    --owner)
+      owner="${2:-}"
+      if [[ -z "$owner" ]]; then echo "Error: --owner requires a value"; exit 1; fi
+      shift 2
+      ;;
+    --no-validate)
+      validate="false"
+      shift
+      ;;
+    --json)
+      json="true"
+      shift
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      ;;
+    --*)
+      echo "Error: unknown option: $1"
+      exit 1
+      ;;
+    *)
+      echo "Error: unexpected positional argument: $1"
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ! "$project_slug" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  echo "Error: project-slug must be kebab-case"
+  exit 1
+fi
+
+if [[ ! "$research_slug" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  echo "Error: research-slug must be kebab-case"
+  exit 1
+fi
+
+root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+cd "$root"
+
+project_dir=".project/projects/$project_slug"
+if [[ ! -d "$project_dir" ]]; then
+  echo "Error: Delano project not found: $project_dir"
+  exit 1
+fi
+
+research_dir="$project_dir/research/$research_slug"
+if [[ -d "$research_dir" ]]; then
+  echo "Error: research intake already exists at $research_dir"
+  exit 1
+fi
+
+now="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
+title="${title:-${research_slug//-/ }}"
+question="${question:-<primary research question>}"
+
+mkdir -p "$research_dir"
+
+cat > "$research_dir/task_plan.md" <<PLAN
+---
+type: research_intake
+project: $project_slug
+slug: $research_slug
+owner: $owner
+status: opened
+created: $now
+updated: $now
+---
+
+# Research Plan: $title
+
+## Goal
+
+Answer the research question and fold durable conclusions into canonical Delano project artifacts.
+
+## Primary Question
+
+$question
+
+## Scope
+
+### In Scope
+
+- Gather relevant evidence.
+- Capture findings and decisions.
+- Identify changes needed in \`spec.md\`, \`plan.md\`, \`decisions.md\`, workstreams, tasks, or updates.
+
+### Out of Scope
+
+- Marking delivery tasks done from research alone.
+- External sync writes without normal Delano approval semantics.
+- Storing secrets, credentials, or private machine paths.
+
+## Current Phase
+
+Opened
+
+## Phases
+
+- [x] Open research intake
+- [ ] Investigate sources and options
+- [ ] Summarize findings
+- [ ] Fold forward into canonical project artifacts or explicitly close as no-action
+
+## Decisions Made
+
+| Decision | Rationale |
+| --- | --- |
+
+## Blockers
+
+| Blocker | Owner | Check-back |
+| --- | --- | --- |
+PLAN
+
+cat > "$research_dir/findings.md" <<FINDINGS
+---
+type: research_findings
+project: $project_slug
+slug: $research_slug
+created: $now
+updated: $now
+---
+
+# Findings: $title
+
+## Source References
+
+- <source, file, command, or artifact inspected>
+
+## Observations
+
+- <finding>
+
+## Options Considered
+
+| Option | Pros | Cons | Decision |
+| --- | --- | --- | --- |
+
+## Fold-Forward Candidates
+
+| Finding | Target Artifact | Proposed Change |
+| --- | --- | --- |
+
+## Open Questions
+
+- <question>
+FINDINGS
+
+cat > "$research_dir/progress.md" <<PROGRESS
+---
+type: research_progress
+project: $project_slug
+slug: $research_slug
+created: $now
+updated: $now
+---
+
+# Progress: $title
+
+## $now
+
+- Opened research intake for project \`$project_slug\`.
+- Primary question: $question
+
+## Validation Evidence
+
+- Pending.
+
+## Handoff Summary
+
+- Pending.
+PROGRESS
+
+validation_status="skipped"
+ok="true"
+error=""
+if [[ "$validate" == "true" ]]; then
+  if [[ "$json" == "true" ]]; then
+    validation_log="$(mktemp)"
+    if "$root/.agents/scripts/pm/validate.sh" >"$validation_log" 2>&1; then
+      validation_status="passed"
+    else
+      validation_status="failed"
+      ok="false"
+      error="validation_failed"
+    fi
+    rm -f "$validation_log"
+  else
+    "$root/.agents/scripts/pm/validate.sh"
+    validation_status="passed"
+  fi
+fi
+
+if [[ "$json" == "true" ]]; then
+  project_json="$(printf '%s' "$project_dir" | json_escape)"
+  research_json="$(printf '%s' "$research_dir" | json_escape)"
+  validation_json="$(printf '%s' "$validation_status" | json_escape)"
+  if [[ "$ok" == "true" ]]; then
+    printf '{"ok":true,"command":"research","project":%s,"research":%s,"files":["task_plan.md","findings.md","progress.md"],"validation":%s}\n' "$project_json" "$research_json" "$validation_json"
+  else
+    error_json="$(printf '%s' "$error" | json_escape)"
+    printf '{"ok":false,"command":"research","project":%s,"research":%s,"files":["task_plan.md","findings.md","progress.md"],"validation":%s,"error":%s}\n' "$project_json" "$research_json" "$validation_json" "$error_json"
+    exit 1
+  fi
+else
+  echo "Created Delano research intake: $research_dir"
+  echo "Files: task_plan.md, findings.md, progress.md"
+  echo "Validation: $validation_status"
+  echo "Next: update findings.md and progress.md, then fold conclusions into canonical Delano artifacts."
+fi

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
@@ -467,6 +468,20 @@ if [[ -n "$artifact_schema_check" ]]; then
   fi
 fi
 
+if [[ -f scripts/check-adapter-manifests.mjs ]]; then
+  echo ""
+  if command -v node >/dev/null 2>&1; then
+    if node scripts/check-adapter-manifests.mjs; then
+      true
+    else
+      errors=$((errors + 1))
+    fi
+  else
+    echo "❌ Node runtime not found for adapter manifest check"
+    errors=$((errors + 1))
+  fi
+fi
+
 operating_modes_check=""
 if [[ -f .agents/scripts/check-operating-modes.mjs ]]; then
   operating_modes_check=".agents/scripts/check-operating-modes.mjs"

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/assets/payload/.delano/viewer/public/styles.css

@@ -602,7 +602,7 @@ button { font-family: inherit; font-size: inherit; color: inherit; background: n
 /* ---------- Workspace dashboard ---------- */
 .project-grid {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
+  grid-template-columns: repeat(auto-fit, minmax(400px, 1fr));
   gap: 14px;
   padding-top: 16px;
 }

package/assets/payload/.project/templates/decisions.md

@@ -0,0 +1,18 @@
+---
+name: <project-name>
+slug: <kebab-case>
+owner: <person-or-team>
+created: <ISO8601 UTC>
+updated: <ISO8601 UTC>
+---
+
+# Decisions: <project-name>
+
+## Active Decisions
+- No decisions recorded at creation.
+
+## Superseded Decisions
+- None.
+
+## Open Decision Questions
+- None recorded at creation.

package/assets/payload/.project/templates/plan.md

@@ -13,8 +13,25 @@ spec_status_at_plan_time: <planned|active|complete|deferred>
 
 ## What Changed After Probe
 
+## Technical Context
+
 ## Architecture Decisions
 
+## Policy and Contract Checks
+- [ ] `.project` remains the execution source of truth
+- [ ] Probe decision is explicit
+- [ ] Evidence gates are defined before handoff
+- [ ] External sync writes require dry-run or operator approval
+
+## Generated Artifact Map
+- `spec.md`: <source or generation notes>
+- `plan.md`: <source or generation notes>
+- `workstreams/`: <source or generation notes>
+- `tasks/`: <source or generation notes>
+
+## Complexity Exceptions
+- <exception, rationale, and owner>
+
 ## Probe-Driven Architecture Changes
 
 ## Workstream Design

package/assets/payload/.project/templates/spec.md

@@ -19,6 +19,12 @@ probe_status: <pending|skipped|completed>
 
 ## Outcome and Success Metrics
 
+## User Stories
+- US-001: As a <user>, I want <capability>, so that <outcome>.
+
+## Acceptance Scenarios
+- AC-001: Given <context>, when <action>, then <observable result>.
+
 ## Scope
 ### In Scope
 ### Out of Scope
@@ -27,6 +33,12 @@ probe_status: <pending|skipped|completed>
 
 ## Non-Functional Requirements
 
+## Assumptions
+- <assumption to validate>
+
+## Needs Clarification
+- <question that must be answered before activation or execution>
+
 ## Hypotheses and Unknowns
 
 ## Touchpoints to Exercise

package/assets/payload/.project/templates/task.md

@@ -13,6 +13,8 @@ conflicts_with: []
 parallel: true
 priority: medium
 estimate: M
+story_id:
+acceptance_criteria_ids: []
 ---
 
 # Task: <task-title>
@@ -22,6 +24,10 @@ estimate: M
 ## Acceptance Criteria
 - [ ]
 
+## Traceability
+- Story: <story_id or none>
+- Acceptance criteria: <acceptance criteria ids or none>
+
 ## Technical Notes
 
 ## Definition of Done

package/assets/payload/.project/templates/workstream.md

@@ -1,4 +1,5 @@
 ---
+id: WS-A
 name: WS-A API Foundation
 owner: backend-team
 status: planned

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bvdm/delano",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "CLI for the Delano delivery runtime.",
   "license": "MIT",
   "repository": {
@@ -58,6 +58,8 @@
     "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"
+    "check:closeout-learning": "node scripts/propose-closeout-learning.mjs --json && node scripts/check-closeout-learning-proposals.mjs",
+    "check:spec-kit-interop": "node scripts/check-spec-kit-interop-fixtures.mjs",
+    "check:adapter-manifests": "node scripts/check-adapter-manifests.mjs"
   }
 }