docs: clarify agent startup and product issue/note guidance (ST-051) #172

Merged

janpeter merged 4 commits from docs/agent-guide-startflow into main

2026-09-30 14:01:22 +02:00

janpeter commented

2026-09-30 13:28:25 +02:00

Owner

The shared guide also explains how to find and manage product issues and private notes using the existing tools, with correct product IDs, issue author fields and closure codes. It preserves the distinction between private notes, shared ProductDocs, task plans and progress logs, and adds no unconditional startup queries.

The change is limited to instructions, tool descriptions, existing job prompts and one test label; handlers and input schemas are unchanged.

Validation: TypeScript and test typechecking pass, 77 tests across eight relevant files pass, and the stdio canary on 83110eca7e90af08dbd55c9153c2b176151d5359 passes with 86 tools. Independent mac:claude source review and delta review are GO. Fresh Claude/Codex client behavior will be checked after the approved Mac stable activation; text tests do not prove that behavior.

Work item: ST-051 / T-155, sprint S-2026-09-29-1. The repository's candidate CI and final merge attestation remain required. Use a merge commit because the final release workflow requires two parents.

Plan and verification context for review:

Approved plan 0.5: ProductDoc cmumzb09o003dda1736ue54hl, revision cmuo0i1su00f4da176fsq0b2c, SHA-256 80c0e0923f8df64b3afed527d0249f447e0108497e43584b79553f8cd5b4441b. MCP URI: scrum4me-doc://product/cmopqt0yj000004jp7lr7mn8e/plans/agent-guide-startinstructies-uitvoering. Product cmopqt0yj000004jp7lr7mn8e; task cmun0vl5n0063da17zrstrzgf.
The approved plan explicitly retains the existing behavior checks and later fresh-client probes, rather than adding tests that copy the new instruction wording. __tests__/lib/agent-guide.test.ts already verifies runtime-only resolution without a model lookup. Actual agent fallback, delegation and job-scope behavior remain explicit client-proof requirements; substring assertions would not establish them.
Candidate CI run 239 succeeded on this exact head: 266 dispatch integration tests passed; the regular suite reports 2016 passed and 61 skipped; source/test typechecks, stdio canary and package verification succeeded. The final merge attestation job is correctly skipped for the PR event and must still run after merge.
The automated review checkout's noexec/esbuild EACCES prevented verification in that environment. It is not evidence of a source failure and does not negate the local or head-bound CI results above.

Main sessions and claimed jobs previously had inconsistent instructions for obtaining and applying the agent guide. This change makes runtime/model identity, single-call fallback, subagent context and compaction recovery explicit while retaining the user's or runner's main model and existing job boundaries. The complete guide remains binding for jobs. The shared guide also explains how to find and manage product issues and private notes using the existing tools, with correct product IDs, issue author fields and closure codes. It preserves the distinction between private notes, shared ProductDocs, task plans and progress logs, and adds no unconditional startup queries. The change is limited to instructions, tool descriptions, existing job prompts and one test label; handlers and input schemas are unchanged. Validation: TypeScript and test typechecking pass, 77 tests across eight relevant files pass, and the stdio canary on `83110eca7e90af08dbd55c9153c2b176151d5359` passes with 86 tools. Independent mac:claude source review and delta review are GO. Fresh Claude/Codex client behavior will be checked after the approved Mac stable activation; text tests do not prove that behavior. Work item: ST-051 / T-155, sprint S-2026-09-29-1. The repository's candidate CI and final merge attestation remain required. Use a merge commit because the final release workflow requires two parents. Plan and verification context for review: - Approved plan 0.5: ProductDoc `cmumzb09o003dda1736ue54hl`, revision `cmuo0i1su00f4da176fsq0b2c`, SHA-256 `80c0e0923f8df64b3afed527d0249f447e0108497e43584b79553f8cd5b4441b`. MCP URI: `scrum4me-doc://product/cmopqt0yj000004jp7lr7mn8e/plans/agent-guide-startinstructies-uitvoering`. Product `cmopqt0yj000004jp7lr7mn8e`; task `cmun0vl5n0063da17zrstrzgf`. - The approved plan explicitly retains the existing behavior checks and later fresh-client probes, rather than adding tests that copy the new instruction wording. `__tests__/lib/agent-guide.test.ts` already verifies runtime-only resolution without a model lookup. Actual agent fallback, delegation and job-scope behavior remain explicit client-proof requirements; substring assertions would not establish them. - [Candidate CI run 239](https://git.jp-visser.nl/janpeter/scrum4me-mcp/actions/runs/239/jobs/0) succeeded on this exact head: 266 dispatch integration tests passed; the regular suite reports 2016 passed and 61 skipped; source/test typechecks, stdio canary and package verification succeeded. The final merge attestation job is correctly skipped for the PR event and must still run after merge. - The automated review checkout's `noexec`/esbuild `EACCES` prevented verification in that environment. It is not evidence of a source failure and does not negate the local or head-bound CI results above.

janpeter added 4 commits

2026-09-30 13:28:25 +02:00

docs: clarify agent guide startup and job boundaries (ST-051) d13c1f6e67

docs: keep the entire agent guide binding in job prompts (ST-051) a0c5fc33aa

docs: explain product issues and notes in the shared agent guide (ST-051) 8cbe2658fa

docs: clarify issue product lookup and author fields (ST-051)

CI / Final merge attestation and immutable publication (pull_request) Has been skipped

Details

CI / PR candidate (never published) (pull_request) Successful in 5m9s

Details

83110eca7e

s4m-codex-reviewer reviewed

2026-09-30 13:32:45 +02:00

s4m-codex-reviewer left a comment

Verdict: COMMENT

MINOR — tests/instructions.test.ts:5: de aangepaste gedeelde bootstraptekst wordt alleen op aanwezigheid van get_context en get_agent_guide getest. De regressies die deze PR introduceert (runtime zonder model-ID, geen tweede fallback bij een aanwezige guide, behoud van job/subagent-scope en de Issues/Notes-verwijzing) blijven daardoor ongedekt. Voeg gerichte assertions toe op deze essentiële contractregels, zonder de volledige tekst te dupliceren.
INFO — verificatie: git diff --check is schoon. npm test -- --run en npm run typecheck konden in deze reviewomgeving niet worden uitgevoerd: de tijdelijke checkout is op een noexec-mount geplaatst en de esbuild-installatie faalde met EACCES. Dit is geen vastgestelde bronfout, maar laat lokaal/CI-testbewijs voor deze head ontbreken.

Geen gekoppeld plan gevonden — beoordeeld op codekwaliteit + product-standaarden.

## Verdict: COMMENT - **MINOR — __tests__/instructions.test.ts:5:** de aangepaste gedeelde bootstraptekst wordt alleen op aanwezigheid van `get_context` en `get_agent_guide` getest. De regressies die deze PR introduceert (runtime zonder model-ID, geen tweede fallback bij een aanwezige guide, behoud van job/subagent-scope en de Issues/Notes-verwijzing) blijven daardoor ongedekt. Voeg gerichte assertions toe op deze essentiële contractregels, zonder de volledige tekst te dupliceren. - **INFO — verificatie:** `git diff --check` is schoon. `npm test -- --run` en `npm run typecheck` konden in deze reviewomgeving niet worden uitgevoerd: de tijdelijke checkout is op een `noexec`-mount geplaatst en de esbuild-installatie faalde met `EACCES`. Dit is geen vastgestelde bronfout, maar laat lokaal/CI-testbewijs voor deze head ontbreken. Geen gekoppeld plan gevonden — beoordeeld op codekwaliteit + product-standaarden.

janpeter merged commit 9560875fcd into main

2026-09-30 14:01:22 +02:00

janpeter referenced this pull request from a commit

2026-09-30 14:01:24 +02:00

Merge pull request 'docs: clarify agent startup and product issue/note guidance (ST-051)' (#172) from docs/agent-guide-startflow into main

janpeter referenced this pull request

2026-09-30 14:26:51 +02:00

test: align canary test timeout with subprocess deadline #173