admin/my-pi
1
0
Fork 0
mirror of https://bitbucket.org/siakitem/my-pi.git synced 2026-08-28 08:35:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: vendor permission system source

Browse Source
This commit is contained in:
云服务部-叶林立
2026-08-19 14:35:19 +08:00
parent 198584daf8
commit 410c50a3e5
809 changed files with 157793 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files
pi-permission-system/docs/retro/0581-model-triage-authorizer-adr.md
+104
View File
@@ -0,0 +1,104 @@
---
issue: 581
issue_title: "pi-permission-system: decision record for the case-by-case model judge (ModelTriageAuthorizer)"
---
# Retro: #581 — decision record for the case-by-case model judge (ModelTriageAuthorizer)
## Stage: Planning (2026-07-14T00:00:00Z)
### Session summary
Planned Phase 11 Step 7: a documentation-only ADR (`docs/decisions/0007-model-triage-authorizer.md`) recording the six settled `ModelTriageAuthorizer` parameters (ask-only surface, decorator shape, fail-closed delegation, `origin: "authorizer:model"` audit tagging, live-only non-persistence, ruleset-expressible bounded delegation).
The design was already fully settled in the architecture doc's `Discriminating delegation` section; the plan transcribes it into an ADR, marks Step 7 complete, and leaves [#472] open with a linked ADR.
Next stage is `/build-plan` (no test cycles).
### Observations
- Authored by the operator (`gotgenes`) and unambiguous (settled architecture-doc design), so the `ask-user` gate was skipped.
- One genuine design choice existed — non-persistence as live-only vs. quarantined-for-review.
Settled as **live-only** (matching the architecture doc's stated preference; quarantine is parenthetical there), with quarantine recorded as a rejected-for-now alternative and a named future extension.
- Flagged an implementation seam deferred to [#472]: a model grant is non-persistent, so `origin: "authorizer:model"` may ride the review-log entry rather than the `RuleOrigin` enum (unlike `"yolo"`, which becomes a real `Rule`).
The ADR settles the *decision* (audited + distinguishable); the mechanism is [#472]'s.
- `Release: independent` per the roadmap — docs-only `docs:` commits, no batch, cuts no release on its own.
- Grep confirmed `ModelTriageAuthorizer` appears only in `architecture.md` — no `src/`/`test/`/README surface references the not-yet-built symbol, so no code or user-doc edits are in scope.
- Build stage must mark Step 7 `✅` on both the heading and the `S7` Mermaid node, and link the ADR from the `Discriminating delegation` section, in the implementation commit (not deferred to ship).
## Stage: Implementation — Build (2026-07-14T00:00:00Z)
### Session summary
Executed the docs-only plan in three commits: authored `docs/decisions/0007-model-triage-authorizer.md` (the six settled parameters, rejected alternatives, accepted limitations), marked Phase 11 Step 7 `✅` (heading + `S7` Mermaid node) with an ADR link in the `Discriminating delegation` section and a refreshed [#472] deferral reference, then reconciled a stale non-persistence parenthetical the pre-completion reviewer flagged.
No `src/`/`test/` changes; `pnpm run lint` and `rumdl` green throughout.
Next stage is `/ship-issue`.
### Observations
- Pre-completion reviewer: **WARN** (1 non-blocking finding), now resolved.
Reviewer warning: the architecture doc's `Discriminating delegation` non-persistence bullet still offered `(or is persisted quarantined for human review)`, which ADR 0007 §5 explicitly rejects — fixed in commit `a9831a4a` (`it stays live-only, per ADR 0007`).
This was exactly the cross-doc consistency the plan's `Invariants at risk` section named; the parenthetical lived at line 627, outside the section the plan's grep targeted.
- Deviation from plan scope: **Phase 11 close deferred.**
All 7 Phase 11 steps are now `✅`, but the plan scoped this build to marking Step 7 only.
Flipping the Phase 11 heading to `(complete)` and extracting its details to a `history/phase-11-*.md` file (the pattern Phases 9–10 follow) is a distinct phase-close activity the plan did not include — now unblocked as a follow-up, best done at `/retro` or a dedicated phase-close pass.
- Step 3 (comment on [#472] linking the ADR) is deferred to `/ship-issue` per the plan — no code change.
- Mermaid `S7` node render verified by the reviewer (`mmdc` rendered all 4 diagrams cleanly).
## Stage: Final Retrospective (2026-07-14T23:11:31Z)
### Session summary
The plan/build/ship stages took Phase 11 Step 7 from plan through ship, authoring ADR 0007 by transcribing the architecture doc's settled `ModelTriageAuthorizer` prose and marking the roadmap step `✅`.
The retro then reversed all of it: the operator pointed out that #581 was a *decision-making* task and I had treated it as *transcription*, and a live design conversation surfaced two concrete use cases (auto-denying errant typo paths; adjudicating opaque bash) that revealed the real design is broader than — and in one respect contradicts — the prose I had committed.
Outcome: ADR 0007 and the Step 7 completion were reverted, [#581] was reopened and closed `not_planned` as superseded, and [#591] was filed capturing the tool-augmented, deny-first, extensible design for `/plan-issue`.
### Observations
#### What went well
- **Scope discipline at the phase boundary.**
The build stage recognized that completing Step 7 finishes all 7 Phase 11 steps, but deliberately did *not* scope-creep into the phase-close (heading `(complete)` + `history/phase-11-*.md` extraction).
It flagged the close as a follow-up, and the ship stage correctly routed it to `/finish-phase` — the archival is a distinct activity, not an implicit rider on the last step.
- **Release attribution was precise.**
The ship stage did not trust the plan's `Release: ship independently` marker blindly — it checked `exclude-paths` and correctly concluded that `docs/decisions` + `docs/architecture` changes cut no release, skipping the release-please merge.
The two axes (roadmap batching vs. whether a release physically cuts) were kept distinct.
- **The pre-completion reviewer earned its keep on a docs-only change.**
It rendered all four Mermaid diagrams, ran the deterministic gates, and caught the one real defect — validating that the reviewer is worth dispatching even when no code changed.
- `wrong-abstraction` (headline) — I treated a decision-record task as a transcription task.
Because the architecture doc already articulated six `ModelTriageAuthorizer` parameters, planning judged the design "settled" and skipped the `Decide` / `ask-user` gate, then build reformatted the prose into ADR shape.
But an ADR's entire value is the deliberation behind it; #581 was asking me to *think*, not to reshape existing text.
Impact: a full plan→build→ship cycle (6 commits, a closed issue, a roadmap `✅`) landed on `main` and then had to be reverted.
Not caught by any deterministic gate — the ADR was internally consistent and faithful to the prose; only the operator's judgment caught that the prose itself was the wrong input.
- `premature-convergence` — the one design choice I *did* notice as open (non-persistence: live-only vs. quarantine) I resolved unilaterally by deferring to the architecture doc's parenthetical lean, rather than surfacing it.
The conversation showed the real forks were far larger (deny vs. allow verdict range; tool-augmented vs. verdict vs. classifier; in-package vs. extensible) — none of which I put to the operator before committing.
- `missing-context` (secondary, now moot) — the build missed the quarantine parenthetical at `architecture.md:627` when reconciling the `Discriminating delegation` section, costing a pre-completion `WARN` round and a follow-up commit (`a9831a4a`).
A downstream symptom of the same root cause; the whole ADR is now reverted, so the specific miss no longer matters.
#### What caused friction (user side)
- **Bidirectional-feedback opportunity, not a fault.**
The operator's redirection was the pivotal intervention of the session — but it landed at `/retro`, after a full cycle had shipped.
The two use cases that reframed everything (errant paths; opaque bash) were context the operator held from the start; had the `Decide` gate not been skipped, an `ask-user` at plan time would have surfaced them before any commit.
The lesson is on the agent side (don't skip the gate for a decision-record issue), but the earliest-possible unlock was a plan-time conversation.
### Diagnostic details
- **Model-performance correlation** — One subagent dispatched: `pre-completion-reviewer` (187.9s, 25 tool uses) on a judgment-appropriate task (ADR fidelity, Mermaid render, doc consistency).
No mismatch.
`tidy-first-assessor` was correctly skipped (docs-only).
Planning dispatched no Explore/Plan subagents — but this was a *symptom* of the root error, not a virtue: I accepted `architecture.md`'s prose as settled instead of probing whether the decisions held, so no exploration felt necessary.
- **Escalation-delay tracking** — No rabbit holes.
The one lint issue (MD057 forward-reference link to the not-yet-created ADR, at plan time) was resolved in a single edit (link → code span).
No sequence exceeded 1 tool call on any error.
- **Unused-tool detection** — the tool left unused at plan time was `ask-user` itself: the `Decide` gate exists precisely to surface open design choices, and skipping it (not a too-narrow grep) is the true root cause.
The secondary grep miss at `architecture.md:627` was preventable with `grep -n "quarantine\|live-only\|non-persist" architecture.md`, but it is moot now that the ADR is reverted.
- **Feedback-loop gap analysis** — `rumdl`/`lint` ran incrementally after each doc edit in every stage; the pre-completion reviewer ran once at the end per protocol.
No end-loaded-verification gap.
### Changes made
1. Deleted `packages/pi-permission-system/docs/decisions/0007-model-triage-authorizer.md` (the premature ADR).
2. Reverted `packages/pi-permission-system/docs/architecture/architecture.md`: un-`✅`'d Phase 11 Step 7 (heading + `S7` Mermaid node, now noting supersession by [#591]), removed the ADR-link sentence from `Discriminating delegation`, restored the original non-persistence parenthetical, rewrote the [#472] sweep-disposition to record the revert, and added the `[#591]` reference-link definition.
3. Filed [#591] (`pi-permission-system: design the model-assisted permission judge`) capturing both use cases and the tool-augmented / deny-first / extensible architecture; supersedes [#581], design gate for [#472].
4. Reopened [#581] and closed it `not_planned` with a superseded-by-[#591] comment; added a design-gate pointer comment on [#472].
5. Added a decision-record/ADR carve-out to `.pi/prompts/plan-issue.md`'s `Decide` gate: do not skip the `ask-user` gate just because a design is already written down (Refs #581).
6. Wrote this Final Retrospective entry.