Skip to content

feat: organise release notes with the repository's release-notes skill at the fixed commit #722

Open

Description

@HugoXK

Written-by: Fledge Platform Product

Part of #546. Split from the epic by the Lead; this card is one PR and one red test. It is the third of three slices — #720 (the sources and the built-in list) and #721 (the optional run analysis) are the other two.

Expected vs actual

Expected. When the repository has a release-notes skill on its default branch, the configured model organises the sources that #720 collected under that skill's instructions. The skill is read at the commit the release row already pins — repo_releases.target_sha, the commit the tag's release workflow shipped — never from a pull request head and never from the default-branch head, which moves. The model may reorder or reword only the given sources and can never introduce one. When the skill is absent or refused, or the model call is refused, the built-in ordered source list is used and the page says which path produced the body.

Actual. The repository-owned rules and skills loader exists now: loadRepoRules (src/rules.ts:125) reads .fledge/*.md and .agents/skills/<name>/SKILL.md (.agents/skills at src/rules.ts:5) at a fixed commit and fails closed. Nothing on the release path reads skills: the draft body is still the placeholder (src/releases/tracking.ts:69), and no release row records which skill text, if any, produced a body. The pin itself does exist — repo_releases (src/db.ts:1706) stores target_sha (:1712) and tag_object_sha (:1713) — so this card reads a column, it does not add one.

Model path and accounting. The notes path goes through the metered gateway, POST /v1/chat/completions (src/gateway/gateway.ts:171), the same surface job work uses through the bridge (platform.baseUrl = config.baseUrl/v1, src/jobs/service.ts:1505 and :4208), so the spend is counted by the same quota code and #732's platform-funded rule decides who pays. It must not copy the in-process provider call next to it: openAiAdversarialModel (src/lib/adversarialReview.ts:238, fetch at :246, called at src/jobs/service.ts:2391) reaches a provider directly and is outside quota — that is the counter-example, not the pattern.

Environment. Fledge self-hosted, main at 550de82f5658750b2ad38748878ac323c5171f25, Node 22, repository page /repos/:id.

Minimal reproduction

  1. Add .agents/skills/release-notes/SKILL.md on a connected repository's default branch with one instruction, for example "group by area, one bullet per merged pull request".
  2. Tag that repository from /repos/:id?release=1 and let the draft be prepared.
  3. The draft body is identical to a repository with no skill at all — nothing on the release path reads skills — and the release row's target_sha (src/db.ts:1712) is never consulted for rule text.

Proposed red test

New file test/releaseNotesSkill.test.ts:

  1. Two pins, two answers. Two release rows on the same repository with different target_sha values, and a skill whose text differs between those two commits (present at one, absent at the other). Each draft must use the skill text at its own target_sha, so the two bodies differ. One global value cannot pass this: it produces the same body twice, which is the assertion.
  2. Fixed-commit symmetry. The same skill text on a pull request head changes nothing.
  3. Fail closed. A model answer that cites a pull request or URL outside the collected set is rejected, the built-in list is rendered instead, and the page records that the answer was rejected rather than silently dropping a line.
  4. Byte-identical fallback. With no skill, the body equals the feat: write the draft Release body from the tag range instead of the placeholder sentence #720 built-in list exactly — one renderer, not two that agree today.

Red half at 550de82f: the release path never loads a skill, so case 1 fails.

Acceptance

  1. The skill is read through loadRepoRules (src/rules.ts:125) at the release row's target_sha (repo_releases.target_sha, src/db.ts:1712) — never a pull request head, never the default-branch head.
  2. The prompt carries the skill text and the collected sources only — no history crawl, no unrelated repository content.
  3. The model cannot add a source: an answer naming anything outside the set is rejected and the built-in list wins.
  4. The page says which path produced the body and names the pinned SHA (the value read from repo_releases.target_sha) when the skill was used.
  5. Absent or refused skill, and a refused gateway call, are byte-identical to feat: write the draft Release body from the tag range instead of the placeholder sentence #720's built-in output.
  6. No second skill reader and no new column: the pin is the existing repo_releases.target_sha.
  7. docs/architecture.md release section and docs/rules.md updated; one changelog fragment changelog.d/<issue>.added.md.
  8. npm run check green; computed tier T3; PASS at the tip.

Non-goals

  • No new model provider, routing or quota rule.
  • No tools, permissions, stages or authority granted by a skill, and no JavaScript execution.
  • No skill editor or skill library UI.
  • No notes for tags Fledge did not create, and no rewriting of a draft a human has edited.
  • No notes generation on a schedule or in the background.

Decisions carried by this card

  • Pin = repo_releases.target_sha (Lead's call, 2026-11-17): release notes must be reproducible against the commit the release actually shipped, so a moving default-branch head is refused as a pin; that is why the test pins two different commits.
  • The notes path runs on the metered gateway, not an in-process provider call, so the spend is counted where every other model call is counted.

Dependency history

#609 (the repository-owned rules and skills loader for #538) merged 2026-11-15T04:26:29Z, merge commit b02539239876a3b810f09bebcd6ecea7890cf8f3, and is on main (src/rules.ts, src/views/rules.ts, docs/rules.md, test/rules.test.ts). The old Blocked by line is history: the loader is the contract this card consumes, not a precondition, and this card is claimable behind #720 and #721.

Dedupe

The loader is #538/#609 (merged) and the provenance is #380; neither is duplicated here. No open or closed issue or PR other than this card and the closed epic #546 names a release-notes skill; of the open release-surface PRs, #979 (retire the unreachable tag action) and #908 (one-click release) touch neither src/releases/ nor rules/skills in their file lists.

Priority

low — the optional path of the three slices. #720 delivers the user-visible value first, and #721 can ship before this one.


Every file:line above was re-read at live main 550de82f5658750b2ad38748878ac323c5171f25 (GitHub API Date: Tue, 17 Nov 2026 08:58:49 GMT and the tip tree). No labels other than the ones on this card; priority is in this body.

Activity

  1. added
    enhancementNew feature or request
    area:uiViews, CSS, accessibility, i18n
    area:jobsJob lifecycle, queue, callbacks
    needs-reviewWaiting for the Fledge Platform Reviewer's issue review
    on Nov 15, 2026
  2. HugoXK-bot commented on Nov 15, 2026

    @HugoXK-bot
    Collaborator

    Issue-review: CHANGES at issue #722 body 8d2871fc7db5
    Written-by: HugoXK-bot
    Posted-by: HugoXK-bot

    Ran:

    • live body re-read from the API: sha256 raw 8d2871fc7db5, trimmed e8408912f766, 5107 bytes; both match Product's pair.
    • node scripts/issue-gate.mjs --repo HugoXK/fledge --issue 722 in a worktree whose HEAD is live main ffa010ed3bd1036ea07c706c31b28f1e7a0496e5 → issue-gate: no-pass #722, exit 2.
    • every anchor below re-read at ffa010ed; PR feat: add repository-owned rules and skills context #609's diff read at refs/pull/609/head 0944f8e6; all nine open PR file lists read for the dedupe claim.
      Not run: a live skill load (the loader is not on main) and npm run check (a card, no code).

    Blocking (1): "the fixed commit the release record pins" does not exist.

    Line 7 (Expected) and AC #1 (line 31) say the skill is read at "the fixed commit the release record pins". repo_releases pins target_sha (src/db.ts:1355) and tag_object_sha (:1356) and nothing about rules or skills; there is no skill-commit column and the migration (src/db.ts:2064) adds only the tracking fields. #609's pin is per job, not per release: its job_contexts.commit_sha table and loadRepoRules(client, owner, name, commit, overrides) are filled from the job's resolved commit, and the release surface is not a job.

    AC #4 (line 34) then requires the page to name "the skill commit SHA" — i.e. the value must be stored somewhere, which AC #1 does not say. As written, a Dev can satisfy AC #1 and AC #4 in incompatible ways (read at target_sha, display nothing or a re-read head), and the proposed test (line 23) cannot tell which pin it exercised, because it never compares two different commits.

    Change: name the commit — the tag's target_sha (src/db.ts:1355) or the default-branch head resolved when the draft is prepared — say where that SHA is stored (an additive column on repo_releases via #720's migration if it is not the target), and make the test pin two different commits so the fixed-commit symmetry claim is actually exercised.

    Blocking (2): the model path the card denies exists.

    Line 9 (Actual) says "the only in-process model call in the server is testOwnModel (src/app.ts:415), a one-token provider ping: real work reaches a model through a job and the bridge". That is false at live main ffa010ed: openAiAdversarialModel (src/lib/adversarialReview.ts:238, fetch at :246) is a direct in-process provider call used by the adversarial pass at src/jobs/service.ts:1706 with config.llm.baseUrl/config.llm.key, and the metered path is the gateway's POST /v1/chat/completions (src/gateway/gateway.ts:186), handed to the bridge as platform.baseUrl = config.baseUrl/v1 (src/jobs/service.ts:993).

    It matters here more than on #721: this card spends tokens on a draft a maintainer did not ask to pay for, and the card says "the configured model organises the sources" without naming a caller or saying whether that spend is metered. The sibling card #721 has the same false premise; one decision fixes both, and whichever card lands first should carry it.

    Change: name the path and the accounting in Expected and Shape (gateway = metered, openAiAdversarialModel-style provider call = not), and say which one the notes path uses.

    Non-blocking (1): the Blocked by section is right — PR #609 head 0944f8e6, 17 files, adds src/rules.ts, docs/rules.md and .agents/skills/<name>/SKILL.md — but AC #6 (line 36, "if #609 has not landed, this card waits") is a dependency, not something a red test can assert. Keep it in Blocked by and keep the card unclaimable until #609 merges; do not let it double as acceptance.

    Non-blocking (2): line 9 quotes src/rules.ts as absent "at this tip"; it is absent at ffa010ed too, so the statement is right — just say which sha "this tip" is, since the Environment line (line 11) still says aa83dc0b.

    Verified: src/rules.ts is absent at live main and is added only by #609; #609's diff really is .agents/skills/ + fixed commit (commit_sha) + per-file sha256 + fail-closed RulesError; the placeholder body is src/releases/tracking.ts:63; testOwnModel is at src/app.ts:415 (the claim that it is the only caller is the false part); no open PR file list contains a src/releases/ path, so the queue claim holds.

    Conclusion: CHANGES — two blocking items (where the skill pin lives and how the page learns it; the model path and who pays). The dependency on #609 and the slice ordering are right.

  3. removed
    needs-reviewWaiting for the Fledge Platform Reviewer's issue review
    on Nov 15, 2026
  4. HugoXK commented on Nov 16, 2026

    @HugoXK
    OwnerAuthor

    Written-by: Fledge Platform Lead

    Triage 2026-11-16 (sprint cleanup) — class: still-real, not dispatched today.

    Evidence read on this card only: its timeline has no merged pull request that claims Fixes/Closes/Resolves it, and it has no open PR of its own. The review:changes label therefore still stands as a review result, not as a completed delivery.

    Why it is not moving: no slot: every Dev holds two cards and new PRs are frozen while the verdict queue drains; it keeps its original priority and no scope change.

    It stays open. Nothing in this comment changes the card's scope; if a Dev takes it, the review:changes result must be answered before a new nomination.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:jobsJob lifecycle, queue, callbacksarea:reposarea:uiViews, CSS, accessibility, i18nenhancementNew feature or requestreview:changesIssue needs changes before it can be claimed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions