# AI Foundations Integration: Session Memory & Evidence Enforcement

**Status:** Proposed
**Date:** 2026-03-27
**Keywords:** session-memory, evidence-enforcement, manage-state, cross-phase-state, accumulative-state, citation-standard, review-gate

## Overview

Integrate two cross-cutting infrastructure improvements inspired by the ai-foundations workflow system into harness-engineering. These upgrades enhance cross-phase communication and output quality without adopting ai-foundations' rigid 8-phase linear model.

**Wave 1 — Session Memory:** Upgrade `manage_state` to support accumulative session-scoped sections (terminology, decisions, constraints, risks, open questions, evidence). Skills append to shared state instead of re-discovering context, eliminating the information loss between skill handoffs.

**Wave 2 — Evidence Enforcement:** Establish an evidence-based claims standard across all skills that produce technical assertions. Skills cite file:line references, test output, or diffs. Review pipelines verify compliance.

## Goals

1. Replace one-way context handoff with accumulative session memory so skills share context without re-discovery
2. Establish an evidence-based claims standard across all skills that produce technical assertions

## Non-Goals

- Adopting ai-foundations' linear 8-phase pipeline (harness keeps its flexible skill invocation model)
- Adding a dedicated BA/requirements phase (brainstorming already covers this)
- Adding a dedicated SDET/test automation planning phase (TDD skill is sufficient)
- Rework/blocker cascade system (deferred — needs real-world blocker data before classification rules can be evidence-based)
- New skills (interface design, tutor) (deferred — depend on session memory proving out in practice)
- LSP/jdtls integration (harness uses tree-sitter and graph-based navigation)
- Cross-session memory via Historian MCP (harness uses `manage_state` and memory files)

## Decisions

| #   | Decision                                                                           | Rationale                                                                                                                                                   |
| --- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1   | Hybrid integration strategy — cross-cutting concerns absorbed into framework       | Avoids skill sprawl; infrastructure improvements benefit all existing skills                                                                                |
| 2   | Upgrade `manage_state` for session memory (not new file or handoff.json extension) | Single state mechanism, already has MCP integration, avoids two competing state systems                                                                     |
| 3   | Evidence enforcement via skill instructions + review gate                          | Belt and suspenders — skills guided to cite during authoring, review catches what slips through                                                             |
| 4   | Scope to Waves 1 and 2 only; defer Waves 3 (rework cascade) and 4 (new skills)     | Rework cascade is high-risk without real-world data; new skills are nice-to-have not urgent. Take infrastructure wins now, add the rest when there's demand |
| 5   | `handoff.json` remains as transition signal; session state is accumulative context | Different purposes — handoff says "what to do next," session state says "what we know so far"                                                               |

## Technical Design

### Wave 1: Session Memory (manage_state upgrade)

#### Current State

- `manage_state` supports key-value project state via `state.json`
- `handoff.json` passes context one-way between skills
- State directory resolution via `getStateDir()`: session slug -> stream (git branch) -> legacy `.harness/`
- Session scoping already exists — new session sections inherit this automatically

#### New Session-Scoped Sections

```
Session State Schema:
  terminology      # Domain terms and definitions (accumulated by all skills)
  decisions        # Key design/implementation decisions with rationale
  constraints      # Hard constraints discovered during workflow
  risks            # Identified risks with severity and mitigation status
  openQuestions    # Unresolved questions (added/resolved by any skill)
  evidence         # Registry of cited file:line references and test outputs
```

#### Accumulative Entry Format

Each entry in a session section follows this structure:

```json
{
  "id": "<auto-generated>",
  "timestamp": "2026-03-27T14:30:00Z",
  "authorSkill": "harness-brainstorming",
  "content": "<entry content>",
  "status": "active"
}
```

Entries are append-only. Skills mark entries as `resolved` or `superseded` rather than deleting them.

#### Behavior Changes

- **Accumulative writes** — Skills append to sections rather than overwriting. Each entry is timestamped and tagged with the authoring skill name.
- **Read-before-write** — `manage_state` returns current session state before accepting writes, preventing stale overwrites.
- **Session scoping** — State is scoped to a workflow session (brainstorm -> plan -> execute -> review). New session = clean state. Previous sessions are archived, not deleted.
- **Backward compatible** — Existing key-value usage continues to work. Session sections are additive.

#### Implementation Phases

**Phase 1.1 — Schema & types**

- Define session section schemas in `@harness-engineering/types`
- Define accumulative entry format (timestamp, authorSkill, content, status)
- Define section names as a union type

**Phase 1.2 — Core state engine**

- Extend `state-persistence.ts` to support section-scoped append operations
- Add read-before-write semantics for session sections
- Add session archival logic (archive on new session, not delete)
- Backward compatibility: existing key-value operations unchanged

**Phase 1.3 — MCP tool upgrade**

- Extend `manage_state` MCP tool to accept section-scoped reads and writes
- New actions: `append_section`, `read_section`, `list_sections`
- Existing actions unchanged

**Phase 1.4 — Skill integration**

- Update brainstorming to write decisions + terminology to session state
- Update planning to read decisions, write constraints + risks
- Update execution to read all sections, write evidence entries

### Wave 2: Evidence Enforcement

#### Skill-Level Instructions (Authoring Time)

Add to every skill that produces technical claims (code-review, debugging, soundness-review, architecture-enforcer, verification):

```
Evidence Standard:
- Every technical assertion MUST include a citation
- File references: file_path:line_number
- Test evidence: command run + pass/fail output
- Diff evidence: before/after with file path
- Uncited claims must be prefixed with [UNVERIFIED]
```

#### Review Gate (Verification Time)

Add an evidence-checking pass to `harness:code-review` and `harness:soundness-review`:

- Scan upstream artifacts for technical assertions
- Flag assertions without citations as findings (severity: low)
- Flag `[UNVERIFIED]` markers that were never resolved as findings (severity: medium)
- Report evidence coverage percentage in review output

#### Implementation Phases

**Phase 2.1 — Skill instructions**

- Add evidence standard block to SKILL.md for: code-review, debugging, soundness-review, architecture-enforcer, verification

**Phase 2.2 — Review gate**

- Add evidence-checking pass to code-review pipeline
- Add evidence-checking pass to soundness-review pipeline
- Define finding severity: uncited assertion = low, surviving `[UNVERIFIED]` = medium
- Report evidence coverage percentage

### Wave Dependencies

Waves 1 and 2 are independent and can be developed in parallel.

```
Wave 1 (Session Memory) ──────→ Done
Wave 2 (Evidence Enforcement) ─→ Done
```

### Performance & AI Usage Impact

| Dimension                 | Wave 1                       | Wave 2                            | Net                 |
| ------------------------- | ---------------------------- | --------------------------------- | ------------------- |
| Disk IO                   | Negligible negative          | Neutral                           | Negligible negative |
| Context window efficiency | Positive (less re-discovery) | Neutral                           | Positive            |
| AI token usage            | Positive (less re-discovery) | Slight negative (more citations)  | Roughly neutral     |
| Output quality per token  | Positive                     | Positive                          | **Positive**        |
| Human time saved          | Positive (no re-explaining)  | Positive (no manual verification) | **Positive**        |

## Success Criteria

### Wave 1 — Session Memory

1. `manage_state` accepts accumulative writes to typed sections (terminology, decisions, constraints, risks, openQuestions, evidence)
2. Appending to a section does not overwrite existing entries — entries are timestamped and tagged with authoring skill
3. Session state is scoped via existing `getStateDir()` resolution chain (session -> stream -> legacy)
4. Existing key-value state operations continue to work unchanged (backward compatibility)
5. At least 3 existing skills (brainstorming, planning, execution) read/write session state sections during their workflow
6. Previous session state is archived (not deleted) when a new session begins

### Wave 2 — Evidence Enforcement

7. All skills that produce technical claims include the evidence standard in their SKILL.md instructions
8. `harness:code-review` and `harness:soundness-review` include an evidence-checking pass that flags uncited assertions
9. Evidence coverage percentage is reported in review output
10. `[UNVERIFIED]` markers that survive to review are flagged as medium-severity findings

## Future Considerations (Deferred)

These capabilities were explored during brainstorming and intentionally deferred. They build on the infrastructure established by Waves 1 and 2:

- **Wave 3 — Rework/Blocker Cascade:** Auto-fix trivial blockers, escalate critical ones, circuit breaker after 2 loops. Deferred because blocker classification needs real-world data from the reworkLog (which Wave 1 enables but doesn't yet populate at scale).
- **Wave 4 — New Skills:**
  - `harness-interface-design`: Optional skill for defining module contracts before implementation. Auto-triggered by planning when graph detects cross-module dependencies or component count >= 3. Override via `--with-interfaces` / `--skip-interfaces`.
  - `harness-tutor`: Read-only codebase + technology teaching skill using Feynman + Socratic method. Question-driven with learner memory via manage_state.
