Plan B: fully remove the degraded/degradedStages concept #293

New issue

david · 2026-08-19T04:27:21Z

david commented

2026-08-19 04:27:21 +00:00

Summary

Delete the now-vestigial degraded / degradedStages concept everywhere:
the mr-result.json artifact schema, the MR description, the final
run summary, and the design docs. This is a deliberate artifact-schema
change and per AGENTS.md must update DESIGN.md, IMPLEMENTATION_PLAN.md,
and the corresponding tests together.

Full implementation plan already exists at
docs/plan-B-remove-degraded.md
(committed in #292) — this issue tracks executing it.

Background

Precondition (met): Plan A — bundling per-stage skill bodies and
retiring *_SKILL_PATH — shipped via issue #28 (closed). Plan A's own
description explicitly states degraded/degradedStages were
intentionally retained at that time for schema/downstream
compatibility, always false/[].
degraded only ever existed to signal "a per-stage skill was missing, so
a default body was used." After Plan A there are no external skills, so
it can never actually be true again — it's dead weight.
Verified still present, unremoved, as of this issue: DegradedStage,
PriorDegradedStage, degradedStages, priorDegradedStages all exist
verbatim in src/mr/types/mr.ts.
No existing issue currently tracks this removal (checked via search
across open/closed issues) — this issue closes that gap.

Why this is a separate, larger change than Plan A

Removing degradedStages touches the artifact contract (mr-result.json),
so it carries schema-compatibility risk and doc churn that Plan A
deliberately avoided by keeping the flag around.

Implementation Details (see `docs/plan-B-remove-degraded.md` for full detail)

Artifact schema + validator — remove DegradedStage, PriorDegradedStage,
the degraded field on stage result types, degradedStages on MrResult,
and priorDegradedStages on the MR stage input
(src/mr/types/mr.ts, src/artifacts/helpers/validateMrResult.ts,
src/artifacts/services/mrResultArtifact.ts).
MR description + final summary — remove the degradedStages input and
the "## Degraded stages" section (src/mr/helpers/buildMrDescription.ts,
src/orchestrator/helpers/buildFinalSummary.ts).
Stage compose + runners — ComposeStagePromptResult becomes
{ systemPrompt } only; remove degraded from every Run*StageResult.
Orchestrator — remove the priorDegradedStages assembly block and the
degraded ? ... : undefined mapping in src/orchestrator/services/runPipeline.ts.
Tests — update alongside the schema change (see plan doc for the full
file list).
Design docs (mandatory, per AGENTS.md) — update DESIGN.md (§3.4 schema,
Stage sections, D15/D16, failure-mode table, config section),
IMPLEMENTATION_PLAN.md, and AGENTS.md's error-handling policy table.

Acceptance Criteria

DegradedStage, PriorDegradedStage, degraded, degradedStages,
priorDegradedStages fully removed from src/mr/types/mr.ts and all
consumers.
mr-result.json schema no longer includes degradedStages; validator
updated to reject it (or ignore it, per the schema-compat decision made
during implementation).
MR description and final run summary no longer reference degraded
stages.
ComposeStagePromptResult is { systemPrompt } only.
DESIGN.md, IMPLEMENTATION_PLAN.md, AGENTS.md updated together with
the code change (per AGENTS.md's schema-compatibility convention).
grep -rn "degrad" src returns clean (or only intentional historical
references in comments/docs).
npm run lint, npm test, npm run build all pass.

Test Plan

Update src/artifacts/helpers/validateMrResult.test.ts,
src/artifacts/services/mrResultArtifact.test.ts,
src/mr/helpers/buildMrDescription.test.ts,
src/orchestrator/helpers/buildFinalSummary.test.ts,
src/orchestrator/services/runPipeline.test.ts,
src/*/services/run*Stage.test.ts,
src/stage/helpers/composeStagePrompt.test.ts per the plan doc.
Gated E2E: PILOOP_E2E=1 npm run e2e to confirm mr-result.json is still
valid without degradedStages.

Compatibility note

Removing degradedStages is a breaking change to mr-result.json. Since
run artifacts are per-run and ephemeral under .pi-loop/runs/<run-id>/,
there is no historical migration to perform, but the schema version/notes in
DESIGN.md must record the removal.

Precondition: #28 (Plan A, closed)
Plan doc: docs/plan-B-remove-degraded.md (committed in #292)

## Summary Delete the now-vestigial `degraded` / `degradedStages` concept everywhere: the `mr-result.json` artifact schema, the MR description, the final run summary, and the design docs. This is a **deliberate artifact-schema change** and per `AGENTS.md` must update `DESIGN.md`, `IMPLEMENTATION_PLAN.md`, and the corresponding tests together. Full implementation plan already exists at [`docs/plan-B-remove-degraded.md`](../src/branch/main/docs/plan-B-remove-degraded.md) (committed in #292) — this issue tracks executing it. ## Background - **Precondition (met):** Plan A — bundling per-stage skill bodies and retiring `*_SKILL_PATH` — shipped via issue #28 (closed). Plan A's own description explicitly states `degraded`/`degradedStages` were **intentionally retained** at that time for schema/downstream compatibility, always `false`/`[]`. - `degraded` only ever existed to signal "a per-stage skill was missing, so a default body was used." After Plan A there are no external skills, so it can never actually be `true` again — it's dead weight. - Verified still present, unremoved, as of this issue: `DegradedStage`, `PriorDegradedStage`, `degradedStages`, `priorDegradedStages` all exist verbatim in `src/mr/types/mr.ts`. - No existing issue currently tracks this removal (checked via search across open/closed issues) — this issue closes that gap. ## Why this is a separate, larger change than Plan A Removing `degradedStages` touches the artifact contract (`mr-result.json`), so it carries schema-compatibility risk and doc churn that Plan A deliberately avoided by keeping the flag around. ## Implementation Details (see `docs/plan-B-remove-degraded.md` for full detail) 1. **Artifact schema + validator** — remove `DegradedStage`, `PriorDegradedStage`, the `degraded` field on stage result types, `degradedStages` on `MrResult`, and `priorDegradedStages` on the MR stage input (`src/mr/types/mr.ts`, `src/artifacts/helpers/validateMrResult.ts`, `src/artifacts/services/mrResultArtifact.ts`). 2. **MR description + final summary** — remove the `degradedStages` input and the "## Degraded stages" section (`src/mr/helpers/buildMrDescription.ts`, `src/orchestrator/helpers/buildFinalSummary.ts`). 3. **Stage compose + runners** — `ComposeStagePromptResult` becomes `{ systemPrompt }` only; remove `degraded` from every `Run*StageResult`. 4. **Orchestrator** — remove the `priorDegradedStages` assembly block and the `degraded ? ... : undefined` mapping in `src/orchestrator/services/runPipeline.ts`. 5. **Tests** — update alongside the schema change (see plan doc for the full file list). 6. **Design docs (mandatory, per AGENTS.md)** — update `DESIGN.md` (§3.4 schema, Stage sections, D15/D16, failure-mode table, config section), `IMPLEMENTATION_PLAN.md`, and `AGENTS.md`'s error-handling policy table. ## Acceptance Criteria - [ ] `DegradedStage`, `PriorDegradedStage`, `degraded`, `degradedStages`, `priorDegradedStages` fully removed from `src/mr/types/mr.ts` and all consumers. - [ ] `mr-result.json` schema no longer includes `degradedStages`; validator updated to reject it (or ignore it, per the schema-compat decision made during implementation). - [ ] MR description and final run summary no longer reference degraded stages. - [ ] `ComposeStagePromptResult` is `{ systemPrompt }` only. - [ ] `DESIGN.md`, `IMPLEMENTATION_PLAN.md`, `AGENTS.md` updated together with the code change (per AGENTS.md's schema-compatibility convention). - [ ] `grep -rn "degrad" src` returns clean (or only intentional historical references in comments/docs). - [ ] `npm run lint`, `npm test`, `npm run build` all pass. ## Test Plan - Update `src/artifacts/helpers/validateMrResult.test.ts`, `src/artifacts/services/mrResultArtifact.test.ts`, `src/mr/helpers/buildMrDescription.test.ts`, `src/orchestrator/helpers/buildFinalSummary.test.ts`, `src/orchestrator/services/runPipeline.test.ts`, `src/*/services/run*Stage.test.ts`, `src/stage/helpers/composeStagePrompt.test.ts` per the plan doc. - Gated E2E: `PILOOP_E2E=1 npm run e2e` to confirm `mr-result.json` is still valid without `degradedStages`. ## Compatibility note Removing `degradedStages` is a **breaking change to `mr-result.json`**. Since run artifacts are per-run and ephemeral under `.pi-loop/runs/<run-id>/`, there is no historical migration to perform, but the schema version/notes in `DESIGN.md` must record the removal. ## Related - Precondition: #28 (Plan A, closed) - Plan doc: `docs/plan-B-remove-degraded.md` (committed in #292)

david added the

chore

label

2026-08-19 04:27:21 +00:00

Sign in to join this conversation.