Validation Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Validation Engine in Delano is a comprehensive suite of checks designed to ensure that the file-backed delivery runtime, project contracts, and local development environment remain consistent and secure. It verifies that the .project/ directory, which serves as the source of truth, adheres to defined schemas and operational rules.
The engine facilitates "contract-first" development by enforcing strict rules on artifact scope, status transitions, and evidence mapping. It acts as a gatekeeper during the project lifecycle, preventing invalid state transitions—such as closing a task while its parent project is still in a "planned" state—and ensuring that privacy-safe logging and path safety standards are maintained.
Sources: README.md:12-16, README.md:188-196
Core Validation Categories
The validation logic is distributed across various scripts and schemas, primarily located in the .agents/scripts/ directory. These are categorized by the type of drift or violation they detect.
1. Artifact and Schema Validation
The engine ensures that all markdown artifacts (specs, plans, tasks, workstreams) within .project/projects/ match their respective JSON schemas. This includes checking for required frontmatter fields and structural integrity.
- Artifact Scope: Verifies that project files do not exceed defined boundaries.
- Schema Consistency: Uses
check-artifact-schemas.mjsandcheck-artifact-scope.mjsto validate local files against definitions in.agents/schemas/artifacts/.
Sources: assets/install-manifest.json:34-42, test/package.test.js:141-155
2. State Transition Logic
Delano enforces a strict lifecycle for tasks and projects. The check-status-transitions.mjs script prevents illegal movements between statuses. For example, a task cannot transition to done if its dependencies are unresolved or if the parent spec.md is still planned.
The following flow represents the dependency resolution logic used by the engine:
3. Safety and Privacy Gates
The engine includes specific checks to prevent the leakage of sensitive data or the introduction of malicious content.
| Component | Target File / Script | Description |
|---|---|---|
| Log Safety | check-log-safety.sh | Ensures logs are privacy-safe and raw prompts are opt-in only. |
| Text Safety | check-text-safety.mjs | Rejects bidirectional (Bidi) control characters that could hide malicious code. |
| Path Safety | check-path-standards.sh | Prevents the leakage of local absolute paths in documentation or contracts. |
| Context Audit | audit-context-files.mjs | Scores context files based on whether they are real, placeholder, or stale. |
Sources: AGENTS.md:46-49, test/package.test.js:126-135, test/package.test.js:315-330
External Synchronization Checks
The validation engine monitors drift between local project state and external platforms like GitHub or Linear. It uses a "drift taxonomy" to classify discrepancies.
Sync Validation Flow
The engine builds a drift report comparing local sync-map.json data with external issue/PR states.
Implementation Details
The CLI provides wrapper commands for these validation routines, which essentially call underlying bash and Node.js scripts.
Key Validation Commands
delano validate: The primary entry point for a full runtime and contract check.bash .agents/scripts/pm/validate.sh: The underlying script that executes individual checks (schema, transition, safety, evals).
Status Constraints
The engine maintains a set of terminal and progressed statuses used during rollup logic:
- Closed Statuses:
done,deferred,canceled. - Progressed Statuses:
in-progress,done.
Sources: src/cli/lib/project-state.js:8-9, README.md:191-196, AGENTS.md:30-35
// Example of dependency assertion in project-state.js
function assertDependenciesDone(project, task, action) {
const dependencies = parseInlineList(task.frontmatter.depends_on || "[]");
for (const dependencyId of dependencies) {
const dependency = findTask(project, dependencyId);
if (dependency && dependency.frontmatter.status !== "done") {
throw new CliError(
`Cannot ${action} ${task.frontmatter.id}: dependency ${dependencyId} is ${dependency.frontmatter.status}.`,
1
);
}
}
}
Sources: src/cli/lib/project-state.js:520-532
Summary
The Validation Engine ensures that Delano repositories maintain high-fidelity delivery contracts. By enforcing schema compliance, lifecycle integrity, and safety standards, it allows multiple agents and operators to coordinate through a shared, verifiable file-backed state without vendor lock-in.