Skip to content

🤖 feat(workflows): evaluate() authoring docs and GitHub issue screening example - #4333

Open
ThomasK33 wants to merge 7 commits into
thomask33/eval-l5-typesafe-providerfrom
thomask33/eval-l6-screening-docs
Open

ThomasK33 wants to merge 7 commits into
thomask33/eval-l5-typesafe-providerfrom
thomask33/eval-l6-screening-docs

Conversation

@ThomasK33

@ThomasK33 ThomasK33 commented Sep 22, 2026

Copy link
Copy Markdown
Member

Summary

Sixth and last layer of the workflow evaluate() primitive (stacked on #4332): authoring documentation for evaluate() in the built-in workflow-authoring skill and a runnable GitHub-issue screening example shipped as a skill asset (skill://workflow-authoring/screen-github-issue.js), exercised end to end through WorkflowService with fake evaluation and agent adapters.

Background

Plan layers: L2a #4321 → L2b #4322 → L3a #4324 → L3b #4329 (runner + CLI) → L4 #4330 (timeline rendering) → L5 #4332 (TypeSafe provider) → L6 (this PR). Docs live inline in the skill Markdown (no free-floating docs), and builtInSkillContent.generated.ts is regenerated from it.

Implementation

  • workflow-authoring.md gains an evaluate(state, options) section: signature and accepted state types (string / JSON array / JSON object), question/answer shapes and bounds, the canonical-JSON state digest, model precedence (per-call model--evaluation-model → persisted evaluationDefaults.model; the Settings card for that default is a separate PR), supported direct routes, the explicit replay key (id + state, questions, model, providerOptions; not title/timeoutMs), attempt semantics including retry_from_checkpoint eligibility for admitted failures, failure vs. interruption (fixed-template error text), the sequential-only rule, and what is not guaranteed. evaluate() is described as tool-free classification, not a sanitizer or security boundary.
  • screen-github-issue.js: a screening workflow with flat args (repo, issueNumber, title, body). One tool-free evaluate() call answers injection, kind and severity (impact scale valid for every kind). not_detected returns the evaluator's triage answers and starts no agent — issue text is never placed in an agent prompt, not even after a false-negative screen (built-in Explore keeps bash/web_fetch). This is prompt isolation, not read isolation: the labeling agent keeps its tools, and "do not read the issue" stays guidance. suspected/uncertain hand only { repo, issueNumber, label, reasonCode, stateSha256 } to an exec agent that applies the needs-human-review label and reports { labeled, detail? } through a schema; the run fails when the label was not applied. The runnable command passes --evaluation-model (for evaluate()) and --model (for the labeling agent) and creates the needs-human-review label once per repository (--add-label does not create labels).
  • evaluateScreening.test.ts (7): runs the example via WorkflowService with fake evaluation and agent adapters — not_detected with a sentinel-bearing body starts no agent task and echoes only triage + digest; suspected/uncertain route to the labeling agent with identifiers and digest only (never the text) and a labeled schema; a labeling agent reporting labeled: false fails the run (no result event, fixed-template error without body bytes); an evaluator failure fails the run before any agent step; resuming after an interrupt in the labeling step replays the evaluation without re-dispatching; a malformed repo is rejected before evaluating.

Validation

  • evaluateScreening.test.ts 7/7 (labeling-failure case red against the previous example); agentSkills suites green after regeneration; make static-check green (includes docs link check).

Follow-ups (non-blocking review findings deferred at the round budget)

  • Label setup line: create needs-human-review only when absent (or pin --color) so a re-run of the advertised gh label create --force cannot recolor an existing label.
  • Docs: describe score answers as a continuous value in [0, levels − 1] (probability-weighted mean when a distribution is returned; an integer only when the provider selects an exact level) and warn against indexing/switching on it.

Risks

  • Docs + a skill asset + tests; no runtime code changes.
  • The example's not_detected branch is intentionally agent-free (data-flow restriction, not host-enforced tool isolation); a host-enforced GitHub label action does not exist and is not claimed.

Generated with xum • Model: coder:anthropic/claude-fable-5-1 • Thinking: xhigh • Cost: $537.54

@ThomasK33
ThomasK33 added this pull request to stack #4326 September 22, 2026 14:55
@chatgpt-codex-connector

This comment has been minimized.

@ThomasK33
ThomasK33 force-pushed the thomask33/eval-l6-screening-docs branch from ae0edda to 6bda6f0 Compare September 22, 2026 15:04

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ae0eddaeee

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/node/builtinSkills/workflow-authoring/screen-github-issue.js Outdated
Comment thread src/node/builtinSkills/workflow-authoring.md Outdated
Comment thread src/node/builtinSkills/workflow-authoring.md Outdated
Comment thread src/node/builtinSkills/workflow-authoring.md Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛡️ Codex Security Review · Automatically triggered

Here are some automated security review suggestions for this pull request.

Reviewed commit: ae0eddaeee

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

Comment thread src/node/builtinSkills/workflow-authoring/screen-github-issue.js Outdated
ThomasK33 added a commit that referenced this pull request Sep 22, 2026
…te() docs match the contract

Codex round 1 on #4333:
- screen-github-issue.js: the labeling agent reports through a schema
  ({ labeled, detail? }); when the label was not applied the run fails with a
  fixed-template error instead of claiming success. Test covers the schema on
  the spec and the failure path (red against the previous example).
- workflow-authoring.md: state accepts string | JSON array | JSON object;
  failed admitted attempts are retryable from checkpoint (pre-admission first
  attempts are not); the runnable command passes --evaluation-model.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8379b672e3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/node/builtinSkills/workflow-authoring.md Outdated
Comment thread src/node/builtinSkills/workflow-authoring.md Outdated
ThomasK33 added a commit that referenced this pull request Sep 22, 2026
…capable agent

Codex security review on #4333: the not_detected branch put the issue title
and body into an Explore agent prompt, and Explore keeps bash and web_fetch,
so a false-negative screen would have exposed a tool-capable agent to the
injected text.

- screen-github-issue.js: one tool-free evaluate() call answers injection,
  kind and severity; not_detected returns the evaluator's triage answers and
  starts no agent. The labeling agent still receives identifiers, the fixed
  label, the enumerated decision and the digest only.
- workflow-authoring.md: evaluate() is tool-free classification, not a
  sanitizer or security boundary; the "not guaranteed" bullet names the tool
  grant and states this is a data-flow restriction, not host-enforced isolation.
- evaluateScreening.test.ts: not_detected with a sentinel-bearing body starts
  no agent task; triage comes from the fake evaluator's answers.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
ThomasK33 added a commit that referenced this pull request Sep 22, 2026
…canonical-JSON state digest

Codex round 2 on #4333 (docs accuracy):
- Replay key = id + canonical JSON of state, questions, per-call model and
  providerOptions; title and timeoutMs are excluded (a retried step keeps the
  timeout it was admitted with).
- state.sha256 / state.bytes digest the canonical JSON of state (sorted keys,
  JSON quoting/escaping), not the raw ingested text.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a66c1ae174

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/node/builtinSkills/workflow-authoring/screen-github-issue.js Outdated
Comment thread src/node/builtinSkills/workflow-authoring/screen-github-issue.js
ThomasK33 added a commit that referenced this pull request Sep 22, 2026
…endent severity

Codex round 3 on #4333 (example accuracy):
- stateSha256 comment names the canonical JSON of the screened state, not raw
  title/body bytes.
- The severity question measures user impact for every issue kind instead of a
  bug-only scale that was still published for feature/question/other.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f0ca0c67c1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/node/builtinSkills/workflow-authoring.md Outdated
ThomasK33 added a commit that referenced this pull request Sep 22, 2026
… model too

Codex round 4 on #4333: --evaluation-model configures only evaluate(); the
labeling agent() inherited the CLI default model, so the advertised command
could not label on an OpenAI-only setup. The command now also passes
--model openai:gpt-5-mini and the docs say what each flag covers.
builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
@ThomasK33

Copy link
Copy Markdown
Member Author

@codex review

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 82b01a8ecf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/node/builtinSkills/workflow-authoring/screen-github-issue.js
Comment thread src/node/builtinSkills/workflow-authoring/screen-github-issue.js Outdated
@chatgpt-codex-connector

Copy link
Copy Markdown

🛡️ Codex Security Review · Automatically triggered

Security review completed. No security issues were found in this pull request.

Reviewed commit: 82b01a8ecf

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

  • You comment "@codex security review"
  • A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.

ThomasK33 added a commit that referenced this pull request Sep 22, 2026
…requires the review label

Codex round 5 on #4333:
- Header comment no longer claims that no agent reads the issue text; it says
  the text is never placed in an agent prompt and that the labeling agent keeps
  its tools ("do not read the issue" stays guidance).
- The needs-human-review label must exist (--add-label does not create it):
  runnable instructions in docs and header add a one-time gh label create,
  and the constant is annotated.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c43599c2a1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread src/node/builtinSkills/workflow-authoring.md
Comment thread src/node/builtinSkills/workflow-authoring.md
@ThomasK33

Copy link
Copy Markdown
Member Author

Review-loop status (round budget reached) — paused for maintainer direction on one gate artifact.

  • Head c43599c2a: Codex code review and security review completed; all review threads replied to and resolved (rounds 1–5 fixed in-PR, the two round-6 non-blocking doc findings are recorded under Follow-ups in the description with their intended fixes). Codex's 👍 was given on 82b01a8ec; the two later commits are one-line doc/comment corrections.
  • CI: every check is green after re-running one pre-existing, untouched WorkflowRunner test that failed once and passes locally (resumes started legacy agent steps that omitted outputSchema), except Codex CommentsRequired.
  • Why Codex Comments is red: Codex's review-summary board still lists the resolved P1 security advisory (discussion_r4073224584, fixed in a917a368d, thread resolved) under Advisory findings without the · **Resolved** marker that scripts/check_codex_comments.sh requires, even after four later security-review completions (three automatic, one explicit @codex review). I have not minimized the board. Options: wait for Codex to mark the advisory resolved and re-run the job, or accept the artifact for this PR.

Stack: #4330 and #4332 are review-clean with green CI; #4329 remains on the hold described in its pause comment (its round-2 exact-head UAT evidence is posted there).

@chatgpt-codex-connector

This comment has been minimized.

@ThomasK33

Copy link
Copy Markdown
Member Author

Also minimized (RESOLVED) the Codex task-summary comment posted at 17:59Z — it is the output of the checker-fix task (ba41b6e, "honor resolved Codex advisory threads"), not a review finding, and the gate counted it as an unresolved Codex comment. Once that fix lands on main and the stack is rebased, neither minimization is needed.

…ng example

Document the evaluate() primitive in the workflow-authoring skill (signature,
question/answer shapes, model precedence, replay and attempt semantics,
failure vs interruption, the sequential-only rule and the not-guaranteed
list) and ship the screening example as a skill asset runnable via
skill://workflow-authoring/screen-github-issue.js, exercised through
WorkflowService with fake evaluation and agent adapters.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$378.37`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=378.37 -->
…te() docs match the contract

Codex round 1 on #4333:
- screen-github-issue.js: the labeling agent reports through a schema
  ({ labeled, detail? }); when the label was not applied the run fails with a
  fixed-template error instead of claiming success. Test covers the schema on
  the spec and the failure path (red against the previous example).
- workflow-authoring.md: state accepts string | JSON array | JSON object;
  failed admitted attempts are retryable from checkpoint (pre-admission first
  attempts are not); the runnable command passes --evaluation-model.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
…capable agent

Codex security review on #4333: the not_detected branch put the issue title
and body into an Explore agent prompt, and Explore keeps bash and web_fetch,
so a false-negative screen would have exposed a tool-capable agent to the
injected text.

- screen-github-issue.js: one tool-free evaluate() call answers injection,
  kind and severity; not_detected returns the evaluator's triage answers and
  starts no agent. The labeling agent still receives identifiers, the fixed
  label, the enumerated decision and the digest only.
- workflow-authoring.md: evaluate() is tool-free classification, not a
  sanitizer or security boundary; the "not guaranteed" bullet names the tool
  grant and states this is a data-flow restriction, not host-enforced isolation.
- evaluateScreening.test.ts: not_detected with a sentinel-bearing body starts
  no agent task; triage comes from the fake evaluator's answers.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
…canonical-JSON state digest

Codex round 2 on #4333 (docs accuracy):
- Replay key = id + canonical JSON of state, questions, per-call model and
  providerOptions; title and timeoutMs are excluded (a retried step keeps the
  timeout it was admitted with).
- state.sha256 / state.bytes digest the canonical JSON of state (sorted keys,
  JSON quoting/escaping), not the raw ingested text.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
…endent severity

Codex round 3 on #4333 (example accuracy):
- stateSha256 comment names the canonical JSON of the screened state, not raw
  title/body bytes.
- The severity question measures user impact for every issue kind instead of a
  bug-only scale that was still published for feature/question/other.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
… model too

Codex round 4 on #4333: --evaluation-model configures only evaluate(); the
labeling agent() inherited the CLI default model, so the advertised command
could not label on an OpenAI-only setup. The command now also passes
--model openai:gpt-5-mini and the docs say what each flag covers.
builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
…requires the review label

Codex round 5 on #4333:
- Header comment no longer claims that no agent reads the issue text; it says
  the text is never placed in an agent prompt and that the labeling agent keeps
  its tools ("do not read the issue" stays guidance).
- The needs-human-review label must exist (--add-label does not create it):
  runnable instructions in docs and header add a one-time gh label create,
  and the constant is annotated.
- builtInSkillContent.generated.ts regenerated.

---

_Generated with `xum` • Model: `coder:anthropic/claude-fable-5-1` • Thinking: `xhigh` • Cost: `$537.54`_

<!-- mux-attribution: model=coder:anthropic/claude-fable-5-1 thinking=xhigh costs=537.54 -->
@ThomasK33
ThomasK33 force-pushed the thomask33/eval-l6-screening-docs branch from c43599c to acba885 Compare September 22, 2026 20:02

This branch has not been deployed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant