docs: add specs and blackbox tests foundation

[yohamta0]

Summary

• add v3 data-plane specs for project layout, YAML schema, value resolution, step references, expression functions, step outputs, and step.run
• add implementation guidance for staged v3 data-plane conformance and testing expectations
• add binary-level schema conformance coverage for dagu workflow validate
• remove the legacy root dagu validate command from the v3 command surface
• suppress command usage output for workflow validation failures

Changes

• Added v3 specification documents and implementation guidance for the data-plane work.
• Added dagu workflow validate <workflow_file> for root/document-level v3 YAML schema validation.
• Removed the legacy root dagu validate command so validation flows through the v3 workflow validate subcommand.
• Expanded binary-level blackbox fixtures for valid workflows, invalid root/document schema, and no-execution validation behavior.
• Clarified that later numbered specs extend dagu workflow validate when their implementation slices land.

Related Issues

No related issue.

Checklist

• Code follows the project style guidelines
• Self-review of the code has been performed
• Tests have been added or updated as needed
• Documentation has been updated as needed
• Changes have been tested locally

Testing

• git diff --check
• go test ./internal/core/v3schema ./internal/cmd ./cmd ./internal/service/telegram
• go test ./internal/service/telegram -run TestDAGRunMonitor_RetriesOnlyUndeliveredTelegramChat -count=100
• go test -race ./internal/service/telegram -run TestDAGRunMonitor_RetriesOnlyUndeliveredTelegramChat -count=100
• go test -race ./internal/service/telegram -count=1
• make lint
• make bin
• DAGU_BIN=.local/bin/dagu go test -count=1 ./tests

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 03df7765-fcba-4a6a-835c-1a7fd964eb48

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR establishes the v3 data-plane specification framework for Dagu workflows. It adds nine specification documents defining project structure, YAML schema validation, value resolution, step references, expression functions, step outputs, and step execution. Implementation guidelines and spec documentation standards are also included, along with test infrastructure and a conformance test.

Changes

v3 Data-Plane Specification & Test Infrastructure

Layer / File(s)	Summary
Specification Documentation Standards specs/README.md, specs/IMPLEMENTATION.md	Defines how v3 specs should be documented (observable behavior, required sections) and v3 implementation rules (spec-authoritative, strict, deterministic, avoiding legacy compatibility).
Project Structure and Workflow Schema Validation specs/001-project.md, specs/002-yaml-schema.md	Specifies .dagu/ directory requirement, direct workflow file discovery, dagu project validate behavior, YAML stream schema rules (entrypoint constraints, required steps, allowed/rejected root fields), working directory resolution, and validation failure conditions without step execution.
Value Resolution and Step References specs/003-value-resolution.md, specs/004-step-reference.md	Formalizes ${{ path }} reference syntax for consts, params, steps namespaces, step identity rules ([a-z][a-z0-9_]* pattern), dependency semantics (no self-dependency, cycle prevention), and value reference requirements with execution ordering constraints.
Expression Functions, Step Outputs, and Step Run specs/005-expression-functions.md, specs/006-step-outputs.md, specs/007-step-run.md	Defines shell(command) function execution with platform-specific behavior, step output file format and parsing (single/multi-line records, string/json types), and step run command execution via platform shell with reference resolution, working directory/environment inheritance, and abort/timeout restrictions.
Test Framework and Conformance Test tests/internal/runner.go, tests/002_schema_test.go, tests/testdata/002_schema/.dagu/entrypoint_name_forbidden.yaml	Introduces Runner test helper for isolated test execution with binary path resolution and assertion methods; adds first conformance test validating schema rejection of forbidden entrypoint name field, confirming validation without execution.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: addition of specification documents and black-box test foundation for v3 data-plane work.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The PR description follows the template structure with Summary, Changes, Related Issues, and Checklist sections. All major changes are documented and testing was performed.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch v3-specs-001-002

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[yohamta0]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/002_schema_test.go`:
- Around line 1-2: The test file starts with only "package tests_test" and is
missing the required GPL v3 license header; add the standard GPL v3 header
comment block at the top of the file (above the package declaration) to match
project policy and/or run the automated tool (make addlicense) to insert the
correct header so the file containing package tests_test includes the GPL v3
license header.

In `@tests/internal/runner.go`:
- Around line 1-2: This Go source file (package dagutest) is missing the
required GPL v3 license header; add the standard GPL v3 header comment block at
the very top of the file (above the package dagutest declaration) matching the
repository's license template (the same header produced by make addlicense) so
the file includes the full GPL v3 notice and copyright line.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a6c50216-c252-4f09-b62c-f7c9b3953d49

📥 Commits

Reviewing files that changed from the base of the PR and between 50d9551 and 65857af.

📒 Files selected for processing (12)

• specs/001-project.md
• specs/002-yaml-schema.md
• specs/003-value-resolution.md
• specs/004-step-reference.md
• specs/005-expression-functions.md
• specs/006-step-outputs.md
• specs/007-step-run.md
• specs/IMPLEMENTATION.md
• specs/README.md
• tests/002_schema_test.go
• tests/internal/runner.go
• tests/testdata/002_schema/.dagu/entrypoint_name_forbidden.yaml

[yohamta0]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.