# v0.4.15 — Issue-driven execution

v0.4.15 makes an **existing GitHub issue** a first-class input to the Harness while preserving the existing trust hierarchy: the remote issue is fetched and frozen, then a sealed QuickContract or SDD/TaskContract becomes normative for the active run.

## Goal

A user or Paseo-hosted lead can say:

> Implement issue #142.

The operational equivalent is:

```bash
aeh issue implement 142
```

or:

```bash
aeh run --issue 142
```

The user does not need to manually create an SDD, duplicate the issue, create a branch, create a worktree, select implementers, manage the review/remediation loop, or perform accepted delivery writes when deterministic finalization is enabled.

## Lifecycle

```text
GitHub issue
   |
   v
fetch + validate issue identity/state
   |
   v
freeze title/body + SHA-256 snapshot
   |
   v
intake evidence
(paths, labels/domains, risk, acceptance, flags)
   |
   v
read-only planner normalization when non-trivial
   |
   v
deterministic QUICK/SPEC decision
   |
   +--> QuickContract
   |
   `--> complete SDD + TaskContract + Gherkin
             |
             v
       validate + seal
             |
             v
bind EXISTING issue to delivery state
             |
             v
reuse/create issue-linked branch
             |
             v
optional Paseo worktree
             |
             v
normal aeh run lifecycle
             |
             v
deterministic validation -> reviews -> convergence -> lead acceptance
             |
             v
optional deterministic commit -> push -> draft PR -> Closes #issue
```

## CLI

### Inspect

```bash
aeh issue inspect 142
```

Fetches the issue and shows preliminary QUICK/SPEC evidence without creating a TaskContract.

### Import/freeze

```bash
aeh issue import 142
```

Creates `GH-142` as a sealed task without executing implementation.

For explicit issue revision acceptance:

```bash
aeh issue import 142 --refresh
```

If an active Paseo delivery workspace already exists, refresh is blocked unless explicitly forced:

```bash
aeh issue import 142 --refresh --force
```

### Complete execution

```bash
aeh issue implement 142
```

Equivalent entrypoint:

```bash
aeh run --issue 142
```

Optional profile:

```bash
aeh issue implement 142 --profile maximum-quality
```

The final CLI summary includes delivery status and the PR URL when finalization creates/reuses a PR.

## Repository resolution

The issue repository is resolved from:

1. `delivery.github.repository` when configured;
2. otherwise the repository's `origin` remote.

The issue endpoint rejects GitHub pull requests returned from `/issues/<number>`; issue-driven execution is intentionally issue-specific.

Public issues may be fetched without authentication. Private repositories require a usable token. Token resolution follows the delivery configuration and environment:

```text
configured tokenEnv
GH_TOKEN
GITHUB_TOKEN
GITHUB_PAT
```

Tokens are never serialized into the issue snapshot, TaskContract or delivery state.

## Frozen issue source

The Harness stores:

```text
.harness/issues/GH-142.json
```

with repository, issue number/URL, title/body, state, labels, timestamps and SHA-256 of normalized title/body.

The TaskContract records the same source identity and fingerprint.

Only **title and body** are treated as normative remote content for the hash. Labels can influence initial routing/triage but changing a label does not silently rewrite requirements. Comments are not incorporated into the active normative contract unless a later intake version explicitly adds that policy.

## Planner normalization

Non-trivial issues or issues without directly extractable acceptance statements can be sent to the configured read-only planner:

```yaml
workflow:
  issueIntake:
    plannerAgent: planner
```

The planner may inspect repository code/tests/architecture to derive implementation detail and existing invariants. It returns a machine-validated intake structure containing problem/outcome, explicit or repository-derived requirements, acceptance scenarios, scope/domains, risk, constraints, proposed design, implementation tasks/non-goals and unresolved decisions.

The planner cannot directly write normative artifacts. The Harness validates its structured output and writes the QuickContract/SDD itself.

If the planner runtime fails or returns invalid output, deterministic extraction provides a fallback rather than making the intake dependent on one LLM session.

## Product-decision boundary

The planner/intake distinguishes:

```text
ready
requires_product_decision
spec_contradiction
```

Repository-derived implementation details are allowed when supported by existing evidence. Product/business choices that cannot be determined from the issue/repository are not invented.

Those become `REQUIRES_PRODUCT_DECISION`. Contradictory authoritative intent becomes `SPEC_CONTRADICTION`. Both follow the Harness human-on-exception policy.

## QUICK vs SPEC

The issue is passed through the same deterministic triage rules used by normal requests.

A QUICK result still requires:

- explicit **concrete** bounded file scope;
- low risk;
- no security/auth/architecture/schema/migration/public API/new-dependency escalation signals;
- observable acceptance statements.

Wildcard scope such as `**`, `src/**`, `src/*.ts` or brace expansion is not accepted as a bounded QUICK scope even if it is represented by one pattern.

Anything outside that boundary becomes a full issue-derived SDD.

Issue-derived SDD requirement IDs are stable:

```text
GH-142-R1
GH-142-R2
...
```

The generated proposal/spec/design/tasks/Gherkin/TaskContract must pass ordinary traceability validation before sealing.

## Existing issue reuse

Issue-driven intake seeds the delivery record with the existing issue identity. Therefore downstream handoff **does not create another issue**.

```text
GitHub #142
    |
    v
GH-142 delivery record
    |
    v
handoff sees issueNumber=142
    |
    v
skip issue creation
```

Reusing an already-frozen TaskContract also re-seeds the delivery identity, so deleting ephemeral delivery state cannot cause the next issue implementation to create a duplicate issue.

## Branch reuse

The configured branch pattern remains:

```yaml
delivery:
  github:
    branchPattern: feature/gh-{issue}-{slug}
```

For an existing issue the Harness first checks the exact remote ref. If it already exists, it reuses that branch. Otherwise it creates it from the captured originating/base branch.

No force push, amend or rebase is used as part of intake recovery/finalization.

## Paseo worktree

When Paseo delivery is enabled, issue-driven handoff reuses the v0.4.14 worktree mechanism:

```text
issue -> existing/new branch -> Paseo checkout-branch worktree
```

The sealed task context, including the issue snapshot, is materialized into the worktree. Implementation, deterministic validation, review, remediation and Graphify execute against that workspace while control state remains in the original checkout.

## ISSUE_DRIFT

Before each issue-derived run, the Harness re-fetches the issue title/body and recalculates the fingerprint.

If the fingerprint differs from the frozen TaskContract:

```text
ISSUE_DRIFT
```

The active run is not silently reinterpreted. The user/lead explicitly accepts revised issue intent with `--refresh` when appropriate; an active implementation workspace makes refresh guarded and requires explicit `--force`.

## Accepted GitHub finalization

Git writes remain outside agent permissions. When enabled:

```yaml
delivery:
  github:
    enabled: true
    finalizeOnAcceptance: true
    pullRequestDraft: true
```

finalization runs only **after** the resulting report is PASS, including configured review/quality/lead gates.

The deterministic control plane:

1. verifies that execution is on the exact issue-linked branch;
2. stages the accepted work with `git add -A`;
3. creates one normal commit (`GH-142: <issue title>`), using repository Git identity when configured and a Harness fallback identity otherwise;
4. checks that the branch is actually ahead of the originating/base branch;
5. pushes `HEAD` to the exact issue branch without force;
6. searches for an existing open PR for that head/base pair;
7. reuses it when present, otherwise creates a draft PR by default;
8. writes `Closes #142` in the PR body.

The worker agents still have `gitWrite: deny`; enabling this feature does not grant them commit/push authority.

A push/token/remote permission problem becomes `BLOCKED_EXTERNAL` and marks human intervention required rather than returning a false successful delivery. A local branch/control-plane inconsistency is `SYSTEM_FAILURE` and is not mislabeled as a product decision.

If the branch contains no commits beyond the base, finalization returns `NO_CHANGES` instead of manufacturing an empty PR.

## Configuration

Default initialized projects include:

```yaml
workflow:
  issueIntake:
    enabled: true
    snapshotDir: .harness/issues
    verifyDriftOnRun: true
    requireOpen: true
    plannerAgent: planner
    autoHandoff: true

delivery:
  github:
    enabled: false
    tokenEnv: GH_TOKEN
    branchPattern: feature/gh-{issue}-{slug}
    finalizeOnAcceptance: true
    pullRequestDraft: true
  paseo:
    enabled: false
    createWorkspace: true
    autoUseWorkspace: true
```

`autoHandoff` invokes the configured delivery flow automatically when GitHub/Paseo delivery is enabled. It does not turn remote delivery on by itself: the `delivery.*.enabled` flags remain explicit project choices.

For automatic issue branch + worktree + PR delivery, enable both GitHub and Paseo delivery. GitHub finalization intentionally refuses to commit a different current branch, protecting the control checkout from accidental delivery writes.

## Trust hierarchy

For issue-driven work:

```text
GitHub issue at intake time
        |
        v
frozen issue snapshot
        |
        v
sealed QuickContract / SDD + TaskContract
        |
        v
implementation and validation
```

During the active run:

```text
sealed TaskContract/SDD > mutable remote issue > agent memory/summaries
```

The remote issue remains provenance and collaboration input; the frozen/sealed contract prevents mutable requirements during execution.

## Natural-language/Paseo behavior

The `engineering-workflow` skill recognizes existing-issue implementation intent. A lead started from Paseo mobile should translate:

> Implement issue #142.

into:

```bash
aeh issue implement 142
```

The same command owns intake, freeze, optional handoff/worktree, autonomous implementation/review and configured accepted-delivery finalization. The lead should not ask the user to manually perform intermediate Harness commands unless a genuine human-on-exception state is reached.
