specs/README.md

Rama main · réplica de lectura del repositorio original.

# Specs

Specs describe data-plane behavior. They are written for implementers and for black-box conformance tests.

Specs are implemented incrementally. A partial implementation must state the behavior it covers and must add black-box coverage for that behavior. Documented behavior remains normative even when product implementation has not caught up.

## Status

This table describes conformance status.
`Not implemented` means the spec documents target conformance behavior.
It must not be treated as product behavior until implementation catches up.

| Spec | Status |
| --- | --- |
| [001: Project](001-project.md) | Not implemented |
| [002: YAML Schema](002-yaml-schema.md) | Implemented |
| [003: Value Resolution and Field Evaluation](003-value-resolution.md) | Implemented |
| [004: Value Resolution Consts](004-value-resolution-consts.md) | Implemented |
| [005: Value Resolution Params](005-value-resolution-params.md) | Implemented |
| [006: Value Resolution Env](006-value-resolution-env.md) | Implemented |
| [007: Value Resolution Steps](007-value-resolution-steps.md) | Implemented |
| [009: Step Reference](009-step-reference.md) | Implemented |
| [011: Dynamic Evaluation](011-dynamic-evaluation.md) | Implemented |
| [012: Step Outputs](012-step-outputs.md) | Implemented |
| [013: Step Run](013-step-run.md) | Partially implemented |
| [014: Step Run Command](014-step-run-command.md) | Implemented |
| [015: Step Run Script](015-step-run-script.md) | Implemented |
| [017: Built-In Run Context](017-built-in-run-context.md) | Implemented |
| [018: Parallel Fan-Out and Foreach Iteration](018-parallel-and-foreach.md) | Implemented |
| [019: Sub-DAG Working Directory](019-sub-dag-working-directory.md) | Implemented |
| [020: MCP Server](020-mcp-server.md) | Not implemented |
| [021: MCP Read Tool](021-mcp-read-tool.md) | Implemented |
| [022: MCP Change Tool](022-mcp-change-tool.md) | Implemented |
| [023: Preconditions](023-preconditions.md) | Implemented |
| [030: Git Worktree Action](030-git-worktree-action.md) | Implemented |
| [031: Human Tasks](031-human-task.md) | Implemented |
| [032: Agent DAGs](032-agent-dag.md) | Implemented |
| [033: Build Workflows](033-build-workflows.md) | Implemented |
| [034: Wiki Page File Format](034-wiki-page-format.md) | Implemented |
| [035: File Dependencies](035-file-dependencies.md) | Implemented |
| [036: MCP Execute Tool](036-mcp-execute-tool.md) | Implemented |
| [037: Docker Run Action](037-docker-run.md) | Partially implemented |
| [038: Kubernetes Run Action](038-kubernetes-run.md) | Partially implemented |
| [039: Wait Actions](039-wait.md) | Implemented |
| [040: Router Route Action](040-router-route.md) | Implemented |
| [041: Log Write Action](041-log-write.md) | Implemented |
| [042: SSH Run Action](042-ssh-run.md) | Partially implemented |
| [043: SFTP Transfer Actions](043-sftp-transfer.md) | Partially implemented |
| [044: Mail Send Action](044-mail-send.md) | Partially implemented |
| [045: HTTP Request Action](045-http-request.md) | Partially implemented |
| [046: PostgreSQL Actions](046-postgres.md) | Partially implemented |
| [047: SQLite Actions](047-sqlite.md) | Partially implemented |
| [048: DuckDB and Action Bundles](048-duckdb-action.md) | Partially implemented |
| [049: Data Convert and Pick Actions](049-data.md) | Partially implemented |
| [050: Outputs Write Action](050-outputs.md) | Implemented |
| [051: Artifact Actions](051-artifact.md) | Partially implemented |
| [052: File Actions](052-file.md) | Partially implemented |
| [053: Archive Actions](053-archive.md) | Partially implemented |
| [054: Template Action](054-template.md) | Partially implemented |
| [055: Git Checkout Action](055-git-checkout.md) | Partially implemented |
| [056: S3 Actions](056-s3.md) | Partially implemented |
| [057: Redis Actions](057-redis.md) | Partially implemented |
| [058: JQ Filter Action](058-jq-filter.md) | Partially implemented |
| [059: Chat Completion Action](059-chat-completion.md) | Partially implemented |
| [060: Node Script Action](060-node-script.md) | Partially implemented |
| [061: Python Script Action](061-python-script.md) | Partially implemented |
| [062: dbt Action](062-dbt.md) | Partially implemented |
| [063: Schedule Descriptors](063-schedule.md) | Implemented |
| [064: Dry-Run Step Checks](064-dry-run-step-checks.md) | Implemented |
| [067: Harness Executor (CLI and ACP)](067-harness.md) | Partially implemented |
| [068: State Executor](068-state.md) | Implemented |
| [069: Secrets Providers](069-secrets-providers.md) | Partially implemented |
| [070: Runtime Profiles](070-runtime-profiles.md) | Partially implemented |
| [071: Decision Evaluation Action](071-decision-evaluate.md) | Implemented |
| [072: Browser Actions](072-browser.md) | Partially implemented |
| [073: Mailbox Actions](073-mailbox-actions.md) | Partially implemented |
| [074: Computer Actions](074-computer.md) | Partially implemented |
| [075: Repeat Policy](075-repeat-policy.md) | Implemented |
| [076: CLI Run Parameter Input](076-cli-run-params.md) | Implemented for local commands |
| [077: XLSX Actions](077-xlsx.md) | Implemented |
| [078: JS Run Action](078-js-run.md) | Implemented |
| [079: Browser Sessions](079-browser-session.md) | Implemented for local commands |
| [080: DAG Restart Policy](080-restart-policy.md) | Implemented |
| [081: ClickHouse Action](081-clickhouse.md) | Partially implemented |
| [083: Continuous Runs](083-continuous-runs.md) | Partially implemented |
| [084: Business Calendars](084-business-calendars.md) | Implemented |
| [085: Scheduler High Availability](085-scheduler-ha.md) | Partially implemented |

**Writing guidelines:**

- Describe observable behavior in a way that cannot be misinterpreted.
- Write specs as observable contracts, not explanations of implementation.
- Keep each file focused on one topic.
- Keep each spec scoped to one owner and explicitly say what it does not define.
- Every numbered spec must include a `Status` section.
- Every numbered spec must include a `Scope` section.
- Name numbered specs with numeric prefixes to show reading order, such as `001-language.md`.
- Define observable behavior, errors, side effects, and lifecycle effects.
- Include examples that can be used as test fixtures.
- Do not require control-plane behavior.
- Remove obsolete functionality or behavior unless an owning spec explicitly keeps it.
- Do not add tests that verify a functionality or behavior is removed.
- Spec is not implementation note. Only document normative behavior.

**Conformance test guidelines:**

- Put each spec's black-box tests in `conformance/<spec_slug>`.
- Put workflow examples in static YAML fixtures under `conformance/<spec_slug>/testdata`.
- Keep Go conformance tests as small tables over fixture filenames and expected outcomes.
- Do not generate DAG YAML dynamically in Go test code.
- Add a new fixture when a behavior needs a new workflow shape.
- Keep setup helpers limited to runtime files or directories that the static fixture needs.

**Each spec should document:**

| Section | Purpose |
| --- | --- |
| Scope | Behavior covered by the spec. |
| Goal | The reason this behavior needs a spec. |
| Behavior | Required behavior. |
| Errors | Invalid input, runtime failure, timeout, abort, and cleanup behavior. |
| Examples | Minimal cases that can become black-box tests. |