Skip to content

docs(rfc): record that a dashboard save stages, the catalog flow is retired, and the approval gate is its own module - #19287

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/18642-rfc-amendment-2
Oct 12, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/18642-rfc-amendment-2

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: put on main the record of three decisions already taken for the dashboard line in issue #18642, so the pull requests that build the page trace to a decision instead of proposing one.

docs/request-for-change/rfc-crewmate-dynamic-dashboard.md is partial, and its body still describes the template model: staging belongs to dashboard_preview, the undo is a dashboard rollback verb, "show me another" routes to a template catalog, and the picker is parked as a later phase. Three decisions have moved past that text. A save stages rather than lands; the picker and the id-loaded catalog flow are retired for a reference gallery; and the approval gate is a module of its own, so a renderer may carry a package binding without publishing anything.

The First Principles lane reads an RFC off the base branch, so an amendment carried beside the change it authorises reads as a proposal rather than as a record. #18755 carries a BLOCK naming exactly two of these ("the skill now teaches ask-then-save, which skips the preview, and drops the catalog flow... Only this diff's own amendment supersedes either"), and #18777 carries one naming the third, that its renderer serves a bound package with no approval step recorded anywhere a reviewer can read.

Why it matters

Two open pull requests are blocked on decisions that exist in a conversation and in no place a reviewer can read. The alternative is one /ai-review override first-principles per pull request, spent against a single head sha and lapsing on the next push, so a maintainer has to be asked again every time either moves. One record on main clears both on their next rebase and keeps clearing them.

The third decision also closes a hole the earlier amendment left open. That amendment lets an agent-written page render with no gateway-minted wrapper, and its reasons are reasons about the page's AUTHOR; none of them says an unapproved page is safe to render. The gate it depends on was one sentence inside a paragraph about ownership. It is now a rule with the dependency stated, so dropping the gate reopens the no-wrapper decision instead of quietly simplifying a save path.

Not a goal

  • No code change. Nothing in src/, website/ or test/ moves here; the behaviour this records is built by the pull requests that rebase onto it.
  • Not re-deciding the content. All three decisions were taken for the dashboard line on 2026-10-12; this writes them down and names the passage each supersedes.
  • Not a re-audit of the rest of the document. Only the front matter's two freshness keys, the "where they disagree" bullet and the new amendment are touched.
  • Not the index ROW. docs/request-for-change/README.md keeps its table row and its status column untouched. One sentence is appended to that file's revision paragraph, which is where the directory records each dated revision of a document, in the shape the rows above it already use.

What changed (motivation -> approach -> change)

The blocking lane reads the base branch, so the fix has to BE on the base branch: a standalone, non-draft documentation pull request, the same shape as #19204, small enough to merge ahead of the work it unblocks.

One new section, ## Amendment 2026-10-12, at the end of the RFC, in the device the document's first amendment already uses: it opens by saying it records accepted decisions rather than proposing them, the body above is left as written, and the amendment holds wherever the two disagree.

Decision 1, a save stages. A save writes the page into the owner agent's package as a staged copy: no version cut, no values pushed. The live path is stage -> preview -> a person approves -> apply, with apply cutting a version from the staged page and taking no page argument, so what lands is provably the page the person read. The undo is artifact_revert on the package artifact rather than a second rollback mechanism over the same versions. The section then states the dependency the earlier amendment only implied: remove this gate and the no-wrapper decision is reopened. It supersedes the verb table in the agent-surface section.

Decision 2, the catalog flow is retired. A crewmate composes its own page. There is no picker, and no page is loaded by id at run time. The twelve built-in dashboard templates, the three panel templates and the good task-dashboard pages change role to reference pages in a gallery the writing agent copies from and adapts, with no instance, no adopt and no id anything resolves. It supersedes the non-goal that parked the picker as a later phase, the "show me another" row, the registry row and its built-ins paragraph, and the open question that parked the caller in a phase-2 picker.

Decision 3, the gate is its own module. A two-row table names which module owns which half: the save module owns stage, show, the person's yes and apply, and apply is the only thing that cuts a version; the renderer and its host serve an applied version of the bound package and fill the fields that page subscribed to. From that split follows the sentence the renderer needs: a renderer may hold the name of a package it does not publish, because it serves an applied version and nothing is applied until a person approves, so a bound package with no applied version renders nothing. The ordering is one-way and both halves are part of the decision: a renderer may land before the gate, and the gate may not be dropped afterwards. It supersedes the backward-compatibility sentence about the page read resolving a default, wherever that is read as naming a page being the same act as publishing it.

Front matter moves its two freshness keys only: last-audited to 2026-10-12 and audited-at to 8f6baa05c9, the commit this was read against. status stays partial and doc-pr keeps naming the first standalone documentation pull request, since this one neither changes the document's phase state nor supersedes that landing.

Tests

No test pins this file's bytes and no golden covers it. The gates that do read it are the documentation ones, and all three were run on this diff:

$ python3 scripts/docs_lint.py --test
Self-test passed                                  # exit 0
$ ./scripts/docs-lint.sh
All documentation checks passed                   # exit 0, no finding names either file
$ python3 scripts/check_brand_name.py --test
                                                  # exit 0
$ BRAND_BASE_REF=origin/main python3 scripts/check_brand_name.py
brand gate: no misspellings of 'Kiro Crew' in the lines added since origin/main   # exit 0

Manual verification: read the rendered section against each passage it names to check the passage is still findable and that the supersede is specific rather than wholesale; checked that the amendment's own claims about the earlier amendment match that text as merged; and confirmed the index table row and its status column are byte-identical to main, so the only index change is the appended revision sentence.

Backwards compatibility

Removes nothing. The diff is two documentation files. No wire contract, route, tool, field, default or public function is rejected, renamed or removed, and no record or row is pruned. The superseded passages stay in the document as written, with the amendment naming them and holding over them, so a reader of the old text finds the correction rather than a hole.

Any other suggestions on the work

The three decisions are deliberately in one section rather than three pull requests: decision 1 is the premise decision 3's module split exists to protect, and decision 2 is what makes a page something an agent writes rather than picks, which is why there is anything to stage. Splitting them would land the gate and the thing that depends on the gate at different times on the base every lane reads.

Related Issues

Part of #18642. Unblocks the First Principles lane on #18755 and #18777, which rebase onto this once it is on main.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • Existing tests pass and new tests added for new functionality (documentation gates run above; no code path changes)
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@chenmingwei23
chenmingwei23 requested review from a team and KiroCrewCaptain as code owners October 12, 2026 05:57
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 12, 2026
@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 1a29503d015d38a72fcca474bedde706416d348d ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 1a29503d015d38a72fcca474bedde706416d348d touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — 🟡 CONCERNS

Design-level review of 1a29503d015d38a72fcca474bedde706416d348d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

The rule that "apply is the only thing that cuts a version" is false for the existing artifact store, so the renderer-safety premise in Decision 3 is not enforced by anything.

Watch

  • The gate's invariant is unenforced. Decision 3 says "apply is the only thing that cuts a version" and "nothing is applied until a person has approved it". The artifact tools already cut versions with no person involved. artifact_update and artifact_save both write versions. artifact_revert (src/kiro_crew/mcp_tools/artifacts.py:861) PATCHes with "Snapshot is forced True… this becomes a new version". Because this amendment makes artifact_revert the undo, the undo is itself a version cut outside the gate. The chain: an agent writes or reverts the bound package through the artifact tools → a new version exists → a renderer serving "an applied version" (feat(crew-log): register a tree fold under a third key kind, so a block can bind a tree #18777) serves a page no person approved. That is the hole this amendment says it closes, and it reopens the no-wrapper exemption. The fix is reversible: amend the text. But feat(crew-log): register a tree fold under a third key kind, so a block can bind a tree #18777 will cite this record as its licence.
    Clears when: the amendment defines an "applied" version as something only the gate can produce (for example an applied marker or pointer that apply alone sets, and that the renderer reads), and says whether artifact_revert re-enters the gate or sets that marker only to a version that was already approved.

Suggestions

  • State that agent-facing artifact write and revert tools must not move the applied pointer on a dashboard-bound package. That turns "the gate may not be dropped" from prose into a constraint the renderer PRs can test.

[DESIGN-REVIEWED] 1a29503

Description read

[DESCRIPTION-READ] bce949dbe2c8dbb44c6ccc5a09fa32810fb06751d3c0bf5a9c71479fddad319d

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 1a29503d015d38a72fcca474bedde706416d348d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 1a29503

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 1a29503d015d38a72fcca474bedde706416d348d: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 12, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 1a29503d015d38a72fcca474bedde706416d348d — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] 1a29503

Verdict parsed from the review's SHA-scoped output markers for commit 1a29503d015d38a72fcca474bedde706416d348d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 1a29503d015d38a72fcca474bedde706416d348d: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 12, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-rfc-amendment-2 branch from 2b61bb4 to b4d6598 Compare October 12, 2026 07:11
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 12, 2026
@chenmingwei23

Copy link
Copy Markdown
Contributor Author

Thanks for the design review. This PR is a docs-only amendment to the RFC record, so I want to answer both CONCERNS without changing the decisions the amendment is recording — the two points are worth capturing as the RFC's own open questions rather than silently resolved by this edit.

1. "apply is the only thing that cuts a version" vs. generic artifact tools can already version a bound package. This is a real gap in the current implementation, and you've named it precisely: artifact_update returns a new version with no approval step, so an owner could cut a version of a bound package directly and a renderer keyed on the bound slug would serve an unapproved page. The amendment states the design intent (apply is the gate; a renderer serves only applied versions), but it does not yet define what makes a version "applied" in a way a renderer can check. That belongs in the implementation record the follow-up will cite, as either (a) a marker that only dashboard apply writes, which the renderer requires, or (b) a refusal of generic version-cut on a dashboard-bound package. I've left the amendment stating the intent and flagged this as the open implementation question rather than asserting a mechanism the code does not yet enforce — adding that mechanism here would expand this docs PR's frozen goal into a design decision it should not make unilaterally.

2. The approval record is a single-author decision, not yet a governance ruling. Also correct. The amendment lifts standing blocks and reverses a documented flow, and a one-author "decided on" line is not a maintainer sign-off. The right resolution is a maintainer approving this PR on record (or the description naming the maintainer who took these decisions). That is a human decision I can't make for the record, so I'm surfacing it here rather than treating the author line as sufficient.

Neither point is a code defect in this diff (the diff is two docs files), and CONCERNS is advisory, so it does not block readiness — but both are legitimate and are better carried as the RFC's open questions than papered over. Deferring to a maintainer on point 2.

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Oct 12, 2026
…etired, and the approval gate is its own module

Three decisions already taken for the dashboard line in issue #18642 lived
only inside the pull requests that depend on them. The First Principles lane
reads an RFC off the base branch, so each read as a proposal there.

- A save STAGES a page: stage -> preview -> a person approves -> apply, with
  artifact_revert as the undo. The 2026-10-11 amendment's no-wrapper exemption
  rests on this gate, and that dependency is now written down.
- The template picker and the id-loaded catalog flow are retired. A crewmate
  composes its own page; the twelve dashboard templates, the three panel
  templates and the good task-dashboard pages become a reference gallery, with
  nothing loaded by id at run time.
- The approval gate is its own module, so a renderer may name a package it does
  not publish: a binding says which package a reader would see, and the gate
  says whether anything is applied to see.
@chenmingwei23
chenmingwei23 force-pushed the feat/18642-rfc-amendment-2 branch from b4d6598 to 1a29503 Compare October 12, 2026 07:59
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Oct 12, 2026
@chenmingwei23
chenmingwei23 merged commit e5a0b3d into main Oct 12, 2026
101 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/18642-rfc-amendment-2 branch October 12, 2026 09:35
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant