diff --git a/AGENTS.md b/AGENTS.md index 923ac9f..b01f13d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,38 +19,74 @@ Do not rely on previous conversation memory. Before making significant changes: 1. Read this `AGENTS.md`. -2. Read `PROJECT_PROGRESS.md`, and the PR record document and - PR description of any open PR you are continuing. +2. Inspect the headings in `PROJECT_PROGRESS.md`, then read the latest + dated Q4 closeout and the sections relevant to this task. Read the + record document and live description of any PR you are continuing. 3. Understand the relevant existing code, architecture, tests, and conventions. -4. Review the current Git branch and working tree. +4. Review the current Git branch and working tree; preserve existing local changes. 5. Continue from the documented current state. Prefer small, safe, targeted changes consistent with existing conventions. Avoid unrelated refactoring unless it is required for the task. +## Repository operations and context + +- Validate fetch and push URLs before network operations; target only + `github.com/SAM-BIM/`. Use explicit SAM-BIM repository/API + targets; avoid automatic fork-parent discovery. Do not contact HoareLea + repositories or request their access/SAML authorization. +- Preserve historical attribution, legacy records and external integration + references; changes to integrations require a separate migration decision. +- Treat dated bootstrap/Q2/Q3 entries as historical evidence. Check Git and + live PR metadata before acting on old status/next-step text. Read earlier + evidence when the task depends on it; do not load whole histories by default. +- Section position is not a period marker: active-quarter closeouts may appear + beneath a historical heading. Scan all dated headings and classify each entry + by its date, PR and base branch, not by the heading it sits under. +- These instructions and `CLAUDE.md` belong on `sow/*` and their feature branches; + never promote internal agent files to `master`. + +## Quarter transition (owner-approved release work) + +Release, product promotion, quarter freeze and quarter bootstrap each need +explicit owner approval; none is implied by merging an ordinary PR. + +- Promote approved Q4 product changes through a reviewed release PR. A normal + merge includes internal files: prepare and verify the promotion tree excludes + `AGENTS.md`, `PROJECT_PROGRESS.md`, `CLAUDE.md` and the internal continuity + records (`documentation/Agent-Continuity-*-Q4.md`). + Classify other documentation separately; retain product documentation + selected for release. +- Complete known-SHA Q4 closeouts before freezing `sow/2026-Q4`. The release-promotion + PR's closeout belongs on the outgoing `sow/2026-Q4`, never on `master`, although + `master` is that PR's base. Preserve the frozen branch as the quarter's record: + no commits, rebase, rename, archive or deletion. +- Create `sow/2027-Q1` from the owner-approved promoted product baseline. Carry + forward useful shared instructions and the Claude import onto Q1 only; update + the active/frozen quarter references and carry unresolved work with evidence. +- Initialize a concise Q1 progress record only as an explicitly authorized + quarter-bootstrap operation, referencing the frozen Q4 commit for history. + This does not widen the ordinary post-merge-only progress-closeout exception. + These steps describe future release work; they are not authorized by this file. + ## Project continuity `PROJECT_PROGRESS.md` is updated only after a PR has merged. During implementation, keep status/evidence on the PR branch in the PR record document and PR description. After merge, fetch the base branch and add the closeout entry, including the merge SHA, as a -direct docs-only commit on the base branch. Do not modify unrelated -stream entries. +direct docs-only commit on the base branch (for a release-promotion +PR into `master`, on the outgoing `sow` branch instead). Do not modify +unrelated stream entries. The order of work is: code + tests + evidence → final PR CI → merge → `PROJECT_PROGRESS.md` closeout commit on the base branch. -Never change `PROJECT_PROGRESS.md` on a PR branch. - -The closeout is written only after the merge SHA is known, so it cannot be -part of the reviewed PR; putting it in the PR would force another review/CI -cycle merely for a progress-file update. Direct commits to `sow/2026-Q4` -are therefore allowed for this one case: the post-merge, docs-only -`PROJECT_PROGRESS.md` closeout. This exception does not cover code, tests, -workflows or any other file. All code changes still go through a feature -branch and a PR. +Never change `PROJECT_PROGRESS.md` on a PR branch. The sole direct-Q4 +exception is its post-merge docs-only closeout with a known merge SHA +and `[skip ci]`; other changes require a feature branch and owner-reviewed PR. Do not record trivial actions such as opening files, searching the repository, or reading documentation. @@ -70,6 +106,15 @@ the `PROJECT_PROGRESS.md` closeout entry must contain: - unresolved issues, risks, or blockers; - exact recommended next step. +Identify the PR, base branch and tested head SHA. Distinguish local results +from GitHub checks, including failures/skips, required dependency order and +remaining gaps. Give reproducible commands and committed evidence paths; label +machine-local evidence and prerequisites that must be copied or provisioned +elsewhere. Record the validated content SHA in the committed PR record. If a +record-only commit follows, keep that tested SHA and its commands in the record, +validate the final docs diff, and identify the final PR head/checks in the PR +description. The post-merge closeout records the immutable merge SHA. + When updating `PROJECT_PROGRESS.md`, preserve still-relevant information from previous sessions. Remove or replace information only when it is obsolete, resolved, or superseded. @@ -83,3 +128,50 @@ switching computers, accounts, sessions, or AI agents. Never assume conversation history, terminal history, generated files, or uncommitted local changes will exist on another computer. + +## Pull requests and merging + +- Implementation, tests, workflows and ordinary documentation changes go + through focused feature branches and owner-reviewed PRs into `sow/2026-Q4`. + Continue an existing PR for the task rather than opening a duplicate. +- Merge only after owner/code-owner approval, required checks passing at the + final PR head, and each review finding resolved or explicitly accepted by + the owner. +- Permission for the direct post-merge closeout does not authorize source, + test, workflow or any other file change. A specific owner exception must be + recorded explicitly and kept narrowly scoped. + +## Post-merge branch cleanup + +Once the owner authorizes a PR merge, cleaning up that task's fully merged +feature branches is included; no separate cleanup approval is needed. + +Before deleting a branch: + +- verify the remote head SHA is the expected (approved) head; +- verify it is completely merged into the intended base on the remote; +- confirm no unmerged local or remote work remains on it; +- confirm no open PR uses it as head or base; +- exclude protected, default, quarterly (`sow/*`), shared and specifically + protected repository branches. + +Delete an eligible remote task branch with a lease guard, for example +`git push origin --force-with-lease=refs/heads/: :refs/heads/`, +then confirm the ref is gone. Return the clean checkout to the active base +and delete the local task branch only when it is fully merged and no worktree +uses it. Never delete or archive worktrees automatically. If any condition +fails, preserve the branch and report why. Never force deletion of unmerged work. + +Dependency resolution: downstream CI may select a dependency branch by PR +branch name before falling back to `sow/2026-Q4`. Inspect that resolution. When +a merged task branch would shadow Q4, clean it up first, then rerun downstream +CI and verify in the logs that the intended merged dependency was selected. + +This covers only the current task's branches. Older unrelated leftovers need +a separate inventory and authorization. + +## Recommendations and handoffs + +When recommending a task or writing a prompt or handover, state the model, +effort, new or existing session and Plan or Build mode, with a brief reason. +A recommendation does not mean any setting was changed automatically. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..cbaeafb --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,4 @@ +@AGENTS.md + +Keep shared project instructions in AGENTS.md. Read task-specific progress +and PR evidence as directed there; do not import the full progress history. diff --git a/documentation/Agent-Continuity-Rollout-Q4.md b/documentation/Agent-Continuity-Rollout-Q4.md new file mode 100644 index 0000000..ae159d3 --- /dev/null +++ b/documentation/Agent-Continuity-Rollout-Q4.md @@ -0,0 +1,68 @@ +# Agent instructions rollout — Q4 (2026-10-12) + +Status: implemented on `docs/agent-instructions-rollout-q4`; owner review required. Not merged. +Kind: Rollout of the shared baseline. +Base: `sow/2026-Q4` at `c0dc4281d87991e2cfc39d7ab4acabe76207f483`. +PR: the live PR for this branch in `SAM-BIM/SAM_Systems` (its number is not committed here). +Tested content SHA: `45f180a73e3b7c4304cc80f34369fc65f27a0fa2` (changes only AGENTS.md, CLAUDE.md). +Final PR head and hosted check results: recorded in the live PR description. A record +cannot contain its own commit SHA, so this file is the only change after the tested SHA. +Baseline: SAM-BIM/SAM#191 (merge `02bbafb8`, closeout `46e96b72`) and SAM-BIM/SAM_OCCT#74 +(merge `3d0a4725`, closeout `c825a40`). + +## Scope + +Documentation only. No product code, build, workflow, dependency pin or tool changed. +`PROJECT_PROGRESS.md` is not changed on this branch; its closeout follows merge. + +## Changes + +- `AGENTS.md`: moves from the 2026-10-06 bootstrap template to the SAM#191 / SAM_OCCT#74 baseline (task-specific progress reads, SAM-BIM-only operations, quarter transition, evidence rules) plus merge conditions, guarded post-merge branch cleanup and the model/effort handoff rule. The repository's own branch-context line is kept. +- `CLAUDE.md` (new): `@AGENTS.md` import, same convention as the pilots. + +Shared rules added or confirmed in `AGENTS.md`: Git and committed records are authoritative; SAM-BIM-only +operations with validated URLs; heading-first, task-specific progress reads; feature branch + owner-reviewed PR +for everything except the post-merge `[skip ci]` progress closeout; tested-SHA, local-versus-hosted, +dependency-order and remaining-gap evidence; merge only after owner approval, final-head checks and resolved +findings; guarded post-merge cleanup of the task's branches (expected-SHA check, full-merge check, no open PR, +lease-guarded delete, no worktree deletion); frozen quarters; internal agent files stay off master promotions; +model/effort/session/mode on every recommendation. + +## Preserved repository-specific rules + +- No repository-specific rule existed beyond the shared template; the repository's own `master` base SHA in Branch context is kept. + +## Validation + +Local, documentation checks only (no product build or test was run, none applies): + +```bash +base=c0dc4281d87991e2cfc39d7ab4acabe76207f483 +tested=45f180a73e3b7c4304cc80f34369fc65f27a0fa2 +final=$(git rev-parse HEAD) # must equal the final head in the PR description +for revision in "$tested" "$final"; do + git diff --check "$base" "$revision"; echo "check $revision exit=$?" + git diff --name-only "$base" "$revision" + git diff --quiet "$base" "$revision" -- PROJECT_PROGRESS.md; echo "progress $revision exit=$?" +done +git diff --name-only "$tested" "$final" +git show "$final":CLAUDE.md | grep -n '^@AGENTS.md' +``` + +Expected: every `exit=` is 0; the full-PR file lists contain only AGENTS.md, CLAUDE.md and this record +(at the tested SHA only AGENTS.md, CLAUDE.md); the tested-to-final list contains only this record; the import +line is found. PowerShell works with `git rev-parse HEAD` and `if ($LASTEXITCODE -ne 0)` checks. + +Result at the tested SHA (2026-10-12, Windows, Git for Windows): `git diff --check` exit=0; +`PROJECT_PROGRESS.md` unchanged exit=0; changed files: AGENTS.md, CLAUDE.md; no CR, no BOM, final newline; +no unreplaced template tokens; `sow/2026-Q4` active, `sow/2026-Q3` frozen, no `sow/2026-Q2` reference. +The same checks at the final head and the hosted PR checks are reported in the PR description; +they are not asserted here. No agent-client token/behaviour benchmark was run for this rollout. + +## Remaining decisions and next step + +- Merge needs owner approval, passing final-head checks and resolved/accepted review findings. Code-owner review is required only for merges to `master` (owner decision recorded in the pilot closeouts). +- After merge: a docs-only `[skip ci]` closeout in `PROJECT_PROGRESS.md` on `sow/2026-Q4` with the merge SHA, then guarded cleanup of `docs/agent-instructions-rollout-q4` per `AGENTS.md`. Stale bootstrap wording already in `PROJECT_PROGRESS.md` is not edited by this PR; labelling it is a closeout matter that needs explicit owner authorization. +- Machine-local: the 29-repository rollout inventory, worktrees and cross-repository status table are in the + local parent `PROJECT_PROGRESS.md` checkpoint (not Git-tracked). The committed cross-repository table is in + SAM-BIM/SAM's `documentation/Agent-Continuity-Rollout-Q4.md` once that PR lists all rollout PRs. \ No newline at end of file