From da6a63d589f37cf3f836af1ac59431fb6c142feb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=BE=84=E6=BD=AD?= Date: Mon, 16 Nov 2026 20:26:00 +0800 Subject: [PATCH 1/4] feat: support evidence-backed workflow feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 澄潭 --- .agents/skills/issue-spec-workflow/SKILL.md | 2 + .../references/workflow-feedback.md | 62 +++++ .../skills/issue-spec-workflow/release.json | 8 +- docs/reference.md | 11 + docs/reference.zh-CN.md | 11 + internal/auth/auth.go | 1 + internal/commands/auth.go | 1 + internal/commands/commands.go | 4 + internal/commands/feedback.go | 98 ++++++++ internal/commands/workflows_test.go | 2 +- internal/feedback/event.go | 106 +++++++++ internal/feedback/event_test.go | 77 ++++++ internal/feedback/policy.go | 162 +++++++++++++ internal/feedback/record.go | 215 +++++++++++++++++ internal/github/client.go | 8 + internal/github/issue_labels.go | 76 ++++++ internal/github/operations.go | 8 + .../issues/feedback_integration_test.go | 225 ++++++++++++++++++ .../api/github/issues/integration_test.go | 13 +- internal/server/api/github/labels/routes.go | 14 ++ internal/server/api/github/labels/service.go | 13 + .../templates/assets/workflow-feedback.md | 62 +++++ internal/templates/skills.go | 5 +- internal/templates/skills_test.go | 2 +- internal/templates/workflow_feedback.go | 6 + issue-spec/specs/workflow-feedback/spec.md | 62 +++++ testdata/workflow-feedback/release-0.6.2.json | 12 + testdata/workflow-feedback/release-0.6.3.json | 12 + .../synthetic-third-release.json | 9 + 29 files changed, 1281 insertions(+), 6 deletions(-) create mode 100644 .agents/skills/issue-spec-workflow/references/workflow-feedback.md create mode 100644 internal/commands/feedback.go create mode 100644 internal/feedback/event.go create mode 100644 internal/feedback/event_test.go create mode 100644 internal/feedback/policy.go create mode 100644 internal/feedback/record.go create mode 100644 internal/github/issue_labels.go create mode 100644 internal/server/api/github/issues/feedback_integration_test.go create mode 100644 internal/templates/assets/workflow-feedback.md create mode 100644 internal/templates/workflow_feedback.go create mode 100644 issue-spec/specs/workflow-feedback/spec.md create mode 100644 testdata/workflow-feedback/release-0.6.2.json create mode 100644 testdata/workflow-feedback/release-0.6.3.json create mode 100644 testdata/workflow-feedback/synthetic-third-release.json diff --git a/.agents/skills/issue-spec-workflow/SKILL.md b/.agents/skills/issue-spec-workflow/SKILL.md index 0c9e45a2..5c39f816 100644 --- a/.agents/skills/issue-spec-workflow/SKILL.md +++ b/.agents/skills/issue-spec-workflow/SKILL.md @@ -22,6 +22,8 @@ For selected issue-spec steps, the built-in phase sequence and canonical artifac 3. Default to `--issue` for a bounded change with one code writer. A single child or subagent is an execution choice, not a reason to create TASK or PROCESS. Use `--proposal` with optional `--design` and `--implement` only when product, design, or concrete coordination risk requires them. File count does not select the path. 4. Read only selected issue bodies and typed planning artifacts. Historical REVIEW, VERIFY, evidence, receipt, finalization, Archive, and merge-authority data are explicit read-only audit history. +When project guidance opts into feedback, use [Workflow feedback](references/workflow-feedback.md) during relevant authorized work. + ## Optional Planning and Implementation - Create Proposal, Design, Implement, and TASK only when product, design, or coordination risk makes that planning useful. Create PROCESS only when a concrete execution need requires managed coordination: concurrent code writers, protection of pre-existing work through isolation, enforced path ownership, restartable cross-session handoff, or dependency-ordered integration. Generate selected canonical SPEC, QUESTION, TASK, and PROCESS planning artifacts; transition existing artifacts instead of regenerating them. diff --git a/.agents/skills/issue-spec-workflow/references/workflow-feedback.md b/.agents/skills/issue-spec-workflow/references/workflow-feedback.md new file mode 100644 index 00000000..b4ef0467 --- /dev/null +++ b/.agents/skills/issue-spec-workflow/references/workflow-feedback.md @@ -0,0 +1,62 @@ +# Workflow feedback + +Use this reference when a consumer project enables feedback in its shared guidance and authorized work exposes a concrete CLI limitation, workflow gap, or project policy problem. Continue the original task and use an ordinary Issue and comments. A skill or available token alone grants no publication authority. + +## Route and record + +1. Identify the owner from the observed behavior. Route CLI limitations and reusable workflow improvements to the configured upstream repository. Route project-specific guidance, validation, and release problems to the originating project. Keep uncertain ownership as a draft. Resolve the destination's Issue profile and repository before reading or writing. +2. Search open and closed discussions for the same cause with `issue-spec search issues --repo OWNER/REPO --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec read issue --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor. +3. For a new report, use `issue-spec issue create simple` with a self-contained body describing the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action. +4. Record each independent event with its original context. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events. +5. Preview before writing. Omit `--dry-run` when the write is authorized and the requested target and count are correct. + +```sh +issue-spec feedback record --repo OWNER/REPO --issue 42 --event-file occurrence.json --dry-run --json +``` + +```json +{ + "source_instance": "github:github.com", + "source_repository": "example/project", + "event_id": "release:v1.2.3@abc1234", + "observed_at": "2026-11-16T10:30:00+08:00", + "revision": "abc1234", + "summary": "The catalog deployment ran before publication and its download check returned HTTP 404.", + "evidence": ["https://github.com/example/project/actions/runs/123"] +} +``` + +Include only sanitized evidence. `revision` is optional. A preview reports the event key and projected confirmed count using the current identity. An event can be recorded by a contributor and remain unconfirmed. A configured reporter can confirm that event by verifying the evidence and recording the same key. The backend supplies the comment author. A submitted field claiming confirmation or identity carries no authority. + +An ambiguous submission is reconciled by rereading the Issue. Retry the same event file if needed. If the result shows a pending label action, an authorized caller can retry that action with the same event without increasing the count. Preserve the Issue URL in handoffs. + +## Enable and maintain a destination policy + +Use a dedicated ordinary policy Issue in the **destination** repository. Its body contains a single JSON object, optionally fenced as JSON. For each trusted account, get the stable ID from `issue-spec auth status --json` under the intended Issue profile (`.auth.user_id`). Then write the IDs as strings. + +```json +{ + "threshold": 3, + "priority_label": "priority/high", + "trusted_reporter_ids": ["123"], + "higher_priority_labels": ["priority/critical"], + "hold_labels": ["priority/deferred"] +} +``` + +The default mode is `suggest`. Set `"mode": "auto"` explicitly to permit automatic escalation. The repository must predefine the configured priority label before an automatic assignment can succeed. Higher-priority and hold labels are optional. `issue-spec/feedback-hold` and `wontfix` are recognized holds. A closed or locked Issue is ineligible. + +```sh +issue-spec feedback configure --repo OWNER/REPO --issue 17 --dry-run --json +issue-spec feedback configure --repo OWNER/REPO --issue 17 +``` + +Publishing requires permission to manage repository label definitions. The command binds the exact policy body to the repository's `issue-spec/feedback-policy` label definition. Change the policy Issue body and publish again to activate a new revision. Remove the policy label definition to disable feedback. During automatic escalation, issue-label permission is independently enforced by the selected backend. On self-hosted, comment recording uses contribution permissions and assigning labels uses triage permissions. Promotion adds only the configured label. + +The commands use the active Issue profile or an explicit global `--profile` verified for the destination. A Source Binding or external code host is independent of where policies, Issues and comments are stored. + +## Enable the project workflow + +Add a project file to `guidance.shared` in `issue-spec/config.yaml`. The file documents when to use this reference, the project and upstream destinations, sanitization rules, and the scope of standing publication authorization if any. Run `issue-spec workflow update --dry-run --repo OWNER/REPO` before adopting the generated reference. Project guidance stays in the project-owned file. + +For a requested interval review, include open and closed feedback Issues and compare their creation dates and dated evidence. Group by root cause and count distinct keys. Record the upstream fix, local adoption revision and comparable verification as they become available in relevant authorized work. Prefer the original Issue and its evidence links for handoff across sessions. diff --git a/.agents/skills/issue-spec-workflow/release.json b/.agents/skills/issue-spec-workflow/release.json index 33b7693e..4386b0cb 100644 --- a/.agents/skills/issue-spec-workflow/release.json +++ b/.agents/skills/issue-spec-workflow/release.json @@ -3,7 +3,7 @@ "release": "development", "source_revision": "unknown", "requirements_skill_content_id": "sha256:35e55ba3b52b377acbd36ca4305cd958e3bd593008d576a7a82c9b06ab862ed1", - "content_digest": "sha256:6644c5543ea8dd9914a3c7d34da7d12f19505d1cb10e99591f7985bb8e3bff7f", + "content_digest": "sha256:359588a8dfe370663d3a987b07078428226d378320c4e23aa38107fe0526fa6d", "files": [ { "path": ".agents/skills/issue-spec-apply/SKILL.md", @@ -19,7 +19,7 @@ }, { "path": ".agents/skills/issue-spec-workflow/SKILL.md", - "sha256": "bc48b5f608258aa5b821738100c68e6d2fa4d8e24aafc1ec615649482369869a" + "sha256": "2fa7c917aa6250ed19f22602aceecfa83aeb036f36925cfbddc9dc08e2133ea4" }, { "path": ".agents/skills/issue-spec-workflow/references/durable-maintenance.md", @@ -40,6 +40,10 @@ { "path": ".agents/skills/issue-spec-workflow/references/question-decisions.md", "sha256": "8c817bb08e73853101a42d8c4ca0e83e72fc81be04221f1f5004623588fa193c" + }, + { + "path": ".agents/skills/issue-spec-workflow/references/workflow-feedback.md", + "sha256": "38fe7d796ae14734b693ccf99509f0ea960d29e4aaba766f75d872704b50bf90" } ] } diff --git a/docs/reference.md b/docs/reference.md index 49bfc17f..1d535dd0 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -54,6 +54,17 @@ The preview reports paths, actions, hashes and conflicts. The apply performs the A legacy whole-directory Claude link is split while preserving previously exposed entries. Later upgrades only add generated skills, never unrelated project skills. Exact redundant Claude copies can become links; differing copies block the update. Existing worktrees retain their own committed skill version. Runtime host discovery still needs verification in a fresh session. +### Workflow feedback + +Use the [workflow feedback reference](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md) to enable optional, evidence-backed feedback in `guidance.shared`. The destination repository publishes its threshold, priority label and trusted reporter identities with `issue-spec feedback configure`. The same commands use the active GitHub or self-hosted Issue profile. Self-hosted repositories need a server that supports the repository label lookup endpoint. + +```bash +issue-spec feedback configure --repo owner/repo --issue 17 --dry-run --json +issue-spec feedback record --repo owner/repo --issue 42 --event-file occurrence.json --dry-run --json +``` + +Omit `--dry-run` for authorized writes. Reuse the event identity for retries. An enabled repository suggests priority changes by default. Automatic promotion requires an explicit policy and issue-label permission. + ### HTML review authoring HTML review authoring is enabled by default. To keep Proposal, Design, and Implement authoring on the typed Markdown workflow without loading or generating human-review projection instructions, configure the required boolean explicitly: diff --git a/docs/reference.zh-CN.md b/docs/reference.zh-CN.md index ebdbec3b..a533c571 100644 --- a/docs/reference.zh-CN.md +++ b/docs/reference.zh-CN.md @@ -25,6 +25,17 @@ issue-spec workflow which --repo owner/repo --json 新的长期 spec 默认写入 `issue-spec/specs//spec.md`。若 `openspec/specs//spec.md` 已存在,`durable-spec` 可以更新那个遗留的长期 spec,并报告所选的兼容路径。 +### 工作流反馈 + +通过 `guidance.shared` 启用可选的反馈流程。目标仓库维护者用 `issue-spec feedback configure` 发布复现阈值、优先级标签和可信报告者身份。GitHub 和自托管使用当前 Issue profile 下的同一套命令。自托管 Server 需支持按名称读取仓库标签。 [反馈指引与配置示例](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md) + +```bash +issue-spec feedback configure --repo owner/repo --issue 17 --dry-run --json +issue-spec feedback record --repo owner/repo --issue 42 --event-file occurrence.json --dry-run --json +``` + +在授权写入时去掉 `--dry-run`。重试沿用原始事件标识。启用后的默认行为是建议升级。自动升级还需目标仓库明确开启,并由后端校验标签权限。 + ### HTML review 创作指引 HTML review 创作指引默认启用。若要让 Proposal、Design 与 Implement 创作只使用类型化 Markdown 工作流,而不加载或生成面向人工 review 的 projection 指令,请显式配置这个必填布尔值: diff --git a/internal/auth/auth.go b/internal/auth/auth.go index f74388d0..0fa2e694 100644 --- a/internal/auth/auth.go +++ b/internal/auth/auth.go @@ -37,6 +37,7 @@ type Token struct { Value string `json:"-"` Source string `json:"source"` User string `json:"user,omitempty"` + UserID int64 `json:"user_id,string,omitempty"` Scopes []string `json:"scopes,omitempty"` Host string `json:"host"` Profile string `json:"profile,omitempty"` diff --git a/internal/commands/auth.go b/internal/commands/auth.go index 588aa166..99e60184 100644 --- a/internal/commands/auth.go +++ b/internal/commands/auth.go @@ -57,6 +57,7 @@ func (a *app) runAuthStatus(ctx context.Context, args []string) int { return 1 } token.User = user.Login + token.UserID = user.ID token.Scopes = scopes if *jsonOut { return a.outputJSON(map[string]any{"ok": true, "auth": token, "backend": token.Backend}) diff --git a/internal/commands/commands.go b/internal/commands/commands.go index f612ae87..60d8a8fb 100644 --- a/internal/commands/commands.go +++ b/internal/commands/commands.go @@ -91,6 +91,8 @@ func Execute(args []string, in io.Reader, out io.Writer, errOut io.Writer) int { return a.runIssue(ctx, args[1:]) case "comment": return a.runComment(ctx, args[1:]) + case "feedback": + return a.runFeedback(ctx, args[1:]) case "question": return a.runQuestion(ctx, args[1:]) case "projection": @@ -223,6 +225,8 @@ Usage: issue-spec comment create --repo owner/repo --issue N --body-file reply.md [--json] issue-spec comment edit --repo owner/repo --comment-id N --body-file reply.md [--json] issue-spec comment delete --repo owner/repo --comment-id N [--json] + issue-spec feedback configure --repo owner/repo --issue N [--dry-run] [--json] + issue-spec feedback record --repo owner/repo --issue N --event-file event.json [--dry-run] [--json] issue-spec comment generate --type SPEC --id SPEC-1001 --input-file spec.json [--status confirmed] [--scope "..."] issue-spec comment generate --type SPEC|TASK --example issue-spec comment upsert --repo owner/repo --issue 1 --type SPEC --id SPEC-1001 --body-file file.md [--allow-noncanonical] diff --git a/internal/commands/feedback.go b/internal/commands/feedback.go new file mode 100644 index 00000000..16487a42 --- /dev/null +++ b/internal/commands/feedback.go @@ -0,0 +1,98 @@ +package commands + +import ( + "context" + "fmt" + + "github.com/higress-group/issue-spec/internal/feedback" +) + +func (a *app) runFeedback(ctx context.Context, args []string) int { + if len(args) == 0 || isHelpArg(args[0]) { + fmt.Fprintln(a.out, "Usage: issue-spec feedback configure|record [options]") + return 0 + } + action := args[0] + if action != "configure" && action != "record" { + a.errorf("unknown feedback command %q\n", action) + return 2 + } + + fs := newFlagSet("feedback "+action, a.err) + repoFlag := fs.String("repo", "", "target Issue repository owner/name") + host := fs.String("hostname", "github.com", "issue backend hostname") + issue := fs.Int("issue", 0, "positive Issue number in the selected repository") + dryRun := fs.Bool("dry-run", false, "preview using read-only backend operations") + jsonOut := fs.Bool("json", false, "write JSON output") + var eventFile *string + if action == "record" { + eventFile = fs.String("event-file", "", "JSON occurrence file, or - for stdin") + } + if ok, code := a.parseFlagSet(fs, args[1:]); !ok { + return code + } + repo, ok := a.validateRepo(*repoFlag) + if !ok { + return 2 + } + if *issue <= 0 { + a.errorf("--issue must be a positive Issue number in the selected repository\n") + return 2 + } + var event feedback.Event + if eventFile != nil { + input, ok := a.readFlagFile(*eventFile, "event-file") + if !ok { + return 2 + } + parsed, err := feedback.ParseEvent(input) + if err != nil { + a.errorf("%v\n", err) + return 2 + } + event = parsed + } + + client, _, err := a.clientFor(ctx, *host) + if err != nil { + a.errorf("select feedback Issue backend: %v\n", err) + return 1 + } + backend, ok := client.(feedback.Backend) + if !ok { + a.errorf("the selected Issue backend does not support feedback label operations\n") + return 1 + } + if action == "configure" { + result, err := feedback.Configure(ctx, backend, repo, *issue, *dryRun) + if err != nil { + a.errorf("%v\n", err) + return 1 + } + if *jsonOut { + return a.outputJSON(result) + } + status := "published" + if *dryRun { + status = "preview" + } + fmt.Fprintf(a.out, "%s %s feedback policy from Issue #%d (%s, threshold %d)\n", + status, repo, *issue, result.Policy.Mode, result.Policy.Threshold) + return 0 + } + + result, err := feedback.Record(ctx, backend, repo, *issue, event, *dryRun) + if err != nil { + a.errorf("%v\n", err) + return 1 + } + if *jsonOut { + return a.outputJSON(result) + } + fmt.Fprintf(a.out, "%s %s#%d %s\n%d confirmed occurrences, promotion %s (%s)\n", + result.EventStatus, repo, *issue, result.EventKey, result.ConfirmedCount, result.Promotion.Status, result.Promotion.Label) + if result.Promotion.Reason != "" { + fmt.Fprintln(a.out, result.Promotion.Reason) + } + return 0 +} diff --git a/internal/commands/workflows_test.go b/internal/commands/workflows_test.go index d87fb8b7..eaab431a 100644 --- a/internal/commands/workflows_test.go +++ b/internal/commands/workflows_test.go @@ -32,7 +32,7 @@ func TestWriteWorkflowArtifactsUsesCurrentCodexSkillPathWithoutGlobalWrites(t *t if got, want := len(result.SkillFiles), 4; got != want { t.Fatalf("skill file count = %d, want %d", got, want) } - if got, want := len(result.SkillResourceFiles), len(templates.HumanReviewProjectionResources())+6; got != want { + if got, want := len(result.SkillResourceFiles), len(templates.HumanReviewProjectionResources())+7; got != want { t.Fatalf("skill resource file count = %d, want %d", got, want) } if got, want := len(result.SkillLinks), 4; got != want { diff --git a/internal/feedback/event.go b/internal/feedback/event.go new file mode 100644 index 00000000..7d8ae447 --- /dev/null +++ b/internal/feedback/event.go @@ -0,0 +1,106 @@ +package feedback + +import ( + "encoding/json" + "fmt" + "html" + "io" + "net/url" + "regexp" + "strings" + "time" +) + +const occurrencePrefix = "" + +var ( + instancePattern = regexp.MustCompile(`^[a-z0-9][a-z0-9._:-]{0,159}$`) + repositoryPattern = regexp.MustCompile(`^[a-z0-9._-]+/[a-z0-9._-]+$`) + eventIDPattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,191}$`) +) + +type Event struct { + SourceInstance string `json:"source_instance"` + SourceRepository string `json:"source_repository"` + EventID string `json:"event_id"` + ObservedAt time.Time `json:"observed_at"` + Revision string `json:"revision,omitempty"` + Summary string `json:"summary"` + Evidence []string `json:"evidence"` +} + +func ParseEvent(input string) (Event, error) { + var event Event + if err := decodeJSON(input, &event); err != nil { + return Event{}, fmt.Errorf("decode feedback event: %w", err) + } + event.SourceInstance = strings.ToLower(strings.TrimSpace(event.SourceInstance)) + event.SourceRepository = strings.ToLower(strings.TrimSpace(event.SourceRepository)) + event.EventID = strings.TrimSpace(event.EventID) + event.Summary = strings.TrimSpace(event.Summary) + event.Revision = strings.TrimSpace(event.Revision) + if !instancePattern.MatchString(event.SourceInstance) || !repositoryPattern.MatchString(event.SourceRepository) { + return Event{}, fmt.Errorf("provide the source instance and repository in owner/name form") + } + if !eventIDPattern.MatchString(event.EventID) { + return Event{}, fmt.Errorf("provide a stable event_id of up to 192 letters, digits or ._:/@- characters") + } + if event.ObservedAt.IsZero() || event.Summary == "" || len(event.Evidence) == 0 { + return Event{}, fmt.Errorf("observed_at, summary and at least one evidence link are required") + } + for _, link := range event.Evidence { + u, err := url.Parse(link) + if err != nil || u.Host == "" || u.User != nil || (u.Scheme != "https" && u.Scheme != "http") { + return Event{}, fmt.Errorf("evidence links must be HTTP or HTTPS URLs without user information") + } + } + return event, nil +} + +func (e Event) Key() string { + return e.SourceInstance + "/" + e.SourceRepository + "/" + e.EventID +} + +func (e Event) commentBody() (string, error) { + data, err := json.Marshal(e) + if err != nil { + return "", err + } + var body strings.Builder + fmt.Fprintf(&body, "%s%s%s\n\n### Workflow feedback occurrence\n\n", occurrencePrefix, data, occurrenceSuffix) + fmt.Fprintf(&body, "%s\n\n- Observed %s\n- Source %s\n", html.EscapeString(e.Summary), e.ObservedAt.Format(time.RFC3339), e.Key()) + if e.Revision != "" { + fmt.Fprintf(&body, "- Revision %s\n", html.EscapeString(e.Revision)) + } + for _, link := range e.Evidence { + fmt.Fprintf(&body, "- Evidence <%s>\n", html.EscapeString(link)) + } + return body.String(), nil +} + +// Only marker lines at the start of a provider-authored body are records. +func appendEvents(body string, yield func(Event)) { + for line := range strings.SplitSeq(body, "\n") { + line = strings.TrimSuffix(line, "\r") + if !strings.HasPrefix(line, occurrencePrefix) || !strings.HasSuffix(line, occurrenceSuffix) { + return + } + input := strings.TrimSuffix(strings.TrimPrefix(line, occurrencePrefix), occurrenceSuffix) + if event, err := ParseEvent(input); err == nil { + yield(event) + } + } +} + +func decodeJSON(input string, dest any) error { + decoder := json.NewDecoder(strings.NewReader(input)) + decoder.DisallowUnknownFields() + if err := decoder.Decode(dest); err != nil { + return err + } + if err := decoder.Decode(new(json.RawMessage)); err != io.EOF { + return fmt.Errorf("expected one JSON object") + } + return nil +} diff --git a/internal/feedback/event_test.go b/internal/feedback/event_test.go new file mode 100644 index 00000000..f7f4acc3 --- /dev/null +++ b/internal/feedback/event_test.go @@ -0,0 +1,77 @@ +package feedback + +import ( + "os" + "strings" + "testing" +) + +func TestCountDistinctConfirmedOccurrencesAcrossBodies(t *testing.T) { + read := func(name string) Event { + t.Helper() + data, err := os.ReadFile("../../testdata/workflow-feedback/" + name + ".json") + if err != nil { + t.Fatal(err) + } + event, err := ParseEvent(string(data)) + if err != nil { + t.Fatal(err) + } + return event + } + original := read("release-0.6.2") + retry := read("release-0.6.3") + third := read("synthetic-third-release") + body := func(event Event) string { + t.Helper() + value, err := event.commentBody() + if err != nil { + t.Fatal(err) + } + return value + } + firstLine := func(event Event) string { + line, _, _ := strings.Cut(body(event), "\n") + return line + } + + state := snapshot{events: make(map[string]occurrence)} + state.addBody(firstLine(original)+"\n"+firstLine(retry)+"\n\nOriginal issue body", true, 0) + state.addBody(body(retry), true, 24) + state.addBody(body(retry), true, 25) + state.addBody("A quoted example\n\n"+body(third), true, 26) + state.addBody(body(third), false, 27) + if state.confirmed != 2 || state.events[third.Key()].confirmed { + t.Fatalf("wrong confirmed count after duplicates and untrusted report: %+v", state) + } + state.addBody(body(third), true, 28) + if state.confirmed != 3 || state.events[third.Key()].commentID != 28 { + t.Fatalf("trusted confirmation failed to reconcile the original key: %+v", state) + } + otherInstance := third + otherInstance.SourceInstance = "another-instance" + state.addBody(body(otherInstance), true, 29) + if state.confirmed != 4 { + t.Fatalf("separate source instances shared an event key: %+v", state) + } +} + +func TestFeedbackCommentKeepsTypedMarkupInert(t *testing.T) { + data, err := os.ReadFile("../../testdata/workflow-feedback/release-0.6.2.json") + if err != nil { + t.Fatal(err) + } + event, err := ParseEvent(string(data)) + if err != nil { + t.Fatal(err) + } + event.Summary = "" + event.Revision = "" + body, err := event.commentBody() + if err != nil { + t.Fatal(err) + } + if strings.Contains(body, "" var ( @@ -68,7 +68,7 @@ func (e Event) commentBody() (string, error) { return "", err } var body strings.Builder - fmt.Fprintf(&body, "%s%s%s\n\n### Workflow feedback occurrence\n\n", occurrencePrefix, data, occurrenceSuffix) + fmt.Fprintf(&body, "%s%s%s\n\n### Workflow feedback occurrence\n\n", OccurrencePrefix, data, occurrenceSuffix) fmt.Fprintf(&body, "%s\n\n- Observed %s\n- Source %s\n", html.EscapeString(e.Summary), e.ObservedAt.Format(time.RFC3339), e.Key()) if e.Revision != "" { fmt.Fprintf(&body, "- Revision %s\n", html.EscapeString(e.Revision)) @@ -83,10 +83,10 @@ func (e Event) commentBody() (string, error) { func appendEvents(body string, yield func(Event)) { for line := range strings.SplitSeq(body, "\n") { line = strings.TrimSuffix(line, "\r") - if !strings.HasPrefix(line, occurrencePrefix) || !strings.HasSuffix(line, occurrenceSuffix) { + if !strings.HasPrefix(line, OccurrencePrefix) || !strings.HasSuffix(line, occurrenceSuffix) { return } - input := strings.TrimSuffix(strings.TrimPrefix(line, occurrencePrefix), occurrenceSuffix) + input := strings.TrimSuffix(strings.TrimPrefix(line, OccurrencePrefix), occurrenceSuffix) if event, err := ParseEvent(input); err == nil { yield(event) } diff --git a/internal/feedback/policy.go b/internal/feedback/policy.go index 1519051f..d9c43297 100644 --- a/internal/feedback/policy.go +++ b/internal/feedback/policy.go @@ -15,7 +15,7 @@ import ( ) const ( - policyLabel = "issue-spec/feedback-policy" + PolicyLabel = "issue-spec/feedback-policy" holdLabel = "issue-spec/feedback-hold" modeSuggest = "suggest" modeAuto = "auto" @@ -54,17 +54,17 @@ func Configure(ctx context.Context, backend Backend, repo string, number int, dr if dryRun { return result, nil } - label, err := backend.GetRepositoryLabel(ctx, repo, policyLabel) + label, err := backend.GetRepositoryLabel(ctx, repo, PolicyLabel) if errors.Is(err, github.ErrRepositoryLabelNotFound) { - if _, err = backend.CreateLabel(ctx, repo, policyLabel, "536D8B", ref); err == nil { - label, err = backend.GetRepositoryLabel(ctx, repo, policyLabel) + if _, err = backend.CreateLabel(ctx, repo, PolicyLabel, "536D8B", ref); err == nil { + label, err = backend.GetRepositoryLabel(ctx, repo, PolicyLabel) } } if err != nil { return PolicyResult{}, fmt.Errorf("read or create feedback policy label: %w", err) } if label.Description != ref { - label, err = backend.UpdateRepositoryLabelDescription(ctx, repo, policyLabel, ref) + label, err = backend.UpdateRepositoryLabelDescription(ctx, repo, PolicyLabel, ref) if err != nil { return PolicyResult{}, fmt.Errorf("publish feedback policy: %w", err) } @@ -75,30 +75,46 @@ func Configure(ctx context.Context, backend Backend, repo string, number int, dr return result, nil } +func defaultPolicy() Policy { + return Policy{Threshold: 3, PriorityLabel: "priority/high", Mode: modeSuggest} +} + func loadPolicy(ctx context.Context, backend Backend, repo string) (Policy, int, string, error) { - label, err := backend.GetRepositoryLabel(ctx, repo, policyLabel) - if errors.Is(err, github.ErrRepositoryLabelNotFound) { - return Policy{}, 0, "", fmt.Errorf("feedback is disabled for %s until its maintainers configure a policy", repo) + label, err := backend.GetRepositoryLabel(ctx, repo, PolicyLabel) + if errors.Is(err, github.ErrRepositoryLabelNotFound) || errors.Is(err, github.ErrRepositoryLabelLookupUnsupported) { + return defaultPolicy(), 0, "", nil } if err != nil { return Policy{}, 0, "", fmt.Errorf("read feedback policy label: %w", err) } - parts := strings.Split(label.Description, ":") + policy, number, err := ResolvePublishedPolicy(label.Description, func(number int) (github.Issue, error) { + return backend.GetIssue(ctx, repo, number) + }) + return policy, number, label.Description, err +} + +// ResolvePublishedPolicy resolves an approved policy within its own Issue repository. +func ResolvePublishedPolicy(reference string, readIssue func(int) (github.Issue, error)) (Policy, int, error) { + parts := strings.Split(reference, ":") if len(parts) != 3 || parts[0] != "v1" { - return Policy{}, 0, "", fmt.Errorf("invalid feedback policy reference on %s", repo) + return Policy{}, 0, fmt.Errorf("invalid feedback policy reference") } number, err := strconv.Atoi(parts[1]) if err != nil || number <= 0 { - return Policy{}, 0, "", fmt.Errorf("invalid feedback policy Issue number on %s", repo) + return Policy{}, 0, fmt.Errorf("invalid feedback policy Issue number") } - policy, ref, err := readPolicyIssue(ctx, backend, repo, number) + issue, err := readIssue(number) if err != nil { - return Policy{}, 0, "", err + return Policy{}, 0, fmt.Errorf("read feedback policy Issue #%d: %w", number, err) } - if label.Description != ref { - return Policy{}, 0, "", fmt.Errorf("feedback policy Issue #%d differs from the published revision", number) + policy, ref, err := parsePolicyIssue(issue, number) + if err != nil { + return Policy{}, 0, err + } + if reference != ref { + return Policy{}, 0, fmt.Errorf("feedback policy Issue #%d differs from the published revision", number) } - return policy, number, ref, nil + return policy, number, nil } func readPolicyIssue(ctx context.Context, backend github.IssueBackend, repo string, number int) (Policy, string, error) { @@ -106,6 +122,10 @@ func readPolicyIssue(ctx context.Context, backend github.IssueBackend, repo stri if err != nil { return Policy{}, "", fmt.Errorf("read feedback policy Issue #%d: %w", number, err) } + return parsePolicyIssue(issue, number) +} + +func parsePolicyIssue(issue github.Issue, number int) (Policy, string, error) { if issue.PullRequest != nil { return Policy{}, "", fmt.Errorf("feedback policy must refer to an Issue") } @@ -123,7 +143,7 @@ func readPolicyIssue(ctx context.Context, backend github.IssueBackend, repo stri } func parsePolicy(source string) (Policy, error) { - var policy Policy + policy := defaultPolicy() if err := decodeJSON(source, &policy); err != nil { return Policy{}, err } @@ -134,12 +154,12 @@ func parsePolicy(source string) (Policy, error) { return Policy{}, fmt.Errorf("mode must be suggest or auto") } policy.PriorityLabel = strings.TrimSpace(policy.PriorityLabel) - if policy.Threshold <= 0 || policy.PriorityLabel == "" || strings.EqualFold(policy.PriorityLabel, policyLabel) || + if policy.Threshold <= 0 || policy.PriorityLabel == "" || strings.EqualFold(policy.PriorityLabel, PolicyLabel) || strings.EqualFold(policy.PriorityLabel, holdLabel) || strings.EqualFold(policy.PriorityLabel, "wontfix") { return Policy{}, fmt.Errorf("a positive threshold and a priority label are required") } - if len(policy.TrustedReporterIDs) == 0 { - return Policy{}, fmt.Errorf("at least one trusted_reporter_ids entry is required") + if policy.Mode == modeAuto && len(policy.TrustedReporterIDs) == 0 { + return Policy{}, fmt.Errorf("auto mode requires at least one trusted_reporter_ids entry") } for _, reporter := range policy.TrustedReporterIDs { id, err := strconv.ParseInt(reporter, 10, 64) @@ -158,5 +178,6 @@ func parsePolicy(source string) (Policy, error) { } func (p Policy) trusts(author *github.User) bool { - return author != nil && author.ID > 0 && slices.Contains(p.TrustedReporterIDs, strconv.FormatInt(author.ID, 10)) + return author != nil && author.ID > 0 && author.Login != "ghost" && + (len(p.TrustedReporterIDs) == 0 || slices.Contains(p.TrustedReporterIDs, strconv.FormatInt(author.ID, 10))) } diff --git a/internal/feedback/record.go b/internal/feedback/record.go index 8928346d..20153288 100644 --- a/internal/feedback/record.go +++ b/internal/feedback/record.go @@ -23,10 +23,11 @@ type Result struct { Promotion Promotion `json:"promotion"` } -type Promotion struct { - Label string `json:"label"` - Status string `json:"status"` - Reason string `json:"reason,omitempty"` +type Promotion = github.FeedbackPromotion + +type RecordOptions struct { + DryRun bool + SelfHosted bool } type occurrence struct { @@ -41,7 +42,7 @@ type snapshot struct { confirmed int } -func Record(ctx context.Context, backend Backend, repo string, number int, event Event, dryRun bool) (Result, error) { +func Record(ctx context.Context, backend Backend, repo string, number int, event Event, options RecordOptions) (Result, error) { policy, policyIssue, policyRef, err := loadPolicy(ctx, backend, repo) if err != nil { return Result{}, err @@ -59,18 +60,18 @@ func Record(ctx context.Context, backend Backend, repo string, number int, event if err != nil { return Result{}, err } - result := Result{Repository: repo, Issue: number, URL: observed.issue.HTMLURL, EventKey: key, DryRun: dryRun} + result := Result{Repository: repo, Issue: number, URL: observed.issue.HTMLURL, EventKey: key, DryRun: options.DryRun} recorded := observed.events[key] needsRecord := !recorded.found || (trusted && !recorded.confirmed) result.EventStatus = "already_recorded" - if dryRun && needsRecord { + if options.DryRun && needsRecord { result.EventStatus = "would_record" recorded.confirmed = trusted if trusted { observed.confirmed++ } } - if !dryRun && needsRecord { + if !options.DryRun && needsRecord { body, err := event.commentBody() if err != nil { return Result{}, err @@ -97,10 +98,14 @@ func Record(ctx context.Context, backend Backend, repo string, number int, event } result.setOccurrence(recorded, observed.confirmed) result.Promotion = promotionPlan(observed.issue, policy, observed.confirmed) - if result.Promotion.Status != "would_promote" || dryRun { + if result.Promotion.Status != "would_promote" || options.DryRun { return result, nil } - result.Promotion = applyPromotion(ctx, backend, repo, number, policy, policyRef, observed.confirmed) + if options.SelfHosted { + result.Promotion = applyHostedPromotion(ctx, backend, repo, number, policy.PriorityLabel, policyRef) + } else { + result.Promotion = applyPromotion(ctx, backend, repo, number, policy, policyRef, observed.confirmed) + } return result, nil } @@ -116,12 +121,22 @@ func observe(ctx context.Context, backend github.IssueBackend, repo string, numb if err != nil { return snapshot{}, fmt.Errorf("read feedback Issue #%d comments: %w", number, err) } + return collectObservations(issue, comments, policy), nil +} + +func collectObservations(issue github.Issue, comments []github.Comment, policy Policy) snapshot { state := snapshot{issue: issue, events: make(map[string]occurrence)} state.addBody(issue.Body, policy.trusts(issue.User), 0) for _, comment := range comments { state.addBody(comment.Body, policy.trusts(comment.User), comment.ID) } - return state, nil + return state +} + +// EvaluatePromotion makes the same decision from backend-authoritative Issue and +// comment state, including when the self-hosted server owns the label mutation. +func EvaluatePromotion(issue github.Issue, comments []github.Comment, policy Policy) Promotion { + return promotionPlan(issue, policy, collectObservations(issue, comments, policy).confirmed) } func (s *snapshot) addBody(body string, trusted bool, commentID int64) { @@ -168,7 +183,7 @@ func promotionPlan(issue github.Issue, policy Policy, count int) Promotion { func applyPromotion(ctx context.Context, backend Backend, repo string, number int, policy Policy, policyRef string, count int) Promotion { pending := Promotion{Label: policy.PriorityLabel, Status: "pending"} - label, err := backend.GetRepositoryLabel(ctx, repo, policyLabel) + label, err := backend.GetRepositoryLabel(ctx, repo, PolicyLabel) if err != nil || label.Description != policyRef { pending.Reason = "feedback policy changed or could not be rechecked" return pending @@ -188,12 +203,7 @@ func applyPromotion(ctx context.Context, backend Backend, repo string, number in } labels, err := backend.AddIssueLabels(ctx, repo, number, []string{policy.PriorityLabel}) if err != nil { - // The provider may have accepted an addition whose response was lost. - if current, readErr := backend.GetIssue(ctx, repo, number); readErr == nil && hasLabel(current.Labels, policy.PriorityLabel) { - return Promotion{Label: policy.PriorityLabel, Status: "applied"} - } - pending.Reason = err.Error() - return pending + return reconcilePromotion(ctx, backend, repo, number, policy.PriorityLabel, err) } if !hasLabel(labels, policy.PriorityLabel) { pending.Reason = "the backend did not assign the label; check label existence and triage permission" @@ -202,6 +212,29 @@ func applyPromotion(ctx context.Context, backend Backend, repo string, number in return Promotion{Label: policy.PriorityLabel, Status: "applied"} } +func applyHostedPromotion(ctx context.Context, backend Backend, repo string, number int, label, policyRef string) Promotion { + promoter, ok := backend.(github.FeedbackPromotionBackend) + if !ok { + return Promotion{Label: label, Status: "pending", Reason: "the selected self-hosted backend does not support feedback promotion"} + } + result, err := promoter.PromoteFeedback(ctx, repo, number, policyRef) + if err != nil { + return reconcilePromotion(ctx, backend, repo, number, label, err) + } + if result.Label == "" { + result.Label = label + } + return result +} + +func reconcilePromotion(ctx context.Context, backend github.IssueBackend, repo string, number int, label string, err error) Promotion { + // The provider may have accepted an addition whose response was lost. + if current, readErr := backend.GetIssue(ctx, repo, number); readErr == nil && hasLabel(current.Labels, label) { + return Promotion{Label: label, Status: "applied"} + } + return Promotion{Label: label, Status: "pending", Reason: err.Error()} +} + func hasLabel(labels []github.Label, name string) bool { return slices.ContainsFunc(labels, func(label github.Label) bool { return strings.EqualFold(label.Name, name) diff --git a/internal/github/issue_labels.go b/internal/github/issue_labels.go index fa017bc5..82e3f22b 100644 --- a/internal/github/issue_labels.go +++ b/internal/github/issue_labels.go @@ -8,7 +8,10 @@ import ( "net/url" ) -var ErrRepositoryLabelNotFound = errors.New("repository label not found") +var ( + ErrRepositoryLabelNotFound = errors.New("repository label not found") + ErrRepositoryLabelLookupUnsupported = errors.New("repository label lookup is unsupported") +) func repositoryLabelPath(repo, name string) string { return "/repos/" + repo + "/labels/" + url.PathEscape(name) @@ -18,8 +21,13 @@ func (c *Client) GetRepositoryLabel(ctx context.Context, repo, name string) (Lab var label Label err := c.doJSON(ctx, http.MethodGet, repositoryLabelPath(repo, name), nil, &label) var apiErr *APIError - if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusNotFound { - return Label{}, ErrRepositoryLabelNotFound + if errors.As(err, &apiErr) { + switch apiErr.StatusCode { + case http.StatusNotFound: + return Label{}, ErrRepositoryLabelNotFound + case http.StatusMethodNotAllowed: + return Label{}, ErrRepositoryLabelLookupUnsupported + } } return label, err } @@ -72,5 +80,25 @@ func (b *GHBackend) AddIssueLabels(ctx context.Context, repo string, issue int, return labels, err } +// FeedbackPromotion is the outcome of one policy-bound priority decision. +type FeedbackPromotion struct { + Label string `json:"label"` + Status string `json:"status"` + Reason string `json:"reason,omitempty"` +} + +// FeedbackPromotionBackend is the self-hosted repository's scoped feedback mutation. +type FeedbackPromotionBackend interface { + PromoteFeedback(context.Context, string, int, string) (FeedbackPromotion, error) +} + +func (c *Client) PromoteFeedback(ctx context.Context, repo string, issue int, policyRef string) (FeedbackPromotion, error) { + var result FeedbackPromotion + path := fmt.Sprintf("/repos/%s/issues/%d/feedback/promotion", repo, issue) + err := c.doJSON(ctx, http.MethodPost, path, map[string]string{"policy_ref": policyRef}, &result) + return result, err +} + +var _ FeedbackPromotionBackend = (*Client)(nil) var _ IssueLabelBackend = (*Client)(nil) var _ IssueLabelBackend = (*GHBackend)(nil) diff --git a/internal/server/api/github/issues/feedback_integration_test.go b/internal/server/api/github/issues/feedback_integration_test.go index e8a369eb..ec38f0a5 100644 --- a/internal/server/api/github/issues/feedback_integration_test.go +++ b/internal/server/api/github/issues/feedback_integration_test.go @@ -98,7 +98,7 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { strconv.FormatInt(codec.StableNumericID(contributor.User.ID.String()), 10), }, } - policyIssue := newIssue("Feedback policy", jsonBody(policy)) + policyIssue := newIssue("Feedback policy", `{"threshold":2}`) policyNumber := strconv.Itoa(policyIssue.Number) configure := func(profile string, flags ...string) (int, string) { args := append([]string{"configure", "--repo", repo, "--issue", policyNumber, "--json"}, flags...) @@ -110,10 +110,6 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { if _, err := owner.GetRepositoryLabel(ctx, repo, "issue-spec/feedback-policy"); !errors.Is(err, github.ErrRepositoryLabelNotFound) { t.Fatalf("policy preview mutated label definition: %v", err) } - if code, out := configure("owner"); code != 0 { - t.Fatalf("publish policy exit=%d output=%s", code, out) - } - events := make([]string, 0, 3) for _, name := range []string{"release-0.6.2", "release-0.6.3", "synthetic-third-release"} { data, err := os.ReadFile(filepath.Join("../../../../../testdata/workflow-feedback", name+".json")) @@ -145,6 +141,44 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { check("owner", issue, 0, 1, "below_threshold") check("owner", issue, 1, 2, "below_threshold") } + defaults := newIssue("HiRoute #495 default policy", "No project feedback policy was published", "existing-category") + initial := check("contributor", defaults, 0, 1, "below_threshold", "--dry-run") + if !initial.DryRun || initial.EventStatus != "would_record" { + t.Fatalf("default preview did not project the first occurrence: %+v", initial) + } + first := check("contributor", defaults, 0, 1, "below_threshold") + if first.EventStatus != "recorded" { + t.Fatalf("the dry-run wrote evidence: %+v", first) + } + check("owner", defaults, 1, 2, "below_threshold") + check("contributor", defaults, 1, 2, "below_threshold") + check("contributor", defaults, 2, 3, "suggested") + if _, err := owner.GetRepositoryLabel(ctx, repo, feedback.PolicyLabel); !errors.Is(err, github.ErrRepositoryLabelNotFound) { + t.Fatalf("default recording provisioned a policy label: %v", err) + } + + publish := func() { + t.Helper() + if code, out := configure("owner"); code != 0 { + t.Fatalf("publish policy exit=%d output=%s", code, out) + } + } + updatePolicy := func(body string) { + t.Helper() + if _, err := owner.UpdateIssue(ctx, repo, policyIssue.Number, github.UpdateIssueOptions{Body: &body}); err != nil { + t.Fatal(err) + } + } + publish() + customThreshold := newIssue("HiRoute #495 custom threshold", "Only threshold is configured") + result := check("contributor", customThreshold, 0, 1, "below_threshold") + if result.Promotion.Label != "priority/high" { + t.Fatalf("custom threshold lost the default label: %+v", result) + } + check("owner", customThreshold, 1, 2, "suggested") + + updatePolicy(jsonBody(policy)) + publish() suggest := newIssue("HiRoute #495 suggestion case", "Two independent catalog merges", "existing-category") seed(suggest) preview := check("owner", suggest, 1, 2, "below_threshold", "--dry-run") @@ -170,18 +204,28 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { check("contributor", suggest, 2, 3, "suggested") policy.Mode = "auto" - policyBody := jsonBody(policy) - if _, err := owner.UpdateIssue(ctx, repo, policyIssue.Number, github.UpdateIssueOptions{Body: &policyBody}); err != nil { - t.Fatal(err) - } + updatePolicy(jsonBody(policy)) if _, err := record("owner", suggest, 2); err == nil || !strings.Contains(err.Error(), "differs from the published revision") { t.Fatalf("an unpublished policy body became active: %v", err) } if code, out := configure("contributor"); code == 0 { t.Fatalf("contributor altered policy label definition: %s", out) } - if code, out := configure("owner"); code != 0 { - t.Fatalf("publish automatic policy exit=%d output=%s", code, out) + publish() + active, err := owner.GetRepositoryLabel(ctx, repo, feedback.PolicyLabel) + if err != nil { + t.Fatal(err) + } + contributorClient, err := github.NewClientWithOptions(github.ClientOptions{BaseURL: server.URL, Token: "contributor"}) + if err != nil { + t.Fatal(err) + } + checkForbidden := func(err error) { + t.Helper() + var apiErr *github.APIError + if !errors.As(err, &apiErr) || apiErr.StatusCode != http.StatusForbidden { + t.Fatalf("expected a permission denial: %v", err) + } } if missing := check("owner", suggest, 2, 3, "pending"); !strings.Contains(missing.Promotion.Reason, "label unavailable") { @@ -190,15 +234,36 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { if _, err := owner.CreateLabel(ctx, repo, "priority/high", "d73a4a", "High priority"); err != nil { t.Fatal(err) } - auto := newIssue("HiRoute #495 automatic case", "Independent catalog merges with automatic triage", "existing-category") + check("unconfirmed-reporter", suggest, 2, 3, "applied") + auto := newIssue("HiRoute #495 automatic case", "Independent catalog merges with automatic escalation", "existing-category") seed(auto) - partial := check("contributor", auto, 2, 3, "pending") - if partial.EventStatus != "recorded" || partial.CommentID <= 0 || !strings.Contains(partial.Promotion.Reason, "HTTP 403") { - t.Fatalf("permission failure lost evidence: %+v", partial) + _, err = contributorClient.AddIssueLabels(ctx, repo, auto.Number, []string{"priority/high"}) + checkForbidden(err) + if plan, err := contributorClient.PromoteFeedback(ctx, repo, auto.Number, active.Description); err != nil || plan.Status != "below_threshold" { + t.Fatalf("the endpoint accepted early escalation: %+v err=%v", plan, err) + } + if plan, err := contributorClient.PromoteFeedback(ctx, repo, auto.Number, "stale-policy"); err != nil || plan.Status != "pending" { + t.Fatalf("the endpoint accepted a stale policy: %+v err=%v", plan, err) + } + + setContribution := func(value string) { + t.Helper() + if _, err := env.pool.Exec(ctx, "UPDATE repos SET contribution_policy = $1 WHERE id = $2", value, env.scope.RepoID); err != nil { + t.Fatal(err) + } } - final := check("owner", auto, 2, 3, "applied") - if final.CommentID != partial.CommentID || final.EventStatus != "already_recorded" { - t.Fatalf("label retry changed occurrence identity: %+v", final) + setContribution("members") + _, err = contributorClient.PromoteFeedback(ctx, repo, auto.Number, active.Description) + checkForbidden(err) + setContribution("public") + + applied := check("contributor", auto, 2, 3, "applied") + if applied.EventStatus != "recorded" || applied.CommentID <= 0 { + t.Fatalf("contributor escalation lost the recorded evidence: %+v", applied) + } + replayedPromotion := check("contributor", auto, 2, 3, "already_at_priority") + if replayedPromotion.CommentID != applied.CommentID || replayedPromotion.EventStatus != "already_recorded" { + t.Fatalf("label replay changed occurrence identity: %+v", replayedPromotion) } comments, err := owner.ListIssueComments(ctx, repo, auto.Number) if err != nil || len(comments) != 3 { @@ -208,18 +273,20 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { if err != nil || !slices.ContainsFunc(current.Labels, func(label github.Label) bool { return label.Name == "existing-category" }) { t.Fatalf("initial category lost: Issue=%+v err=%v", current, err) } - check("owner", auto, 2, 3, "already_at_priority") - if _, err := owner.CreateLabel(ctx, repo, "issue-spec/feedback-hold", "bfdadc", "Maintainer hold"); err != nil { t.Fatal(err) } - if _, err := owner.AddIssueLabels(ctx, repo, suggest.Number, []string{"issue-spec/feedback-hold"}); err != nil { + if _, err := owner.AddIssueLabels(ctx, repo, defaults.Number, []string{"issue-spec/feedback-hold"}); err != nil { t.Fatal(err) } - check("owner", suggest, 2, 3, "held") + if plan, err := contributorClient.PromoteFeedback(ctx, repo, defaults.Number, active.Description); err != nil || plan.Status != "held" { + t.Fatalf("the endpoint ignored the maintainer hold: %+v err=%v", plan, err) + } closed := "closed" - if _, err := owner.UpdateIssue(ctx, repo, suggest.Number, github.UpdateIssueOptions{State: &closed}); err != nil { + if _, err := owner.UpdateIssue(ctx, repo, defaults.Number, github.UpdateIssueOptions{State: &closed}); err != nil { t.Fatal(err) } - check("owner", suggest, 2, 3, "closed") + if plan, err := contributorClient.PromoteFeedback(ctx, repo, defaults.Number, active.Description); err != nil || plan.Status != "closed" { + t.Fatalf("the endpoint ignored closure: %+v err=%v", plan, err) + } } diff --git a/internal/server/api/github/labels/feedback.go b/internal/server/api/github/labels/feedback.go new file mode 100644 index 00000000..0259a51c --- /dev/null +++ b/internal/server/api/github/labels/feedback.go @@ -0,0 +1,89 @@ +package labels + +import ( + "context" + "errors" + + "github.com/google/uuid" + "github.com/higress-group/issue-spec/internal/feedback" + "github.com/higress-group/issue-spec/internal/github" + "github.com/higress-group/issue-spec/internal/server/api/github/codec" + "github.com/higress-group/issue-spec/internal/server/authz" + "github.com/higress-group/issue-spec/internal/server/models" + "github.com/higress-group/issue-spec/internal/server/store" +) + +// PromoteFeedback uses the same repository permission as creating an Issue. +// The published policy and persisted occurrence evidence determine the label. +func (s *Service) PromoteFeedback(ctx context.Context, owner, repository string, number int64, expectedPolicy string, subject authz.Subject) (feedback.Promotion, error) { + result := feedback.Promotion{Status: "pending", Reason: "feedback policy changed or could not be rechecked"} + var resource models.RepositoryResource + err := s.mutate(ctx, owner, repository, subject, authz.OperationContribute, func(repositoryStore store.RepoStore, actor uuid.UUID) error { + definition, err := repositoryStore.LabelByNameForShare(ctx, feedback.PolicyLabel) + if errors.Is(err, store.ErrNotFound) { + return nil + } + if err != nil { + return err + } + if definition.Description != expectedPolicy { + return nil + } + policy, policyIssue, err := feedback.ResolvePublishedPolicy(definition.Description, func(number int) (github.Issue, error) { + issue, err := repositoryStore.IssueByNumber(ctx, int64(number)) + return github.Issue{Body: issue.Body}, err + }) + if err != nil { + result.Reason = err.Error() + return nil + } + if int64(policyIssue) == number { + return nil + } + + // Lock the target definition before the Issue, in the same order as label + // definition updates that invalidate associated Issue representations. + _, labelErr := repositoryStore.LabelByNameForShare(ctx, policy.PriorityLabel) + if labelErr != nil && !errors.Is(labelErr, store.ErrNotFound) { + return labelErr + } + issue, labels, err := repositoryStore.IssueLabelsForUpdate(ctx, number) + if err != nil { + return err + } + input := github.Issue{State: string(issue.State), Body: issue.Body, User: feedbackAuthor(issue.AuthorID)} + for _, label := range labels { + input.Labels = append(input.Labels, github.Label{Name: label.Name}) + } + records, err := repositoryStore.ListIssueCommentsWithPrefix(ctx, issue.ID, feedback.OccurrencePrefix) + if err != nil { + return err + } + comments := make([]github.Comment, 0, len(records)) + for _, record := range records { + comments = append(comments, github.Comment{Body: record.Body, User: feedbackAuthor(record.AuthorID)}) + } + result = feedback.EvaluatePromotion(input, comments, policy) + if result.Status != "would_promote" { + return nil + } + if labelErr != nil { + result.Status = "pending" + result.Reason = "configured priority label unavailable" + return nil + } + if _, _, err := repositoryStore.AddIssueLabels(ctx, number, []string{policy.PriorityLabel}, actor); err != nil { + return err + } + result.Status = "applied" + return nil + }, &resource) + return result, err +} + +func feedbackAuthor(id *uuid.UUID) *github.User { + if id == nil { + return nil + } + return &github.User{ID: codec.StableNumericID(id.String())} +} diff --git a/internal/server/api/github/labels/routes.go b/internal/server/api/github/labels/routes.go index db9a9fd5..7f2b2821 100644 --- a/internal/server/api/github/labels/routes.go +++ b/internal/server/api/github/labels/routes.go @@ -37,6 +37,7 @@ func NewRouteSet(deps Dependencies) (routeset.RouteSet, error) { {Name: "github.issue_labels.list", Method: http.MethodGet, Pattern: "/repos/{owner}/{repo}/issues/{number}/labels", Handler: issues.WithRequestID(authentication.AuthenticateOptional(http.HandlerFunc(h.listIssue)))}, {Name: "github.issue_labels.add", Method: http.MethodPost, Pattern: "/repos/{owner}/{repo}/issues/{number}/labels", Handler: issues.WithRequestID(authentication.Authenticate(http.HandlerFunc(h.addIssue)))}, {Name: "github.issue_labels.replace", Method: http.MethodPut, Pattern: "/repos/{owner}/{repo}/issues/{number}/labels", Handler: issues.WithRequestID(authentication.Authenticate(http.HandlerFunc(h.replaceIssue)))}, + {Name: "github.issue_labels.feedback_promotion", Method: http.MethodPost, Pattern: "/repos/{owner}/{repo}/issues/{number}/feedback/promotion", Handler: issues.WithRequestID(authentication.Authenticate(http.HandlerFunc(h.promoteFeedback)))}, {Name: "github.issue_labels.remove", Method: http.MethodDelete, Pattern: "/repos/{owner}/{repo}/issues/{number}/labels/{name}", Handler: issues.WithRequestID(authentication.Authenticate(http.HandlerFunc(h.removeIssue)))}, }} return set, set.Validate() @@ -205,6 +206,26 @@ func (h handlers) changeIssue(w http.ResponseWriter, r *http.Request, replace bo issues.WriteJSON(w, http.StatusOK, presentLabels(h.presenter, resource, labels)) } +func (h handlers) promoteFeedback(w http.ResponseWriter, r *http.Request) { + number, ok := positive(w, r, "number") + if !ok { + return + } + var input struct { + PolicyRef string `json:"policy_ref"` + } + if err := codec.DecodeJSON(r.Body, &input); err != nil || input.PolicyRef == "" { + h.validation(w, r, []codec.Violation{{Resource: "Issue", Field: "policy_ref", Code: "invalid", Message: "a published feedback policy reference is required"}}) + return + } + result, err := h.service.PromoteFeedback(r.Context(), r.PathValue("owner"), r.PathValue("repo"), number, input.PolicyRef, issues.Subject(r)) + if err != nil { + issues.WriteError(w, r, err) + return + } + issues.WriteJSON(w, http.StatusOK, result) +} + func (h handlers) removeIssue(w http.ResponseWriter, r *http.Request) { number, ok := positive(w, r, "number") if !ok { diff --git a/internal/server/store/comments.go b/internal/server/store/comments.go index 229bdc5b..cedb72c3 100644 --- a/internal/server/store/comments.go +++ b/internal/server/store/comments.go @@ -240,6 +240,29 @@ func (s RepoStore) UpdateCommentCAS(ctx context.Context, compatibilityID, expect return result, nil } +// ListIssueCommentsWithPrefix reads only matching bodies on the selected Issue. +func (s RepoStore) ListIssueCommentsWithPrefix(ctx context.Context, issueID uuid.UUID, prefix string) ([]models.Comment, error) { + if err := s.validate(); err != nil || issueID == uuid.Nil || prefix == "" { + return nil, ErrInvalidInput + } + rows, err := s.db.Query(ctx, `SELECT `+commentColumns+` FROM comments WHERE organization_id = $1 + AND repository_id = $2 AND issue_id = $3 AND starts_with(body, $4)`, + s.scope.OrgID, s.scope.RepoID, issueID, prefix) + if err != nil { + return nil, fmt.Errorf("load Issue evidence comments: %w", err) + } + defer rows.Close() + var comments []models.Comment + for rows.Next() { + comment, err := scanComment(rows) + if err != nil { + return nil, err + } + comments = append(comments, comment) + } + return comments, rows.Err() +} + func (s RepoStore) ListComments(ctx context.Context, options models.CommentListOptions) (models.CommentPage, error) { if err := s.validate(); err != nil || options.Page < 1 || options.PerPage < 1 { return models.CommentPage{}, ErrInvalidInput diff --git a/internal/server/store/labels.go b/internal/server/store/labels.go index bafb1ca1..a59ba598 100644 --- a/internal/server/store/labels.go +++ b/internal/server/store/labels.go @@ -78,12 +78,27 @@ func (s RepoStore) CreateLabel(ctx context.Context, input models.NewLabel) (mode } func (s RepoStore) LabelByName(ctx context.Context, name string) (models.Label, error) { + return s.labelByName(ctx, name, false) +} + +// LabelByNameForShare holds the definition stable through a policy-bound mutation. +func (s RepoStore) LabelByNameForShare(ctx context.Context, name string) (models.Label, error) { + if err := s.requireMutationTx(); err != nil { + return models.Label{}, err + } + return s.labelByName(ctx, name, true) +} + +func (s RepoStore) labelByName(ctx context.Context, name string, forShare bool) (models.Label, error) { if err := s.validate(); err != nil { return models.Label{}, err } - label, err := scanLabel(s.db.QueryRow(ctx, `SELECT `+labelColumns+` FROM labels - WHERE organization_id = $1 AND repository_id = $2 AND name_key = lower($3)`, - s.scope.OrgID, s.scope.RepoID, strings.TrimSpace(name))) + query := `SELECT ` + labelColumns + ` FROM labels + WHERE organization_id = $1 AND repository_id = $2 AND name_key = lower($3)` + if forShare { + query += ` FOR SHARE` + } + label, err := scanLabel(s.db.QueryRow(ctx, query, s.scope.OrgID, s.scope.RepoID, strings.TrimSpace(name))) if err != nil { return models.Label{}, fmt.Errorf("get label: %w", mapLabelError(err)) } @@ -131,6 +146,19 @@ func (s RepoStore) IssueLabels(ctx context.Context, number int64) (models.Issue, return issue, labels, err } +// IssueLabelsForUpdate serializes a label decision with Issue, label and comment writes. +func (s RepoStore) IssueLabelsForUpdate(ctx context.Context, number int64) (models.Issue, []models.Label, error) { + if err := s.requireMutationTx(); err != nil { + return models.Issue{}, nil, err + } + issue, err := s.issueForLabelMutation(ctx, number) + if err != nil { + return models.Issue{}, nil, err + } + labels, err := s.labelsForIssue(ctx, issue.ID) + return issue, labels, err +} + func (s RepoStore) AddIssueLabels(ctx context.Context, number int64, names []string, actor uuid.UUID) (models.Issue, []models.Label, error) { return s.changeIssueLabels(ctx, number, names, actor, false) } diff --git a/internal/templates/assets/workflow-feedback.md b/internal/templates/assets/workflow-feedback.md index b4ef0467..49f65a8f 100644 --- a/internal/templates/assets/workflow-feedback.md +++ b/internal/templates/assets/workflow-feedback.md @@ -1,10 +1,10 @@ # Workflow feedback -Use this reference when a consumer project enables feedback in its shared guidance and authorized work exposes a concrete CLI limitation, workflow gap, or project policy problem. Continue the original task and use an ordinary Issue and comments. A skill or available token alone grants no publication authority. +Use this reference when authorized work exposes a concrete CLI limitation, workflow gap, or project policy problem. Continue the original task and use an ordinary Issue and comments. Apply the current task's publication authorization and any standing authorization in project guidance. ## Route and record -1. Identify the owner from the observed behavior. Route CLI limitations and reusable workflow improvements to the configured upstream repository. Route project-specific guidance, validation, and release problems to the originating project. Keep uncertain ownership as a draft. Resolve the destination's Issue profile and repository before reading or writing. +1. Identify the owner from the observed behavior. Route CLI limitations and reusable workflow improvements to the upstream repository identified by the task or project guidance. Route project-specific guidance, validation, and release problems to the originating project. Keep an internal draft while the destination is uncertain. Resolve the destination's Issue profile and repository before reading or writing. 2. Search open and closed discussions for the same cause with `issue-spec search issues --repo OWNER/REPO --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec read issue --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor. 3. For a new report, use `issue-spec issue create simple` with a self-contained body describing the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action. 4. Record each independent event with its original context. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events. @@ -26,17 +26,22 @@ issue-spec feedback record --repo OWNER/REPO --issue 42 --event-file occurrence. } ``` -Include only sanitized evidence. `revision` is optional. A preview reports the event key and projected confirmed count using the current identity. An event can be recorded by a contributor and remain unconfirmed. A configured reporter can confirm that event by verifying the evidence and recording the same key. The backend supplies the comment author. A submitted field claiming confirmation or identity carries no authority. +Include only sanitized evidence. `revision` is optional. A preview reports the event key and projected confirmed count using the current identity. With a trusted reporter list, a contributor can record an event for confirmation. When the destination restricts trusted reporters, a configured reporter can confirm an earlier unconfirmed event by verifying the evidence and recording the same key. The backend supplies the comment author. A submitted field claiming confirmation or identity carries no authority. An ambiguous submission is reconciled by rereading the Issue. Retry the same event file if needed. If the result shows a pending label action, an authorized caller can retry that action with the same event without increasing the count. Preserve the Issue URL in handoffs. -## Enable and maintain a destination policy +## Defaults and optional destination policy -Use a dedicated ordinary policy Issue in the **destination** repository. Its body contains a single JSON object, optionally fenced as JSON. For each trusted account, get the stable ID from `issue-spec auth status --json` under the intended Issue profile (`.auth.user_id`). Then write the IDs as strings. +Recording and preview work after ordinary initialization. The default policy counts distinct evidence from authenticated Issue authors and suggests `priority/high` at three confirmed occurrences. + +To change the threshold or enable automatic escalation, publish a policy from an ordinary Issue in the **destination** repository. Its body contains a single JSON object, optionally fenced as JSON. To customize just the threshold, the entire body can be `{"threshold": 5}`. + +Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For each trusted account, get the stable ID from `issue-spec auth status --json` under the intended Issue profile (`.auth.user_id`). Write the IDs as strings. ```json { "threshold": 3, + "mode": "auto", "priority_label": "priority/high", "trusted_reporter_ids": ["123"], "higher_priority_labels": ["priority/critical"], @@ -44,19 +49,19 @@ Use a dedicated ordinary policy Issue in the **destination** repository. Its bod } ``` -The default mode is `suggest`. Set `"mode": "auto"` explicitly to permit automatic escalation. The repository must predefine the configured priority label before an automatic assignment can succeed. Higher-priority and hold labels are optional. `issue-spec/feedback-hold` and `wontfix` are recognized holds. A closed or locked Issue is ineligible. +An automatic assignment uses a predefined repository label. The priority label defaults to `priority/high`. Higher-priority and hold labels are optional. `issue-spec/feedback-hold` and `wontfix` are recognized holds. A closed or locked Issue is ineligible. ```sh issue-spec feedback configure --repo OWNER/REPO --issue 17 --dry-run --json issue-spec feedback configure --repo OWNER/REPO --issue 17 ``` -Publishing requires permission to manage repository label definitions. The command binds the exact policy body to the repository's `issue-spec/feedback-policy` label definition. Change the policy Issue body and publish again to activate a new revision. Remove the policy label definition to disable feedback. During automatic escalation, issue-label permission is independently enforced by the selected backend. On self-hosted, comment recording uses contribution permissions and assigning labels uses triage permissions. Promotion adds only the configured label. +Publishing requires permission to manage repository label definitions. The command binds the exact policy body to the repository's `issue-spec/feedback-policy` label definition. Change the policy Issue body and publish again to activate a new revision. Remove the policy label definition to return to the built-in suggestion policy. GitHub enforces the caller's permission to assign a label. On self-hosted, a caller who can create Issues can request promotion. The server rechecks the published policy, persisted evidence and Issue eligibility before assigning the configured label. The ordinary issue-label API uses its triage authorization. The commands use the active Issue profile or an explicit global `--profile` verified for the destination. A Source Binding or external code host is independent of where policies, Issues and comments are stored. -## Enable the project workflow +## Customize project guidance -Add a project file to `guidance.shared` in `issue-spec/config.yaml`. The file documents when to use this reference, the project and upstream destinations, sanitization rules, and the scope of standing publication authorization if any. Run `issue-spec workflow update --dry-run --repo OWNER/REPO` before adopting the generated reference. Project guidance stays in the project-owned file. +Use an entry in `guidance.shared` in `issue-spec/config.yaml` to customize when to use feedback, project and upstream destinations, sanitization, or standing publication authorization. The generated reference is available after ordinary init or a workflow update. Preview an existing checkout's update with `issue-spec workflow update --dry-run --repo OWNER/REPO`. For a requested interval review, include open and closed feedback Issues and compare their creation dates and dated evidence. Group by root cause and count distinct keys. Record the upstream fix, local adoption revision and comparable verification as they become available in relevant authorized work. Prefer the original Issue and its evidence links for handoff across sessions. diff --git a/internal/templates/skills.go b/internal/templates/skills.go index 39116e59..218568aa 100644 --- a/internal/templates/skills.go +++ b/internal/templates/skills.go @@ -137,7 +137,7 @@ Use this workflow for a bounded simple Issue or optional Proposal, Design, Imple 3. Default to ` + "`--issue`" + ` for a bounded change with one code writer. A single child or subagent is an execution choice, not a reason to create TASK or PROCESS. Use ` + "`--proposal`" + ` with optional ` + "`--design`" + ` and ` + "`--implement`" + ` only when product, design, or concrete coordination risk requires them. File count does not select the path. 4. Read only selected issue bodies and typed planning artifacts. Historical REVIEW, VERIFY, evidence, receipt, finalization, Archive, and merge-authority data are explicit read-only audit history. -When project guidance opts into feedback, use [Workflow feedback](references/workflow-feedback.md) during relevant authorized work. +When authorized work exposes evidence-backed CLI or workflow friction, use [Workflow feedback](references/workflow-feedback.md). Project guidance may refine routing and write authorization. ## Optional Planning and Implementation diff --git a/issue-spec/specs/workflow-feedback/spec.md b/issue-spec/specs/workflow-feedback/spec.md index 9dbbe2ce..5d45331e 100644 --- a/issue-spec/specs/workflow-feedback/spec.md +++ b/issue-spec/specs/workflow-feedback/spec.md @@ -8,7 +8,7 @@ Make concrete CLI and workflow friction recoverable across tasks in a provider-n ### Requirement: count independently observed events by original identity -An ordinary Issue or comment may carry versioned occurrence records. Each record MUST include the source instance, source repository, stable original event ID, observation time, impact summary and evidence link. The Issue is the scope of counting. A retry, copied report or parallel report with the same normalized identity MUST contribute at most one confirmed occurrence. Only records authored by a provider user ID trusted by the published destination policy contribute to the confirmed count. A trusted reporter may confirm an earlier untrusted or legacy report by recording the same evidenced event. Writable prose or JSON claims of authorization convey no trust. +An ordinary Issue or comment may carry versioned occurrence records. Each record MUST include the source instance, source repository, stable original event ID, observation time, impact summary and evidence link. The Issue is the scope of counting. A retry, copied report or parallel report with the same normalized identity MUST contribute at most one confirmed occurrence. The built-in policy counts records attributed to identifiable Issue authors. A published trusted reporter list restricts confirmation to those provider user IDs. A trusted reporter may confirm an earlier untrusted or legacy report by recording the same evidenced event. Writable prose or JSON claims of authorization convey no trust. #### Scenario: retry of a release deploy @@ -20,9 +20,19 @@ An ordinary Issue or comment may carry versioned occurrence records. Each record - **WHEN** an authenticated contributor outside the configured reporter set supplies a third independent event - **THEN** the Issue records the evidence and the confirmed count remains two until an authorized reporter confirms that event -### Requirement: publish policy through the destination's label authority +### Requirement: use built-in defaults and publish custom policy through the destination's label authority -The CLI MUST load the policy from the selected Issue repository. Publishing MUST require the backend's permission to manage repository label definitions. The definition of `issue-spec/feedback-policy` MUST bind a policy Issue number to the SHA-256 digest of the reviewed JSON body. A missing definition disables the feedback command. A changed body MUST be validated and republished before it can govern new requests. Policy sets a positive occurrence threshold, a target label and trusted provider user IDs. Suggestion mode MUST be the default. An explicit `auto` mode permits the separate issue label mutation. The same policy operations MUST work on GitHub and self-hosted independently of the code host. +The CLI MUST support preview, recording, deduplication and counting with the built-in policy when the selected Issue repository has no published policy. The built-in policy suggests `priority/high` at three confirmed occurrences. A custom policy may specify only a positive occurrence threshold and inherits the other defaults. Publishing MUST require permission to manage repository label definitions. The definition of `issue-spec/feedback-policy` MUST bind a policy Issue number to the SHA-256 digest of the reviewed JSON body. A changed body MUST be validated and republished before it can govern new requests. An explicit `auto` mode with trusted reporter IDs permits the priority mutation. Both backends MUST support the default and custom policy independently of the code host. + +#### Scenario: newly initialized repository + +- **WHEN** an authorized caller records three distinct evidenced occurrences after ordinary init without publishing a policy +- **THEN** the CLI reports three confirmed occurrences and suggests `priority/high` + +#### Scenario: custom threshold only + +- **WHEN** a maintainer publishes a policy containing only the threshold +- **THEN** the CLI uses the custom threshold with suggestion mode and the built-in priority label #### Scenario: policy publication and preview @@ -36,17 +46,24 @@ The CLI MUST load the policy from the selected Issue repository. Publishing MUST ### Requirement: save evidence before permission-checked promotion -An explicit record request MUST preview the selected Issue, event identity, count and priority decision without writing when dry-run is selected. A real record request MUST save its evidence before attempting priority mutation. Automatic escalation requires a qualifying confirmed count, an open, unlocked Issue without a configured or built-in hold, an existing target label, unchanged published policy and effective backend permission to add the target label. Higher-priority and unrelated labels MUST be preserved. On self-hosted, contribution governs ordinary comment creation and triage governs issue label assignment. +An explicit record request MUST preview the selected Issue, event identity, count and priority decision without writing when dry-run is selected. A real record request MUST save its evidence before attempting priority mutation. Automatic escalation requires a qualifying confirmed count, an open, unlocked Issue without a configured or built-in hold, an existing target label and unchanged published policy. Higher-priority and unrelated labels MUST be preserved. GitHub MUST enforce its effective issue label permission. On self-hosted, the feedback promotion operation MUST enforce the same repository permission as creating an Issue. It MUST verify the published policy reference, re-evaluate the persisted evidence and Issue state in the mutation transaction, and apply only the policy's target label. Ordinary issue label assignment continues to require triage. A denied or unsuccessful label operation MUST preserve the recorded evidence and return the Issue identity, observed count and pending reason. The next request for the same occurrence MUST reconcile the existing record before retrying the label. An ambiguous comment or label response MUST be resolved by reading provider state before any repeated mutation. -#### Scenario: third occurrence with separate comment and label permissions +#### Scenario: GitHub third occurrence with separate comment and label permissions - **WHEN** an accepted third occurrence is recorded under automatic policy by a contributor who cannot assign labels - **THEN** the Issue contains the evidence and returns a count of three with promotion pending - **AND WHEN** an authorized triager retries the same event - **THEN** the priority label is added and the recorded event identity and count are preserved +#### Scenario: self-hosted Issue creator promotes a qualifying Issue + +- **WHEN** a caller with permission to create issues requests promotion against a published automatic policy and the stored evidence meets its threshold +- **THEN** the self-hosted server adds the configured priority label +- **AND WHEN** that caller requests promotion below the threshold or against a stale policy +- **THEN** the stored Issue labels remain intact + #### Scenario: maintainer hold or closed decision - **WHEN** a repository maintainer has held the Issue or the Issue is closed @@ -54,7 +71,7 @@ A denied or unsuccessful label operation MUST preserve the recorded evidence and ### Requirement: project instructions select the optional feedback procedure -The generated workflow MUST offer a shared feedback reference that projects can select through `guidance.shared` with their own destination and authorization rules. The procedure MUST use existing open and closed discussion search and ordinary Issues and comments. The project can use the feedback procedure during relevant authorized work and report adoption and verification with the original Issue. Workflow update preview MUST retain its read-only behavior and project-owned instructions. +The generated workflow MUST include a feedback reference for authorized tasks after ordinary initialization. Projects MAY refine triggering conditions, destinations and authorization through `guidance.shared`. The procedure MUST use existing open and closed discussion search and ordinary Issues and comments. The project can use the feedback procedure during relevant authorized work and report adoption and verification with the original Issue. Workflow update preview MUST retain its read-only behavior and project-owned instructions. ## Implementation references From 4691e44eb2bc29a39f03ca61aef96e810ec2cd4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=BE=84=E6=BD=AD?= Date: Mon, 16 Nov 2026 23:39:03 +0800 Subject: [PATCH 3/4] fix: recheck feedback promotion before labeling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 澄潭 --- internal/feedback/record.go | 71 ++++--- internal/feedback/record_test.go | 195 ++++++++++++++++++ .../issues/feedback_integration_test.go | 3 + issue-spec/specs/workflow-feedback/spec.md | 12 +- 4 files changed, 256 insertions(+), 25 deletions(-) create mode 100644 internal/feedback/record_test.go diff --git a/internal/feedback/record.go b/internal/feedback/record.go index 20153288..4839cf24 100644 --- a/internal/feedback/record.go +++ b/internal/feedback/record.go @@ -98,15 +98,18 @@ func Record(ctx context.Context, backend Backend, repo string, number int, event } result.setOccurrence(recorded, observed.confirmed) result.Promotion = promotionPlan(observed.issue, policy, observed.confirmed) - if result.Promotion.Status != "would_promote" || options.DryRun { + if result.Promotion.Status != "would_promote" { + return result, nil + } + if options.DryRun { + result.Promotion = checkPromotionLabel(ctx, backend, repo, result.Promotion) return result, nil } if options.SelfHosted { result.Promotion = applyHostedPromotion(ctx, backend, repo, number, policy.PriorityLabel, policyRef) - } else { - result.Promotion = applyPromotion(ctx, backend, repo, number, policy, policyRef, observed.confirmed) + return result, nil } - return result, nil + return applyGitHubPromotion(ctx, backend, result, policyRef), nil } func observe(ctx context.Context, backend github.IssueBackend, repo string, number int, policy Policy) (snapshot, error) { @@ -181,35 +184,55 @@ func promotionPlan(issue github.Issue, policy Policy, count int) Promotion { return plan } -func applyPromotion(ctx context.Context, backend Backend, repo string, number int, policy Policy, policyRef string, count int) Promotion { - pending := Promotion{Label: policy.PriorityLabel, Status: "pending"} - label, err := backend.GetRepositoryLabel(ctx, repo, PolicyLabel) - if err != nil || label.Description != policyRef { - pending.Reason = "feedback policy changed or could not be rechecked" - return pending +func applyGitHubPromotion(ctx context.Context, backend Backend, result Result, policyRef string) Result { + policy, _, currentRef, err := loadPolicy(ctx, backend, result.Repository) + if err != nil || currentRef != policyRef { + result.CountStale = true + result.Promotion.Status = "pending" + result.Promotion.Reason = "published feedback policy changed" + if err != nil { + result.Promotion.Reason = fmt.Sprintf("recheck feedback policy: %v", err) + } + return result } - issue, err := backend.GetIssue(ctx, repo, number) + + current, err := observe(ctx, backend, result.Repository, result.Issue, policy) if err != nil { - pending.Reason = "could not recheck Issue state and labels" - return pending + result.CountStale = true + result.Promotion.Status = "pending" + result.Promotion.Reason = fmt.Sprintf("recheck feedback evidence and Issue state: %v", err) + return result } - plan := promotionPlan(issue, policy, count) - if plan.Status != "would_promote" { - return plan + result.setOccurrence(current.events[result.EventKey], current.confirmed) + result.Promotion = promotionPlan(current.issue, policy, current.confirmed) + if result.Promotion.Status != "would_promote" { + return result } - if _, err := backend.GetRepositoryLabel(ctx, repo, policy.PriorityLabel); err != nil { - pending.Reason = fmt.Sprintf("configured priority label unavailable: %v", err) - return pending + + result.Promotion = checkPromotionLabel(ctx, backend, result.Repository, result.Promotion) + if result.Promotion.Status != "would_promote" { + return result } - labels, err := backend.AddIssueLabels(ctx, repo, number, []string{policy.PriorityLabel}) + labels, err := backend.AddIssueLabels(ctx, result.Repository, result.Issue, []string{policy.PriorityLabel}) if err != nil { - return reconcilePromotion(ctx, backend, repo, number, policy.PriorityLabel, err) + result.Promotion = reconcilePromotion(ctx, backend, result.Repository, result.Issue, policy.PriorityLabel, err) + return result } if !hasLabel(labels, policy.PriorityLabel) { - pending.Reason = "the backend did not assign the label; check label existence and triage permission" - return pending + result.Promotion.Status = "pending" + result.Promotion.Reason = "the backend did not assign the label; check label existence and triage permission" + return result + } + result.Promotion.Status = "applied" + return result +} + +func checkPromotionLabel(ctx context.Context, backend github.IssueLabelBackend, repo string, plan Promotion) Promotion { + if _, err := backend.GetRepositoryLabel(ctx, repo, plan.Label); err != nil { + plan.Status = "pending" + plan.Reason = fmt.Sprintf("configured priority label unavailable: %v", err) } - return Promotion{Label: policy.PriorityLabel, Status: "applied"} + return plan } func applyHostedPromotion(ctx context.Context, backend Backend, repo string, number int, label, policyRef string) Promotion { diff --git a/internal/feedback/record_test.go b/internal/feedback/record_test.go new file mode 100644 index 00000000..3520f995 --- /dev/null +++ b/internal/feedback/record_test.go @@ -0,0 +1,195 @@ +package feedback + +import ( + "context" + "os" + "strings" + "testing" + + "github.com/higress-group/issue-spec/internal/github" +) + +const ( + feedbackTestRepo = "example/project" + feedbackTestIssue = 42 + feedbackTestPolicyIssue = 17 + feedbackTestReporterID = 42 +) + +func TestGitHubPromotionRechecksPolicyAndEvidence(t *testing.T) { + for _, tc := range []struct { + name string + change func(*recordTestBackend) + wantStatus string + wantCount int + wantReason string + wantWrites int + }{ + { + name: "evidence withdrawn", + change: func(backend *recordTestBackend) { + backend.comments = backend.comments[1:] + }, + wantStatus: "below_threshold", + wantCount: 2, + }, + { + name: "published policy Issue edited", + change: func(backend *recordTestBackend) { + backend.policyBody = `{"mode":"suggest"}` + }, + wantStatus: "pending", + wantCount: 3, + wantReason: "differs from the published revision", + }, + { + name: "policy and evidence still qualify", + wantStatus: "applied", + wantCount: 3, + wantWrites: 1, + }, + } { + t.Run(tc.name, func(t *testing.T) { + backend, event := newRecordTestBackend(t) + backend.beforePolicyRecheck = tc.change + + result, err := Record(t.Context(), backend, feedbackTestRepo, feedbackTestIssue, event, RecordOptions{}) + if err != nil { + t.Fatal(err) + } + if result.Promotion.Status != tc.wantStatus || result.ConfirmedCount != tc.wantCount || + backend.labelWrites != tc.wantWrites || !strings.Contains(result.Promotion.Reason, tc.wantReason) { + t.Fatalf("result = %+v, label writes = %d", result, backend.labelWrites) + } + if result.EventStatus != "recorded" || result.CommentID != 3 || !result.Confirmed || + len(backend.comments) != tc.wantCount || backend.comments[len(backend.comments)-1].ID != result.CommentID { + t.Fatalf("the third event was not preserved: result=%+v comments=%+v", result, backend.comments) + } + }) + } +} + +func TestAutomaticPromotionPreviewChecksTargetLabel(t *testing.T) { + for _, tc := range []struct { + name string + selfHosted bool + labelExists bool + wantStatus string + wantReason string + }{ + {name: "GitHub available", labelExists: true, wantStatus: "would_promote"}, + {name: "GitHub missing", wantStatus: "pending", wantReason: "configured priority label unavailable: repository label not found"}, + {name: "self-hosted available", selfHosted: true, labelExists: true, wantStatus: "would_promote"}, + {name: "self-hosted missing", selfHosted: true, wantStatus: "pending", wantReason: "configured priority label unavailable: repository label not found"}, + } { + t.Run(tc.name, func(t *testing.T) { + backend, event := newRecordTestBackend(t) + backend.targetLabelExists = tc.labelExists + + preview, err := Record(t.Context(), backend, feedbackTestRepo, feedbackTestIssue, event, RecordOptions{ + DryRun: true, SelfHosted: tc.selfHosted, + }) + if err != nil { + t.Fatal(err) + } + if preview.EventStatus != "would_record" || preview.ConfirmedCount != 3 || + preview.Promotion.Status != tc.wantStatus || preview.Promotion.Label != "priority/high" || + preview.Promotion.Reason != tc.wantReason { + t.Fatalf("preview = %+v", preview) + } + if len(backend.comments) != 2 || backend.labelWrites != 0 { + t.Fatalf("preview changed provider state: comments=%d label writes=%d", len(backend.comments), backend.labelWrites) + } + }) + } +} + +type recordTestBackend struct { + Backend + policyBody string + policyRef string + policyReads int + beforePolicyRecheck func(*recordTestBackend) + comments []github.Comment + targetLabelExists bool + labelWrites int +} + +func newRecordTestBackend(t *testing.T) (*recordTestBackend, Event) { + t.Helper() + backend := &recordTestBackend{ + policyBody: `{"mode":"auto","trusted_reporter_ids":["42"]}`, + targetLabelExists: true, + } + _, reference, err := parsePolicyIssue(github.Issue{Body: backend.policyBody}, feedbackTestPolicyIssue) + if err != nil { + t.Fatal(err) + } + backend.policyRef = reference + + var event Event + for n, name := range []string{"release-0.6.2", "release-0.6.3", "synthetic-third-release"} { + data, err := os.ReadFile("../../testdata/workflow-feedback/" + name + ".json") + if err != nil { + t.Fatal(err) + } + event, err = ParseEvent(string(data)) + if err != nil { + t.Fatal(err) + } + if n == 2 { + break + } + body, err := event.commentBody() + if err != nil { + t.Fatal(err) + } + if _, err := backend.CreateComment(t.Context(), feedbackTestRepo, feedbackTestIssue, body); err != nil { + t.Fatal(err) + } + } + return backend, event +} + +func (b *recordTestBackend) GetRepositoryLabel(_ context.Context, _, name string) (github.Label, error) { + if name == PolicyLabel { + b.policyReads++ + if b.policyReads == 2 && b.beforePolicyRecheck != nil { + b.beforePolicyRecheck(b) + } + return github.Label{Name: name, Description: b.policyRef}, nil + } + if name == "priority/high" && b.targetLabelExists { + return github.Label{Name: name}, nil + } + return github.Label{}, github.ErrRepositoryLabelNotFound +} + +func (b *recordTestBackend) GetIssue(_ context.Context, _ string, number int) (github.Issue, error) { + issue := github.Issue{Number: number, State: "open"} + if number == feedbackTestPolicyIssue { + issue.Body = b.policyBody + } + return issue, nil +} + +func (b *recordTestBackend) GetUser(context.Context) (github.User, []string, error) { + return github.User{ID: feedbackTestReporterID, Login: "reporter"}, nil, nil +} + +func (b *recordTestBackend) ListIssueComments(context.Context, string, int) ([]github.Comment, error) { + return b.comments, nil +} + +func (b *recordTestBackend) CreateComment(_ context.Context, _ string, _ int, body string) (github.Comment, error) { + comment := github.Comment{ + ID: int64(len(b.comments) + 1), Body: body, User: &github.User{ID: feedbackTestReporterID, Login: "reporter"}, + } + b.comments = append(b.comments, comment) + return comment, nil +} + +func (b *recordTestBackend) AddIssueLabels(_ context.Context, _ string, _ int, names []string) ([]github.Label, error) { + b.labelWrites++ + return []github.Label{{Name: names[0]}}, nil +} diff --git a/internal/server/api/github/issues/feedback_integration_test.go b/internal/server/api/github/issues/feedback_integration_test.go index ec38f0a5..4ff0dde3 100644 --- a/internal/server/api/github/issues/feedback_integration_test.go +++ b/internal/server/api/github/issues/feedback_integration_test.go @@ -228,6 +228,9 @@ func TestFeedbackHiRoute495SelfHosted(t *testing.T) { } } + if preview := check("owner", suggest, 2, 3, "pending", "--dry-run"); !preview.DryRun || !strings.Contains(preview.Promotion.Reason, "label unavailable") { + t.Fatalf("preview did not report the missing label: %+v", preview) + } if missing := check("owner", suggest, 2, 3, "pending"); !strings.Contains(missing.Promotion.Reason, "label unavailable") { t.Fatalf("missing label did not leave promotion pending: %+v", missing) } diff --git a/issue-spec/specs/workflow-feedback/spec.md b/issue-spec/specs/workflow-feedback/spec.md index 5d45331e..89a9e69d 100644 --- a/issue-spec/specs/workflow-feedback/spec.md +++ b/issue-spec/specs/workflow-feedback/spec.md @@ -46,7 +46,7 @@ The CLI MUST support preview, recording, deduplication and counting with the bui ### Requirement: save evidence before permission-checked promotion -An explicit record request MUST preview the selected Issue, event identity, count and priority decision without writing when dry-run is selected. A real record request MUST save its evidence before attempting priority mutation. Automatic escalation requires a qualifying confirmed count, an open, unlocked Issue without a configured or built-in hold, an existing target label and unchanged published policy. Higher-priority and unrelated labels MUST be preserved. GitHub MUST enforce its effective issue label permission. On self-hosted, the feedback promotion operation MUST enforce the same repository permission as creating an Issue. It MUST verify the published policy reference, re-evaluate the persisted evidence and Issue state in the mutation transaction, and apply only the policy's target label. Ordinary issue label assignment continues to require triage. +An explicit record request MUST preview the selected Issue, event identity, count and priority decision without writing when dry-run is selected. A real record request MUST save its evidence before attempting priority mutation. Automatic escalation requires a qualifying confirmed count, an open, unlocked Issue without a configured or built-in hold, an existing target label and unchanged published policy. Higher-priority and unrelated labels MUST be preserved. When an automatic preview otherwise qualifies, the CLI MUST check target label existence with a read-only request. Before requesting a GitHub label write, the CLI MUST revalidate the published policy Issue digest and recompute eligibility from current evidence and Issue state. GitHub MUST enforce its effective issue label permission. On self-hosted, the feedback promotion operation MUST enforce the same repository permission as creating an Issue. It MUST verify the published policy reference, re-evaluate the persisted evidence and Issue state in the mutation transaction, and apply only the policy's target label. Ordinary issue label assignment continues to require triage. A denied or unsuccessful label operation MUST preserve the recorded evidence and return the Issue identity, observed count and pending reason. The next request for the same occurrence MUST reconcile the existing record before retrying the label. An ambiguous comment or label response MUST be resolved by reading provider state before any repeated mutation. @@ -57,6 +57,16 @@ A denied or unsuccessful label operation MUST preserve the recorded evidence and - **AND WHEN** an authorized triager retries the same event - **THEN** the priority label is added and the recorded event identity and count are preserved +#### Scenario: GitHub evidence or policy changes before promotion + +- **WHEN** a GitHub promotion initially qualifies but a confirmed occurrence is withdrawn or the published policy Issue body changes before final validation +- **THEN** the CLI stops the promotion and reports the updated count or the invalid policy + +#### Scenario: automatic preview with a missing label + +- **WHEN** an automatic promotion otherwise qualifies and its configured label is missing +- **THEN** the preview reports the pending label requirement with no provider mutation + #### Scenario: self-hosted Issue creator promotes a qualifying Issue - **WHEN** a caller with permission to create issues requests promotion against a published automatic policy and the stored evidence meets its threshold From a336a142321f914927f5569267ef2c1c0be1d790 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=BE=84=E6=BD=AD?= Date: Tue, 17 Nov 2026 17:44:30 +0900 Subject: [PATCH 4/4] Enable default project skill feedback and preflight GitHub init (#491) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: 澄潭 --- .agents/skills/issue-spec-feedback/SKILL.md | 16 ++ .agents/skills/issue-spec-workflow/SKILL.md | 2 +- .../references/workflow-feedback.md | 31 ++- .../skills/issue-spec-workflow/release.json | 10 +- .claude/skills/issue-spec-feedback | 1 + docs/reference.md | 10 +- docs/reference.zh-CN.md | 10 +- internal/commands/init.go | 89 +++++-- internal/commands/init_feedback_test.go | 233 ++++++++++++++++++ internal/commands/init_language_test.go | 18 ++ internal/commands/init_self_hosted_test.go | 6 +- internal/commands/workflow_install.go | 17 +- internal/commands/workflows.go | 24 +- internal/commands/workflows_test.go | 6 +- .../templates/assets/workflow-feedback.md | 31 ++- internal/templates/skills.go | 6 +- internal/templates/skills_test.go | 6 +- internal/templates/workflow_feedback.go | 11 + internal/workflow/workflow.go | 20 +- .../spec.md | 9 +- issue-spec/specs/workflow-feedback/spec.md | 16 +- 21 files changed, 483 insertions(+), 89 deletions(-) create mode 100644 .agents/skills/issue-spec-feedback/SKILL.md create mode 120000 .claude/skills/issue-spec-feedback create mode 100644 internal/commands/init_feedback_test.go diff --git a/.agents/skills/issue-spec-feedback/SKILL.md b/.agents/skills/issue-spec-feedback/SKILL.md new file mode 100644 index 00000000..add320e2 --- /dev/null +++ b/.agents/skills/issue-spec-feedback/SKILL.md @@ -0,0 +1,16 @@ +--- +name: issue-spec-feedback +description: Capture reproducible friction from any project skill, CLI command, or workflow. Use when instructions, references, or scripts cause a concrete problem during work. +license: MIT +metadata: + requires: "Requires issue-spec CLI." + author: issue-spec + version: "1.0" + generatedBy: "issue-spec" +--- + +# Issue Spec Feedback + +When a skill's instructions, references, or scripts cause a reproducible problem, record the skill name, repository-relative path, applicable revision, observed behavior, and impact on the task. Direct the report to the repository that owns the cause. + +Follow the [feedback guide](../issue-spec-workflow/references/workflow-feedback.md) to load project guidance, verify the Issue destination, and record evidence. Issue writes use the task's authorization and the target backend's permissions. diff --git a/.agents/skills/issue-spec-workflow/SKILL.md b/.agents/skills/issue-spec-workflow/SKILL.md index cfdf8c5a..fd3f51a4 100644 --- a/.agents/skills/issue-spec-workflow/SKILL.md +++ b/.agents/skills/issue-spec-workflow/SKILL.md @@ -22,7 +22,7 @@ For selected issue-spec steps, the built-in phase sequence and canonical artifac 3. Default to `--issue` for a bounded change with one code writer. A single child or subagent is an execution choice, not a reason to create TASK or PROCESS. Use `--proposal` with optional `--design` and `--implement` only when product, design, or concrete coordination risk requires them. File count does not select the path. 4. Read only selected issue bodies and typed planning artifacts. Historical REVIEW, VERIFY, evidence, receipt, finalization, Archive, and merge-authority data are explicit read-only audit history. -When authorized work exposes evidence-backed CLI or workflow friction, use [Workflow feedback](references/workflow-feedback.md). Project guidance may refine routing and write authorization. +When authorized work exposes evidence-backed CLI, workflow, or project skill friction, use [Workflow feedback](references/workflow-feedback.md). Project guidance may refine routing and write authorization. ## Optional Planning and Implementation diff --git a/.agents/skills/issue-spec-workflow/references/workflow-feedback.md b/.agents/skills/issue-spec-workflow/references/workflow-feedback.md index 49f65a8f..5c4008bc 100644 --- a/.agents/skills/issue-spec-workflow/references/workflow-feedback.md +++ b/.agents/skills/issue-spec-workflow/references/workflow-feedback.md @@ -1,17 +1,24 @@ # Workflow feedback -Use this reference when authorized work exposes a concrete CLI limitation, workflow gap, or project policy problem. Continue the original task and use an ordinary Issue and comments. Apply the current task's publication authorization and any standing authorization in project guidance. +Use this reference when authorized work exposes a reproducible problem with a project skill, CLI command, or workflow. The standalone `issue-spec-feedback` skill also links to this reference during ordinary project tasks. Continue the original task and use an ordinary Issue and comments. Apply the current task's publication authorization and any standing authorization in project guidance. + +## Find the project context + +From the checkout root, read `.issue-spec/config.json` to find the project's Issue repository (`repo`), `profile`, `hostname`, and self-hosted `server_instance_id` when present. If the file is absent, use the project Issue target established by the task. The code remote or Source Binding can point to a different repository. + +Run `issue-spec workflow which --repo "$project_repo" --json` with the project's Issue repository. Read the config at `.workflow.source.config_path` when present, including `openspec/config.yaml` if selected. Apply the relevant project rules and load the repository-relative files in `.workflow.config.guidance.shared`. ## Route and record -1. Identify the owner from the observed behavior. Route CLI limitations and reusable workflow improvements to the upstream repository identified by the task or project guidance. Route project-specific guidance, validation, and release problems to the originating project. Keep an internal draft while the destination is uncertain. Resolve the destination's Issue profile and repository before reading or writing. -2. Search open and closed discussions for the same cause with `issue-spec search issues --repo OWNER/REPO --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec read issue --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor. -3. For a new report, use `issue-spec issue create simple` with a self-contained body describing the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action. -4. Record each independent event with its original context. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events. -5. Preview before writing. Omit `--dry-run` when the write is authorized and the requested target and count are correct. +1. Choose the destination repository by root cause. Use the project's Issue target for locally owned skills, guidance, validation, and release problems. For CLI limitations, reusable workflow improvements, or externally maintained skills, use the owning upstream Issue target identified by the task or project guidance. Set `feedback_repo` and `feedback_profile` from that destination. Keep an internal draft while the destination is uncertain. +2. Run `issue-spec --profile "$feedback_profile" auth status --json` and require `.ok` and the intended `.auth.profile`. Confirm the expected GitHub host or the self-hosted `.auth.server_instance_id` for the destination. For GitHub Enterprise with the built-in `github` profile, pass the destination's `--hostname` to auth and each Issue command as well. Use the same verified profile and repository for every destination read and write, including a retry. User or project authorization and backend permissions govern writes. +3. Search open and closed discussions for the same cause with `issue-spec --profile "$feedback_profile" search issues --repo "$feedback_repo" --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec --profile "$feedback_profile" read issue --repo "$feedback_repo" --issue N --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor. +4. For a new authorized report, use `issue-spec --profile "$feedback_profile" issue create simple --repo "$feedback_repo" --title 'Observed problem' --body-file report.md`. Include the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action. +5. Record each independent event with its original context. For a skill problem, include the skill name, repository-relative path, applicable revision, and the step and impact that can be verified. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events. +6. Preview the record. Confirm the returned `url` identifies the intended Issue and the count is correct. Omit `--dry-run` when the write is authorized. ```sh -issue-spec feedback record --repo OWNER/REPO --issue 42 --event-file occurrence.json --dry-run --json +issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json ``` ```json @@ -36,7 +43,7 @@ Recording and preview work after ordinary initialization. The default policy cou To change the threshold or enable automatic escalation, publish a policy from an ordinary Issue in the **destination** repository. Its body contains a single JSON object, optionally fenced as JSON. To customize just the threshold, the entire body can be `{"threshold": 5}`. -Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For each trusted account, get the stable ID from `issue-spec auth status --json` under the intended Issue profile (`.auth.user_id`). Write the IDs as strings. +Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For each trusted account, get the stable ID from `issue-spec --profile "$feedback_profile" auth status --json` (`.auth.user_id`). Write the IDs as strings. ```json { @@ -52,16 +59,14 @@ Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For An automatic assignment uses a predefined repository label. The priority label defaults to `priority/high`. Higher-priority and hold labels are optional. `issue-spec/feedback-hold` and `wontfix` are recognized holds. A closed or locked Issue is ineligible. ```sh -issue-spec feedback configure --repo OWNER/REPO --issue 17 --dry-run --json -issue-spec feedback configure --repo OWNER/REPO --issue 17 +issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json +issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 ``` Publishing requires permission to manage repository label definitions. The command binds the exact policy body to the repository's `issue-spec/feedback-policy` label definition. Change the policy Issue body and publish again to activate a new revision. Remove the policy label definition to return to the built-in suggestion policy. GitHub enforces the caller's permission to assign a label. On self-hosted, a caller who can create Issues can request promotion. The server rechecks the published policy, persisted evidence and Issue eligibility before assigning the configured label. The ordinary issue-label API uses its triage authorization. -The commands use the active Issue profile or an explicit global `--profile` verified for the destination. A Source Binding or external code host is independent of where policies, Issues and comments are stored. - ## Customize project guidance -Use an entry in `guidance.shared` in `issue-spec/config.yaml` to customize when to use feedback, project and upstream destinations, sanitization, or standing publication authorization. The generated reference is available after ordinary init or a workflow update. Preview an existing checkout's update with `issue-spec workflow update --dry-run --repo OWNER/REPO`. +Use an entry in `guidance.shared` in the selected workflow config to customize when to use feedback, project and upstream destinations, sanitization, or standing publication authorization. The standalone feedback skill and shared reference are available after ordinary init or a workflow update. Preview an existing checkout's update with `issue-spec workflow update --dry-run --repo "$project_repo"`. For a requested interval review, include open and closed feedback Issues and compare their creation dates and dated evidence. Group by root cause and count distinct keys. Record the upstream fix, local adoption revision and comparable verification as they become available in relevant authorized work. Prefer the original Issue and its evidence links for handoff across sessions. diff --git a/.agents/skills/issue-spec-workflow/release.json b/.agents/skills/issue-spec-workflow/release.json index d3c20499..fd8b1f62 100644 --- a/.agents/skills/issue-spec-workflow/release.json +++ b/.agents/skills/issue-spec-workflow/release.json @@ -3,12 +3,16 @@ "release": "development", "source_revision": "unknown", "requirements_skill_content_id": "sha256:35e55ba3b52b377acbd36ca4305cd958e3bd593008d576a7a82c9b06ab862ed1", - "content_digest": "sha256:c0deac0a4b5f47e3adaa9789ee03e4e676a309ca6002ea6f5f903561509461f6", + "content_digest": "sha256:cf1870225bea33dcc6a8058b06a2badab1db6a2a6dabb9b728a0c35f7f72134f", "files": [ { "path": ".agents/skills/issue-spec-apply/SKILL.md", "sha256": "2351606737a7b0201c13ecc61ce4cd652d9d4bafaa66d20abc64c51ec56b2d56" }, + { + "path": ".agents/skills/issue-spec-feedback/SKILL.md", + "sha256": "247843d9acd7ae4fe8cb72289ab357c16bd665021f86df859505f985f98a7a72" + }, { "path": ".agents/skills/issue-spec-github/SKILL.md", "sha256": "a2a1cfeb647e737f66dbbbd97a53cfc752c84395ee4f6f080d7bfab3ee48d7d5" @@ -19,7 +23,7 @@ }, { "path": ".agents/skills/issue-spec-workflow/SKILL.md", - "sha256": "a736768ac79ae173d2ded184d544f657d3f711f40ea5ff727c316b5e14dbb799" + "sha256": "e94c748d919eff7fbd11e4f9de61d8268272a733278087d1fa19cb2a58348b58" }, { "path": ".agents/skills/issue-spec-workflow/references/durable-maintenance.md", @@ -43,7 +47,7 @@ }, { "path": ".agents/skills/issue-spec-workflow/references/workflow-feedback.md", - "sha256": "fb963ad59aa03820f1fc819d873b0c828915f3dd61a3130d5923fa2452b0dafb" + "sha256": "aff8d95d905aa39c10f78a0cb605582f7d55766478b74cb42bf31f909d70e06a" } ] } diff --git a/.claude/skills/issue-spec-feedback b/.claude/skills/issue-spec-feedback new file mode 120000 index 00000000..175f9619 --- /dev/null +++ b/.claude/skills/issue-spec-feedback @@ -0,0 +1 @@ +../../.agents/skills/issue-spec-feedback \ No newline at end of file diff --git a/docs/reference.md b/docs/reference.md index d170800e..ba484ab1 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -27,7 +27,7 @@ New durable specs default to `issue-spec/specs//spec.md`. If `opensp ### Shared skills and safe updates -`init` defaults to `--delivery skills`. `.agents/skills/` is canonical; Claude receives relative links per generated skill. `--delivery both|commands` remains an explicit legacy integration option. Root `AGENTS.md`/`CLAUDE.md` and project-specific skills remain project-owned. +`init` defaults to `--delivery skills`. When tool selection is omitted, skills delivery detects repository tool directories and falls back to canonical `.agents/skills` in a fresh checkout. GitHub init validates workflow inputs and checks file conflicts before saving the Issue binding and ensuring labels. Claude receives relative links when selected or detected. `--delivery both|commands` remains an explicit legacy integration option. Root `AGENTS.md`/`CLAUDE.md` and project-specific skills remain project-owned. ```yaml # issue-spec/config.yaml — optional supplements, paths relative to checkout root @@ -56,11 +56,13 @@ A legacy whole-directory Claude link is split while preserving previously expose ### Workflow feedback -Ordinary `issue-spec init` makes feedback recording, deduplication and counting available. The built-in policy suggests `priority/high` at three confirmed occurrences. Projects can use `guidance.shared` to refine routing and standing authorization. [Workflow feedback reference](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md) +Ordinary `issue-spec init` supplies the standalone `issue-spec-feedback` skill. It can be discovered when using any project skill exposes a reproducible issue with instructions, references, or scripts. The skill shares the feedback guide with `issue-spec-workflow` and uses the existing recording and deduplication commands. The built-in policy suggests `priority/high` at three confirmed occurrences. Projects can use `guidance.shared` to refine routing and standing authorization. [Workflow feedback reference](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md) + +For feedback about your own project, start with `repo` and `profile` from `.issue-spec/config.json`. Use the verified destination profile and repository in both previews and writes. ```bash -issue-spec feedback record --repo owner/repo --issue 42 --event-file occurrence.json --dry-run --json -issue-spec feedback configure --repo owner/repo --issue 17 --dry-run --json +issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json +issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json ``` Omit `--dry-run` for authorized writes. Use `feedback configure` when the destination wants a custom threshold or automatic escalation. GitHub checks label permission. On self-hosted, the updated Server checks Issue creation permission and validates eligibility from stored evidence. diff --git a/docs/reference.zh-CN.md b/docs/reference.zh-CN.md index 34666821..3002598c 100644 --- a/docs/reference.zh-CN.md +++ b/docs/reference.zh-CN.md @@ -27,11 +27,13 @@ issue-spec workflow which --repo owner/repo --json ### 工作流反馈 -常规 `issue-spec init` 后即可记录反馈、去重和计数。默认累计三次确认复现时建议标记 `priority/high`。项目可通过 `guidance.shared` 定制上报去向和授权范围。 [反馈指引与配置示例](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md) +常规 `issue-spec init` 默认生成独立的 `issue-spec-feedback` 技能。使用任意项目技能时遇到可复核的指令、引用或脚本问题,都能通过它找到反馈入口。它和 `issue-spec-workflow` 共用指引,沿用现有记录、去重和计数命令。默认累计三次确认复现时建议标记 `priority/high`。项目可通过 `guidance.shared` 定制上报去向和授权范围。 [反馈指引与配置示例](../.agents/skills/issue-spec-workflow/references/workflow-feedback.md) + +反馈本项目的问题时,先读取 `.issue-spec/config.json` 中的 `repo` 和 `profile`。预览和写入都使用核验后的目标仓库和 profile。 ```bash -issue-spec feedback record --repo owner/repo --issue 42 --event-file occurrence.json --dry-run --json -issue-spec feedback configure --repo owner/repo --issue 17 --dry-run --json +issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json +issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json ``` 在授权写入时去掉 `--dry-run`。自定义阈值或开启自动升级时,由目标仓库维护者运行 `feedback configure`。GitHub 按标签权限校验。自托管由新版 Server 校验 Issue 创建权限,并根据已保存证据判断能否升级。 @@ -87,7 +89,7 @@ rules: ### 共享技能、项目补充与安全升级 -`init` 默认 `--delivery skills`。通用技能保存在 `.agents/skills/`,Claude 按技能目录使用相对软链。`--delivery both|commands` 仅在显式选择时生成旧命令。项目维护 `AGENTS.md`、`CLAUDE.md`、自有技能与补充规则。 +`init` 默认 `--delivery skills`。省略 `--tools` 时按仓库已有目录探测宿主,空仓库默认生成 `.agents/skills`。GitHub 初始化会在保存 Issue 绑定和设置标签前校验工作流配置及文件冲突。显式选择或探测到 Claude 时按技能目录生成相对软链。`--delivery both|commands` 仅在显式选择时生成旧命令。项目维护 `AGENTS.md`、`CLAUDE.md`、自有技能与补充规则。 ```yaml # issue-spec/config.yaml,路径相对于仓库根目录 diff --git a/internal/commands/init.go b/internal/commands/init.go index 6551c982..5307a441 100644 --- a/internal/commands/init.go +++ b/internal/commands/init.go @@ -1,6 +1,7 @@ package commands import ( + "bytes" "context" "encoding/json" "errors" @@ -12,10 +13,12 @@ import ( "github.com/higress-group/issue-spec/internal/auth" "github.com/higress-group/issue-spec/internal/github" + "github.com/higress-group/issue-spec/internal/workflow" "gopkg.in/yaml.v3" ) const workflowNeutralLanguageGuidance = "configure rules.language in the selected project workflow; for legacy OpenSpec, use openspec/config.yaml" +const workflowLanguageConfigPath = "issue-spec/config.yaml" func (a *app) runInit(ctx context.Context, args []string) int { fs := newFlagSet("init", a.err) @@ -89,6 +92,14 @@ func (a *app) runInit(ctx context.Context, args []string) int { if !ok { return 2 } + var workflowPlan initWorkflowPlan + if !workflowNeutral { + workflowPlan, err = planGitHubInitWorkflow(".", *repoFlag, *tools, *delivery, *language) + if err != nil { + a.errorf("validate init workflow: %v\n", err) + return 1 + } + } client, token, err := a.clientFor(ctx, *host) if err != nil { a.errorf("auth required for init on %s: %v\n", auth.NormalizeHost(*host), err) @@ -126,11 +137,19 @@ func (a *app) runInit(ctx context.Context, args []string) int { } } - languageRequested := strings.TrimSpace(*language) != "" var languageConfigPath string - if languageRequested && !workflowNeutral { - languageConfigPath, err = writeWorkflowLanguageConfig(".", *language) + if workflowPlan.languageConfig != nil { + languageConfigPath = workflowLanguageConfigPath + current, err := renderWorkflowLanguageConfig(languageConfigPath, *language) if err != nil { + a.errorf("check planned workflow language config: %v\n", err) + return 1 + } + if !bytes.Equal(current, workflowPlan.languageConfig) { + a.errorf("%s changed after workflow preflight\n", languageConfigPath) + return 1 + } + if err := writeTextFile(languageConfigPath, string(workflowPlan.languageConfig)); err != nil { a.errorf("write workflow language config: %v\n", err) return 1 } @@ -138,7 +157,7 @@ func (a *app) runInit(ctx context.Context, args []string) int { workflows := workflowGenerationResult{Delivery: *delivery} if !workflowNeutral { - workflows, err = writeWorkflowArtifacts(".", *repoFlag, *tools, *delivery) + workflows, err = installWorkflowArtifacts(".", workflowPlan.update) if err != nil { a.errorf("generate workflow artifacts: %v\n", err) return 1 @@ -149,6 +168,7 @@ func (a *app) runInit(ctx context.Context, args []string) int { } } + languageRequested := strings.TrimSpace(*language) != "" result := map[string]any{"ok": true, "repo": *repoFlag, "hostname": token.Host, "auth": token, "backend": token.Backend, "config": configPath, "labels": labels, "workflows": workflows} if languageConfigPath != "" { result["language"] = languageDisplay(*language) @@ -185,6 +205,38 @@ func (a *app) runInit(ctx context.Context, args []string) int { return 0 } +type initWorkflowPlan struct { + update workflowUpdatePlan + languageConfig []byte +} + +func planGitHubInitWorkflow(root, repo, toolsArg, delivery, language string) (initWorkflowPlan, error) { + var result initWorkflowPlan + delivery, tools, err := resolveWorkflowGenerationOptions(root, toolsArg, delivery) + if err != nil { + return result, err + } + result.update.Generation.Delivery = delivery + if strings.TrimSpace(language) != "" { + result.languageConfig, err = renderWorkflowLanguageConfig(filepath.Join(root, workflowLanguageConfigPath), language) + if err != nil { + return result, err + } + } + if len(tools) == 0 { + return result, nil + } + plan, err := workflow.ResolveWithOptions(workflow.ResolveOptions{Root: root, IssueSpecConfig: result.languageConfig}) + if err != nil { + return result, err + } + result.update, err = planWorkflowUpdate(root, repo, delivery, tools, plan, nil) + if err != nil { + return result, err + } + return result, result.update.conflictError() +} + func resolveGlobalPromptInstallOptions(install bool, directory string, dryRun bool, delivery string) (globalPromptInstallOptions, error) { options := globalPromptInstallOptions{ Enabled: install || strings.TrimSpace(directory) != "" || dryRun, @@ -243,19 +295,30 @@ func (a *app) printWorkflowGeneration(workflows workflowGenerationResult) { // generated workflow artifacts instruct agents to author natural-language content // in the requested language while keeping canonical structural tokens in English. func writeWorkflowLanguageConfig(root, language string) (string, error) { + path := filepath.Join(root, workflowLanguageConfigPath) + out, err := renderWorkflowLanguageConfig(path, language) + if err != nil { + return "", err + } + if err := writeTextFile(path, string(out)); err != nil { + return "", err + } + return filepath.ToSlash(path), nil +} + +func renderWorkflowLanguageConfig(path, language string) ([]byte, error) { display := languageDisplay(language) - path := filepath.Join(root, "issue-spec", "config.yaml") cfg := map[string]any{} if data, err := os.ReadFile(path); err == nil { if err := yaml.Unmarshal(data, &cfg); err != nil { - return "", fmt.Errorf("parse existing %s: %w", filepath.ToSlash(path), err) + return nil, fmt.Errorf("parse existing %s: %w", filepath.ToSlash(path), err) } if cfg == nil { cfg = map[string]any{} } } else if !errors.Is(err, os.ErrNotExist) { - return "", err + return nil, err } rules, _ := cfg["rules"].(map[string]any) @@ -270,17 +333,7 @@ func writeWorkflowLanguageConfig(root, language string) (string, error) { rules["language_instructions"] = fmt.Sprintf("Write natural-language body content (descriptions, rationale, design notes, questions, decisions, task descriptions, and QUESTION/scenario prose) in %[1]s. %[2]s Ordinary (non-staged) issue titles use a descriptive %[1]s title. Keep canonical structural tokens in English so validation passes: the `## Requirement:` and `### Scenario:` headings, the `**WHEN**`/`**THEN**` scenario bullets, the MUST/SHALL normative keywords, and typed comment headers.", display, stagedTitleInstructions) cfg["rules"] = rules - out, err := yaml.Marshal(cfg) - if err != nil { - return "", err - } - if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil { - return "", err - } - if err := os.WriteFile(path, out, 0o644); err != nil { - return "", err - } - return filepath.ToSlash(path), nil + return yaml.Marshal(cfg) } // languageDisplay maps common language codes to a descriptive label while diff --git a/internal/commands/init_feedback_test.go b/internal/commands/init_feedback_test.go new file mode 100644 index 00000000..3e0b3bbc --- /dev/null +++ b/internal/commands/init_feedback_test.go @@ -0,0 +1,233 @@ +package commands + +import ( + "bytes" + "context" + "encoding/json" + "fmt" + "net/http" + "net/http/httptest" + "os" + "path/filepath" + "strings" + "sync/atomic" + "testing" + + "github.com/higress-group/issue-spec/internal/auth" + "github.com/higress-group/issue-spec/internal/feedback" + "github.com/higress-group/issue-spec/internal/github" +) + +func TestInitInstallsStandaloneFeedbackSkillByDefault(t *testing.T) { + for _, tc := range []struct { + name string + skill string + claude bool + }{ + {name: "fresh repository"}, + {name: "existing Codex skill", skill: ".agents/skills/local-check/SKILL.md"}, + {name: "existing Claude skill", skill: ".claude/skills/local-check/SKILL.md", claude: true}, + } { + t.Run(tc.name, func(t *testing.T) { + t.Chdir(t.TempDir()) + const instructions = "# Project instructions\n\nUse the project check skill.\n" + const projectSkill = "---\nname: local-check\ndescription: Run project checks.\n---\n\nRun the project checks.\n" + writeWorkflowTestFile(t, "AGENTS.md", instructions) + if tc.skill != "" { + writeWorkflowTestFile(t, tc.skill, projectSkill) + } + + var out, errOut bytes.Buffer + app := newInitTestApp(t, &out, &errOut) + if code := app.runInit(t.Context(), []string{"--repo", "acme/widgets"}); code != 0 { + t.Fatalf("init exit = %d, stderr=%q", code, errOut.String()) + } + + const entry = ".agents/skills/issue-spec-feedback/SKILL.md" + const guide = "../issue-spec-workflow/references/workflow-feedback.md" + feedback := readTestFile(t, entry) + if !strings.Contains(feedback, "name: issue-spec-feedback\n") || !strings.Contains(feedback, "("+guide+")") { + t.Fatalf("feedback skill is missing its discoverable name or shared guide:\n%s", feedback) + } + if guideBody := readTestFile(t, filepath.Join(filepath.Dir(entry), guide)); !strings.Contains(guideBody, " feedback record ") { + t.Fatal("the shared guide did not lead to feedback record") + } + workflow := readTestFile(t, ".agents/skills/issue-spec-workflow/SKILL.md") + if !strings.Contains(workflow, "(references/workflow-feedback.md)") { + t.Fatal("workflow and standalone feedback must use the same guide") + } + + claudePath := filepath.Join(".claude", "skills", "issue-spec-feedback") + if tc.claude { + if link, err := os.Readlink(claudePath); err != nil || link != "../../.agents/skills/issue-spec-feedback" { + t.Fatalf("Claude feedback link = %q, err=%v", link, err) + } + if got := readTestFile(t, filepath.Join(claudePath, "SKILL.md")); got != feedback { + t.Fatal("Claude resolved a different feedback skill") + } + readTestFile(t, filepath.Join(claudePath, guide)) + } else if _, err := os.Lstat(claudePath); !os.IsNotExist(err) { + t.Fatalf("unexpected Claude feedback exposure: %v", err) + } + if got := readTestFile(t, "AGENTS.md"); got != instructions { + t.Fatal("init modified project-owned instructions") + } + if tc.skill != "" && readTestFile(t, tc.skill) != projectSkill { + t.Fatal("init modified a project-owned skill") + } + if _, err := os.Stat("issue-spec/config.yaml"); !os.IsNotExist(err) { + t.Fatalf("default skill discovery required workflow configuration: %v", err) + } + }) + } +} + +func TestGitHubInitRejectsInvalidWorkflowBeforeWrites(t *testing.T) { + const bindingPath = ".issue-spec/config.json" + const binding = `{"version":1,"repo":"acme/previous","profile":"github","hostname":"github.com"}` + const feedbackPath = ".agents/skills/issue-spec-feedback/SKILL.md" + for _, tc := range []struct { + name string + path string + body string + args []string + err string + }{ + {name: "malformed workflow without detected tools", path: "issue-spec/config.yaml", body: "rules: [", err: "yaml:"}, + {name: "project-owned skill collision", path: feedbackPath, body: "Project-owned feedback.", args: []string{"--language", "zh"}, err: "locally changed or not managed"}, + } { + t.Run(tc.name, func(t *testing.T) { + t.Chdir(t.TempDir()) + writeWorkflowTestFile(t, bindingPath, binding) + writeWorkflowTestFile(t, tc.path, tc.body) + var out, errOut bytes.Buffer + app := newInitTestApp(t, &out, &errOut) + labelWrites := 0 + app.newGitHubBackend = func(_ context.Context, selection auth.GitHubBackendSelection) (github.Backend, error) { + return fakeGitHubBackend{ + info: github.BackendInfo{Name: selection.Name, Kind: selection.Kind, Host: selection.Host}, + user: github.User{Login: "octocat"}, + createLabel: func(_ context.Context, _ string, name, _, _ string) (github.LabelResult, error) { + labelWrites++ + return github.LabelResult{Name: name, Created: true}, nil + }, + }, nil + } + + args := append([]string{"--repo", "acme/widgets"}, tc.args...) + if code := app.runInit(t.Context(), args); code == 0 || !strings.Contains(errOut.String(), tc.err) { + t.Fatalf("init exit = %d, stderr=%q", code, errOut.String()) + } + if got := readTestFile(t, bindingPath); got != binding || labelWrites != 0 { + t.Fatalf("failed init changed binding to %q and attempted %d label writes", got, labelWrites) + } + if got := readTestFile(t, tc.path); got != tc.body { + t.Fatalf("failed init changed project file to %q", got) + } + for _, path := range []string{"issue-spec/config.yaml", feedbackPath, workflowManifestPath} { + if path == tc.path { + continue + } + if _, err := os.Lstat(path); !os.IsNotExist(err) { + t.Fatalf("failed init created %s: %v", path, err) + } + } + }) + } +} + +func TestGeneratedFeedbackPreviewUsesBoundProfile(t *testing.T) { + const repo = "acme/widgets" + occurrence := readTestFile(t, "../../testdata/workflow-feedback/release-0.6.3.json") + for _, tc := range []struct { + kind auth.ProfileKind + profile string + }{ + {kind: auth.ProfileKindGitHub, profile: "github"}, + {kind: auth.ProfileKindHosted, profile: "team"}, + } { + t.Run(string(tc.kind), func(t *testing.T) { + clearCommandAuthEnv(t) + t.Setenv(auth.GitHubBackendEnv, "rest") + t.Setenv(auth.ProfileEnv, "") + t.Setenv("ISSUE_SPEC_TOKEN", "test-reporter") + t.Chdir(t.TempDir()) + if err := os.Mkdir(".git", 0o755); err != nil { + t.Fatal(err) + } + + target, _ := newFeedbackTestServer(t) + other, otherRequests := newFeedbackTestServer(t) + profile := auth.Profile{Name: tc.profile, Kind: tc.kind, Hostname: "github.com", + APIURL: target.URL, NativeAPIURL: target.URL + "/api/v1", WebURL: target.URL, ServerInstanceID: "intended"} + if err := auth.SaveProfile(profile, false); err != nil { + t.Fatal(err) + } + if err := auth.SaveProfile(auth.Profile{Name: "other", Kind: auth.ProfileKindHosted, + APIURL: other.URL, NativeAPIURL: other.URL + "/api/v1", WebURL: other.URL, ServerInstanceID: "other"}, true); err != nil { + t.Fatal(err) + } + if tc.kind == auth.ProfileKindGitHub { + // An explicitly active profile also takes precedence over the GitHub checkout marker. + t.Setenv(auth.ProfileEnv, "other") + } + writeWorkflowTestFile(t, ".issue-spec/config.json", fmt.Sprintf(`{"repo":%q,"profile":%q,"hostname":"github.com"}`, repo, profile.Name)) + writeWorkflowTestFile(t, "occurrence.json", occurrence) + if _, err := writeWorkflowArtifacts(".", repo, "", workflowDeliverySkills); err != nil { + t.Fatal(err) + } + guide := readTestFile(t, ".agents/skills/issue-spec-workflow/references/workflow-feedback.md") + var args []string + for line := range strings.Lines(guide) { + if strings.HasPrefix(line, "issue-spec ") && strings.Contains(line, " feedback record ") { + resolved := strings.NewReplacer(`"$feedback_profile"`, profile.Name, `"$feedback_repo"`, repo) + args = strings.Fields(resolved.Replace(line))[1:] + break + } + } + if len(args) == 0 { + t.Fatal("the shared guide has no feedback preview example") + } + var out, errOut bytes.Buffer + if code := Execute(args, strings.NewReader(""), &out, &errOut); code != 0 { + t.Fatalf("feedback preview exit = %d, stderr=%q", code, errOut.String()) + } + var result feedback.Result + if err := json.Unmarshal(out.Bytes(), &result); err != nil { + t.Fatal(err) + } + if result.URL != target.URL+"/acme/widgets/issues/42" || otherRequests.Load() != 0 || + !result.DryRun || result.EventStatus != "would_record" || result.ConfirmedCount != 1 { + t.Fatalf("feedback preview = %+v, requests to global profile = %d", result, otherRequests.Load()) + } + }) + } +} + +func newFeedbackTestServer(t *testing.T) (*httptest.Server, *atomic.Int32) { + t.Helper() + var requests atomic.Int32 + server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + requests.Add(1) + if r.Method != http.MethodGet { + t.Errorf("feedback preview attempted %s %s", r.Method, r.URL.Path) + w.WriteHeader(http.StatusMethodNotAllowed) + return + } + switch r.URL.Path { + case "/user": + writeTestJSON(w, github.User{ID: 7, Login: "reporter"}) + case "/repos/acme/widgets/issues/42": + writeTestJSON(w, github.Issue{Number: 42, State: "open", HTMLURL: "http://" + r.Host + "/acme/widgets/issues/42"}) + case "/repos/acme/widgets/issues/42/comments": + writeTestJSON(w, []github.Comment{}) + case "/repos/acme/widgets/labels/issue-spec/feedback-policy": + http.NotFound(w, r) + default: + t.Errorf("unexpected request %s", r.URL.Path) + http.NotFound(w, r) + } + })) + t.Cleanup(server.Close) + return server, &requests +} diff --git a/internal/commands/init_language_test.go b/internal/commands/init_language_test.go index 7b99adb9..e0256660 100644 --- a/internal/commands/init_language_test.go +++ b/internal/commands/init_language_test.go @@ -178,6 +178,24 @@ func TestInitWithoutLanguageDoesNotWriteWorkflowConfig(t *testing.T) { } } +func TestInitLanguagePreflightsTheNewConfigInsteadOfLegacy(t *testing.T) { + t.Chdir(t.TempDir()) + const legacy = "schema: missing-legacy-schema\n" + writeWorkflowTestFile(t, "openspec/config.yaml", legacy) + var out, errOut bytes.Buffer + app := newInitTestApp(t, &out, &errOut) + if code := app.runInit(t.Context(), []string{"--repo", "acme/widgets", "--language", "zh"}); code != 0 { + t.Fatalf("init exit=%d stderr=%q", code, errOut.String()) + } + if got := readTestFile(t, "openspec/config.yaml"); got != legacy { + t.Fatalf("init changed the legacy config: %q", got) + } + skill := readTestFile(t, ".agents/skills/issue-spec-workflow/SKILL.md") + if !strings.Contains(skill, "- Workflow Config: `issue-spec/config.yaml`") { + t.Fatalf("the generated skills did not use the planned config:\n%s", skill) + } +} + func TestInitToolsNoneReportsLanguageWithoutWorkflowWrites(t *testing.T) { for _, jsonOutput := range []bool{false, true} { name := "text" diff --git a/internal/commands/init_self_hosted_test.go b/internal/commands/init_self_hosted_test.go index 83c7df59..ce6d3ca7 100644 --- a/internal/commands/init_self_hosted_test.go +++ b/internal/commands/init_self_hosted_test.go @@ -584,7 +584,7 @@ func TestSelfHostedInitEnsuresRepositoryBindingAndResumesIdempotently(t *testing journalBefore := readTestFile(t, filepath.Join(root, ".issue-spec", "init-state.json")) remoteCallsBefore := [3]int{ensureCalls, bindingCalls, labelCalls} noProviderArgs := []string{"--repo", "local-source/local-checkout", "--server-org", "browser-e2e", "--server-repo", "httpbin", - "--skip-source-binding", "--skip-labels", "--tools", "codex", "--delivery", "skills", "--json"} + "--skip-source-binding", "--skip-labels", "--json"} { var out, errOut bytes.Buffer app := newApp(strings.NewReader(""), &out, &errOut) @@ -616,6 +616,10 @@ func TestSelfHostedInitEnsuresRepositoryBindingAndResumesIdempotently(t *testing t.Fatalf("provider-neutral rerun exit=%d stderr=%s stdout=%s", code, errOut.String(), out.String()) } } + feedbackSkill := readTestFile(t, filepath.Join(root, ".agents", "skills", "issue-spec-feedback", "SKILL.md")) + if !strings.Contains(feedbackSkill, "../issue-spec-workflow/references/workflow-feedback.md") { + t.Fatalf("default self-hosted init did not link the shared feedback guide:\n%s", feedbackSkill) + } preservedConfig := readTestFile(t, filepath.Join(root, ".issue-spec", "config.json")) for _, want := range []string{`"key": "code.example"`, `"external_repository": "acme/widgets"`, `"change.create"`, `"change.comment"`} { if !strings.Contains(preservedConfig, want) { diff --git a/internal/commands/workflow_install.go b/internal/commands/workflow_install.go index 6e17ac17..7372bfa0 100644 --- a/internal/commands/workflow_install.go +++ b/internal/commands/workflow_install.go @@ -29,6 +29,13 @@ type workflowUpdatePlan struct { Generation workflowGenerationResult `json:"generation"` } +func (p workflowUpdatePlan) conflictError() error { + if len(p.Conflicts) > 0 { + return fmt.Errorf("workflow update conflicts:\n%s", strings.Join(p.Conflicts, "\n")) + } + return nil +} + const workflowManifestPath = ".agents/skills/issue-spec-workflow/release.json" func workflowHash(body []byte) string { return fmt.Sprintf("%x", sha256.Sum256(body)) } @@ -311,8 +318,8 @@ func planClaudeSkillLinks(root, stage string, update *workflowUpdatePlan) error // Move each replaced entry into a sibling backup before installing it. A failed // write rolls back all completed moves, including directory/link migrations. func applyWorkflowUpdate(root string, update workflowUpdatePlan) (err error) { - if len(update.Conflicts) > 0 { - return fmt.Errorf("workflow update conflicts:\n%s", strings.Join(update.Conflicts, "\n")) + if err := update.conflictError(); err != nil { + return err } if len(update.Changes) == 0 { return nil @@ -412,7 +419,11 @@ func writeWorkflowArtifactsResolvedWithProvider(root, repo, delivery string, too if err != nil { return update.Generation, err } - if err = applyWorkflowUpdate(root, update); err != nil { + return installWorkflowArtifacts(root, update) +} + +func installWorkflowArtifacts(root string, update workflowUpdatePlan) (workflowGenerationResult, error) { + if err := applyWorkflowUpdate(root, update); err != nil { return update.Generation, err } for _, change := range update.Changes { diff --git a/internal/commands/workflows.go b/internal/commands/workflows.go index b4b7cb7e..34b5ac1a 100644 --- a/internal/commands/workflows.go +++ b/internal/commands/workflows.go @@ -69,8 +69,10 @@ type globalPromptInstallOptions struct { DryRun bool } +var codexWorkflowTool = workflowTool{ID: "codex", RootDir: ".agents"} + var workflowTools = []workflowTool{ - {ID: "codex", RootDir: ".agents"}, + codexWorkflowTool, {ID: "claude", RootDir: ".claude"}, } @@ -451,6 +453,9 @@ func resolveWorkflowGenerationOptions(root, toolsArg, delivery string) (string, if err != nil { return "", nil, err } + if len(tools) == 0 && strings.TrimSpace(toolsArg) == "" && delivery == workflowDeliverySkills { + tools = []workflowTool{codexWorkflowTool} + } return delivery, tools, nil } @@ -461,21 +466,18 @@ func workflowSkills(repo string, plan workflow.Plan) []templates.RenderedSkill { func workflowSkillsWithProvider(repo string, plan workflow.Plan, provider *workflow.ProviderPlan) []templates.RenderedSkill { options := templates.WorkflowAuthoringOptions{HTMLReviewEnabled: plan.HTMLReviewEnabled()} skills := templates.IssueSpecSkillsWithOptions(repo, options) - notice := workflowNotice(plan) + notice := strings.TrimRight(workflowNotice(plan), "\n") + if provider != nil { + notice += "\n\n" + strings.TrimRight(templates.ProviderWorkflowNotice(*provider), "\n") + } for i := range skills { - if skills[i].Name == "issue-spec-github" { + switch skills[i].Name { + case "issue-spec-feedback", "issue-spec-github": continue } - skills[i].Content = strings.TrimRight(skills[i].Content, "\n") + "\n\n" + strings.TrimRight(notice, "\n") + "\n" + skills[i].Content = strings.TrimRight(skills[i].Content, "\n") + "\n\n" + notice + "\n" } if provider != nil { - providerNotice := templates.ProviderWorkflowNotice(*provider) - for i := range skills { - if skills[i].Name == "issue-spec-github" { - continue - } - skills[i].Content = strings.TrimRight(skills[i].Content, "\n") + "\n\n" + strings.TrimRight(providerNotice, "\n") + "\n" - } skills = append(skills, templates.IssueSpecProviderSkill(repo, *provider)) } return skills diff --git a/internal/commands/workflows_test.go b/internal/commands/workflows_test.go index eaab431a..f54b7174 100644 --- a/internal/commands/workflows_test.go +++ b/internal/commands/workflows_test.go @@ -29,13 +29,13 @@ func TestWriteWorkflowArtifactsUsesCurrentCodexSkillPathWithoutGlobalWrites(t *t if err != nil { t.Fatal(err) } - if got, want := len(result.SkillFiles), 4; got != want { + if got, want := len(result.SkillFiles), 5; got != want { t.Fatalf("skill file count = %d, want %d", got, want) } if got, want := len(result.SkillResourceFiles), len(templates.HumanReviewProjectionResources())+7; got != want { t.Fatalf("skill resource file count = %d, want %d", got, want) } - if got, want := len(result.SkillLinks), 4; got != want { + if got, want := len(result.SkillLinks), 5; got != want { t.Fatalf("skill links = %v, want %v", got, want) } if got, want := len(result.CommandFiles), 2; got != want { @@ -412,11 +412,13 @@ func TestCheckedInWorkflowArtifactsExactlyMatchGenerator(t *testing.T) { for _, relative := range append( []string{ filepath.Join(".agents", "skills", "issue-spec-apply", "SKILL.md"), + filepath.Join(".agents", "skills", "issue-spec-feedback", "SKILL.md"), filepath.Join(".agents", "skills", "issue-spec-github", "SKILL.md"), filepath.Join(".agents", "skills", "issue-spec-propose", "SKILL.md"), filepath.Join(".agents", "skills", "issue-spec-workflow", "SKILL.md"), filepath.Join(".agents", "skills", "issue-spec-workflow", "release.json"), filepath.Join(".claude", "skills", "issue-spec-apply", "SKILL.md"), + filepath.Join(".claude", "skills", "issue-spec-feedback", "SKILL.md"), filepath.Join(".claude", "skills", "issue-spec-github", "SKILL.md"), filepath.Join(".claude", "skills", "issue-spec-propose", "SKILL.md"), filepath.Join(".claude", "skills", "issue-spec-workflow", "SKILL.md"), diff --git a/internal/templates/assets/workflow-feedback.md b/internal/templates/assets/workflow-feedback.md index 49f65a8f..5c4008bc 100644 --- a/internal/templates/assets/workflow-feedback.md +++ b/internal/templates/assets/workflow-feedback.md @@ -1,17 +1,24 @@ # Workflow feedback -Use this reference when authorized work exposes a concrete CLI limitation, workflow gap, or project policy problem. Continue the original task and use an ordinary Issue and comments. Apply the current task's publication authorization and any standing authorization in project guidance. +Use this reference when authorized work exposes a reproducible problem with a project skill, CLI command, or workflow. The standalone `issue-spec-feedback` skill also links to this reference during ordinary project tasks. Continue the original task and use an ordinary Issue and comments. Apply the current task's publication authorization and any standing authorization in project guidance. + +## Find the project context + +From the checkout root, read `.issue-spec/config.json` to find the project's Issue repository (`repo`), `profile`, `hostname`, and self-hosted `server_instance_id` when present. If the file is absent, use the project Issue target established by the task. The code remote or Source Binding can point to a different repository. + +Run `issue-spec workflow which --repo "$project_repo" --json` with the project's Issue repository. Read the config at `.workflow.source.config_path` when present, including `openspec/config.yaml` if selected. Apply the relevant project rules and load the repository-relative files in `.workflow.config.guidance.shared`. ## Route and record -1. Identify the owner from the observed behavior. Route CLI limitations and reusable workflow improvements to the upstream repository identified by the task or project guidance. Route project-specific guidance, validation, and release problems to the originating project. Keep an internal draft while the destination is uncertain. Resolve the destination's Issue profile and repository before reading or writing. -2. Search open and closed discussions for the same cause with `issue-spec search issues --repo OWNER/REPO --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec read issue --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor. -3. For a new report, use `issue-spec issue create simple` with a self-contained body describing the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action. -4. Record each independent event with its original context. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events. -5. Preview before writing. Omit `--dry-run` when the write is authorized and the requested target and count are correct. +1. Choose the destination repository by root cause. Use the project's Issue target for locally owned skills, guidance, validation, and release problems. For CLI limitations, reusable workflow improvements, or externally maintained skills, use the owning upstream Issue target identified by the task or project guidance. Set `feedback_repo` and `feedback_profile` from that destination. Keep an internal draft while the destination is uncertain. +2. Run `issue-spec --profile "$feedback_profile" auth status --json` and require `.ok` and the intended `.auth.profile`. Confirm the expected GitHub host or the self-hosted `.auth.server_instance_id` for the destination. For GitHub Enterprise with the built-in `github` profile, pass the destination's `--hostname` to auth and each Issue command as well. Use the same verified profile and repository for every destination read and write, including a retry. User or project authorization and backend permissions govern writes. +3. Search open and closed discussions for the same cause with `issue-spec --profile "$feedback_profile" search issues --repo "$feedback_repo" --scope discussion --state all --query 'specific behavior'`. Read plausible matches with `issue-spec --profile "$feedback_profile" read issue --repo "$feedback_repo" --issue N --comments`. Reuse an existing Issue for the same unresolved cause and supplement a closed decision with authorized evidence when appropriate. Link a distinct regression after a fix to its predecessor. +4. For a new authorized report, use `issue-spec --profile "$feedback_profile" issue create simple --repo "$feedback_repo" --title 'Observed problem' --body-file report.md`. Include the dated observation, originating project and revisions, expected and actual result, impact, owning layer, suggested correction and acceptance. Follow the destination's classification policy. An initial taxonomy uses `improvement/feedback` and one of `improvement/cli`, `improvement/workflow-generic`, or `improvement/workflow-project`. If classification needs a separate authorized label action, retain the original Issue identity and retry that action. +5. Record each independent event with its original context. For a skill problem, include the skill name, repository-relative path, applicable revision, and the step and impact that can be verified. Use the provider's stable source instance identifier, source repository and original task or release identifier. For a retried release, preserve its original key even when the run or attempt changes. A maintainer or configured trusted reporter can map each verifiable historical event to its own record and link the original evidence. Count independent events across Issue bodies and ordinary comments. Treat discussion, handoffs and repair verification as context for those events. +6. Preview the record. Confirm the returned `url` identifies the intended Issue and the count is correct. Omit `--dry-run` when the write is authorized. ```sh -issue-spec feedback record --repo OWNER/REPO --issue 42 --event-file occurrence.json --dry-run --json +issue-spec --profile "$feedback_profile" feedback record --repo "$feedback_repo" --issue 42 --event-file occurrence.json --dry-run --json ``` ```json @@ -36,7 +43,7 @@ Recording and preview work after ordinary initialization. The default policy cou To change the threshold or enable automatic escalation, publish a policy from an ordinary Issue in the **destination** repository. Its body contains a single JSON object, optionally fenced as JSON. To customize just the threshold, the entire body can be `{"threshold": 5}`. -Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For each trusted account, get the stable ID from `issue-spec auth status --json` under the intended Issue profile (`.auth.user_id`). Write the IDs as strings. +Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For each trusted account, get the stable ID from `issue-spec --profile "$feedback_profile" auth status --json` (`.auth.user_id`). Write the IDs as strings. ```json { @@ -52,16 +59,14 @@ Automatic escalation uses `"mode": "auto"` and a list of trusted reporters. For An automatic assignment uses a predefined repository label. The priority label defaults to `priority/high`. Higher-priority and hold labels are optional. `issue-spec/feedback-hold` and `wontfix` are recognized holds. A closed or locked Issue is ineligible. ```sh -issue-spec feedback configure --repo OWNER/REPO --issue 17 --dry-run --json -issue-spec feedback configure --repo OWNER/REPO --issue 17 +issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 --dry-run --json +issue-spec --profile "$feedback_profile" feedback configure --repo "$feedback_repo" --issue 17 ``` Publishing requires permission to manage repository label definitions. The command binds the exact policy body to the repository's `issue-spec/feedback-policy` label definition. Change the policy Issue body and publish again to activate a new revision. Remove the policy label definition to return to the built-in suggestion policy. GitHub enforces the caller's permission to assign a label. On self-hosted, a caller who can create Issues can request promotion. The server rechecks the published policy, persisted evidence and Issue eligibility before assigning the configured label. The ordinary issue-label API uses its triage authorization. -The commands use the active Issue profile or an explicit global `--profile` verified for the destination. A Source Binding or external code host is independent of where policies, Issues and comments are stored. - ## Customize project guidance -Use an entry in `guidance.shared` in `issue-spec/config.yaml` to customize when to use feedback, project and upstream destinations, sanitization, or standing publication authorization. The generated reference is available after ordinary init or a workflow update. Preview an existing checkout's update with `issue-spec workflow update --dry-run --repo OWNER/REPO`. +Use an entry in `guidance.shared` in the selected workflow config to customize when to use feedback, project and upstream destinations, sanitization, or standing publication authorization. The standalone feedback skill and shared reference are available after ordinary init or a workflow update. Preview an existing checkout's update with `issue-spec workflow update --dry-run --repo "$project_repo"`. For a requested interval review, include open and closed feedback Issues and compare their creation dates and dated evidence. Group by root cause and count distinct keys. Record the upstream fix, local adoption revision and comparable verification as they become available in relevant authorized work. Prefer the original Issue and its evidence links for handoff across sessions. diff --git a/internal/templates/skills.go b/internal/templates/skills.go index 218568aa..50391639 100644 --- a/internal/templates/skills.go +++ b/internal/templates/skills.go @@ -46,7 +46,7 @@ func IssueSpecSkills(repo string) []RenderedSkill { func IssueSpecSkillsWithOptions(repo string, options WorkflowAuthoringOptions) []RenderedSkill { workflows := issueSpecWorkflows(repo, options) - out := make([]RenderedSkill, 0, len(workflows)+1) + out := make([]RenderedSkill, 0, len(workflows)+2) for _, tmpl := range workflows { body := tmpl.Body reviewPath := "../issue-spec-workflow/references/implementation-review.md" @@ -73,7 +73,7 @@ func IssueSpecSkillsWithOptions(repo string, options WorkflowAuthoringOptions) [ } out = append(out, skill) } - out = append(out, githubCLISkill()) + out = append(out, feedbackSkill(), githubCLISkill()) return out } @@ -137,7 +137,7 @@ Use this workflow for a bounded simple Issue or optional Proposal, Design, Imple 3. Default to ` + "`--issue`" + ` for a bounded change with one code writer. A single child or subagent is an execution choice, not a reason to create TASK or PROCESS. Use ` + "`--proposal`" + ` with optional ` + "`--design`" + ` and ` + "`--implement`" + ` only when product, design, or concrete coordination risk requires them. File count does not select the path. 4. Read only selected issue bodies and typed planning artifacts. Historical REVIEW, VERIFY, evidence, receipt, finalization, Archive, and merge-authority data are explicit read-only audit history. -When authorized work exposes evidence-backed CLI or workflow friction, use [Workflow feedback](references/workflow-feedback.md). Project guidance may refine routing and write authorization. +When authorized work exposes evidence-backed CLI, workflow, or project skill friction, use [Workflow feedback](references/workflow-feedback.md). Project guidance may refine routing and write authorization. ## Optional Planning and Implementation diff --git a/internal/templates/skills_test.go b/internal/templates/skills_test.go index e8de7088..e2114c72 100644 --- a/internal/templates/skills_test.go +++ b/internal/templates/skills_test.go @@ -12,7 +12,7 @@ import ( func TestIssueSpecSkillAndCommandTemplates(t *testing.T) { skills := IssueSpecSkills("owner/repo") - if got, want := len(skills), 4; got != want { + if got, want := len(skills), 5; got != want { t.Fatalf("skills = %d, want %d", got, want) } if !strings.Contains(skills[0].Content, `generatedBy: "issue-spec"`) { @@ -136,7 +136,7 @@ func TestHTMLReviewAuthoringOptionsPreserveEnabledDefaultsAndOmitDisabledGuidanc func TestGeneratedGuidanceMakesBuiltInPhaseProtocolAuthoritative(t *testing.T) { const authority = "For selected issue-spec steps, the built-in phase sequence and canonical artifact carriers are authoritative; never reorder/omit steps or move open decisions." for _, skill := range IssueSpecSkills("owner/repo") { - if skill.Name == "issue-spec-github" { + if skill.Name == "issue-spec-github" || skill.Name == "issue-spec-feedback" { continue } if !strings.Contains(skill.Content, authority) { @@ -147,7 +147,7 @@ func TestGeneratedGuidanceMakesBuiltInPhaseProtocolAuthoritative(t *testing.T) { func TestTypedCommentWriterGuidanceRepeatsIssueScopedIDAllocation(t *testing.T) { for _, skill := range IssueSpecSkillsWithOptions("owner/repo", WorkflowAuthoringOptions{HTMLReviewEnabled: false}) { - if skill.Name == "issue-spec-github" { + if skill.Name == "issue-spec-github" || skill.Name == "issue-spec-feedback" { continue } for _, want := range []string{ diff --git a/internal/templates/workflow_feedback.go b/internal/templates/workflow_feedback.go index 4d21da0c..73d7c330 100644 --- a/internal/templates/workflow_feedback.go +++ b/internal/templates/workflow_feedback.go @@ -4,3 +4,14 @@ import _ "embed" //go:embed assets/workflow-feedback.md var workflowFeedbackReference string + +func feedbackSkill() RenderedSkill { + const name = "issue-spec-feedback" + const description = "Capture reproducible friction from any project skill, CLI command, or workflow. Use when instructions, references, or scripts cause a concrete problem during work." + const body = `# Issue Spec Feedback + +When a skill's instructions, references, or scripts cause a reproducible problem, record the skill name, repository-relative path, applicable revision, observed behavior, and impact on the task. Direct the report to the repository that owns the cause. + +Follow the [feedback guide](../issue-spec-workflow/references/workflow-feedback.md) to load project guidance, verify the Issue destination, and record evidence. Issue writes use the task's authorization and the target backend's permissions.` + return RenderedSkill{Name: name, Content: renderSkill(name, description, body)} +} diff --git a/internal/workflow/workflow.go b/internal/workflow/workflow.go index 3fe7aad0..2d064534 100644 --- a/internal/workflow/workflow.go +++ b/internal/workflow/workflow.go @@ -131,6 +131,9 @@ type ResolveOptions struct { Root string Schema string UserConfigDir string + // IssueSpecConfig previews pending issue-spec/config.yaml contents. + // A nil value reads the repository's existing configuration. + IssueSpecConfig []byte } func Resolve(root string) (Plan, error) { @@ -147,7 +150,7 @@ func ResolveWithOptions(opts ResolveOptions) (Plan, error) { issueConfig := filepath.Join(root, "issue-spec", "config.yaml") legacyConfig := filepath.Join(root, "openspec", "config.yaml") - hasIssueConfig := fileExists(issueConfig) + hasIssueConfig := opts.IssueSpecConfig != nil || fileExists(issueConfig) hasLegacyConfig := fileExists(legacyConfig) switch { @@ -162,7 +165,7 @@ func ResolveWithOptions(opts ResolveOptions) (Plan, error) { Path: filepath.ToSlash(legacyConfig), }) } - cfg, err := readConfig(issueConfig) + cfg, err := readConfig(issueConfig, opts.IssueSpecConfig) if err != nil { return withError(plan, Diagnostic{Severity: "error", Code: "invalid_config", Message: err.Error(), Path: filepath.ToSlash(issueConfig)}) } @@ -170,7 +173,7 @@ func ResolveWithOptions(opts ResolveOptions) (Plan, error) { case hasLegacyConfig: plan.Source.Kind = SourceLegacyOpenSpec plan.Source.ConfigPath = filepath.ToSlash(legacyConfig) - cfg, err := readConfig(legacyConfig) + cfg, err := readConfig(legacyConfig, nil) if err != nil { return withError(plan, Diagnostic{Severity: "error", Code: "invalid_config", Message: err.Error(), Path: filepath.ToSlash(legacyConfig)}) } @@ -326,10 +329,13 @@ func withError(plan Plan, diagnostic Diagnostic) (Plan, error) { return plan, errors.New(diagnostic.Message) } -func readConfig(path string) (Config, error) { - data, err := os.ReadFile(path) - if err != nil { - return Config{}, err +func readConfig(path string, data []byte) (Config, error) { + if data == nil { + var err error + data, err = os.ReadFile(path) + if err != nil { + return Config{}, err + } } var cfg Config if err := yaml.Unmarshal(data, &cfg); err != nil { diff --git a/issue-spec/specs/workflow-configuration-and-templates/spec.md b/issue-spec/specs/workflow-configuration-and-templates/spec.md index 3b8016a5..f8cc8f55 100644 --- a/issue-spec/specs/workflow-configuration-and-templates/spec.md +++ b/issue-spec/specs/workflow-configuration-and-templates/spec.md @@ -122,6 +122,13 @@ Source SPEC comments: Init MUST generate Skills and workflow guidance from the selected built-in or project workflow, MUST expose provider capabilities only for requested operations, and MUST produce a usable implementation-to-human-handoff path without classifying a repository as planning-only or disabling Runner dispatch because automatic merge is unavailable. When init applies a non-English workflow language, the generated guidance MUST keep the English `Proposal:`, `Design:`, and `Implement:` stage prefixes while using the selected language for each staged title subject and every ordinary issue title, MUST require an explicit `--title` for staged issues instead of relying on title derivation, and MUST keep canonical structural tokens in English. +GitHub init MUST validate the effective workflow and check generated-file conflicts before saving the Issue binding, changing the workflow language config, or ensuring repository labels. Preflight uses the proposed language config when requested. Explicit `--tools none` skips workflow generation and its preflight. + +#### Scenario: GitHub default init encounters an invalid project workflow + +- **WHEN** ordinary init selects skills delivery in a checkout with an invalid workflow configuration +- **THEN** init fails before changing the existing Issue binding or making a label write + #### Scenario: non-merging provider receives complete handoff guidance - **WHEN** init selects a provider with change creation and ordinary discussion but no conditional merge @@ -277,7 +284,7 @@ Shared skills MUST reference the selected config for context, rules and general ### Requirement: workflow updates protect local ownership -`workflow update --dry-run` MUST report planned file changes and conflicts without modifying repository files or remote state. Default delivery MUST be skills. Canonical skills live under `.agents/skills`; Claude links each selected generated skill using a checkout-relative directory symlink. The updater MUST preserve unrelated files, skills and host-specific exposure. An old whole-directory link MAY migrate to individual links preserving its existing exposure. A release manifest records managed file hashes; modified or untracked collisions MUST block all generated-file writes. Unmodified retired managed files MAY be removed. A write failure MUST roll back replaced entries; repeated generation MUST produce no changes. Legacy command delivery remains explicit. +`workflow update --dry-run` MUST report planned file changes and conflicts without modifying repository files or remote state. Default delivery MUST be skills. With omitted tool selection, the ordinary skills delivery MUST detect repository tool directories and fall back to canonical `.agents/skills` for a fresh checkout. Claude links each selected generated skill using a checkout-relative directory symlink. The updater MUST preserve unrelated files, skills and host-specific exposure. An old whole-directory link MAY migrate to individual links preserving its existing exposure. A release manifest records managed file hashes; modified or untracked collisions MUST block all generated-file writes. Unmodified retired managed files MAY be removed. A write failure MUST roll back replaced entries; repeated generation MUST produce no changes. Legacy command delivery remains explicit. #### Scenario: a locally modified skill blocks an upgrade diff --git a/issue-spec/specs/workflow-feedback/spec.md b/issue-spec/specs/workflow-feedback/spec.md index 89a9e69d..87c50dfd 100644 --- a/issue-spec/specs/workflow-feedback/spec.md +++ b/issue-spec/specs/workflow-feedback/spec.md @@ -79,9 +79,21 @@ A denied or unsuccessful label operation MUST preserve the recorded evidence and - **WHEN** a repository maintainer has held the Issue or the Issue is closed - **THEN** automatic promotion is ineligible even when the confirmed threshold is met -### Requirement: project instructions select the optional feedback procedure +### Requirement: default skills expose feedback during ordinary project work -The generated workflow MUST include a feedback reference for authorized tasks after ordinary initialization. Projects MAY refine triggering conditions, destinations and authorization through `guidance.shared`. The procedure MUST use existing open and closed discussion search and ordinary Issues and comments. The project can use the feedback procedure during relevant authorized work and report adoption and verification with the original Issue. Workflow update preview MUST retain its read-only behavior and project-owned instructions. +The default skills delivery MUST include a standalone `issue-spec-feedback` entry so that applicable feedback is discoverable during ordinary project work. A reproducible problem with any repository skill's instructions, references, or scripts can be a feedback source. The standalone skill and generated workflow MUST reference the same guide. Projects MAY refine triggering conditions, destinations and authorization through `guidance.shared`. The procedure MUST use existing open and closed discussion search and ordinary Issues and comments. The project can use the feedback procedure during relevant authorized work and report adoption and verification with the original Issue. Workflow update preview MUST retain its read-only behavior and project-owned instructions. + +The shared guide MUST identify the project's Issue repository and profile from its init binding or an explicit task target. It MUST load shared guidance from the selected workflow configuration, including compatible OpenSpec, and use the verified destination profile and repository explicitly for feedback search, preview, writes, and retries. The Issue target is independent of the source code remote. + +#### Scenario: project skill feedback after default initialization + +- **WHEN** a repository runs ordinary init and authorized use of a project skill exposes a reproducible problem +- **THEN** the generated standalone feedback skill leads to the shared guide for routing, recording, and deduplicating the evidence + +#### Scenario: the active profile differs from the project's feedback destination + +- **WHEN** the project's GitHub or self-hosted Issue target and the active profile have the same repository name and Issue number +- **THEN** the shared feedback procedure previews and records against the verified destination profile ## Implementation references