Testing Strategies & Execution Hygiene

Relevant source files

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

• test/cli.test.js
• test/package.test.js
• assets/install-manifest.json
• package.json
• README.md
• AGENTS.md
• src/cli/lib/project-state.js

Delano employs a multi-layered testing and validation strategy designed to ensure the integrity of file-backed delivery contracts and the shared agent runtime. The core of this strategy revolves around "hygiene"—maintaining strict boundaries between system assets and project-specific data, validating state transitions, and ensuring privacy-safe logging across all execution environments.

The testing ecosystem spans from low-level unit tests for CLI logic to high-level validation scripts that audit the health of a repository's .project/ and .agents/ directories. This ensures that coding agents and human operators work from a consistent, verifiable operating model without vendor lock-in.
Sources: README.md:12-16, AGENTS.md:14-22

Validation Runtime & Hygiene

Delano's hygiene is enforced through the validate command and a series of specialized scripts under .agents/scripts/pm/. These tools perform structural audits of the repository to prevent "drift" between the installed runtime and the project manifest.

Core Validation Gates

The validation suite checks several critical domains:

• Artifact Schemas: Ensures .project files (specs, plans, tasks) adhere to defined JSON schemas.
• Status Transitions: Validates that tasks cannot progress if their dependencies are unresolved or if the parent project/workstream is in a "planned" state.
• Text Safety: Rejects bidirectional (Bidi) control characters to prevent prompt injection or code obfuscation.
• Log Safety: Audits logs for absolute paths or sensitive data leaks.

Sources: README.md:147-158, test/package.test.js:154-160, test/package.test.js:180-200

Execution Flow for Validation

The following diagram illustrates how the validation runtime audits the local environment:

Testing Layers

1. Unit & Integration Testing

Delano uses the native node:test runner for CLI and library logic. Key focus areas include:

• State Management: Testing project-state.js functions like addTaskFromTemplate and applyTaskAction to ensure markdown frontmatter is updated correctly.
• CLI Invocation: Verifying that shorthand flags (e.g., --yes for install) resolve to the correct internal commands.
• Dependency Resolution: Ensuring that closing a task automatically triggers the "ready" status for dependent tasks if they were only blocked by that dependency.

Sources: test/cli.test.js:1-50, test/cli.test.js:127-150, src/cli/lib/project-state.js:336-350

2. Package & Asset Hygiene

Tests in test/package.test.js ensure that the distributed npm package remains generic. A critical hygiene rule is that the package must never include the developer's own local .project/context files, instead shipping generic templates.

Hygiene Check	Description	Source File Reference
Git Config Exclusion	Ensures .gitignore and .gitattributes are not leaked into the npm payload.	test/package.test.js:13-25
Manifest Drift	Verifies that the files in the assets/payload/ directory match the install-manifest.json.	test/package.test.js:115-121
Template Staging	Confirms that build:assets replaces live context with <placeholder> templates.	test/package.test.js:52-70

Multi-Agent Execution Hygiene

To support multiple agents working in the same repository, Delano implements a lease-based coordination system. This prevents race conditions and conflicting edits to the file-backed contracts.

Lease Lifecycle

Agents must acquire an "exclusive" or "shared" lease before performing mutations.

1. Acquire: Agent requests a lease for a specific "zone" (e.g., a specific task file).
2. Execute: Agent performs the work.
3. Release: Agent must provide a handoff summary to release the lease.

Continuous Verification Commands

Command	Purpose	Hygiene/Testing Role
delano validate	Full audit of schemas, safety, and drift.	Primary gate for release and execution readiness.
npm test	Runs the Node.js test suite.	Validates CLI logic and package integrity.
delano status --open --brief	Emits minimal project state.	Used by Codex/Agents to establish initial context hygiene.
bash .agents/scripts/pm/validate.sh	Shell-based validation entrypoint.	Allows for validation in non-Node environments (e.g., minimal containers).

Sources: README.md:154-165, AGENTS.md:27-32, test/package.test.js:129-138

Summary of Execution Principles

• Smallest Task-Safe Change: Agents are instructed to choose the minimal change required to satisfy the contract.
• Evidence-First: A task is not considered "done" until validation evidence is recorded in the task markdown or update log.
• Privacy-Safe Logs: Committed logs must pass the check-log-safety.sh script to ensure no PII or absolute local paths are leaked.
  Sources: AGENTS.md:14-22, AGENTS.md:34-40, package.json:54