hammerkit 1.6.0 → 1.7.0

package/specs/build-file/caches/spec.md

@@ -1,114 +0,0 @@
-# Feature Specification: Build File: Caches
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/caches.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Skip unchanged tasks using the default local cache (Priority: P1)
-
-A developer runs hammerkit for the first time. Results are stored in the local cache (`~/.hammerkit/remote-cache`). On subsequent runs, hammerkit compares source file checksums and skips tasks whose inputs have not changed, saving build time without any configuration.
-
-**Why this priority**: Local caching is the out-of-the-box experience for every hammerkit user; it is always active.
-
-**Independent Test**: Run a task twice without modifying source files. Confirm the second run skips execution. Modify a source file and confirm the task runs again.
-
-**Acceptance Scenarios**:
-
-1. **Given** a task with `src:` files that have not changed since the last run, **When** the task is invoked, **Then** hammerkit skips execution and reports the task as up-to-date.
-2. **Given** a task with `src:` files where at least one has changed, **When** the task is invoked, **Then** hammerkit executes the task commands.
-
-### User Story 2 - Share build results across machines via a remote cache (Priority: P1)
-
-A team uses an S3 bucket as a shared cache. When a developer or CI job completes a task, the result is pushed to S3. The next machine to request the same task pulls the cached result and skips execution, dramatically reducing CI time.
-
-**Why this priority**: Remote caching is the primary new capability in 1.6.0 and a key differentiator for team and CI workflows.
-
-**Independent Test**: Declare an S3-backed cache, run a task on machine A and confirm the result is pushed. On machine B (with empty local cache), run the same task and confirm it is pulled and skipped.
-
-**Acceptance Scenarios**:
-
-1. **Given** a named cache with `type: s3` is declared and a task references it, **When** a task completes successfully, **Then** the result is pushed to the configured S3 bucket.
-2. **Given** the S3 bucket contains a cached result for the current source checksum, **When** the task is invoked on a machine without a local result, **Then** hammerkit pulls from the bucket and skips task execution.
-3. **Given** the S3 backend is unreachable, **When** a task runs, **Then** hammerkit emits a warning and continues — the pull or push failure does NOT fail the build.
-
-### User Story 3 - Override the default cache for all tasks (Priority: P2)
-
-A team wants all tasks to use a remote S3 bucket without modifying each task individually. They declare a `caches.default` entry in the build file, redirecting the implicit default cache to their S3 bucket.
-
-**Why this priority**: This is the recommended way to enable remote caching for an entire project with a single configuration change.
-
-**Independent Test**: Declare `caches.default` pointing to S3, run several tasks that do not explicitly reference any cache, and confirm each pushes results to the S3 bucket.
-
-**Acceptance Scenarios**:
-
-1. **Given** `caches.default` is declared with an S3 backend, **When** a task that does not reference any named cache runs and succeeds, **Then** its result is pushed to the S3 bucket specified in `caches.default`.
-
-### User Story 4 - Choose a change-detection method for a cache (Priority: P2)
-
-A developer with a large source tree wants faster change detection. They configure a named cache to use `modify-date` instead of `checksum`. A CI workflow that must always rebuild configures a cache with `none` method.
-
-**Why this priority**: Method selection lets users trade precision for speed or disable skipping entirely for correctness-critical pipelines.
-
-**Independent Test**: Configure a task with `method: none`; run it twice and confirm it always executes. Configure a task with `method: modify-date`; run it twice without touching files and confirm it is skipped.
-
-**Acceptance Scenarios**:
-
-1. **Given** a cache with `method: none`, **When** any task using that cache is invoked, **Then** the task always executes, regardless of source file state.
-2. **Given** a cache with `method: checksum` (default), **When** source file content is identical to the previous run, **Then** the task is skipped.
-3. **Given** a cache with `method: modify-date`, **When** source file modification timestamps are unchanged, **Then** the task is skipped without computing checksums.
-
-### Edge Cases
-
-- Two built-in caches are always available: `default` (local backend, checksum method) and `none` (disables skipping).
-- Declaring `caches.default` overrides the built-in `default` cache for all tasks that do not explicitly reference a cache.
-- The `--cache` CLI flag overrides the method for implicit (non-explicitly-referenced) tasks at runtime and takes precedence over what `caches.default` declares for the method.
-- S3 credentials are never stored in the build file; they are read from the AWS SDK credential chain.
-- Azure Blob Storage is explicitly unsupported through the built-in `s3` backend.
-- Any S3-compatible service (MinIO, Cloudflare R2, GCS via HMAC keys) can be used via the `endpoint` field.
-- `forcePathStyle` defaults to `true` when a custom `endpoint` is set.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The build file MUST support a top-level `caches:` map where each entry declares a named cache with a `method` and a `backend`.
-- **FR-002**: Each cache entry MUST support a `method` field with values `checksum` (default), `modify-date`, or `none`.
-- **FR-003**: Each cache entry MUST support a `backend` field specifying the storage backend type (`local` or `s3`).
-- **FR-004**: The `local` backend MUST accept an optional `path` field; when omitted it MUST default to `~/.hammerkit/remote-cache`.
-- **FR-005**: The `s3` backend MUST require a `bucket` field and accept optional `region`, `endpoint`, `prefix`, and `forcePathStyle` fields.
-- **FR-006**: S3 credentials MUST be sourced from the AWS SDK credential chain and MUST NOT be stored in the build file.
-- **FR-007**: Before a task runs, the system MUST attempt to pull a cached result from the backend if no local result is present; if the sources are unchanged, the task MUST be skipped.
-- **FR-008**: After a task completes successfully, the system MUST push the result to the configured backend.
-- **FR-009**: Backend errors during pull or push MUST emit a warning and MUST NOT cause the build to fail.
-- **FR-010**: Declaring `caches.default` MUST override the built-in default cache for all tasks that do not explicitly reference a named cache.
-- **FR-011**: A built-in `none` cache MUST always be available, which disables task skipping entirely.
-- **FR-012**: A task MUST be able to reference a named cache by setting `cache.name` in its task configuration.
-
-### Key Entities
-
-- **Cache**: A named entry in the `caches:` map; contains a `method` (change detection strategy) and a `backend` (storage configuration).
-- **Local Backend**: Stores cache entries on the local filesystem; configurable via a `path` field.
-- **S3 Backend**: Stores cache entries in an S3-compatible bucket; configurable via `bucket`, `region`, `endpoint`, `prefix`, and `forcePathStyle`.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: An unchanged task is skipped on the second invocation when using the default local cache with `checksum` method.
-- **SC-002**: A task result pushed from one machine is pulled and skips execution on a second machine using the same S3-backed cache configuration.
-- **SC-003**: A build completes successfully even when the configured S3 backend is unreachable, with a warning visible in the output.
-- **SC-004**: Declaring `caches.default` with an S3 backend causes all tasks (that do not explicitly reference a different cache) to push their results to that S3 bucket.
-- **SC-005**: A task using `method: none` executes on every invocation regardless of whether source files have changed.
-
-## Assumptions
-
-- The `cache.name` field on a task (referencing a named cache) is the task-level hook into this feature; full task-level caching options are covered by the task/caching spec page.
-- The `--cache` CLI flag controls the method for tasks using the implicit default cache; it does not affect tasks that explicitly reference a named cache by name.
-- "Pulling" a cached result means restoring the task's `generates:` outputs so downstream tasks can use them without re-running the producing task.
-- The `checksum` method hashes file content; `modify-date` compares filesystem mtime; both apply to the files listed in the task's `src:` field.

package/specs/build-file/environment-variables/spec.md

@@ -1,82 +0,0 @@
-# Feature Specification: Build File: Environment Variables
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/environment-variables.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Pass shell environment variables into a task (Priority: P1)
-
-A developer needs a task to use a variable (e.g. `VERSION`) that is set in the shell before running hammerkit. They declare the variable in the task's `envs:` block referencing the shell value (`$VERSION`). Hammerkit validates the variable is set and injects it into the task execution environment.
-
-**Why this priority**: This is the most common env-var pattern; it prevents silent failures from unset variables.
-
-**Independent Test**: Export a variable in the shell, declare it in the task `envs:`, run the task, and confirm the command receives the correct value. Then unset the variable and confirm hammerkit throws an error rather than passing an empty value.
-
-**Acceptance Scenarios**:
-
-1. **Given** a shell variable `VERSION=1.0.0` is exported, **When** a task declares `VERSION: $VERSION` in its `envs:` and runs `echo $VERSION`, **Then** the output is `1.0.0`.
-2. **Given** a task declares `VERSION: $VERSION` but the shell variable is not set, **When** the task is invoked, **Then** hammerkit throws an error before executing any commands.
-
-### User Story 2 - Use .env file for secret values (Priority: P2)
-
-A developer stores sensitive credentials (e.g. `NPM_TOKEN`) in a `.env` file that is excluded from version control. The task `envs:` block references the variable using the `$NPM_TOKEN` syntax. Hammerkit reads the `.env` file and makes the value available to the task.
-
-**Why this priority**: Keeps secrets out of the build file and version history while still being available during task execution.
-
-**Independent Test**: Create a `.env` file with `NPM_TOKEN=abc`, declare it in the task `envs:`, run the task, and confirm the token is available to the command.
-
-**Acceptance Scenarios**:
-
-1. **Given** a `.env` file containing `NPM_TOKEN=abc`, **When** a task declares `NPM_TOKEN: $NPM_TOKEN` in its `envs:` and is executed, **Then** the command receives `NPM_TOKEN=abc`.
-
-### User Story 3 - Define environment variables in the build file (Priority: P2)
-
-A developer defines default values for environment variables at the top-level `envs:` block or within a specific task's `envs:` block. Task-level declarations override the file-level defaults for that task only.
-
-**Why this priority**: Centralises configuration that does not change per-developer while allowing per-task overrides.
-
-**Independent Test**: Declare `NODE_VERSION: 14.16.0` at the top level and `NODE_VERSION: 14.0.0` inside one task's `envs:`. Run each task and verify each receives the correct version string.
-
-**Acceptance Scenarios**:
-
-1. **Given** `NODE_VERSION: 14.16.0` is declared in the top-level `envs:`, **When** a task that does not override it runs `echo $NODE_VERSION`, **Then** the output is `14.16.0`.
-2. **Given** a task declares `NODE_VERSION: 14.0.0` in its own `envs:`, **When** that task runs, **Then** its value (`14.0.0`) takes precedence over the top-level value.
-3. **Given** top-level `envs:` are declared in file A, **When** a task from a referenced or included build file B runs, **Then** it does NOT have access to file A's top-level env vars.
-
-### Edge Cases
-
-- Referencing an undefined shell variable that is not in `.env` causes a hard error before task execution begins.
-- Variables declared in a build file's top-level `envs:` are scoped to that file; they do not leak into referenced or included build files.
-- The `.env` file is loaded relative to the project directory containing the build file.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST support declaring environment variables in the top-level `envs:` map of a build file, making them available to all tasks in that file.
-- **FR-002**: The system MUST support declaring environment variables in a task-level `envs:` map, overriding any same-named top-level declaration for that task.
-- **FR-003**: The system MUST resolve `$VAR` references in `envs:` values from the shell environment at the time the task is executed.
-- **FR-004**: The system MUST read environment variable values from a `.env` file in the project directory and make them available for `$VAR` resolution.
-- **FR-005**: The system MUST throw an error if an `envs:` entry references a shell or `.env` variable that is not defined, rather than passing an empty or undefined value to the task.
-- **FR-006**: Top-level `envs:` declarations MUST be scoped to the build file in which they are defined and MUST NOT be visible to referenced or included build files.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task that declares a shell-sourced env var receives the correct value when the variable is set, and hammerkit exits with a non-zero code and an error message when the variable is unset.
-- **SC-002**: A task that sources a value from `.env` receives the correct value without the secret appearing in the build file.
-- **SC-003**: A task-level `envs:` declaration overrides a file-level declaration for the same variable name within that task only.
-- **SC-004**: Tasks in a referenced or included build file do not inherit top-level env vars from the including build file.
-
-## Assumptions
-
-- `.env` file loading is automatic; no explicit declaration in the build file is needed beyond the `$VAR` reference in `envs:`.
-- Variables defined as literal values in `envs:` (not using `$VAR` syntax) are always available and require no shell validation.
-- The precedence order (most specific wins) is: task-level `envs:` > top-level `envs:` > `.env` file > shell environment, though the docs do not enumerate this explicitly; this assumption is recorded here for review.

package/specs/build-file/includes/spec.md

@@ -1,60 +0,0 @@
-# Feature Specification: Build File: Includes
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/includes.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Reuse a shared task definition across multiple projects (Priority: P1)
-
-In a monorepo with multiple packages that each have a `package.json`, a developer extracts the common `npm install` task into a shared `build.npm.yaml` file at the repo root. Each package's build file declares an `includes:` entry pointing to that shared file under the alias `npm`. The `npm:install` task is then available as a dependency in each package and executes with the working directory set to the package that included it — not the location of the shared file.
-
-**Why this priority**: Includes are the canonical way to eliminate duplicated task definitions in monorepos; getting the working directory right is the core value proposition.
-
-**Independent Test**: Create a shared build file with a task that writes a file. Include it in two different package build files. Run `hammerkit npm:install` from each package context and confirm the output file is written to the respective package directory, not the shared file's directory.
-
-**Acceptance Scenarios**:
-
-1. **Given** `build.npm.yaml` at the repo root defines task `install`, and `packages/a/.hammerkit.yaml` declares `includes: { npm: ../../build.npm.yaml }`, **When** the user runs `npm:install` in the context of package `a`, **Then** the task executes with the working directory set to `packages/a/`.
-2. **Given** the same shared file is included in `packages/b/.hammerkit.yaml`, **When** `npm:install` runs in package `b`'s context, **Then** the working directory is `packages/b/`, independent of package `a`.
-3. **Given** `packages/b/.hammerkit.yaml` declares `deps: [npm:install, a:build]`, **When** the build task runs, **Then** `npm:install` runs in `packages/b/`'s working directory and `a:build` runs as a reference with `packages/a/`'s working directory.
-
-### Edge Cases
-
-- Includes differ from references in that the working directory is the location of the including build file, not the location of the included file.
-- Top-level `envs:` from the including build file are not visible to tasks in the included build file.
-- An included file can itself declare further references, mixing the two mechanisms as shown in the monorepo example.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The build file MUST support a top-level `includes:` map where each key is an alias and each value is a path to a shared build YAML file.
-- **FR-002**: Tasks from an included build file MUST be addressable using the `<alias>:<task-name>` notation from the CLI and in task `deps:` lists.
-- **FR-003**: When a task from an included build file executes, the working directory MUST be the directory of the build file that declared the `includes:` entry, NOT the directory of the included file.
-- **FR-004**: The same shared build file MAY be included by multiple build files, with each inclusion using the working directory of the including file independently.
-- **FR-005**: Includes and references MAY be combined in the same build file, allowing tasks from included files to coexist with tasks from referenced sub-projects as dependencies.
-
-### Key Entities
-
-- **Include**: A named entry in the `includes:` map; the key is the alias used to prefix task names, the value is the relative path to the shared build YAML file.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task sourced from an included build file runs with the working directory of the including project, not the directory where the shared file resides.
-- **SC-002**: The same shared task file included by two different packages produces independent executions, each in their own package directory.
-- **SC-003**: A build file that combines `includes:` and `references:` correctly resolves both sets of task namespaces and executes each with the correct working directory.
-
-## Assumptions
-
-- Include paths are relative to the directory of the build file containing the `includes:` block.
-- Included files are standard hammerkit build YAML files and may contain any valid build file content (`tasks:`, `envs:`, etc.).
-- The working-directory rule applies to all task types within an included file (container tasks and local tasks alike), though the docs only illustrate local tasks.
-- Unlike references, includes do not require the target path to be a directory — they point directly to a `.yaml` file.

package/specs/build-file/references/spec.md

@@ -1,56 +0,0 @@
-# Feature Specification: Build File: References
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/references.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Run a task from a referenced sub-project (Priority: P1)
-
-A developer has a monorepo with multiple sub-directories, each containing its own build file. They declare a `references:` map in the root build file, giving each sub-project a short alias. They can then invoke tasks in those sub-projects from the CLI using the `<alias>:<task>` syntax, or declare them as dependencies in root tasks.
-
-**Why this priority**: References are the primary mechanism for composing multi-project builds from a single entry-point build file.
-
-**Independent Test**: Create a root build file with a reference to a sub-directory build file. Run `hammerkit <alias>:<task>` and confirm the task in the sub-project executes.
-
-**Acceptance Scenarios**:
-
-1. **Given** a root build file declares `references: { foo: project/foo }`, and `project/foo/.hammerkit.yaml` contains a task named `example`, **When** the user runs `hammerkit foo:example`, **Then** the `example` task from `project/foo` executes.
-2. **Given** a root task declares `foo:example` in its `deps:`, **When** that root task runs, **Then** `foo:example` is executed as a prerequisite with the working directory fixed to `project/foo`.
-
-### Edge Cases
-
-- The working directory for tasks in a referenced build file is fixed to the directory where the referenced build file resides, not the directory of the referencing build file.
-- Top-level `envs:` from the referencing build file are not visible to tasks in the referenced build file.
-- Circular references (A references B which references A) are not discussed in the docs; behavior is assumed to be an error or undefined.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The build file MUST support a top-level `references:` map where each key is an alias and each value is a path to another project directory containing a build file.
-- **FR-002**: Tasks from a referenced build file MUST be addressable using the `<alias>:<task-name>` notation from the CLI.
-- **FR-003**: Tasks from a referenced build file MUST be usable as dependency entries in the referencing build file's task `deps:` list using the `<alias>:<task-name>` notation.
-- **FR-004**: The working directory for tasks executing in a referenced build file MUST be the directory of that referenced build file, not the directory of the referencing file.
-
-### Key Entities
-
-- **Reference**: A named entry in the `references:` map; the key is the alias used to prefix task names, the value is the relative path to the sub-project directory.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A task in a referenced build file is successfully invoked via `hammerkit <alias>:<task>` and executes with the working directory set to the referenced project directory.
-- **SC-002**: A task in the root build file that lists `<alias>:<task>` as a dependency causes that referenced task to run before the root task's commands execute.
-
-## Assumptions
-
-- The path in the `references:` value points to a directory, and hammerkit locates the build file (`build.yaml` or `.hammerkit.yaml`) within that directory automatically.
-- Reference paths are relative to the directory of the build file containing the `references:` block.
-- Deeply nested references (a reference to a build file that itself references another) are assumed to be supported, though not explicitly documented.

package/specs/build-file/spec.md

@@ -1,62 +0,0 @@
-# Feature Specification: Build File: Overview
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/build-file/README.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Define a project build file (Priority: P1)
-
-A developer creates a `build.yaml` (or `.hammerkit.yaml`) file at the root of their project directory. They declare top-level environment variables, one or more named tasks, references to sub-projects, and includes for shared task files. They then invoke tasks by name via the hammerkit CLI.
-
-**Why this priority**: The build file is the central configuration artifact; all other hammerkit features depend on it.
-
-**Independent Test**: Create a minimal build file with a single task and verify `hammerkit <task>` executes it.
-
-**Acceptance Scenarios**:
-
-1. **Given** a project directory, **When** a `build.yaml` file is placed there with a valid `tasks:` block, **Then** hammerkit discovers and executes named tasks from that file via the CLI.
-2. **Given** a build file with a top-level `envs:` block, **When** a task is run, **Then** the declared environment variables are available to the task commands.
-3. **Given** a build file with `references:` and `includes:` blocks, **When** hammerkit starts, **Then** it loads the referenced and included build files and makes their tasks available under the appropriate namespaced names.
-
-### Edge Cases
-
-- A build file with no `tasks:` block is valid but produces no executable targets.
-- The filename may be `build.yaml` or `.hammerkit.yaml`; behavior is identical.
-- Top-level `envs:` are scoped to the build file where they are declared and do not propagate to referenced or included files.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: The system MUST read build configuration from a YAML file named `build.yaml` or `.hammerkit.yaml` located in the project directory.
-- **FR-002**: The build file MUST support a top-level `envs:` map for declaring environment variables shared across all tasks in that file.
-- **FR-003**: The build file MUST support a top-level `tasks:` map where each key is a task name and the value is the task configuration.
-- **FR-004**: The build file MUST support a top-level `references:` map pointing to other build files in sub-directories.
-- **FR-005**: The build file MUST support a top-level `includes:` map pointing to shared build files whose tasks are merged under a namespace.
-- **FR-006**: Tasks declared in a build file MUST be invocable by name via the hammerkit CLI.
-
-### Key Entities
-
-- **Build File**: A YAML file (`build.yaml` / `.hammerkit.yaml`) containing `envs`, `tasks`, `references`, and `includes` top-level keys.
-- **Task**: A named unit of work inside the `tasks:` map; may declare commands, dependencies, source files, and generated outputs.
-- **Reference**: A named pointer to another project directory containing its own build file.
-- **Include**: A named pointer to a shared build YAML file whose tasks are reused with the working directory of the including file.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: A build file with all four top-level sections (`envs`, `tasks`, `references`, `includes`) loads without errors and all tasks are accessible via the CLI.
-- **SC-002**: Environment variables defined in the top-level `envs:` block are resolved correctly within tasks in the same file and are not visible in referenced or included files.
-
-## Assumptions
-
-- The primary filename used in examples is `.hammerkit.yaml`; `build.yaml` is also accepted based on the docs description.
-- The `caches:` top-level key (introduced in 1.6.0) exists in the build file schema but is covered by its own spec page.
-- Task-level details (image, cmds, deps, src, generates) are covered by the Task spec pages, not this overview.

package/specs/cli/clean/spec.md

@@ -1,85 +0,0 @@
-# Feature Specification: CLI: clean
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/cli/clean.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Remove generated outputs and local cache state for a clean rebuild (Priority: P1)
-
-A developer suspects their build is producing stale results due to a previous cached state. They run `hammerkit clean` to delete all generated directories and files as well as hammerkit's per-task cache state for the current checkout, then re-run tasks to verify everything builds from scratch.
-
-**Why this priority**: The primary purpose of `clean` is to reset local state so that builds are fully reproducible without prior artifacts.
-
-**Independent Test**: Run a task that produces a `generates` output. Run `hammerkit clean`. Confirm the generated output no longer exists and that hammerkit re-executes the task on the next run regardless of unchanged inputs.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks have been run and generated outputs and cache state exist, **When** `hammerkit clean` is run, **Then** all generated outputs and per-task local cache state are removed.
-
-2. **Given** `hammerkit clean` has completed, **When** a task is run again with unchanged inputs, **Then** hammerkit re-executes the task because the local cache state is absent.
-
-### User Story 2 - Drop stored remote/backend cache results to force a full rebuild (Priority: P2)
-
-A developer encounters a persistent caching issue and needs to force the next run to rebuild from scratch even against a configured cache backend (local result store or remote, e.g. S3). They run `hammerkit clean --cache` to also purge stored results from the backend.
-
-**Why this priority**: The `--cache` flag addresses a deeper reset need when the standard clean is insufficient due to a populated cache backend.
-
-**Independent Test**: Configure a cache backend. Run tasks so results are stored in the backend. Run `hammerkit clean --cache`. Confirm the backend has no stored results for the project and that the next run rebuilds all tasks.
-
-**Acceptance Scenarios**:
-
-1. **Given** a configured cache backend with stored task results, **When** `hammerkit clean --cache` is run, **Then** the stored results in the backend (local `~/.hammerkit/remote-cache` or remote) are deleted in addition to generated outputs and local cache state.
-
-2. **Given** `--cache` is omitted, **When** `hammerkit clean` is run, **Then** stored results in the cache backend are preserved; only local generated outputs and per-task cache state are removed.
-
-### User Story 3 - Clean a subset of tasks and services using label filters (Priority: P2)
-
-A developer wants to clean only a specific subset of tasks without affecting others. They use `--filter` or `--exclude` with label selectors to target or omit specific tasks and services.
-
-**Why this priority**: Label-scoped clean reduces disruption to unrelated tasks in large build files.
-
-**Independent Test**: Tag two tasks with different labels. Run both. Run `hammerkit clean --filter <label>`. Confirm only the filtered task's outputs and cache state are removed while the other task's outputs remain.
-
-**Acceptance Scenarios**:
-
-1. **Given** tasks are labeled, **When** `hammerkit clean --filter <label>` is run, **Then** only the tasks and services matching the label are cleaned.
-
-2. **Given** tasks are labeled, **When** `hammerkit clean --exclude <label>` is run, **Then** tasks and services matching the label are skipped and all others are cleaned.
-
-### Edge Cases
-
-- Running `hammerkit clean` when no tasks have been run (no generated outputs, no cache state) should complete without error.
-- `hammerkit clean --cache` removes the local result store at `~/.hammerkit/remote-cache` or a configured remote backend, not just the per-checkout cache state.
-- Label filters apply to both tasks and services, consistent with their behavior in other commands.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST remove all generated outputs (files and directories declared via `generates`) for all tasks and services in the current checkout when `hammerkit clean` is run.
-- **FR-002**: System MUST remove the per-task local cache state for the current checkout when `hammerkit clean` is run.
-- **FR-003**: When `--cache` is supplied, system MUST additionally delete stored results from the configured cache backend (defaulting to `~/.hammerkit/remote-cache` for local backends).
-- **FR-004**: System MUST support `-f`/`--filter` and `-e`/`--exclude` label options to restrict which tasks and services are cleaned.
-- **FR-005**: System MUST complete without error when there are no generated outputs or cache state to remove.
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit clean`, no generated output directories or files from any task's `generates` field exist in the working tree.
-- **SC-002**: After `hammerkit clean`, running any task re-executes it fully regardless of whether its inputs have changed.
-- **SC-003**: After `hammerkit clean --cache`, the cache backend contains no stored results for the project and the next run rebuilds all tasks from source.
-- **SC-004**: After `hammerkit clean --filter <label>`, only tasks matching the label have their outputs and cache state removed; all other task outputs remain intact.
-
-## Assumptions
-
-- "Per-task cache state" refers to the hammerkit-internal tracking of input hashes used to determine whether a task is up to date; this is distinct from stored build results in the cache backend.
-- The `--cache` flag targets whatever backend is configured in the build file's `caches` section, defaulting to the local result store at `~/.hammerkit/remote-cache`.
-- The `clean` command does not prompt for confirmation; it is destructive by design.
-- There is no `--dry-run` option documented; the command always performs the deletion.

package/specs/cli/down/spec.md

@@ -1,85 +0,0 @@
-# Feature Specification: CLI: down
-
-**Feature Branch**: `001-current-state-specs`
-
-**Created**: 2026-05-30
-
-**Status**: Current State (reverse-specified from docs, hammerkit 1.6.0)
-
-**Input**: Existing behavior documented in `docs/cli/down.md`
-
-## User Scenarios & Testing *(mandatory)*
-
-### User Story 1 - Stopping all running services (Priority: P1)
-
-A developer has finished their work session and wants to free the resources held by services that were started with `hammerkit up` (foreground or daemon). They run `hammerkit down` and all services defined in the build file are stopped.
-
-**Why this priority**: `down` is the natural complement to `up` and the primary way to cleanly release containerized service resources.
-
-**Independent Test**: Start services with `hammerkit up --daemon`, then run `hammerkit down` and verify that all service containers are no longer running.
-
-**Acceptance Scenarios**:
-
-1. **Given** services started with `hammerkit up --daemon`, **When** the user runs `hammerkit down`, **Then** all services defined in the build file are stopped and exit cleanly.
-
-2. **Given** services started with `hammerkit up` (foreground, now interrupted), **When** the user runs `hammerkit down`, **Then** any remaining service containers are stopped.
-
-3. **Given** no services currently running, **When** the user runs `hammerkit down`, **Then** the command exits with code 0 without error.
-
-### User Story 2 - Stopping a subset of services by label (Priority: P2)
-
-A developer is running multiple services and wants to stop only a specific subset without affecting others. They use `--filter` or `--exclude` to target the relevant services.
-
-**Why this priority**: Label filtering is consistent across all service-related commands and supports fine-grained lifecycle control in complex builds.
-
-**Independent Test**: Start two labeled services, run `hammerkit down -f <label>` matching only one, and verify the other remains running.
-
-**Acceptance Scenarios**:
-
-1. **Given** multiple services with different labels, **When** the user runs `hammerkit down -f <label>`, **Then** only services matching the label are stopped; others remain running.
-
-2. **Given** multiple services with different labels, **When** the user runs `hammerkit down -e <label>`, **Then** services matching the excluded label are not stopped; all others are stopped.
-
-### User Story 3 - Stopping services in a named environment (Priority: P3)
-
-A developer has services running in a Kubernetes environment and wants to stop them without affecting local Docker services. They pass `--env <name>` to target that environment.
-
-**Why this priority**: Multi-environment support is consistent with `up` but is a power-user scenario.
-
-**Independent Test**: Given services running in a named Kubernetes environment, run `hammerkit down --env <name>` and verify those services stop while local Docker services are unaffected.
-
-**Acceptance Scenarios**:
-
-1. **Given** services running in a named environment, **When** the user runs `hammerkit down --env <name>`, **Then** services in that environment are stopped.
-
-### Edge Cases
-
-- `hammerkit down` with no running services must not error.
-- `hammerkit down -f <label>` where no services match the label must exit with code 0 without affecting other services.
-- `--filter` and `--exclude` used together must apply both constraints; services matching both conditions are excluded.
-
-## Requirements *(mandatory)*
-
-### Functional Requirements
-
-- **FR-001**: System MUST stop all services defined in the build file when `hammerkit down` is run without filter options.
-- **FR-002**: System MUST support label-based inclusion filtering via `-f / --filter <key=value>` to stop only matching services.
-- **FR-003**: System MUST support label-based exclusion filtering via `-e / --exclude <key=value>` to skip stopping matching services.
-- **FR-004**: System MUST support an `--env <name>` option to stop services in a configured named environment.
-- **FR-005**: System MUST exit with code 0 when no services are running (idempotent stop).
-
-## Success Criteria *(mandatory)*
-
-### Measurable Outcomes
-
-- **SC-001**: After `hammerkit down`, no service containers defined in the build file remain in a running state.
-- **SC-002**: `hammerkit down` exits with code 0 regardless of whether services were running before the command.
-- **SC-003**: With `-f <label>`, only services bearing that label are stopped; services with other labels continue running.
-- **SC-004**: With `--env <name>`, only services in the named environment are stopped; services in other environments are unaffected.
-
-## Assumptions
-
-- `hammerkit down` targets the same set of services as the corresponding `hammerkit up` invocation when no filters are applied.
-- The command does not require that services were started specifically via `hammerkit up`; it stops matching service containers regardless of how they were started.
-- `down` has no `--daemon`, `--concurrency`, `--watch`, `--log`, or `--cache` options (these do not appear in the documented option list).
-- Stopping a service that is not running is treated as a success (idempotent), consistent with the "no error on empty" edge case documented implicitly.