[ajs-uk-dev]

Closes #711 (AB#301154).

What changes

A school on a 16-19 window can ask to include a student. Include_Post16.json turns the journey on: pick the student, give or skip PDF evidence and an explanation, review, submit, get a reference and the deadline for further amendments.

Who can be picked (AC9). Students in the non-included file, and students the included file carries with P_INCL 502 ("not included in performance measures"). Ingress now writes a second stamp, INCLUDABLE, beside INCLUDED: true when the record is not included, or when its code is one the schema's new x-ingress.includable rule names. Only students-included_schema.json carries the rule (502). KS4 and KS2 get !INCLUDED, so nothing changes for them. INCLUDED, the tabs, Remove and Merge are untouched: a 502 student is still included for those.

• PupilFilter: Includable and NotIncludable added, NonIncluded removed. The KS4 Include flow uses Includable and returns the same pupils as before.
• The Include journey's three "already included" guards look a name up among NotIncludable pupils, so a 502 student can never trip the guard against themselves.
• "Pupil not found" and "This pupil is already included" use the window's noun and offer "Start adding" only where the window type has an Add flow. 16-19 has none.
• The KS2 dev seed skips the new stamp (it builds CSV columns from the schema).
• An x-ingress.includable rule with no field, an undeclared field, no codes or a blank code fails the ingress run by name. So does a schema that declares INCLUDED but not INCLUDABLE, shipped or uploaded: it would otherwise offer nobody for inclusion.
• Rules: no change. Every 16-19 include goes to Scrutiny (INC-DEF); the Inclusion rules name KS4 codes only.
• Docs: question-flows, request-journey, domain-model, blob-storage, ks2-journeys, the 16-19 schema README, the functional overview's flow list, one AGENTS.md bullet.

Data note. A pupil file ingested before this change has no INCLUDABLE. This affects every key stage, not only 16-19. Until the exercise is validated again, the Include search finds nobody, and the "already included" check matches every typed name, so a school sees "This pupil is already included". The dev seed (SeedDevelopmentData, on in development and review only) validates each seeded window again at each start, so those windows restamp themselves. Every other exercise keeps its old files until an admin validates it again. The service is not live.

Not in this PR. The suggestion label still says INCLUDED for a 502 student (true by file) - a wording question for the BA. 16-19 auto-decision rules - a BA question.

After deploy

Do this in each environment after this change deploys to it:

• QA: validate each pupil-data exercise again (the window summary page, Validate Pupil data checking).
• Preprod: the same.
• Production: the same, if it has any pupil-data exercise.
• Development: the same for an exercise an admin made by hand. The seeded windows need nothing.

Security

Touches the journey's personal-data pages (the two decision pages) and file upload only through the existing EvidenceUpload page. No new endpoint, parameter or dependency. No new POST action. Nothing logged beyond the existing lookup-failure messages, which carry the window id only.

Journeys checked by hand

At 7fa5e85a (main merged after #745), in the local containers, as the dev editor (Kingsmead). The later merge of #698 changes sign-in and impersonation only, no file this PR changes:

• 16-19 Include, 502 student (Julia Smith): offered in the search, evidence, summary, submit. Reference CYPMD_16to19_CA80BE9; the rules engine decided Scrutiny, INC-DEF.
• 16-19 Include, 501 student (Alice Smith): not offered; typed, it gives "This student is already included" with Abort only.
• 16-19 Include, unknown name: "Student not found" with Search again only; Search again goes back to the search.
• 16-19 What to change: Merge, Include, Remove.
• KS4 June Include: the search offers only NOT INCLUDED pupils; a pick reaches the evidence page; an unknown name gives "Pupil not found" with Start adding and Search again.

Checks

All at the head commit, 74af814b (main merged after #698):

• Build 0 errors; unit 7,744 passed, 0 failed; integration 1,144 passed, 0 failed (CI build job)
• Review app: smoke set green, ZAP baseline green, whole-suite E2E 381 passed, 0 failed, 4 skipped
• scripts/check-pins.sh, scripts/check-playwright-pin.sh

[github-actions]

Review app for PR 721 was deleted

[github-actions]

E2E tests passed

381 passed, 0 failed, 4 skipped in 18 min 16 s

Commit 74af814 against https://check-performance-data-pr-721.test.teacherservices.cloud (run)

[dfe-lance]

LGTM

[dfe-lance]

LGTM

[ajs-uk-dev]

Response to the review (suggestions 1-6):

1. Data note. Confirmed. On a pupil file written before INCLUDABLE, IsIncludable reads false on every key stage, so the Includable search finds nobody and the NotIncludable guard matches every typed name ("This pupil is already included"). The PR's data note now says this and asks for a re-validation of each pupil-data exercise in any environment whose blob storage keeps pupil files across deploys. docs/blob-storage.md says the same. I have not added a fallback that reads a missing stamp as !INCLUDED, because AGENTS.md says not to write fallbacks for data written before a change while the service is not live.

2 and 3. Stamp coupling. All five schemas that declare INCLUDED already declare INCLUDABLE. But schemas can also be uploaded from the admin screen, and a test that walks Data/Ingress would not catch an uploaded one. So the check is in ingress itself (748e7d9): a schema that declares INCLUDED but not INCLUDABLE fails the run by name before any row is read, the same way a broken x-ingress.includable rule does. The old test that allowed the omission is now A_schema_declaring_INCLUDED_but_not_INCLUDABLE_fails_the_run_by_name, and the inline test schemas declare both. The shipped-schema test was missing ks2/pupils-december_schema.json; it covers it now.

4. Trimmed codes. Already pinned: The_schemas_includable_rule_stamps_INCLUDABLE_from_the_code_or_from_not_included has a " 502 " case (CsvSchemaFileProcessorTests.cs). 0502 and 502.0 are not normalised, so the includable rule compares codes exactly as the existing inclusion rule does.

5. Checks at head. At 748e7d9: unit 7,775 passed, 0 failed; integration 1,126 passed, 0 failed (CI build job); review-app whole-suite E2E 381 passed, 0 failed, 4 skipped; smoke set and ZAP baseline green. The PR's Checks list is updated.

6. 16 to 19 - Include journey AB#301154 #711 in comments. No change. Each reference also states the reason, so the comment still reads if the number goes away, and none of them reads as a plan or phase. Ticket references in comments are already common in src (about 345 on main, for example EnquiryQuestionIds cites Results Enquiry - Recent Enquiries - Show grade information #712).