david/pi-loop
Watch
1
0
Fork
You've already forked pi-loop
 0
Code Issues 20 Pull requests 1 Projects Releases Packages Wiki Activity Actions

documentation: commit orphaned local docs (ADR-017, ADR-019, design/plan docs) #292

Merged
david merged 1 commit from documentation/2026-08-19/reconcile-orphaned-local-docs into main 2026-08-19 04:26:56 +00:00
Conversation 0 Commits 1 Files changed 8 +1594
david commented 2026-08-19 04:26:52 +00:00
Owner
Copy link

Summary

Reconciles 8 documentation files that existed on disk in this local clone
but were never committed to git. Root cause: a local, untracked
.git/info/exclude entry (/docs/) silently shadowed the entire docs/
tree from git's perspective — the same underlying misconfiguration behind
issue #286 / ADR-019's docs-stage failure. The exclude entry has been
removed locally; this PR reconciles the actual content that got orphaned
by it over time.

Each file was cross-checked against current shipped code/docs for
staleness before committing (see per-file notes below).

What's included

  • docs/adr/017-mr-skip-when-no-changes.md — Accepted ADR (2026-08-16).
    Verified accurate against the shipped hasNothingToShip() /
    runMrStage implementation. Fills the 016→018 gap in the ADR sequence.
  • docs/adr/019-fatal-docs-scope-ignore-preflight.md — Accepted ADR
    (2026-08-19) for the fatal docs-scope preflight shipped in PR #289;
    already referenced by path from AGENTS.md/DESIGN.md but never itself
    committed until now.
  • docs/design-commit-model.md — per-stage commit model design doc.
    Fixed inline: §7/§8 referenced a nonexistent cleanPiLoopGitignore();
    corrected to the actual shipped assertPiLoopGitignore() (a fail-fast
    assert per ADR-009, not a mutating cleanup).
  • docs/design-rest-mr-creation.md — REST-based MR/PR creation design
    doc. Fixed inline: the "Proposed Architecture" section described an
    outdated hybrid model (LLM agent still drives git/content, code only
    does the REST POST). Added a "Superseded" note clarifying the MR stage
    that actually shipped is fully deterministic — no agent session at
    all    . The *MrClient/REST endpoint details in §4.1 were already
    accurate and are unchanged.
  • docs/plan-A-bundle-skill-bodies.md — self-marked "STATUS: DONE";
    verified consistent with the current bundled-skills architecture
    (src/skills/, degraded permanently false/[]).
  • docs/plan-B-remove-degraded.md — verified accurate and still
    outstanding     (DegradedStage/degradedStages remain verbatim in
    src/mr/types/mr.ts). Tracked going forward by a new issue (see below).
  • docs/plan-B1-vertex-anthropic-provider.md,
    docs/scope-option-B-claude-on-vertex.md — Claude-on-Vertex feature
    planning docs, referenced by README.md's shipped "Claude on Vertex"
    section. Verified consistent with the shipped
    src/model/vertexAnthropic/ implementation.

Verification

  • No code changes; documentation-only PR (2 files received small inline
    corrections for accuracy, described above).
  • Each doc cross-referenced against current source/AGENTS.md/DESIGN.md
    before inclusion.

Related

  • Issue #286 / PR #289 / ADR-019
    (the docs-scope preflight this reconciliation was prompted by).
  • Follow-up: a new issue tracks docs/plan-B-remove-degraded.md's
    still-outstanding work.
## Summary Reconciles 8 documentation files that existed on disk in this local clone but were never committed to git. Root cause: a local, untracked `.git/info/exclude` entry (`/docs/`) silently shadowed the entire `docs/` tree from git's perspective — the same underlying misconfiguration behind issue #286 / ADR-019's docs-stage failure. The exclude entry has been removed locally; this PR reconciles the actual content that got orphaned by it over time. Each file was cross-checked against current shipped code/docs for staleness before committing (see per-file notes below). ## What's included - **`docs/adr/017-mr-skip-when-no-changes.md`** — Accepted ADR (2026-08-16). Verified accurate against the shipped `hasNothingToShip()` / `runMrStage` implementation. Fills the 016→018 gap in the ADR sequence. - **`docs/adr/019-fatal-docs-scope-ignore-preflight.md`** — Accepted ADR (2026-08-19) for the fatal docs-scope preflight shipped in PR #289; already referenced by path from `AGENTS.md`/`DESIGN.md` but never itself committed until now. - **`docs/design-commit-model.md`** — per-stage commit model design doc. **Fixed inline**: §7/§8 referenced a nonexistent `cleanPiLoopGitignore()`; corrected to the actual shipped `assertPiLoopGitignore()` (a fail-fast assert per ADR-009, not a mutating cleanup). - **`docs/design-rest-mr-creation.md`** — REST-based MR/PR creation design doc. **Fixed inline**: the "Proposed Architecture" section described an outdated hybrid model (LLM agent still drives git/content, code only does the REST POST). Added a "Superseded" note clarifying the MR stage that actually shipped is **fully deterministic — no agent session at all**. The `*MrClient`/REST endpoint details in §4.1 were already accurate and are unchanged. - **`docs/plan-A-bundle-skill-bodies.md`** — self-marked "STATUS: DONE"; verified consistent with the current bundled-skills architecture (`src/skills/`, `degraded` permanently `false`/`[]`). - **`docs/plan-B-remove-degraded.md`** — verified accurate and **still outstanding** (`DegradedStage`/`degradedStages` remain verbatim in `src/mr/types/mr.ts`). Tracked going forward by a new issue (see below). - **`docs/plan-B1-vertex-anthropic-provider.md`**, **`docs/scope-option-B-claude-on-vertex.md`** — Claude-on-Vertex feature planning docs, referenced by README.md's shipped "Claude on Vertex" section. Verified consistent with the shipped `src/model/vertexAnthropic/` implementation. ## Verification - No code changes; documentation-only PR (2 files received small inline corrections for accuracy, described above). - Each doc cross-referenced against current source/AGENTS.md/DESIGN.md before inclusion. ## Related - Issue #286 / PR #289 / [ADR-019](docs/adr/019-fatal-docs-scope-ignore-preflight.md) (the docs-scope preflight this reconciliation was prompted by). - Follow-up: a new issue tracks `docs/plan-B-remove-degraded.md`'s still-outstanding work. 
Reconciles 8 documentation files that existed locally but were never
committed, due to a local .git/info/exclude entry (/docs/) silently
shadowing the entire docs/ tree from git's perspective. This
contradicted ADR-002 (no git info exclude) and is the same root cause
behind issue #286/ADR-019's docs-stage failure.

- docs/adr/017-mr-skip-when-no-changes.md: Accepted ADR (2026-08-16),
  verified accurate against the shipped hasNothingToShip()/runMrStage
  implementation. Fills the 016->018 gap in the ADR sequence.
- docs/adr/019-fatal-docs-scope-ignore-preflight.md: Accepted ADR
  (2026-08-19) for the fatal docs-scope preflight shipped in PR #289;
  already referenced by path from AGENTS.md/DESIGN.md but never itself
  committed.
- docs/design-commit-model.md: per-stage commit model design doc.
  Fixed inline: references to a nonexistent cleanPiLoopGitignore()
  corrected to the actual shipped assertPiLoopGitignore() (a fail-fast
  assert per ADR-009, not a mutating cleanup).
- docs/design-rest-mr-creation.md: REST-based MR/PR creation design
  doc. Fixed inline: the 'Proposed Architecture' section described an
  outdated hybrid model (LLM agent still drives git/content). Added a
  superseded-note clarifying the MR stage that shipped is fully
  deterministic with no agent session at all; the *MrClient/REST
  endpoint details in SS4.1 were already accurate and are unchanged.
- docs/plan-A-bundle-skill-bodies.md: self-marked DONE; verified
  consistent with the current bundled-skills architecture.
- docs/plan-B-remove-degraded.md: verified accurate and still
  outstanding (degradedStages etc. remain in src/mr/types/mr.ts);
  tracked going forward by a new issue.
- docs/plan-B1-vertex-anthropic-provider.md,
  docs/scope-option-B-claude-on-vertex.md: Claude-on-Vertex feature
  planning docs, referenced by README.md's shipped 'Claude on Vertex'
  section; verified consistent with the shipped
  src/model/vertexAnthropic/ implementation.

Pi-Loop-Stage: none (manual documentation commit)
david merged commit deebe7a79b into main 2026-08-19 04:26:56 +00:00
david deleted branch documentation/2026-08-19/reconcile-orphaned-local-docs 2026-08-19 04:26:56 +00:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels   
batch

   
bug

   
chore
Maintenance tasks, cleanup, housekeeping

  
documentation

   
enhancement

   
pi-loop

   
ready

   
resume
No labels
batch
bug
chore
documentation
enhancement
pi-loop
ready
resume
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
david/pi-loop!292
No description provided.