Goal on Alwaldend

Mon, 01 Jan 0001 00:00:00 +0000

Goal graph organization

Use this reference when one objective may need related goals, parallel work, or dependency-aware resumption. The graph is a view over ordinary local Goal resources. The execution harness remains responsible for scheduling and permissions.

Decide whether to decompose

Keep ordinary ordered steps in one attempt plan. Create a separate goal only when the subgoal benefits from at least one independent property:

lifecycle or resumption;
acceptance criteria and evidence;
ownership or retention;
substantial parallel execution; or
reuse by more than one objective.

The coordination cost of another goal and edge must be lower than the value of making that boundary explicit.

Mon, 01 Jan 0001 00:00:00 +0000

Attempt lifecycle and evidence

Use this reference for maintained goals, repeated failures, and complex coordination. Ordinary progress uses the compact checkpoint workflow in the skill entry point.

Plan before work

One attempt is a bounded work unit with one reviewable outcome. Establish before implementation:

the observed Goal resource version as the next checkpoint’s compare-and-swap token; the store derives generation, lifecycle, criteria, and digest bindings rather than requiring manual transcription;
the uncertainty or stable defect being targeted;
work type and hypothesis when the work tests one;
the smallest high-leverage module or question, its stop condition, and the minimum whole-result context needed to detect interface or integration harm;
the plan, inputs, parameters, intended result identity, and review packet;
affected criteria and the fixed regression checks; and
parent checkpoint or prior attempt when one exists.

Preflight deterministic geometry, numeric gates, controlling references, paths, APIs, tools, permissions, and whether the proposed artifact can satisfy its own acceptance gate. Preserve material preflight evidence without turning discarded prose drafts into fake attempts.

Mon, 01 Jan 0001 00:00:00 +0000

Promotion and migration

Use this reference only when promoting a workspace goal or importing an unversioned record.

Promote workspace to project

Promotion changes storage and retention, not goal identity. It must:

require an explicit maintained-project decision and an owning project root;
lock the source and destination paths in canonical order, then validate the source at an expected resource version;
preserve the goal ID and closed attempt history;
record source scope and promotion provenance;
require repository-relative or stable external links;
retain, copy, or make reproducible every acceptance-critical artifact;
scan for absolute local paths, credentials, private environment details, and ignored evidence that would become broken; and
validate and render the destination before making it canonical.

Do not promote caches or routine coordination logs. Refuse a destination that would shadow another goal with the same ID or that cannot retain critical evidence. Leave the workspace source intact until the destination is verified.

Mon, 01 Jan 0001 00:00:00 +0000

Goal resource format v1alpha1

Use this reference for checkpoint payloads, criteria changes, record semantics, or validation errors. Ordinary resume uses the CLI’s bounded view. The files use Kubernetes-style resource envelopes for familiar versioning and evolution; they are portable local records, not Kubernetes objects or CRDs.

Layout

The same directory shape is used in both scopes:

<goal-id>/
  goal.yaml
  criteria.yaml
  criteria-revisions/
    <revision>.yaml
  README.md
  attempts/
    <attempt-id>/
      attempt.yaml
      plan.md
      result.md
      evidence/

Workspace records normally live at out/<task>/goals/<goal-id>/. The recommended direct-initialization layout for project records is <owner-root>/goals/<goal-id>/. This is guidance rather than a CLI constraint; direct initialization, promotion, and migration accept other safe in-workspace roots. A goal ID is stable across promotion and must not be reused.

Mon, 01 Jan 0001 00:00:00 +0000

Sessions and concurrency

Use this reference when resuming, switching goals, delegating, or reconciling a stale update.

Many records, one focus

A goal is identified by its stable goal ID and scope, not by a chat thread. A GoalSessionBinding is a replaceable pointer to the current goal. Its attachment-time generation, revision, and digest fields only detect whether that pointer’s view has become stale. List and inspect stored goals before attaching when identity is uncertain. Starting a new session must not create a duplicate merely because the old thread is unavailable.

Mon, 01 Jan 0001 00:00:00 +0000

Goal

Keep the objective, acceptance check, current candidate, evidence, and next action inspectable. The CLI owns record identity, revisions, digests, locking, and interrupted-write recovery. Use it instead of editing canonical YAML or generated README projections.

Ordinary tasks

Use an ignored workspace goal under out/<task>/goals/<goal-id>/. A project goal under <owner-root>/goals/<goal-id>/ is appropriate only when the user requests, or the project establishes, maintained history. Length alone does not justify committed records. A question grants no new mutation authority.

Goal architecture

Mon, 01 Jan 0001 00:00:00 +0000

Goal architecture

The goal tool is a local CLI for one coordinator working on a goal at a time. It edits ordinary files inside the workspace. It does not require a service, daemon, database, controller, or network connection.

The tool release is 0.0.1. The independent resource-schema version is goals.alwaldend.com/v1alpha1; v1alpha1 describes schema stability and does not imply a stable tool release.

Goal pursuit loop

The pursuit loop belongs to the goal skill and its coordinator. The CLI does not schedule or perform the work; it validates and checkpoints the state transitions chosen by the coordinator.