Change sync instruction

Interactive submission

scripts/ci.sh (also accepting --interactive) starts this interactive workflow. It also reads repeated stig.ci.consumer entries from this checkout's local Git configuration. For example, git config --local --add stig.ci.consumer /path/to/stig-product adds a private consumer to future ci.sh runs; --consumer can still supply additional checkouts for one run. Keep these paths local rather than adding private project names to the public script.

This mode uses the PhASAR sibling beside the canonical STIG checkout containing the script. It needs no saved repository-role configuration. After PhASAR and STIG, it offers each supplied --consumer, followed by the public stig-project template and stig-robot example. Private consumer names belong in the invocation or local Git configuration, outside the public script. Until stig-robot is initialized, decline it or leave its checkout path blank. Explicit consumer paths are used directly. For each consumer named without a path, it checks only the named siblings of the invocation checkout, the script's logical checkout path, and the canonical STIG checkout. A missing or ambiguous checkout requires an explicit path; blank skips it. Canonical paths are deduplicated. Each consumer uses its configured STIG source; published consumers need no sibling checkout. To use the private sibling layout, invoke the script from that consumer, for example ../stig/scripts/submit.sh --interactive --consumer stig-product from stig-product. It guides the following sequence:

1. Fetch the configured upstreams and display PhASAR's Git status, including staged, unstaged, untracked, and unpushed changes. List new files and offer A to add all remaining listed files, or y/n for individual files. Then ask before staging tracked edits/deletions, creating a commit, pulling with rebase, and pushing, in that order. The commit summary is entered at the terminal.

2. Display STIG's status and ask about its new files. If it has changes, offer a preparation commit without a release marker, then ask to pull with rebase. A clean checkout still pulls. Declining a needed preparation commit or the pull stops STIG processing before dependency updates, cleanup, and verification.

3. Run scripts/update-phasar-pin.sh even when PhASAR had no changes. The updater requires a clean PhASAR checkout whose HEAD matches the published stig-patches-2026.06 tip; refusing a needed PhASAR commit or push can therefore prevent pin synchronization.

4. Ask whether to run scripts/update.sh --major, --minor, or --patch, or skip dependency updates (default). This source-maintainer updater is separate from the consumer stigUpdate task and from the STIG release choice. Its existing prompts and output remain interactive. It can also update the public template's wrapper and dependency-verification files; the final stig-project prompt lets you submit those changes.

5. Offer ./gradlew cleanup. Display its normal output directly, without adding Gradle flags or redirecting it to a command log. Cleanup also regenerates third-party notices. Independently of that choice, refresh notices with ./gradlew generateThirdPartyNotices --console=plain --info after updating dependency pins on the rebased sources, then run ./gradlew :stig-gradle-plugin:syncJavaBootstrap --console=plain --info. The checked-in bootstrap embeds those notices, so a native dependency pin change also requires this regeneration. Both steps run when cleanup is skipped. Refresh an existing Graphify graph after source changes, and ask about any new files produced by these steps.

6. Offer ./gradlew preReleaseCheck, defaulting to No, with the same normal output. On Linux, the script starts a private 1920×1080 Xvfb display for this gate, including on Wayland and headless hosts. Install xvfb-run, Xvfb, and Xauthority before running the gate; missing display support stops verification. No manual display wrapper is needed. A failed selected command stops the workflow with its exit code. Source changes during verification require another run.

7. Ask for major, minor, patch, or none (default). A release choice adds incrementMajor:, incrementMinor:, or incrementPatch: to the entered STIG commit summary. If pre-release verification was skipped, offer it now; a release marker requires a successful check of the current sources. An explicitly requested release can create an empty commit when needed. Existing unpushed release markers require a matching explicit release choice.

8. Show STIG's final status, ask again about any new files, and ask before staging, creating the final commit, and pushing. There is no second STIG pull/rebase after verification. The commit preview shows the staged diff summary and exact subject. Declining commit or push leaves the approved staging or local commit available for later use.

9. When patch, minor, or major was selected, end the local workflow after the STIG push. Publication CI dispatches the configured consumers' update jobs, which select the latest published STIG release, verify, commit, and push their updates. Leave local consumer edits untouched while those jobs run. Successful dispatch only means GitLab accepted the requests; check each consumer job's result before synchronizing its checkout. Local --consumer options and stig.ci.consumer entries do not register GitLab release triggers. A consumer absent from the protected STIG_USER_PROJECTS list receives no automatic update. After consumer CI succeeds, synchronize the desired checkouts before any local verification. A later interactive run with release choice none can perform the normal consumer verification and submission workflow. With release choice none, offer consumer verification → add/commit → pull with rebase → push for the requested consumers, stig-project, and stig-robot, separately, using their configured STIG source without updating it. Model consumers offer version (default) or html: ./gradlew stigPrintVersion --console=plain --info verifies that the build configuration loads and reports the selected STIG source and loaded plugin version; ./gradlew stigGenerateHtml --console=plain --info generates the report and can run native source analysis. Application consumers (stigUpdateProfile=application) report the configured stigToolchainVersion and offer tasks (default) or check instead. tasks runs ./gradlew tasks to load the build and list available tasks; check runs the explicit stigApplicationCheckTasks. Both use --console=plain --info. Neither choice runs stigUpdate. A failed selected verification stops before committing or pushing that consumer. After verification, refresh its existing Graphify graph and use the same new-file, staging, commit-summary, rebase, and push prompts. Declining a consumer leaves its checkout untouched.

Every approved pull uses git -c rebase.autoStash=false pull --rebase --no-autostash with the configured upstream, including for a clean checkout with no local commits. After the first successful rebase, offer latte setup-graphify in that checkout, defaulting to No. This applies to PhASAR, STIG, and every visited consumer. Setup uses the rebased files; its changes follow the usual new-file and commit prompts. Then offer another pull/rebase before continuing, without offering setup again. The sequence is preparation commit → pull/rebase → optional setup → setup commit → pull/rebase → remaining work and push. Both STIG pulls finish before dependency updates and verification. A successful setup supplies the graph refresh for that rebase, so unchanged sources do not trigger another AST refresh. A selected setup failure stops the workflow with its exit code. Use --graphify to run setup in every visited repository without answering the setup prompt, including with --default. Latte initializes a missing index, repairs an incomplete or broken local setup, or refreshes an existing index. The flag requires --interactive; it does not visit consumers deferred by a release choice. With the flag, preparation commits retain the existing graph and defer AST refresh until setup has run after the first pull, allowing Latte to repair a broken index before ordinary incremental refreshes resume. Remaining uncommitted changes skip pull and push; for STIG they also stop the workflow before cleanup and verification. If all conflicts are in the generated Graphify outputs, interactive mode automatically restores the upstream output set and continues the rebase. This covers graph.json, manifest.json, GRAPH_REPORT.md, graph.html, .graphify_labels.json, and .graphify_labels.json.sig under graphify-out/. All six outputs come from the original rebase target, including files that merged cleanly, so the manifest and graph remain consistent. A commit left empty by this resolution is skipped. Source conflicts, saved Graphify notes, and other conflicts stop for manual resolution without changing any conflicted files. The script never auto-stashes, aborts conflicts, or force-pushes.

Git hooks remain enabled. Rebase and its continuation use the Graphify hook guard, then an existing graph is refreshed if source content changed or upstream graph outputs were restored. Restoring outputs invalidates any earlier graph refresh, even when the source content is unchanged. Any resulting files require the usual add/commit choices before pushing. This automatic conflict handling applies only to interactive mode; numbered paths retain their existing failure and review workflow.

STIG's order is preparation commit when needed → pull/rebase → PhASAR pin and dependency updates → cleanup → notice, bootstrap, and graph refresh → preReleaseCheck → release choice and final commit → push. Cleanup and verification therefore use the rebased sources. Review and commit any pin, cleanup, or graph changes through the same prompts. If upstream advances again before pushing, Git rejects a non-fast-forward push; the script does not rebase after verification. Rerun the workflow to synchronize before checking again. Commands keep their normal terminal output, including both plain Gradle invocations. Git status, diff summaries, whitespace checks, and commit lists explicitly disable paging, so a configured pager such as less cannot pause the workflow for keyboard input, including with --default.

New-file prompts use [A/y/n/q]: Enter or a adds all remaining files from the displayed list in that checkout; y adds just the current file; n offers an exact local ignore rule in Git's info/exclude. The bulk choice uses literal paths from that list, excludes tracked edits and ignored files, and does not carry over to later lists or other repositories. A new file appearing after the list was displayed still requires a separate decision. Declining both add and ignore stops for a file decision. Tracked files use git add -u; partial staging is replaced by the full current contents only after the staging prompt is accepted.

If git diff --cached --check reports whitespace errors, offer a Git-only repair and retry. This fixes whitespace introduced by the staged changes, including extra blank lines at EOF and trailing spaces, without running the full cleanup task. Prepare the correction in a temporary index, validate it, then apply it to the working tree and staging area. Unchanged lines retain their existing whitespace. A successful repair refreshes Graphify and offers to repeat any previously selected preReleaseCheck; declining that renewed check stops before committing. Declining the repair, quitting, or ending input leaves the staged changes available for manual correction. Errors Git cannot repair, such as conflict markers, still stop the workflow.

Other yes/no confirmations use [Y/n/q], so Enter accepts staging, committing, pulling with rebase, pushing, required verification, or visiting a consumer. The latte setup-graphify prompt, ./gradlew cleanup, and the initial optional ./gradlew preReleaseCheck prompt use [y/N/q], with Enter declining them. Dependency-update and release-level menus retain their explicit choices and skip/none defaults. A displayed default takes effect when Enter is pressed; q quits and end-of-input stops without answering further prompts. With --interactive --default, the runner supplies every displayed default without reading terminal input: staging, new-file bulk addition, commits, rebase and push are accepted; commit messages use Update <repository>; dependency-tool updates are skipped; Graphify setup is declined unless --graphify is supplied; cleanup and optional pre-release verification are declined; the release choice is none; consumer verification is version for models or tasks for applications. Missing or ambiguous checkout paths default to skipping that consumer. An existing unpushed release marker that needs an explicit release choice stops this mode instead of selecting a release automatically. --default requires interactive mode; ci.sh forwards it to the same runner. Git hooks remain enabled; a completed Graphify refresh uses the documented hook guard for its commit.

Graphify output is enclosed by a labeled index-refresh start and finish. This is a one-time code-navigation index update, not a Git commit or compilation. AST extraction reports parsing progress; not classified identifies unsupported file formats; parser syntax errors warn that some symbols or relationships may be missing from the index. They are not compiler diagnostics. No code-graph topology changes means the extracted relationships stayed the same, so existing graph outputs were retained. The code-only refresh needs no API key; documentation/image processing tips describe separate optional work. Tool output, warnings, and failures remain visible unchanged. Commit previews explicitly label the proposed new subject, and push previews label existing local commits and their recorded subjects.

Interactive mode has optional local STIG checks and, without a release, optional consumer submissions with a version/HTML choice for models and tasks/check for applications. A selected STIG release hands consumer updates and verification to GitLab CI. It does not create numbered-path review checkpoints or Commit-Path trailers, run the numbered paths' consumer gates, or choose a release automatically. After Maven publication, GitLab release CI triggers the configured user projects' update pipelines; each project's CI controls its checks and publication. The regular Git push can still reject a concurrent upstream update after the rebase. It rejects combination with numbered-path, resume, configuration, or release command-line options. The numbered paths below keep their existing gates and review/resume behavior.

Configure numbered submissions

Configure the checkout roles once, using paths whose roles you have confirmed from their repository guidance:

These directory names are examples, not role detection. STIG is the checkout containing the script. Canonical paths are deduplicated, including when the template is also the requested product. The configured consumers must resolve their documented ../stig sibling to this STIG checkout; configured PhASAR must be the ../phasar checkout used by STIG. The runner does not rewrite Gradle configuration or change branches. If there is no local PhASAR sibling, use --no-phasar instead of --phasar. Template and product roles remain required.

Configuration is stored in stig-submit/config.json under STIG's resolved Git metadata directory, including for a Git worktree. Re-run --configure to change roles for future runs. Existing runs keep their saved configuration. The runtime prerequisites are Bash 4.4+, Git, jq, flock, and rg, plus the selected repositories' normal build tools and Graphify where required by their source-change rules. No toolchain fallback is introduced.

The final example uses STIG subject incrementMinor: Release summary. Sibling subjects use Release summary, without the marker. With a marker-only request, sibling subjects are Synchronize changes. Path 3 requires an explicit marker or --increment patch|minor|major; paths 0–2 reject release markers. A clean STIG tree can still receive the explicitly requested empty release-trigger commit, after verification. Resuming does not duplicate an already-prepared empty trigger. Path 0 defaults to Snapshot current state when no message is supplied.

Optional local CI toolchain checks

Paths 2–3 accept --local-container-checks on|off, defaulting to off for new runs. Routine submissions retain the full host and consumer verification gates without also rebuilding the Fedora CI image and repeating its jobs locally. GitLab image, build/test, compatibility, and release gates remain mandatory and unchanged.

Opt in when debugging toolchain/CI changes locally or when GitLab is unavailable:

With on, the runner executes ciToolchainImageBuild then ciToolchainCheck after cleanup review and before preReleaseCheck. The first builds/refreshes the current content-derived Fedora image locally without publishing; the second runs ciBuildAndTest in that image. Both must pass. Matching image layers can be reused, but changed pins may require expensive rebuilds. The disposable check workspace does not reuse the host's incremental outputs. An enabled container check fails normally if the runtime or image is unavailable; it does not silently skip.

This option controls only those two CI toolchain tasks. Host verification, consumer builds, documentation checks, and Qodana remain required, including containers used internally by documentation or Qodana. It does not make a submission offline: Git synchronization and uncached dependencies still require their usual access.

An AI agent must leave the default off unless the user explicitly asks for local CI container work, for example: "Path 3 submit, increment minor, with local container checks." Do not infer opt-in merely from changed CI files. Paths 0–1 and repository configuration reject this option.

Resume keeps the recorded mode. Older checkpoints without a mode retain their former on behavior. To change an unfinished run before STIG has been pushed, pass the option explicitly:

The checkpoint records the change and preserves completed results and failure logs. Disabled tasks are marked not required, never passed; any recorded failure still needs its cause/correction review. Enabling the mode adds the required gates without discarding valid host/consumer results. A mode change after STIG is pushed or the run is complete requires a new submission; an ordinary resume never changes the saved choice.

Invoking a path authorizes staging all tracked edits/deletions and including explicitly added new files in its configured repositories, committing, rebasing on each current branch's configured upstream, and pushing. The runner does not decide which untracked files to add or ignore, stash changes, resolve conflicts, force-push, or repair failures automatically. Detached HEADs, unfinished Git operations, dirty submodules, or a changed branch/upstream stop checked submissions. An invocation lock prevents two runners from using the same STIG checkout concurrently.

Review, failure, and resume

Checked paths save checkpoint.json, review.md, source/history patches, and complete command logs under stig-submit/runs/<run-id>/ in Git metadata. They print each command's log link; the log records the exact command, working directory, stdout, and stderr. Execution is quiet by default. These runtime files are not staged into the source repositories.

Paths 2–3 run generateThirdPartyNotices after PhASAR pin synchronization, then cleanup, review their mutations, and run preReleaseCheck and the consumer gates. Notice generation is a logged preparation step, not a replacement for verifyThirdPartyNotices inside preReleaseCheck. It also runs on pending resumes before STIG is pushed, using Gradle's normal up-to-date behavior, so a newly refreshed pin cannot leave stale committed notices. Paths 0–1 do not add this full-verification preparation. The optional local CI toolchain checks insert image preparation and container verification before preReleaseCheck; their failures use the same repair review and resume process as other gates.

When human or AI judgment is needed, the runner exits successfully with status 0 and emits a STIG_SUBMIT_EVENT JSON line with event: "review_required" (or "paused" for a continuation without a pending review). It also writes the same object to event.json beside the checkpoint and prints the review file and resume command. This process-completion event returns control to the caller; the runner does not wait or poll for AI approval. The caller should await process completion, not poll logs or repeatedly resume a running process. Host notification and update limits still apply; a shell event does not itself invoke an AI agent.

Exit 0 does not by itself mean submission complete. Check event: "complete" means the submission finished; "review_required" and "paused" require continuation. Real failures emit "failed" when a checked run exists and preserve the actual nonzero exit code. The event includes run_id, exit_code, checkpoint, the pending review path when applicable, and the last command log path. Review the evidence, make required source/documentation corrections, and record findings in review.md. Only on path 3, review/update the changelog and set Changelog: updated or Changelog: not-needed according to Changelog writing below. Paths 1–2 use Changelog: not-required and do not edit CHANGELOG.md. Approval is the exact line Decision: approved:

If source changed since that review was created, the first resume archives it and produces a fresh review snapshot; approve that snapshot and resume again. The file names the repository groups needing renewed review and links the retained findings for unchanged groups. New source-changing commits also renew history review, even when their final tree matches the earlier tree. Review approval also covers the saved history baseline: an older path-3 run that started at a path-2 commit is widened to the preceding release and reviewed again. This does not discard unchanged build results or let a release commit prepared by that run become its own review baseline. The runner never evaluates the review or checkpoint as shell code. Ask an AI to help edit/review the named files if useful; this first version does not call an AI service itself.

AI execution and additional builds

An instruction to submit on path 0, 1, 2, or 3 authorizes the AI to run scripts/submit.sh, inspect completed step results, review the evidence, repair failures within the requested scope, and continue to completion. Reuse the saved repository configuration and user decisions. The script owns command execution and checkpoints; do not reimplement its checked paths as a second agent-authored sequence.

The successful review_required exit is a review event for the person or AI doing the submission, not completion. An AI should carry out the required review, record concrete findings and Decision: approved when justified, and execute the printed resume command. It must not approve blindly or return to the user solely because the runner needs a review. After source edits, refresh the snapshot before approving it. A failed submission operation or gate requires focused diagnosis, correction, and renewed checks; record Cause: and Correction: and resume. Resolve routine repairs and clear rebase conflicts using the existing authorization. Ask the user only for a missing release marker, an ambiguous change, or a decision beyond that scope.

During commands the runner prints log links, keeping command details, stdout and stderr inside those complete logs. On failure it identifies the failed step and preserves its exit code without dumping a stack-trace tail. Use the terminal event, exit status, and log links printed by the runner. Wait for a command or step to finish before reading its results; do not tail logs repeatedly to produce status updates. Follow Submission execution for quiet waiting, bounded failure diagnostics, and retained gates.

A separate request to build a project such as stig-project authorizes that checkout's requested Gradle task and in-scope repairs, without a submission or changelog edit. Resolve the actual checkout, run the requested task, wait for completion, and check its exit status under the same execution policy. If a build is additionally requested as part of a submission, complete it before the affected push, retain its input state/result, and renew it only when those inputs change. Extra builds do not select another submission path or a release marker.

Every failed submission operation or verification gate stops the run with its actual exit code and a log link. Read bounded failure evidence from that log. A resume requires a repair review with Cause: and Correction: before retrying. Record focused evidence and any test/contract decisions in its findings; do not approve an unexplained retry. Rebase conflicts must be resolved explicitly outside the runner. An interrupted command whose recorded process is still alive is not restarted or killed by resume.

Gate inputs include effective source content, untracked non-ignored files, tag state, and configured local STIG and PhASAR dependency states. The user's index is not changed by fingerprinting. Source/dependency changes invalidate affected results; generated graphify-out/ changes alone do not invalidate Gradle gates. Cleanup records its resulting source state and pauses for mutation review. Rebased input changes require renewed evidence before push. Once STIG is pushed, that run freezes its STIG/PhASAR input revisions and can finish remaining consumers; further changes to those published inputs need a new run.

On checked paths 1–3, changed local PhASAR is verified through the existing pinned native build/test driver, with the configured checkout passed explicitly:

It must succeed before PhASAR is committed/pushed on those paths. The helper scripts/update-phasar-pin.sh then writes its clean, published commit ID before STIG gates. Path 0 also invokes that helper after the PhASAR push and again after rebasing STIG, committing any resulting pin correction before pushing STIG. The helper remains available as a standalone command; its clean-checkout and published-commit validation is shared by every path. Use --skip-phasar-pin only on a new checked run for an explicit opt-out; it is saved and reported. The runner prepares Graphify before checked commits and suppresses the redundant asynchronous Graphify post-commit hook without disabling the other checked-path hooks. Path 0 has no review or checkpoint and uses its file preflight, Git synchronization, and pin refresh without verification gates.

CI observation after checked submissions

After all repositories have been pushed on paths 1–3, the runner invokes gitlabCtrl --action ciStatus for the checkpoint's exact submitted STIG SHA, not a subsequently moving HEAD. This is an advisory snapshot, without waiting for pipeline completion. Path 0 performs Git synchronization and pin refresh without querying CI.

The observation saves its JSON and available failed-job traces in a fresh directory under the run's ci/ directory. The checkpoint's ci entry retains the commit, observed status/outcome, pipeline URL, actual command exit code, and report/log paths. A failed pipeline, missing pipeline, authentication error, or unavailable API is reported separately from successful pushes and local gates. An observation failure neither fails the completed submission nor invalidates passed gates, and no CI failure is silently presented as success.

Resume retains an already-recorded observation for that commit. If observation was interrupted before it was recorded, resume checks that its process is no longer running, then makes a fresh attempt without a repair-review pause. Each attempt uses a new output directory so an old report cannot be mistaken for fresh evidence. Resuming a completed run does not refresh CI or repeat submission commands.

To refresh the result or explicitly wait, run from STIG:

See Inspect CI for a submitted commit for status/log semantics, polling controls, and the structured report. These later commands produce fresh evidence without changing the completed submission checkpoint.

Reporting CI does not by itself authorize source fixes, job retries, pipeline triggers, or another push. Report the failure and evidence; repair and resubmit only when the user requests that work. Honor an existing explicit request to repair/resubmit without asking for routine approval again, and use a new checked submission for changed published revisions.

Template commit before HTML verification

Report tasks allow dirty source by default; paths 2–3 verify the template from a clean local commit. When it has intended changes:

1. Run its ./gradlew build.

2. Review the complete diff and run git diff --check.

3. Create its final local commit with Commit-Path: N.

4. Run ./gradlew stigGenerateHtml against that clean commit.

Keep the commit local until PhASAR, when applicable, and STIG have been pushed. A later template correction requires an amended or corrective local commit and renewal of the gates whose inputs changed.

Failures and renewed verification

Investigate every failed gate, fix its producing source, and rerun it plus each later gate invalidated by the fix. Fix mechanical conversion or migration errors directly. For a real or suspected bug, determine the root cause and implement a durable in-scope fix, with regression tests or contract checks when they provide meaningful evidence. Record any separate technical-debt work. Reuse decisions and authorization already given in the request or checkpoint; ask only when the correction needs a material choice outside that authorization. Finish the repair and required verification before declaring completion.

A passing unexplained retry is insufficient. Record the cause, correction, and renewed evidence. The execution guide defines how to retain valid results while marking affected gates stale.