Project State Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/cli/commands/state.js
• src/cli/lib/project-state.js
• src/cli/index.js
• README.md
• test/cli.test.js
• DESIGN.md

Project State Management in Delano is a file-backed system that treats the .project/ directory as the canonical source of truth for delivery contracts. It encompasses the creation, tracking, and lifecycle transitions of projects, workstreams, and tasks through markdown artifacts. By maintaining planning and evidence on disk, the system allows maintainers and autonomous agents to operate from a unified, vendor-agnostic model.

The architecture is built around "Local Dossiers," which emphasize visible provenance, tracing implementation through evidence logs, and maintaining a strict relationship between parent projects and child workstreams or tasks. State transitions are governed by automated rollups that ensure parent artifacts (like a project Spec or Plan) accurately reflect the progress of underlying work.

Sources: README.md:12-25, src/cli/lib/project-state.js:12-20, DESIGN.md:99-110

Core Artifact Architecture

The state of a project is distributed across several key markdown files and directories. Each artifact uses YAML frontmatter to store metadata and structured markdown sections for human-readable content.

Artifact Components

Artifact	Location	Purpose
Spec	spec.md	Defines the measurable target, outcome, and high-level uncertainty.
Plan	plan.md	Details the delivery strategy, risk levels, and artifact maps.
Decisions	decisions.md	Records technical or strategic choices made during the project.
Workstream	workstreams/*.md	Groups related tasks into logical delivery streams.
Task	tasks/*.md	The smallest unit of work, containing status, dependencies, and evidence.
Update	updates/*.md	Temporal logs of progress, blockers, or completed actions.

Sources: src/cli/lib/project-state.js:75-85, src/cli/lib/project-state.js:207-231, src/cli/commands/state.js:24-115

Logical Structure

The following diagram illustrates the relationship between the project root and its constituent state files.

State Lifecycle and Rollups

State transitions in Delano are rarely isolated. Updating a task often triggers "rollups"—automatic status updates to parent workstreams or projects to ensure consistency across the dossier.

Task Lifecycle Transitions

The applyTaskAction function handles status changes such as open, start, close, block, and defer.

• Start/Close: Promoting a task to in-progress or done automatically promotes the parent project (Spec/Plan) and the parent Workstream to active.
• Automatic Opening: When a task is closed, the system scans for dependent tasks. If a task was blocked solely by that dependency (owner: dependency), it is automatically transitioned to ready.
• Completion Rollups: If all tasks in a workstream are closed, the workstream status transitions to done. If all tasks in a project are closed, the project Spec becomes complete and the Plan becomes done.

Sources: src/cli/lib/project-state.js:419-460, src/cli/lib/project-state.js:487-512

Transition Logic Flow

This diagram shows the logic flow when a task is closed.

State Manipulation Functions

The library src/cli/lib/project-state.js provides the underlying mechanics for parsing and updating markdown artifacts.

Key Data Operations

• Frontmatter Parsing: The system uses regex to extract and update YAML-style frontmatter without corrupting the markdown body.
• Template Rendering: New artifacts are generated by replacing tokens (e.g., <project-name>, <ISO8601 UTC>) in templates located in .project/templates/.
• Evidence Logging: Significant changes append entries to an "Evidence Log" or "Updates" section within the markdown file to maintain a traceable audit trail.

// Example of template rendering and frontmatter update
// Sources: [src/cli/lib/project-state.js:58-65](https://github.com/MajesteitBart/delano/blob/1cc5ca42cabef6817667fe269a54d00eea2e8a2e/src/cli/lib/project-state.js#L58-L65), [src/cli/lib/project-state.js:126-140](https://github.com/MajesteitBart/delano/blob/1cc5ca42cabef6817667fe269a54d00eea2e8a2e/src/cli/lib/project-state.js#L126-L140)
function renderTemplate(root, templateName, replacements) {
  let text = readTemplate(root, templateName);
  for (const [token, value] of Object.entries(replacements)) {
    text = text.split(token).join(String(value));
  }
  return text;
}

function setFrontmatter(file, key, value) {
  file.frontmatter[key] = String(value);
  file.text = updateFrontmatterText(file.text, file.frontmatter);
}

Dependency Validation

The system strictly enforces that a task cannot be started or closed if its dependencies (defined in the depends_on frontmatter) are not in a done status. This ensures that the execution order adheres to the planned delivery strategy.

Sources: src/cli/lib/project-state.js:698-709, test/cli.test.js:154-175

Command Interface

The State Management system is exposed via the delano CLI, providing commands for projects, workstreams, tasks, and updates.

Command	Subcommands	Primary Responsibility
delano project	create, show, start, close, block, defer, update	Manages top-level Spec and Plan artifacts.
delano workstream	add, show, start, close, block, defer, update	Manages workstream-level status and grouping.
delano task	add, open, start, close, block, defer, update	Manages individual task lifecycle androllups.
delano update	add	Creates a new progress update markdown file.

Sources: src/cli/commands/state.js:132-178, src/cli/index.js:52-78

Summary

Project State Management in Delano ensures that delivery state is decentralized and traceable. By leveraging file-backed contracts, the system provides a robust framework where status transitions are governed by logical rollups and every significant action is recorded as evidence. This local-first approach ensures that the project's "ground truth" is always accessible, verifiable, and independent of specific vendor platforms.