# Artifacts Weyaw stores durable workflow evidence in the initialized project workspace, normally `.aw/`. Use Weyaw commands and skills to mutate registered artifacts; do not hand-edit task state or lifecycle JSON. ## Project-level surfaces - `project.md` — project goal, users, constraints, decisions, and source evidence. - `blueprint/` — durable specifications, standards, vocabulary, and core guidance such as `aw.md`. A root such as `spec-example.md` may own a matching `spec-example/` directory of canonical Markdown children. Nested ids are Blueprint-relative paths without `.md`, inherit the root role and heading template, and must all be reachable through ordered `## Components` links. Composition is a bounded read-only projection, not another artifact. - `roadmap/phases.json` — ordered phases and auxiliary per-phase `item_order`; `roadmap/items/.json` — authoritative item existence, phase, lifecycle, intentions, and task references. Reads keep valid unlisted items visible; normal mutations atomically publish one business file under a shared runtime lock. This is the only current roadmap layout. - `knowledge/` — retained project knowledge written through the knowledge command. - `config.toml` — strict, versionless project settings. The file contains complete explicit values for `repositories`, `services`, `agent_server`, `index_server`, `actions`, `triggers`, `order_presets`, `profiles`, `task`, `docs`, `signal`, and `language`; it does not store runtime identity, artifact-root ownership, update timestamps, Dashboard lifecycle, deprecated provider-total budgets, or the fixed retry-exhaustion result. Repository kinds are fixed to `git` and `none`: Git-only commit, worktree, review, and restore behavior is selected only for configured `vcs = "git"`, while `vcs = "none"` retains Git-independent read, write, index, and source-writable Agent behavior without discovering or launching Git. Official Action and Trigger identities are immutable. Fresh config initializes empty `explorer`, `thinker`, `reviewer`, `executor`, `light-reviewer`, and `light-executor` presets so provider choices remain user-owned. Normal reads accept only this current shape. `aw config repair` restores missing or incorrectly typed current-template fields from recognized current settings and does not interpret retired names, values, or files. Every AW config writer uses one short exclusive lock at `.aw/.runtime/locks/config.lock`. A mutation rereads the stored bytes inside the lock, rejects a stale load-time SHA-256 digest, validates the full candidate, patches the TOML document, and atomically replaces the file. Raw `${project_root}` and `${artifact_root}` expressions, comments, and representable formatting remain stored; resolved paths are runtime or Settings-preview projections only. Init, explicit repair, and full reset may generate the informational `# Generated by aw ...` comment. Ordinary saves preserve that comment if present but do not update or create it. When config validation returns both missing and redundant structural fields, AW retains `artifact_validation` and adds explicit CLI-artifact skew evidence: current project-config fingerprint, resolved executable path, executable mtime, and config mtime. One-sided or non-structural failures are not labeled as skew. ## Task-level surfaces Tasks live under lifecycle directories such as `tasks/todo/`, `tasks/active/`, and `tasks/archive/`. A task may contain: - `intention.md` and `task-status.json`; tracked `brainstorm`, `analyze`, `plan`, `verify`, and `review` records carry ordered todo DAG nodes with stable ids, explicit `depends_on[]`, and `todo | doing | done` status; - `analysis.json` and `plan.json`; Plan steps own approved Execute dependencies, while Plan schema version 3 requires task-wide `accepted_limits[]` for delivery boundaries explicitly confirmed by the user; - `execution.json` and `action-log.json`; Execute progress lives here rather than in task-status todos. Plan-backed rows omit `title` and keep execution `depends_on: []` because title, abstract, and edges derive from Plan. Titled execution-only work owns explicit dependencies and deviation evidence discovered after Plan approval; - `verify.json` and `review.md`; Verify schema version 2 requires `open_risks[]` for unresolved issues discovered during Execute or Verify. Concrete check evidence stays in `checks[]`; there is no separate failure collection or risk-acceptance flag; - `summary.jsonl` and blueprint feedback. Agent evidence is centralized under `.aw/agents` and projected into task views through group ownership. The compiled artifact template registry is the sole structural contract source. `aw contract list` and `show` expose stable ids, ownership reasons, owning write commands, deterministic SHA-256 fingerprints, shapes, headings, and canonical examples; `aw contract validate` checks caller-supplied JSON, TOML, line-aware JSONL, Markdown, or text without writing. Structural rejection returns the complete deterministic issue batch with ownership evidence. Current task JSON uses one strict shape: independently meaningful fields are required and empty collections are written explicitly as `[]`. Dependency arrays on tracked todos and execution rows are explicit in the current schema and every current writer emits them. Graph validation rejects missing references, self-edges, duplicate edges, cycles, and active or done nodes whose predecessors are not accepted done. `task-status.json`, `action-log.json`, `task-config.json`, `analysis.json`, `plan.json`, `execution.json`, `verify.json`, `consolidate.json`, `commit.json`, and `blueprint-update.json` each carry one root `schema_version`, `agent_runtime`, and `workflow_runtime`. The Host obtains its real Agent `name=version` from its own environment and registers it at task creation or resume; AW copies that current task-session author value into changed JSON and always overwrites `workflow_runtime` with its executing version. Runtime metadata describes the current file snapshot and never selects an older parser or relaxes the current Schema. Action-log rows require a concise summary but do not repeat runtime fields; action-specific sessions, adapters, commands, fallback decisions, and contributors remain in owning evidence. JSONL artifacts retain per-record source/provenance instead of receiving a file envelope. Tracked Todo ids, Plan step ids, and execution `plan_step_id` values use 1..64 ASCII characters from `[A-Za-z0-9._-]`. Authored Todo, Plan, and execution-only titles are limited to 32 display columns, while their required `abstract` values are limited to 256 display columns. Length-gated `title` and `abstract` values are single-line and contain no control character, because a newline costs one column at the gate but produces a whole additional rendered line. Plan steps use their owning arrays rather than a generic `notes[]` field. Each natural-language value states the shortest complete fact uniquely owned by that field without abbreviating exact commands, paths, identifiers, or error text. `AccessMode` is one ordered lowercase enum, `none < read < write`, reused only with an explicit named resource boundary. Every Plan step persists required `project_access` as an intentional redundant check against its project-content scopes: `none` requires empty `target_files[]` and `read_first[]`; `read` requires empty targets and non-empty reads; `write` requires both arrays non-empty. All steps require non-empty `implementation[]`, `verification[]`, `convergence[]`, and `acceptance[]`. Task and workflow artifacts, runtime state, build output, and Host command persistence are not project-content targets or inputs. Strict Plan validation owns these deterministic checks before Plan completion; Execute only rereads the same contract defensively. Every Agent launch creates one durable group under `.aw/agents//`, including singleton groups with `group_size = 1`. `group.json` alone owns task or project attribution. Each session persists one semantic `agent_id`, one authored title of at most 48 display columns, one objective, and subordinate turns; group assignment `id` maps directly to `agent_id`. Durable identity is `group → session → turn`, and current readers require that identity. `blueprint-update.json` keeps `roadmap_progress_updates[]` and `events[]` under their existing generic record contracts, but `blueprint_candidates[]` is strict. Each candidate requires `id`, `source_step`, `source_artifact`, `target_file`, optional `target_section`, `summary`, `rationale`, `proposed_change`, and exactly one status from `proposed | applied | rejected`; decision metadata never changes the candidate content fields. Only `proposed` to `applied` and `proposed` to `rejected` write. Proposal, application, and rejection append `blueprint-candidate-recorded`, `blueprint-candidate-applied`, and `blueprint-candidate-rejected` events respectively, each with timestamp, `source_task_id`, and `blueprint_candidate_id` in the same validated write. Rejection events additionally require `reason` and may contain `replacement_blueprint_candidate_id` for one distinct known task-local candidate. Repeating the same terminal decision performs no write; an applied-to-rejected or rejected-to-applied decision fails. Event timestamps are the durable decision times, so there are no duplicate candidate timestamp fields. Current proposed and applied artifacts remain readable across lifecycle moves, and neither archive nor textual similarity infers candidate decisions. The CLI validates artifact schemas and owns lifecycle moves. The Host mutates tracked todos through typed `aw step todo add|update|remove`; complete-list replacement is repair-only through `--input` or `--input-file `. Normal task JSON is assembled through semantic `aw artifact` commands, registered Markdown is edited through section or exact text operations, and `aw write --input` or `--input-file ` is reserved for complete-document creation or repair. Pi and generated contributors only observe the resulting artifacts. Archived artifacts remain readable for later tasks and index discovery. `task-config.json` freezes execution settings on the first Execute entry and binds the task's worktree mode for the rest of its life. A resumed Host may still refresh only `agent_runtime` through `aw task config --agent-runtime `; this does not change worktree, retry, reverse-feedback, or freeze state. Rollback restarts step work and never changes that binding. Untouched JSON keeps its prior file provenance, while regenerated JSON receives the current registered Agent and AW versions. The single binding exception is `aw task migrate-worktree`, a one-way Host-owned mutation that converts an eligible frozen worktree-disabled task into a worktree-enabled one: it re-reads the task's baseline immediately before publishing, records `worktree_migration` evidence — including the `source_head` it created the checkout at and whether a HEAD-only binding was acknowledged — preserves the original `frozen_at`, and appends `task.worktree_migrated`. There is no reverse direction, so never hand-edit a binding into or out of a frozen config. Archived enabled bindings are retired only through `aw task retire-worktree --reason --confirm`. Before non-force cleanup, the command writes `worktree_retirement` with `status = "in_progress"`, the ordered binding snapshot, `started_at`, and the exact operator reason. After every recorded worktree directory, Git registration, and branch is absent, it writes `status = "completed"` with `completed_at` and appends `task.worktree_retired`. An interrupted operation keeps the in-progress evidence so the same command and reason can resume idempotently; completed replay reports no change only when the recorded resources remain absent. Retirement is terminal for the archived task binding, so rollback refuses to reopen a task once this evidence exists. Verify completion, Commit completion, and archive require `status: "passed"`, `open_risks: []`, and every `checks[].result` to equal `passed`. An issue discovered after Plan cannot become an accepted limit automatically: the task returns to Plan, presents the revised `accepted_limits[]`, and obtains explicit user confirmation. Retired task JSON is not parsed through a compatibility route and Runtime never dispatches an older schema. Repair means an Agent reads the latest template, preserves still-valid semantic facts, supplies its real runtime, and rewrites each invalid file through existing validated AW commands. Weyaw does not provide an artifact migration command, converter, default-filled parser, or automatic semantic rewrite. ## Runtime and generated content `.aw/.runtime/` contains only local, disposable process and cache state beneath the concrete owners `agent-server`, `index-server`, `dashboard`, `locks`, and `tmp`. It is safe to delete after services stop and must be excluded from Git, packages, synchronization, Project Index ingestion, and portable artifact validation. Agent Server generation state under `.aw/.runtime/agent-server` records the directly executed npm/system `aw` path, or the source checkout's `target/debug/aw` path, together with its SHA-256, file instance, package version, canonical artifact root, and worker-runtime config identity. No binary is copied into `.aw`. Owner-specific millisecond heartbeats carry generation, slot, nonce, executable digest, and process-start identity; only fresh matching evidence counts toward operational capacity. Status and readiness are pure observations. Use `aw agent-server restart` for drift or health recovery; restart may retain a draining old generation while its already-running sessions finish under their original timeout. Durable Agent evidence lives under `.aw/agents//sessions//`. Group ownership, session and turn records, prompts, responses, final messages, and numeric event segments remain outside `.aw/.runtime`. Runtime `status`, `observed_changes`, and `review_decision` remain independent evidence: a terminal status does not establish mutation or acceptance, and observed changes do not establish an accepted implementation. Rebuildable Project Index contents live under `.aw/.runtime/index-server`. Durable minimized usage evidence lives under `.aw/logs/project-index/tasks//.jsonl` or `.aw/logs/project-index/project//.jsonl`. Segments are numerically ordered and rotate before 256 records or 512 KiB, except that one oversized record may occupy an oversized segment. Every non-task Agent run still creates a project-owned durable group under `.aw/agents`; temporary control grants and process coordination remain runtime-only. Promote useful Agent conclusions into task, action-log, or knowledge artifacts before treating advisory evidence as workflow authority. Generated agent skill directories such as `.agents/`, `.codex/`, and `.claude/` are project integration surfaces rather than packaged project history. The workflow workspace may be a separate Git repository. Commit tooling treats project changes and workflow artifacts independently and stages only the current archived task scope. See [Concepts](concepts.md) and [CLI](cli.md).