playbook/antigravity-awesome-skills/skills/ecl-harness-engineer/references/ecl-harness.md

# ECL-aware Harness Reference

Use this reference when creating `docs/ECL.md`, `harness/changes`, change templates,
`harness/evolution`, `scripts/harness-change.*`, `scripts/harness-evolve.*`,
`scripts/lint-ecl.*`, and `scripts/lint-encoding.*`.

Choose the command surface from the target project before wiring docs, Makefile/package scripts, or
CI. Bash, PowerShell, Node, and Python implementations are equivalent profiles when they preserve the
same command set and invariants. For Windows projects that select Bash, document Git Bash, WSL,
MSYS2, or CI Linux shell as a prerequisite. PowerShell templates remain available for projects that
accept `.ps1`; they must support Windows PowerShell 5.1 as well as PowerShell 7.

Command surface selection is automatic. Ask the user only when project evidence conflicts, when no
reasonable runtime or shell can be inferred, or when the user has already stated a hard constraint
such as "no ps1" or "bash only".

## 1. Design Rules

### 1.1 Roles

| Artifact | Role |
|----------|------|
| `AGENTS.md` | Navigation map for agents; keep it short and link to detailed docs |
| `docs/ECL.md` | Project operating manual for change lifecycle and context loading |
| `docs/STATUS.md` | Lightweight handoff summary used only when no active change exists |
| `harness/changes/active/` | Current task context; personal development allows only one active task |
| `harness/changes/parking/` | Paused tasks that may resume later |
| `harness/changes/archive/` | Closed tasks: completed, blocked, or abandoned |
| `harness/changes/INDEX.json` | Generated search index; never hand-edit |
| `harness/evolution/state.json` | Auto-evolve threshold and last-run state |
| `harness/evolution/pending.md` | Generated instruction when enough archived evidence exists |
| `harness/evolution/results.tsv` | Darwin-style keep/revert score log for harness evolution |
| `scripts/harness-change.*` | State transition and index generation tool |
| `scripts/harness-evolve.*` | Mechanical threshold check and pending-context generator |
| `scripts/lint-ecl.*` | Mechanical ECL integrity gate |

Before implementation starts, require an approved plan review. Record it as
`plan_review: "approved"` in `summary.md` front matter or as an approved plan review in
`reviews/`. This gate prevents raw requirements from moving directly into coding.

Structured changes use plan-aware intake. If the user provides only a requirement, ask the smallest
set of high-impact questions needed to draft `spec.md`. If the user already provides a plan, review
that plan as a draft, split WHAT/WHY into `spec.md` and HOW into `plan.md`, and ask only about gaps
that affect implementation direction or acceptance. If the plan is complete and does not conflict
with repository evidence, do not restart the interview. If it conflicts with code, docs, commands,
or existing harness constraints, record the conflict and return to Intake Review. Each intake round
asks at most three questions.
Low-risk unknowns become assumptions; high-impact unknowns become `[NEEDS CLARIFICATION: ...]` and
block implementation.

### 1.2 When to create a change

Create a change when any condition applies:

- The work spans more than two files.
- The work touches APIs, databases, permissions, architecture, or cross-client behavior.
- The work needs user confirmation or plan review.
- The work needs multi-step tests or regression checks.
- The work is likely to take more than 20 minutes.
- A failure needs to be captured as a new constraint, task, or regression.

Small, local fixes can skip `harness/changes` if the final response records validation.
Evidence, non-goals, options, and plan review are mandatory for non-trivial active changes. Small
local fixes that skip a change do not need the full template, but the final response must still
record assumptions and validation.

Decision tree:

1. Existing active change: keep using it; do not create another active context.
2. Small Change: copy, comments, README text, formatting, or an obviously local single-file fix with
   no runtime, API, data, permission, architecture, or validation-chain impact.
3. Structured Change: APIs, data, permissions, architecture, multiple modules, release/runtime
   behavior, unclear requirements, or work likely to exceed 20 minutes.
4. Unclear impact: inspect read-only first. If uncertainty remains, ask one high-impact question or
   upgrade to Structured Change; do not assume Small Change.

### 1.3 Change lifecycle

```text
new -> active/in_progress
active -> close completed -> archive/YYYY-MM-DD-slug
active -> close abandoned -> archive/YYYY-MM-DD-slug
active -> close blocked -> archive/YYYY-MM-DD-slug
active -> park -> parking/YYYY-MM-DD-slug
parking/YYYY-MM-DD-slug -> resume -> active
```

Rules:

- `active/` has no persistent change id. The id is created only when parking or closing.
- Starting a new task must never overwrite an existing active task.
- `INDEX.json` is derived from `parking/*/summary.md` and `archive/*/summary.md`.
- `harness/evolution/pending.md` is generated only after enough new archived changes accumulate.
- Hook and CI may validate, but must not auto-write docs or move changes.
- `docs/STATUS.md` is a handoff summary, not a change record. Active change files always
  override it for the current task.

Close-change STATUS protocol:

1. Before closing active work, update `docs/STATUS.md` from active `summary.md`, `spec.md`,
   `plan.md`, `tasks.md`, and relevant `reviews/` with completed work, validation, residual risks, and
   the next resume point.
2. Run the generated `scripts/harness-change.* close <completed|blocked|abandoned>` command so the active change
   moves to `archive/` and `INDEX.json` is rebuilt.
3. After close, update `docs/STATUS.md` with the final archive `summary.md` path.
4. Run `scripts/harness-evolve.* check` through `harness-change.* close`; if the threshold is
   reached, it creates `harness/evolution/pending.md` but does not edit docs or scripts.
5. Run the generated harness lint command. CI and hooks may validate STATUS, but must not
   update it automatically.

### 1.4 Auto-evolve lifecycle

Core ECL includes auto-evolve threshold checking by default. This is not the advanced eval,
observability, or long-term memory profile. It is a small loop that learns from closed changes:

```text
close/reindex -> count eligible archive evidence -> generate pending.md when threshold reached
pending.md + no active change -> Codex asks whether to handle pending maintenance now
started pending evolution -> proposal -> independent scoring or dry_run -> verify -> results.tsv -> mark-complete
```

Rules:

- `scripts/harness-evolve.*` only performs mechanical counting and pending generation.
- `harness/evolution/pending.md` is a maintenance reminder, not a hard lock. Reading it for context
  does not start pending evolution and must not block ordinary user work.
- When no active change exists and pending maintenance is present, Codex should ask the user whether
  to handle it now unless the user already prioritized the current task. A user yes starts the
  pending evolution flow; a no leaves pending in place and ordinary work continues.
- Pending evolution starts when Codex creates or uses an `auto-evolve-harness-*` change, writes an
  evolution proposal/result, or edits Harness files based on pending evidence.
- Generated scripts do not call subagents. They create pending context; the Codex run that handles
  pending evolution requests an independent auditor/subagent when available. User approval to handle
  pending implies permission to request independent review; if the environment still requires
  explicit authorization, ask once before falling back.
- Codex performs semantic extraction and file edits, inside a dedicated active change.
- Once pending evolution starts, Codex must finish with a proposal, one `results.tsv` row, and
  `harness-evolve mark-complete`; otherwise park or close blocked, not completed.
- Codex must write a proposal before editing harness files. Rejected or no-op candidates stay in
  the proposal and must not enter AGENTS.md, ECL, STATUS, lint, or CI.
- Auto-apply requires independent auditor/subagent scoring. If independent scoring is unavailable,
  declined, or still unauthorized after asking, record `noop` with `eval_mode=dry_run`, keep the
  proposal, run `mark-complete`, and do not auto-apply the delta.
- No independent scorer = no auto-apply.
- Machinery repair (`harness-evolve`, pending templates, lint) is allowed as a prerequisite but does
  not complete pending evolution by itself. After repair, evaluate candidate archives or park/block.
- Before evaluating candidates, rebuild `harness/changes/INDEX.json` and use the current eligible
  archive window. Candidate Archives inside an older pending file are a trigger snapshot, not the
  only allowed evidence.
- Complexity budget: prefer clarifying or replacing existing rules over adding new sections. If an
  idea can be expressed by editing an existing paragraph, do not create a new document, directory,
  script, or workflow.
- AGENTS.md must not carry auto-evolve details; it only points to the pending context when present.
- If active work exists, finish or park it before executing pending evolution.
- Every durable new rule must cite archived change evidence.
- One-off business bugs are not enough to create permanent harness rules.
- The default auto-evolve path must not create `harness/eval`, `harness/trace`, `harness/state`,
  `harness/checkpoints`, `harness/memory`, or `harness/metrics`.
- A delta is kept only when hard gates pass, score is at least 80, independent review passes, and
  validation passes; otherwise log `noop` for reviewed evidence with no durable rule, `rejected`
  for proposals that fail hard gates before apply, or revert the failed applied delta and log
  `revert` in `harness/evolution/results.tsv`. Every started pending evolution ends with
  `harness-evolve mark-complete` or stays parked/blocked.

Auto-evolve scoring:

| Dimension | Weight |
|-----------|-------:|
| Evidence grounding | 30 |
| Project relevance | 25 |
| Mechanical enforceability | 15 |
| Regression safety | 20 |
| Context cost | 10 |

`results.tsv` status values are `keep`, `revert`, `rejected`, and `noop`. Prefer `noop` for
reviewed candidates that yield no durable harness rule. Use
`eval_mode=independent_review` when a separate auditor/subagent scored the proposal and
`eval_mode=dry_run` when independent scoring was unavailable, declined, or still unauthorized after
asking. The `note` field must explain why a candidate was rejected, no-op'd, or reverted.

Minimal proposal template:

```markdown
# Harness Auto-Evolve Proposal

## Accepted Candidates

- [candidate] — evidence: `harness/changes/archive/.../summary.md`

## Rejected Candidates

- [candidate] — reason: [no archive evidence / not project-relevant / too broad / too costly]

## Evidence

- `harness/changes/archive/.../summary.md`

## Project Relevance

- Files/modules/commands/failures/user corrections:

## Target Files

- [existing harness file to edit]

## Score

| Dimension | Score | Notes |
|-----------|------:|-------|
| Evidence grounding /30 |  |  |
| Project relevance /25 |  |  |
| Mechanical enforceability /15 |  |  |
| Regression safety /20 |  |  |
| Context cost /10 |  |  |

## Validation

- Harness checks:
- Relevant business gates:

## Decision

- keep / revert / rejected / noop:
- eval_mode:
- results.tsv note:
```

## 2. Default Change Template

Use the 5-file template by default for new active changes. Old archived changes that only have the
previous 4-file template remain valid and must not fail compatibility checks solely because
`plan.md` is absent.

```text
harness/changes/active/
  summary.md
  spec.md
  plan.md
  tasks.md
  reviews/
```

### 2.1 `summary.md`

```markdown
---
title: "{{TITLE}}"
slug: "{{SLUG}}"
status: "in_progress"
location: "active"
phase: "intake"
intake_status: "pending"
spec_review: "pending"
plan_review: "pending"
modules: []
files: []
tags: []
validation_status: "unknown"
created_at: "{{DATE}}"
updated_at: "{{DATE}}"
---

# Summary

## Outcome

Pending.

## Decisions

- Pending.

## Validation

- Pending.

## Next Step

- Run Intake Review, then update `spec.md` and `plan.md`.
```

### 2.2 `spec.md`

```markdown
# Spec

## Intake Review

- Intake type: Small Change | Structured Change
- Input shape: requirement-first | plan-first | mixed
- Questions asked this round: 0

## Goal And Evidence

- Real problem or user request:
- Current behavior:
- Source of evidence:

## User Scenarios And Success

- Primary user/system scenario:
- Success criteria:
- Acceptance criteria:

## Non-Goals

- Pending.

## Constraints

- Pending.

## Assumptions

- Pending.

## Open Questions

- [NEEDS CLARIFICATION: Replace with a specific high-impact question, or remove before implementation.]

## Resolved Clarifications

- Pending.
```

### 2.3 `plan.md`

```markdown
# Plan

## Technical Approach

- Pending.

## Impacted Modules And Files

- Pending.

## Interfaces, Data, Permissions

- Pending.

## Spec Gaps Found From Planning

- Pending.

## Risks And Mitigations

- Pending.

## Verification Plan

- Pending.
```

### 2.4 `tasks.md`

```markdown
# Tasks

## Format

- `- [ ] T001 [P?] [US?] Action with target path and validation note`
- `[P]` means parallel-safe. `[US1]` maps to a user story when stories exist.

## Setup / Intake

- [ ] T001 Review `spec.md` and `plan.md` gates before implementation.

## Implementation

- [ ] T002 Pending implementation task with target path.

## Validation

- [ ] T003 Pending validation task with command or scenario.

## Deferred Tasks

- None.
```

### 2.5 `reviews/review.md`

```markdown
# Review

## Intake Review

- Status: pending
- Notes:

## Spec Review

- Status: pending
- Open high-impact clarifications:
- WHAT/HOW separation:

## Plan Review

- Status: pending
- Spec gaps found from planning:

## Code Review

- Status: pending

## Validation Review

- Status: pending
```

Complex tasks may split `spec.md`, `plan.md`, or `tasks.md` into focused supporting files only when
the single files become hard to navigate. Do not split small or ordinary changes by default.

### 2.6 Short response examples

Small Change final response:

```markdown
Updated the README typo. I treated this as a Small Change because it only touched documentation copy
and had no runtime, API, data, permission, or architecture impact.

Verification: reviewed the README diff.
```

Structured blocker response:

```markdown
I cannot safely move this to implementation yet. The draft plan leaves high-impact gaps:

1. Which roles or actors must be supported?
2. Which resources/actions require enforcement?
3. What acceptance scenario proves the change works?

I would record these in `spec.md` as `[NEEDS CLARIFICATION: ...]` and keep `plan_review: pending`.
```

Complete plan accepted response:

```markdown
The provided plan includes goal, acceptance criteria, non-goals, constraints, verification commands,
and no conflicts with repository evidence. I would split it into `spec.md` for WHAT/WHY, `plan.md`
for HOW, generate `tasks.md`, and proceed without another intake interview.
```

## 3. Context Loading

Load context progressively:

1. `AGENTS.md`
2. `docs/ECL.md`
3. If active exists: `harness/changes/active/summary.md`
4. If active exists: `harness/changes/active/spec.md`, `plan.md`, `tasks.md`, and relevant `reviews/`
5. If no active exists and `harness/evolution/pending.md` exists: read it before `docs/STATUS.md`,
   mention it as pending maintenance, and ask whether to handle it now unless the user already
   prioritized the current task. Asking or reading does not start auto-evolve.
6. If no active exists and no pending evolution exists: `docs/STATUS.md`
7. Relevant architecture, design, API, or reference docs for the task
8. `harness/changes/INDEX.json` only when selecting historical context
9. Selected archived `summary.md` files only
10. Selected archived spec/plan/tasks/reviews only for explicit resume, review, failure debugging, or auto-evolve evidence extraction

The normal path reads current task context and stable docs. If active change exists, do not use
`docs/STATUS.md` as authority. Archive history is never loaded wholesale. Search or read history
only when the user asks to continue prior work, STATUS points to an archive path, the current task
matches INDEX modules/files/tags, a current failure matches historical validation notes, or
`harness/evolution/pending.md` records a bounded trigger snapshot. When processing starts, refresh
`harness/changes/INDEX.json` and use the current eligible archive window.

## 4. `docs/ECL.md` Required Contents

Create `docs/ECL.md` with these sections:

1. Purpose and scope
2. When to create a change
3. Change lifecycle and state transitions
4. Stage-boundary update protocol
5. Plan review gate before implementation
6. Context loading order
7. STATUS handoff update before and after closing active work
8. Selective archive loading through STATUS and `INDEX.json`
9. Failure feedback and regression capture
10. Auto-evolve threshold checking and pending handling
11. Script command reference
12. Rule: `INDEX.json` is generated by script only

Keep philosophy brief. This is an operating manual.

## 5. Command Surface Profiles

Select one script profile and wire all docs, CI, Makefile targets, and package-manager scripts to
that profile. Do not mix profiles unless the project deliberately exposes aliases to the same
implementation. Choose automatically from project evidence; do not stop for human selection unless
the evidence is contradictory or no supported profile is available.

Supported profiles:

- **Bash profile**: use `.sh` scripts and commands such as `bash scripts/lint-ecl.sh`. On Windows,
  document Git Bash, WSL, MSYS2, or CI Linux shell as a prerequisite.
- **PowerShell profile**: use `.ps1` scripts. Detect whether `pwsh` is available before wiring
  commands; if it is not, use `powershell -NoProfile -ExecutionPolicy Bypass`.
- **Node profile**: use `.mjs` scripts when TypeScript/Node is already the primary project runtime.
- **Python profile**: use `.py` scripts when Python is already a primary project runtime.

Every profile must implement the same commands and invariants:

- `harness-change`: `new`, `status`, `validate`, `park`, `resume`, `close`, `search`, `context`,
  `reindex`, and `index-json`.
- `harness-evolve`: `check`, `collect`, and `mark-complete`.
- `lint-ecl`: active change structure, STATUS presence, completed validation, pending task
  consistency, generated index freshness, and auto-evolve state presence.
- `lint-encoding`: UTF-8 and mojibake-risk checks for source and docs.
- `close` and `reindex` must trigger `harness-evolve check`; hooks and CI may validate but must not
  rewrite docs, move changes, or update STATUS.

### PowerShell Profile Templates

Use these templates only when the selected command surface is PowerShell. Keep them compatible with
Windows PowerShell 5.1 and PowerShell 7; avoid non-ASCII marker literals and ambiguous method
overloads in `.ps1` templates.

### 5.1 `scripts/harness-change.ps1`

```powershell
param(
  [Parameter(Position = 0)]
  [ValidateSet("new", "status", "validate", "park", "resume", "close", "search", "context", "reindex", "index-json")]
  [string]$Command,

  [Parameter(Position = 1, ValueFromRemainingArguments = $true)]
  [string[]]$Args
)

$ErrorActionPreference = "Stop"

$Root = (Get-Location).Path
$Changes = Join-Path $Root "harness/changes"
$Active = Join-Path $Changes "active"
$Parking = Join-Path $Changes "parking"
$Archive = Join-Path $Changes "archive"
$IndexPath = Join-Path $Changes "INDEX.json"
$Template = Join-Path $Root "harness/templates/change"
$Evolution = Join-Path $Root "harness/evolution"
$EvolutionPending = Join-Path $Evolution "pending.md"
$HarnessEvolve = Join-Path $Root "scripts/harness-evolve.ps1"

function Ensure-Dirs {
  foreach ($dir in @($Changes, $Active, $Parking, $Archive, $Template, (Join-Path $Template "reviews"), $Evolution, (Join-Path $Evolution "proposals"))) {
    if (-not (Test-Path -LiteralPath $dir)) {
      New-Item -ItemType Directory -Path $dir | Out-Null
    }
  }
}

function Get-DateText {
  return (Get-Date).ToString("yyyy-MM-dd")
}

function ConvertTo-Slug([string]$Text) {
  $slug = $Text.ToLowerInvariant() -replace "[^a-z0-9]+", "-"
  $slug = $slug.Trim("-")
  if ([string]::IsNullOrWhiteSpace($slug)) { $slug = "change" }
  return $slug
}

function Read-Text([string]$Path) {
  if (-not (Test-Path -LiteralPath $Path)) { return "" }
  return Get-Content -Encoding UTF8 -Raw -LiteralPath $Path
}

function Write-Text([string]$Path, [string]$Content) {
  $parent = Split-Path -Parent $Path
  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
    New-Item -ItemType Directory -Path $parent | Out-Null
  }
  Set-Content -Encoding UTF8 -LiteralPath $Path -Value $Content
}

function Parse-FrontMatter([string]$Path) {
  $text = Read-Text $Path
  $result = @{}
  if (-not $text.StartsWith("---")) { return $result }
  $lines = $text -split "`r?`n"
  for ($i = 1; $i -lt $lines.Length; $i++) {
    if ($lines[$i] -eq "---") { break }
    if ($lines[$i] -match "^\s*([^:#]+):\s*(.*)\s*$") {
      $key = $Matches[1].Trim()
      $value = $Matches[2].Trim().Trim('"')
      if ($value -match "^\[(.*)\]$") {
        $items = $Matches[1].Split(",") | ForEach-Object { $_.Trim().Trim('"') } | Where-Object { $_ }
        $result[$key] = @($items)
      } else {
        $result[$key] = $value
      }
    }
  }
  return $result
}

function Set-FrontMatterValues([string]$Path, [hashtable]$Values) {
  $text = Read-Text $Path
  if (-not $text.StartsWith("---")) { throw "$Path has no front matter." }
  foreach ($key in $Values.Keys) {
    $value = $Values[$key]
    $line = if ($value -is [array]) {
      $quoted = $value | ForEach-Object { '"' + ($_ -replace '"', '\"') + '"' }
      "${key}: [" + ($quoted -join ", ") + "]"
    } else {
      "${key}: `"$value`""
    }
    if ($text -match "(?m)^$([regex]::Escape($key)):\s*.*$") {
      $text = [regex]::Replace($text, "(?m)^$([regex]::Escape($key)):\s*.*$", [System.Text.RegularExpressions.MatchEvaluator]{ param($m) $line }, 1)
    } else {
      $lines = $text -split "`r?`n"
      for ($i = 1; $i -lt $lines.Length; $i++) {
        if ($lines[$i] -eq "---") {
          $before = @($lines[0..($i - 1)])
          $after = @($lines[$i..($lines.Length - 1)])
          $text = (@($before + $line + $after) -join "`n")
          break
        }
      }
    }
  }
  Write-Text $Path $text
}

function Get-SectionLines([string]$Path, [string]$Heading) {
  $text = Read-Text $Path
  if (-not $text) { return @() }
  $lines = $text -split "`r?`n"
  $found = $false
  $items = New-Object System.Collections.Generic.List[string]
  foreach ($line in $lines) {
    if ($line -match "^##\s+$([regex]::Escape($Heading))\s*$") {
      $found = $true
      continue
    }
    if ($found -and $line -match "^##\s+") { break }
    if ($found -and $line.Trim()) {
      $items.Add($line.Trim())
    }
  }
  return @($items)
}

function Get-ValidationStatus([string]$SummaryPath, [hashtable]$Meta) {
  if ($Meta.ContainsKey("validation_status") -and $Meta["validation_status"]) {
    return $Meta["validation_status"]
  }
  $validation = (Get-SectionLines $SummaryPath "Validation") -join " "
  if ($validation -match "(?i)\bpass(ed)?\b|success|ok") { return "pass" }
  if ($validation -match "(?i)\bfail(ed)?\b|error|blocked") { return "fail" }
  return "unknown"
}

function Get-IndexEntries {
  $entries = New-Object System.Collections.Generic.List[object]
  foreach ($pair in @(@("parking", $Parking), @("archive", $Archive))) {
    $location = $pair[0]
    $base = $pair[1]
    if (-not (Test-Path -LiteralPath $base)) { continue }
    Get-ChildItem -LiteralPath $base -Directory | ForEach-Object {
      $summary = Join-Path $_.FullName "summary.md"
      if (-not (Test-Path -LiteralPath $summary)) { return }
      $meta = Parse-FrontMatter $summary
      $decisions = Get-SectionLines $summary "Decisions" | Where-Object { $_ -notmatch "Pending" }
      $relativePath = (Resolve-Path -LiteralPath $_.FullName -Relative).TrimStart([char[]]@(".", "\"))
      $entries.Add([ordered]@{
        id = $_.Name
        title = $meta["title"]
        status = $meta["status"]
        location = $location
        modules = @($meta["modules"])
        files = @($meta["files"])
        tags = @($meta["tags"])
        decisions = @($decisions)
        validation_status = Get-ValidationStatus $summary $meta
        path = ($relativePath -replace "\\", "/")
        updated_at = $meta["updated_at"]
      })
    }
  }
  return $entries.ToArray()
}

function Get-IndexJson {
  $entries = Get-IndexEntries
  if ($entries.Count -eq 0) { return "[]`n" }
  $json = $entries | ConvertTo-Json -Depth 8
  return ($json + "`n")
}

function Reindex {
  Ensure-Dirs
  $entries = Get-IndexEntries
  Write-Text $IndexPath (Get-IndexJson)
  Write-Output "Rebuilt harness/changes/INDEX.json ($($entries.Count) entries)."
}

function Invoke-EvolutionCheck([string]$Reason) {
  if (-not (Test-Path -LiteralPath $HarnessEvolve)) { return }
  try {
    & $HarnessEvolve check -Reason $Reason
  } catch {
    Write-Warning "Auto-evolve check failed: $($_.Exception.Message)"
  }
}

function Show-EvolutionReminder {
  if (Test-Path -LiteralPath $EvolutionPending) {
    Write-Warning "Harness evolution is pending: harness/evolution/pending.md"
  }
}

function Assert-NoActive {
  $summary = Join-Path $Active "summary.md"
  if (Test-Path -LiteralPath $summary) {
    throw "Active change exists. Run 'status', then 'park', 'close', or finish it before starting a new change."
  }
}

function New-Change([string]$Title) {
  Ensure-Dirs
  if ([string]::IsNullOrWhiteSpace($Title)) { throw "Missing title." }
  Assert-NoActive
  $date = Get-DateText
  $slug = ConvertTo-Slug $Title
  Write-Text (Join-Path $Active "summary.md") @"
---
title: "$Title"
slug: "$slug"
status: "in_progress"
location: "active"
phase: "intake"
intake_status: "pending"
spec_review: "pending"
plan_review: "pending"
modules: []
files: []
tags: []
validation_status: "unknown"
created_at: "$date"
updated_at: "$date"
---

# Summary

## Outcome

Pending.

## Decisions

- Pending.

## Validation

- Pending.

## Next Step

- Run Intake Review, then update ``spec.md`` and ``plan.md``.
"@
  Write-Text (Join-Path $Active "spec.md") @"
# Spec

## Intake Review

- Intake type: Small Change | Structured Change
- Input shape: requirement-first | plan-first | mixed
- Questions asked this round: 0

## Goal And Evidence

- Real problem or user request:
- Current behavior:
- Source of evidence:

## User Scenarios And Success

- Primary user/system scenario:
- Success criteria:
- Acceptance criteria:

## Non-Goals

- Pending.

## Constraints

- Pending.

## Assumptions

- Pending.

## Open Questions

- [NEEDS CLARIFICATION: Replace with a specific high-impact question, or remove before implementation.]

## Resolved Clarifications

- Pending.
"@
  Write-Text (Join-Path $Active "plan.md") @"
# Plan

## Technical Approach

- Pending.

## Impacted Modules And Files

- Pending.

## Interfaces, Data, Permissions

- Pending.

## Spec Gaps Found From Planning

- Pending.

## Risks And Mitigations

- Pending.

## Verification Plan

- Pending.
"@
  Write-Text (Join-Path $Active "tasks.md") @"
# Tasks

## Format

- ``- [ ] T001 [P?] [US?] Action with target path and validation note``
- ``[P]`` means parallel-safe. ``[US1]`` maps to a user story when stories exist.

## Setup / Intake

- [ ] T001 Review ``spec.md`` and ``plan.md`` gates before implementation.

## Implementation

- [ ] T002 Pending implementation task with target path.

## Validation

- [ ] T003 Pending validation task with command or scenario.

## Deferred Tasks

- None.
"@
  Write-Text (Join-Path $Active "reviews/review.md") @"
# Review

## Intake Review

- Status: pending
- Notes:

## Spec Review

- Status: pending
- Open high-impact clarifications:
- WHAT/HOW separation:

## Plan Review

- Status: pending
- Spec gaps found from planning:

## Code Review

- Status: pending

## Validation Review

- Status: pending
"@
  Write-Output "Created active change: $Title"
  Show-EvolutionReminder
}

function Validate-Change([string]$Dir) {
  $required = @("summary.md", "spec.md", "tasks.md")
  $isActive = ((Resolve-Path -LiteralPath $Dir).Path -eq (Resolve-Path -LiteralPath $Active).Path)
  if ($isActive) {
    $required = @("summary.md", "spec.md", "plan.md", "tasks.md")
  }
  foreach ($file in $required) {
    if (-not (Test-Path -LiteralPath (Join-Path $Dir $file))) {
      throw "Missing $file in $Dir"
    }
  }
  if (-not (Test-Path -LiteralPath (Join-Path $Dir "reviews"))) {
    throw "Missing reviews/ in $Dir"
  }
  $summary = Join-Path $Dir "summary.md"
  $meta = Parse-FrontMatter $summary
  $status = $meta["status"]
  if (-not $status) { throw "summary.md missing status front matter." }
  $phase = $meta["phase"]
  $planReview = $meta["plan_review"]
  $spec = Read-Text (Join-Path $Dir "spec.md")
  $reviewText = ""
  $reviewPath = Join-Path $Dir "reviews/review.md"
  if (Test-Path -LiteralPath $reviewPath) { $reviewText = Read-Text $reviewPath }
  $tasks = Read-Text (Join-Path $Dir "tasks.md")
  if ($isActive -and $phase -match "^(implement|validate|done)$" -and $spec -match "\[NEEDS CLARIFICATION:") {
    throw "spec.md has high-impact [NEEDS CLARIFICATION] markers. Resolve them or move the change back to intake/plan before implementation."
  }
  if ($isActive -and $phase -match "^(implement|validate|done)$" -and $planReview -ne "approved" -and $reviewText -notmatch "(?is)Plan Review.*Status:\s*approved") {
    throw "summary.md plan_review must be approved before implementation. Record plan approval in summary.md or reviews/review.md."
  }
  if ($isActive -and $tasks -match "(?m)^- \[[ xX]\] (?!T\d{3})" -and $tasks -notmatch "## Deferred Tasks") {
    throw "tasks.md task lines must use T### ids with target paths and validation notes so agents can execute them predictably."
  }
  if ($status -eq "completed") {
    $validation = Get-ValidationStatus $summary $meta
    if ($validation -ne "pass") { throw "completed change must have validation_status: pass or a passing Validation section." }
    if ($tasks -match "- \[ \] " -and $tasks -notmatch "## Deferred Tasks\s+(\r?\n)+-\s+(None|Deferred|Explained)") {
      throw "completed change has pending tasks without a Deferred Tasks explanation."
    }
  }
}

function Show-Status {
  Ensure-Dirs
  $summary = Join-Path $Active "summary.md"
  if (-not (Test-Path -LiteralPath $summary)) {
    Write-Output "No active change."
    return
  }
  $meta = Parse-FrontMatter $summary
  Write-Output "Active: $($meta["title"])"
  Write-Output "Status: $($meta["status"])"
  Write-Output "Phase: $($meta["phase"])"
}

function New-ClosedId([hashtable]$Meta) {
  $date = Get-DateText
  if ($Meta["updated_at"] -match "^\d{4}-\d{2}-\d{2}$") { $date = $Meta["updated_at"] }
  $slug = $Meta["slug"]
  if (-not $slug) { $slug = ConvertTo-Slug $Meta["title"] }
  $id = "$date-$slug"
  return $id
}

function Move-Active([string]$TargetBase, [string]$Status, [string]$Reason) {
  Ensure-Dirs
  $summary = Join-Path $Active "summary.md"
  if (-not (Test-Path -LiteralPath $summary)) { throw "No active change." }
  $meta = Parse-FrontMatter $summary
  if ($TargetBase -eq $Archive -and $Status -notin @("completed", "blocked", "abandoned")) {
    throw "close status must be completed, blocked, or abandoned."
  }
  if ($Status -eq "completed") { Validate-Change $Active }
  $targetLocation = if ($TargetBase -eq $Parking) { "parking" } else { "archive" }
  $newStatus = if ($TargetBase -eq $Parking) { "parked" } else { $Status }
  Set-FrontMatterValues $summary @{
    status = $newStatus
    location = $targetLocation
    updated_at = (Get-DateText)
  }
  if ($Reason) {
    Add-Content -Encoding UTF8 -LiteralPath $summary -Value "`n## Transition Note`n`n- $Reason`n"
  }
  $meta = Parse-FrontMatter $summary
  $id = New-ClosedId $meta
  $target = Join-Path $TargetBase $id
  $n = 2
  while (Test-Path -LiteralPath $target) {
    $target = Join-Path $TargetBase "$id-$n"
    $n++
  }
  Move-Item -LiteralPath $Active -Destination $target
  New-Item -ItemType Directory -Path $Active | Out-Null
  Reindex
  if ($TargetBase -eq $Archive) { Invoke-EvolutionCheck "close" }
  Write-Output "Moved active change to $target"
}

function Resume-Change([string]$Id) {
  Ensure-Dirs
  Assert-NoActive
  $source = Join-Path $Parking $Id
  if (-not (Test-Path -LiteralPath $source)) { throw "Parking change not found: $Id" }
  $summary = Join-Path $source "summary.md"
  if (Test-Path -LiteralPath $summary) {
    Set-FrontMatterValues $summary @{
      status = "in_progress"
      location = "active"
      updated_at = (Get-DateText)
    }
  }
  Move-Item -LiteralPath $source -Destination $Active
  Reindex
  Write-Output "Resumed $Id into active. Run validate before continuing."
}

function Search-Index([string]$Query) {
  if (-not (Test-Path -LiteralPath $IndexPath)) { Reindex }
  $items = Get-Content -Encoding UTF8 -Raw -LiteralPath $IndexPath | ConvertFrom-Json
  $items | Where-Object { ($_ | ConvertTo-Json -Depth 8) -match [regex]::Escape($Query) } |
    Select-Object id,title,status,location,path,validation_status | Format-Table -AutoSize
}

function Show-Context {
  Write-Output "Required:"
  foreach ($p in @("AGENTS.md", "docs/ECL.md", "harness/changes/active/summary.md", "harness/changes/active/spec.md", "harness/changes/active/plan.md", "harness/changes/active/tasks.md")) {
    if (Test-Path -LiteralPath (Join-Path $Root $p)) { Write-Output "- $p" }
  }
  if (-not (Test-Path -LiteralPath (Join-Path $Root "harness/changes/active/summary.md")) -and
      (Test-Path -LiteralPath $EvolutionPending)) {
    Write-Output "- harness/evolution/pending.md"
  }
  if (-not (Test-Path -LiteralPath (Join-Path $Root "harness/changes/active/summary.md")) -and
      (Test-Path -LiteralPath (Join-Path $Root "docs/STATUS.md"))) {
    Write-Output "- docs/STATUS.md"
  }
  Write-Output ""
  Write-Output "History index:"
  if (Test-Path -LiteralPath $IndexPath) { Write-Output "- harness/changes/INDEX.json" } else { Write-Output "- Run scripts/harness-change.ps1 reindex" }
}

Ensure-Dirs
switch ($Command) {
  "new" { New-Change ($Args -join " ") }
  "status" { Show-Status }
  "validate" { Validate-Change $Active; Write-Output "ECL active change is valid." }
  "park" { Move-Active $Parking "parked" ($Args -join " ") }
  "resume" { Resume-Change $Args[0] }
  "close" { Move-Active $Archive $Args[0] "" }
  "search" { Search-Index ($Args -join " ") }
  "context" { Show-Context }
  "reindex" { Reindex; Invoke-EvolutionCheck "reindex" }
  "index-json" { Write-Output (Get-IndexJson) }
  default { throw "Command required: new/status/validate/park/resume/close/search/context/reindex" }
}
```

### 5.2 `scripts/harness-evolve.ps1`

```powershell
param(
  [Parameter(Position = 0)]
  [ValidateSet("check", "collect", "mark-complete")]
  [string]$Command = "check",

  [int]$Threshold = 5,
  [int]$Window = 10,
  [string]$Reason = "manual"
)

$ErrorActionPreference = "Stop"

$Root = (Get-Location).Path
$Changes = Join-Path $Root "harness/changes"
$IndexPath = Join-Path $Changes "INDEX.json"
$Evolution = Join-Path $Root "harness/evolution"
$StatePath = Join-Path $Evolution "state.json"
$PendingPath = Join-Path $Evolution "pending.md"
$ResultsPath = Join-Path $Evolution "results.tsv"
$Proposals = Join-Path $Evolution "proposals"

function Ensure-EvolutionDirs {
  foreach ($dir in @($Evolution, $Proposals)) {
    if (-not (Test-Path -LiteralPath $dir)) {
      New-Item -ItemType Directory -Path $dir | Out-Null
    }
  }
}

function Write-Text([string]$Path, [string]$Content) {
  $parent = Split-Path -Parent $Path
  if ($parent -and -not (Test-Path -LiteralPath $parent)) {
    New-Item -ItemType Directory -Path $parent | Out-Null
  }
  Set-Content -Encoding UTF8 -LiteralPath $Path -Value $Content
}

function Read-State {
  Ensure-EvolutionDirs
  if (-not (Test-Path -LiteralPath $StatePath)) {
    $initial = [ordered]@{
      enabled = $true
      threshold = $Threshold
      window = $Window
      last_evolved_archive_count = 0
      last_evolved_change_id = $null
      last_score = $null
      last_run_at = $null
      pending = $false
    }
    Write-Text $StatePath (($initial | ConvertTo-Json -Depth 5) + "`n")
  }
  return Get-Content -Encoding UTF8 -Raw -LiteralPath $StatePath | ConvertFrom-Json
}

function Write-State($State) {
  Write-Text $StatePath (($State | ConvertTo-Json -Depth 8) + "`n")
}

function Test-AutoEvolveArchive($Item) {
  $id = [string]$Item.id
  if ($id -match "^auto-evolve-harness-") { return $true }
  foreach ($tag in @($Item.tags)) {
    if ([string]$tag -eq "auto-evolve") { return $true }
  }
  return $false
}

function Get-ArchiveItems {
  if (-not (Test-Path -LiteralPath $IndexPath)) {
    throw "Missing harness/changes/INDEX.json. Run scripts/harness-change.ps1 reindex first."
  }
  $raw = Get-Content -Encoding UTF8 -Raw -LiteralPath $IndexPath
  if ([string]::IsNullOrWhiteSpace($raw)) { return @() }
  $parsed = $raw | ConvertFrom-Json
  $items = @($parsed | ForEach-Object { $_ })
  return @($items | Where-Object {
    $_.location -eq "archive" -and -not (Test-AutoEvolveArchive $_)
  } | Sort-Object updated_at, id)
}

function Ensure-ResultsHeader {
  if (-not (Test-Path -LiteralPath $ResultsPath)) {
    Write-Text $ResultsPath "timestamp`tchange_id`told_score`tnew_score`tstatus`tdimension`tnote`teval_mode`n"
  }
}

function Add-ResultRow([string]$ChangeId, [string]$OldScore, [string]$NewScore, [string]$Status, [string]$Dimension, [string]$Note, [string]$EvalMode) {
  Ensure-ResultsHeader
  if ($Status -notin @("keep", "revert", "rejected", "noop")) {
    throw "status must be keep, revert, rejected, or noop."
  }
  if ($EvalMode -notin @("independent_review", "dry_run", "full_test")) {
    throw "eval_mode must be independent_review, dry_run, or full_test."
  }
  $timestamp = (Get-Date).ToString("s")
  $line = @($timestamp, $ChangeId, $OldScore, $NewScore, $Status, $Dimension, ($Note -replace "`t", " "), $EvalMode) -join "`t"
  Add-Content -Encoding UTF8 -LiteralPath $ResultsPath -Value $line
}

function New-Pending([object[]]$ArchiveItems, $State, [string]$TriggerReason) {
  if (Test-Path -LiteralPath $PendingPath) {
    Write-Output "Harness evolution already pending: harness/evolution/pending.md"
    return
  }
  $candidateItems = @($ArchiveItems | Select-Object -Last $State.window)
  $candidateLines = @()
  foreach ($item in $candidateItems) {
    $path = [string]$item.path
    if (-not $path) { $path = "harness/changes/archive/$($item.id)" }
    $candidateLines += "- $path/summary.md"
  }
  $now = (Get-Date).ToString("s")
  $content = @'
# Harness Evolution Pending

Generated at: {{NOW}}

## Trigger

- Reason: {{TRIGGER_REASON}}
- Eligible archived changes since last evolution: {{DELTA}}
- Threshold: {{THRESHOLD}}
- Scan window: {{WINDOW}}
- INDEX source: harness/changes/INDEX.json
- Excludes: archive ids beginning with auto-evolve-harness- and archives tagged auto-evolve

## Candidate Archives

{{CANDIDATE_LINES}}

These candidates are the trigger snapshot. Before processing, rebuild `harness/changes/INDEX.json`
and use the current eligible archive window so changes closed after this file was generated are not
missed.

## Instruction For Codex

Run harness auto-evolve:
1. Read docs/ECL.md and this pending file.
2. Rebuild `harness/changes/INDEX.json`, then inspect the current eligible archive window first.
3. Read spec/plan/tasks/reviews only when evidence requires it.
4. Extract repeated failures, verification gaps, user corrections, and reusable constraints.
5. Generate `harness/evolution/proposals/YYYY-MM-DD-auto-evolve.md` from the proposal template in docs/ECL.md or references/ecl-harness.md before editing harness files.
6. Request one independent auditor/subagent score before applying. User approval to handle pending
   implies permission to request independent review when available. If the environment still
   requires explicit authorization, ask once. If scoring is unavailable, declined, or still
   unauthorized after asking, record `status=noop` with `eval_mode=dry_run` and do not auto-apply.
7. Apply only accepted candidates with archive evidence, project relevance, score >= 80, and independent approval.
8. Prefer clarifying existing rules over adding new sections, documents, scripts, or workflows.
9. Run harness checks and relevant business gates.
10. Record one terminal result in `harness/evolution/results.tsv`: `keep` for accepted deltas,
    `noop` for reviewed evidence with no durable rule, `rejected` for pre-apply hard-gate
    failures, or `revert` if an applied delta fails validation.
11. Run `harness-evolve mark-complete` after writing the result. If you cannot complete these
    steps, park or close blocked; do not close completed while leaving the same pending file.
'@
  $content = $content.Replace("{{NOW}}", $now)
  $content = $content.Replace("{{TRIGGER_REASON}}", $TriggerReason)
  $content = $content.Replace("{{DELTA}}", [string]($ArchiveItems.Count - [int]$State.last_evolved_archive_count))
  $content = $content.Replace("{{THRESHOLD}}", [string]$State.threshold)
  $content = $content.Replace("{{WINDOW}}", [string]$State.window)
  $content = $content.Replace("{{CANDIDATE_LINES}}", ($candidateLines -join "`n"))
  Write-Text $PendingPath $content
  $State.pending = $true
  Write-State $State
  Write-Output "Created harness/evolution/pending.md"
}

function Check-Evolution {
  Ensure-EvolutionDirs
  Ensure-ResultsHeader
  $state = Read-State
  if (-not $state.enabled) {
    Write-Output "Harness auto-evolve disabled in harness/evolution/state.json."
    return
  }
  if (-not $state.threshold) { $state.threshold = $Threshold }
  if (-not $state.window) { $state.window = $Window }
  $archives = @(Get-ArchiveItems)
  if ([int]$state.last_evolved_archive_count -gt $archives.Count) {
    $state.last_evolved_archive_count = $archives.Count
    Write-State $state
  }
  $delta = [Math]::Max(0, $archives.Count - [int]$state.last_evolved_archive_count)
  if ($delta -lt [int]$state.threshold) {
    Write-Output "Harness evolution not due ($delta/$($state.threshold) new archived changes)."
    return
  }
  New-Pending $archives $state $Reason
}

function Collect-EvolutionInput {
  Check-Evolution
  if (Test-Path -LiteralPath $PendingPath) {
    Write-Output "Read: harness/evolution/pending.md"
  }
}

function Mark-Complete {
  $state = Read-State
  $archives = @(Get-ArchiveItems)
  $state.last_evolved_archive_count = $archives.Count
  $last = @($archives | Select-Object -Last 1)
  $state.last_evolved_change_id = if ($last.Count -gt 0) { $last[0].id } else { $null }
  $state.last_run_at = (Get-Date).ToString("s")
  $state.pending = $false
  Write-State $state
  if (Test-Path -LiteralPath $PendingPath) {
    Remove-Item -LiteralPath $PendingPath
  }
  Ensure-ResultsHeader
  Write-Output "Marked harness evolution complete."
}

switch ($Command) {
  "check" { Check-Evolution }
  "collect" { Collect-EvolutionInput }
  "mark-complete" { Mark-Complete }
  default { throw "Command required: check/collect/mark-complete" }
}
```

### 5.3 `scripts/lint-ecl.ps1`

```powershell
$ErrorActionPreference = "Stop"

$Root = (Get-Location).Path
$Changes = Join-Path $Root "harness/changes"
$Active = Join-Path $Changes "active"
$IndexPath = Join-Path $Changes "INDEX.json"
$HarnessChange = Join-Path $Root "scripts/harness-change.ps1"
$HarnessEvolve = Join-Path $Root "scripts/harness-evolve.ps1"
$StatusPath = Join-Path $Root "docs/STATUS.md"
$EvolutionState = Join-Path $Root "harness/evolution/state.json"

function Fail([string]$Message) {
  Write-Error $Message
  exit 1
}

if (-not (Test-Path -LiteralPath $Changes)) {
  Fail "Missing harness/changes. Run ecl-harness-engineer or create ECL harness structure."
}

foreach ($dir in @("active", "parking", "archive")) {
  if (-not (Test-Path -LiteralPath (Join-Path $Changes $dir))) {
    Fail "Missing harness/changes/$dir."
  }
}

if (-not (Test-Path -LiteralPath $HarnessChange)) {
  Fail "Missing scripts/harness-change.ps1."
}

if (-not (Test-Path -LiteralPath $HarnessEvolve)) {
  Fail "Missing scripts/harness-evolve.ps1."
}

if (-not (Test-Path -LiteralPath $EvolutionState)) {
  Fail "Missing harness/evolution/state.json."
}

if (-not (Test-Path -LiteralPath $StatusPath)) {
  Fail "Missing docs/STATUS.md. Create a lightweight handoff summary; active change files override it when present."
}

if (Test-Path -LiteralPath (Join-Path $Active "summary.md")) {
  foreach ($file in @("summary.md", "spec.md", "plan.md", "tasks.md")) {
    if (-not (Test-Path -LiteralPath (Join-Path $Active $file))) {
      Fail "Active change missing $file."
    }
  }
  if (-not (Test-Path -LiteralPath (Join-Path $Active "reviews"))) {
    Fail "Active change missing reviews/."
  }
  $summary = Get-Content -Encoding UTF8 -Raw -LiteralPath (Join-Path $Active "summary.md")
  $spec = Get-Content -Encoding UTF8 -Raw -LiteralPath (Join-Path $Active "spec.md")
  $tasks = Get-Content -Encoding UTF8 -Raw -LiteralPath (Join-Path $Active "tasks.md")
  $review = ""
  $reviewPath = Join-Path $Active "reviews/review.md"
  if (Test-Path -LiteralPath $reviewPath) { $review = Get-Content -Encoding UTF8 -Raw -LiteralPath $reviewPath }
  $phase = [regex]::Match($summary, '(?m)^phase:\s*"?([^"\r\n]+)"?').Groups[1].Value
  $planReview = [regex]::Match($summary, '(?m)^plan_review:\s*"?([^"\r\n]+)"?').Groups[1].Value
  if ($phase -match "^(implement|validate|done)$" -and $spec -match "\[NEEDS CLARIFICATION:") {
    Fail "Active spec.md still has high-impact [NEEDS CLARIFICATION] markers. Resolve them or move phase back to intake/plan."
  }
  if ($phase -match "^(implement|validate|done)$" -and $planReview -ne "approved" -and $review -notmatch "(?is)Plan Review.*Status:\s*approved") {
    Fail "Active change cannot enter implementation until plan_review is approved in summary.md or an equivalent approved Plan Review is recorded."
  }
  if ($tasks -match "(?m)^- \[[ xX]\] (?!T\d{3})") {
    Fail "tasks.md contains executable task lines without T### ids. Use '- [ ] T001 [P?] [US?] Action with target path and validation note'."
  }
}

if (-not (Test-Path -LiteralPath $IndexPath)) {
  Fail "Missing harness/changes/INDEX.json. Run: powershell -NoProfile -ExecutionPolicy Bypass -File scripts/harness-change.ps1 reindex"
}
$actual = Get-Content -Encoding UTF8 -Raw -LiteralPath $IndexPath
$expected = (& $HarnessChange index-json) -join "`n"
if ($actual.Trim() -ne $expected.Trim()) {
  Fail "harness/changes/INDEX.json is stale. Run: powershell -NoProfile -ExecutionPolicy Bypass -File scripts/harness-change.ps1 reindex"
}

Write-Output "ECL lint passed."
```

### 5.4 `scripts/lint-encoding.ps1`

```powershell
$ErrorActionPreference = "Stop"

$markers = @(
  ([char]0x9505),
  ([char]0x951B),
  ([char]0x9286),
  ([char]0x9983),
  ([char]0x8133),
  ([char]0x7459),
  ([char]0x8930),
  ([char]0x95C6),
  ([char]0x9365),
  ([char]0x9359),
  ([char]0x9366),
  (([char]0x93C8).ToString() + ([char]0xE047).ToString())
)
$exclude = "\\(node_modules|vendor|\.git|dist|build|coverage|target|\.cache)\\"
$extensions = @(".ts", ".tsx", ".js", ".jsx", ".json", ".md", ".ps1", ".py", ".go", ".rs", ".java", ".cs", ".yml", ".yaml")
$violations = New-Object System.Collections.Generic.List[string]

Get-ChildItem -Recurse -File | Where-Object {
  $_.FullName -notmatch $exclude -and $extensions -contains $_.Extension
} | ForEach-Object {
  $path = $_.FullName
  $lines = @(Get-Content -Encoding UTF8 -LiteralPath $path)
  for ($i = 0; $i -lt $lines.Count; $i++) {
    foreach ($marker in $markers) {
      if ($lines[$i].Contains($marker)) {
        $rel = Resolve-Path -LiteralPath $path -Relative
        $violations.Add("${rel}:$($i + 1): possible mojibake marker '$marker'")
      }
    }
  }
}

if ($violations.Count -gt 0) {
  $violations | ForEach-Object { Write-Error $_ }
  exit 1
}

Write-Output "Encoding lint passed."
```

## 6. Validation Expectations

After creating ECL harness files, run the selected profile's equivalent commands. For the Bash
profile:

```bash
bash scripts/harness-change.sh reindex
bash scripts/harness-evolve.sh check
bash scripts/lint-ecl.sh
bash scripts/lint-encoding.sh
```

For the PowerShell profile:

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/harness-change.ps1 reindex
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/harness-evolve.ps1 check
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/lint-ecl.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/lint-encoding.ps1
```

If `lint-ecl` reports stale `INDEX.json`, run the generated `harness-change reindex` equivalent,
then rerun `lint-ecl`.
If `lint-ecl` reports missing `docs/STATUS.md`, create it from the STATUS template. Do not let
CI or hooks generate it automatically.
If `harness/evolution/pending.md` exists and no active change exists, read it as pending
maintenance before `docs/STATUS.md`. Reading it does not start auto-evolve or block ordinary user
work. Once Codex starts acting on pending evidence, finish with proposal + results.tsv +
`harness-evolve mark-complete`, or park/block. Do not let hooks or CI apply pending changes.