# Implementation context pack

Section 11 of the plan. The stable, machine-readable contract a follow-up
implementation agent (`gitnexus-work`, or any executor) consumes to start
work **without repeating the investigation**. Distilled from the ledger;
every entry traceable to verified evidence.

**Compact plans emit the mini-pack** — only: `task_summary`,
`evidence_provenance`, `files_to_modify`, `tests`,
`verification_commands`, `pdg_constraints` (only when a slice actually
ran), `assumptions`, `open_questions`, `avoid`. Full plans emit every
field. Field semantics are identical in both; `evidence_provenance` is
mandatory in both forms. `gitnexus-work` treats absent optional fields as
empty, not as errors.

## Schema

This is the sole normative emitted `evidence_provenance` field schema. The
portable byte contract and executable serializer live in
`evidence-provenance.md` and `../scripts/evidence-provenance.mjs`; sibling
documents must reference them rather than reimplementing canonical bytes.

```yaml
implementation_context:
  task_summary: ''
  acceptance_criteria: []

  evidence_provenance:
    schema_version: 2
    head_commit: '' # full commit SHA that source citations pin to
    # normalized repo-relative docs/plans/<date>-gitnexus-plan-<3-5-word-slug>.md;
    # safely written; exact path excluded from global_dirty_digest
    generated_plan_path: ''
    global_dirty_digest:
      algorithm: 'sha256'
      canonicalization: 'gitnexus-evidence-provenance-v2 NUL-framed UTF-8 records'
      value: '' # digest only; do not embed the whole dirty-path manifest
    cited_path_manifest: # sorted by normalized repo-relative path
      - path: ''
        object_kind: # per layer: regular | symlink | gitlink | directory | absent
          head: ''
          index: ''
          worktree: ''
          untracked: ''
        state: 'clean | staged | unstaged | untracked | deleted | renamed | mixed | absent'
        rename_from: null
        rename_to: null
        head_digest: 'sha256:<hex> | absent'
        index_digest: 'sha256:<hex> | absent'
        worktree_digest: 'sha256:<hex> | absent'
        untracked_digest: 'sha256:<hex> | absent'

  primary_symbols:
    - symbol: ''
      file: ''
      lines: ''
      role: ''

  related_symbols:
    - symbol: ''
      relationship: '' # CALLS / IMPORTS / EXTENDS / test-of / ...
      relevance: ''

  execution_path: [] # ordered prose steps, from §2/§5

  pdg_constraints: # from the PDG slice; empty + note if no layer
    - description: ''
      affected_statements: [] # "<file>:<line>" refs
      implementation_consequence: ''

  architectural_patterns:
    - pattern: ''
      example_location: '' # repo-relative file (+ symbol)
      usage_guidance: ''

  files_to_modify:
    - file: ''
      symbols: []
      intended_change: ''

  tests:
    - file: '' # existing file to update, or new path to create
      scenarios: [] # input → action → expected outcome

  verification_commands: [] # real commands verified to exist AND be runnable —
    # prefer npm/CI scripts that carry their pre-hooks

  risks: []
  assumptions: [] # faithful condensation of plan §12 assumptions;
    # each entry names WHAT to check and HOW —
    # gitnexus-work re-verifies them before executing
  open_questions: [] # faithful condensation of plan §12 open questions

  avoid:
    - 'Do not repeat full repository discovery'
    - 'Do not replace established patterns without evidence'
    # + task-specific prohibitions discovered during planning
```

## Must not contain

- full files;
- the repository-wide raw dirty-path manifest (store only its canonical
  `global_dirty_digest`; detailed entries are bounded to cited paths);
- large raw GitNexus responses;
- unfiltered PDG dumps;
- duplicate code excerpts (cite `file:line`, don't re-quote);
- speculative implementation details presented as facts.

## Stability contract

Field names above are the interface consumed by `gitnexus-work` (fields it
does not act on directly travel as executor context). Add fields
freely; do not rename or repurpose existing ones. `assumptions` and `avoid`
are load-bearing: an executor treats `assumptions` as things to re-verify
cheaply before relying on them, and `avoid` as hard constraints.
`evidence_provenance` is also load-bearing: its version, global digest, and
sorted cited-path manifest let the executor distinguish commit drift from
staged, unstaged, untracked, deleted, renamed, mixed, or absent working-tree
evidence. Legacy packs that lack it or use schema 1 require a conservative
schema-2 re-anchor; they are not interpreted as a clean tree.
`generated_plan_path` is always normalized, relative to the target repo, and
scoped to the generated-plan filename shape under `docs/plans/`; schema 2 has
no external-output representation. An executor must load the plan with the
helper's descriptor-anchored `read-plan` command and require this field to
equal the receipt's canonical target-repo-relative path byte-for-byte.