Skip to content

Human action 19

Jerry Holland edited this page Oct 16, 2026 · 8 revisions

Decide and pilot the real branch-and-land workflow

Canonical work item: #19.

When required: Before claiming real branch-and-land adoption evidence. The issue carries current status, decisions, and completion evidence.

Owner role: Repository owner and participating workflow users.

Prerequisites: Select a suitable real repository, participants, and identified Windows/POSIX hosts. Review the accepted causal object retention policy and backfill procedure; #49 is fixed by PR #75. Existing historical notes require explicit backfill before relying on their object retention.

The owner has adopted a bounded pilot in this repository; #19 records the earlier increments and subsequent evidence. Continue with actual reviewed work using the procedure below. This adoption does not establish the outstanding POSIX or sustained-workload evidence by itself.

  1. Run cst fetch origin and start from the delivered base. It fetches the branches and brings origin's records in through a validated import. In a clean working checkout, use cst branch <work-branch> origin/main. For stacked increments, explicitly name the preceding source branch and record the PR dependency. Never assume a previously landed source branch has advanced to the new main.

  2. Implement and review one coherent increment. Stage the intended files with git add, inspect git diff --cached, then run cst commit -m "<conventional subject>" --generated-by <agent> --json. Use the agent actually producing the work. Do not declare --reviewed-by before that review has happened. Save the Change-Id, commit, and declared provenance. Measure whole-process elapsed time separately from receipt fields.

  3. Push the work branch with cst push -u origin <work-branch> (#269). It pushes refs/notes/causet and refs/causet/retention first, in one atomic push, fast-forward and never forced (fetching and merging origin's first if they moved), and then the branch. It refuses while a parked record conflict has no disposition. Name no causal ref by hand; refs/notes/vcs-lab and refs/vcs-lab/retention are gone from origin (ADR-0039 §6) and are never pushed again.

    The Windows checkout is the exception. Its refs/causet/retention diverged from origin's before the rename (#159), and cst push would merge origin's into it and publish the diverged history. From there, push with cst push --no-records -u origin <work-branch> and then git push origin refs/notes/causet, until the owner has looked at git log --oneline refs/causet-remote/origin/retention..refs/causet/retention (after a cst fetch) and decided whether that history may go to origin. Open a PR with its issue, compatibility impact, and validation. Follow the ordinary review and CI policy; high-risk changes need full platform qualification on the source candidate. Use Serves #N for partial work so a merge does not close a larger evidence item prematurely.

  4. After review and checks pass, run cst fetch origin again in the clean checkout holding main (cst pull --ff-only if it is behind). Confirm it matches origin/main, the source SHA still matches the reviewed PR, and the expected merge tree matches the reviewed result. For a stack, land in dependency order and retarget the next PR to main before its landing. Stop on an unexpected source or target movement.

  5. Run cst merge <work-branch> --compact -m "<landing subject>" --json in that clean main checkout. Keep the source parent; do not use --hard-squash in this pilot. Measure the whole invocation and retain the receipt. Compare the resulting tree with the reviewed candidate and confirm the two parents.

  6. Run cst provenance <landing-commit> --json and cst metadata validate --json. Confirm carried provenance names the absorbed source commit, expected actor declarations are retained, and validation reports no errors or warnings. Publish the records and then main with cst push origin main (the Windows checkout uses the step 3 exception).

  7. Verify remote refs and the PR's merged state. Retain public-safe source/landing IDs, Change-Ids, receipt IDs, carried-provenance evidence, tree equality, metadata validation counts, CI links, and whole-invocation measurements on #19. State host/load conditions and distinguish unexercised forecast, resolution-reuse, workspace, or recovery behavior from observed outcomes.

  8. Before the next independent increment, start a fresh branch from updated origin/main, or fast-forward a clean retained working branch with cst git merge --ff-only origin/main (cst merge is the causal merge and takes no --ff-only). Compact landing does not advance the old source branch. Never reset or discard dirty work to catch up.

A plain git fetch does not transfer the causal metadata between clones; cst fetch, cst pull and cst clone do. The retention and transfer procedure covers bringing another participating clone or host into the pilot.

Workspace and forecast participation

The workspace pilot observation uses real #86 work and a separate review workspace. It supplies one clean forecast/application pair, not a conflicted-history rate or concurrent-agent benefit. Repeat on actual work, including the participating POSIX host:

  1. From the current repository, run cst workspace create <work-name> --from origin/main --path <new-worktree-path> --owner <actual-actor> --focus <work-purpose> --json. Record whole-process time and materialized files/bytes outside the tracked tree. Expected result: a registered workspace and vlab/ws/<work-name> compatibility branch.
  2. Work in that path. Before a handoff, record HEAD and git diff --cached, run cst workspace checkpoint --label <handoff-label> --json, and confirm HEAD/index stayed unchanged while the checkpoint captured the intended draft. Record whether the next actor actually used it; do not manufacture a recovery event.
  3. Commit the reviewed work with the attributed commit procedure above. Create a second clean review workspace from the intended target with the same workspace create syntax and a different name/path.
  4. In the review workspace, run cst forecast vlab/ws/<work-name> --json. Inspect classifications, blockers, and predicted tree. If it is complete and acceptable, run cst reconcile vlab/ws/<work-name> --use-forecast <forecast-id> --json. If blocked or stale, preserve the report and resolve/reforecast through the documented workflow; do not bypass the pin.
  5. Compare the forecast's predicted tree, receipt result tree, and git rev-parse 'HEAD^{tree}'. Validate the actual change and run cst metadata validate --strict --json. Retain source/result IDs, preserved Change-Ids, receipt schema, whole-invocation time, process counters, and observed outcomes on #19. Treat receipt phase timings separately from complete invocation timings.
  6. Land the original reviewed source through the compact workflow above. A review-workspace application is an integration check, not the main landing. Preserve its branch/receipt evidence. When finished and clean with no pending operation, cst workspace archive <review-name> --json releases its worktree while retaining workspace identity and branch/checkpoint refs. Preserve failures and use the operation's --abort before archiving a pending operation.

Owner decisions still needed: name the participating POSIX host/actor, report whether the workflow improved actual work, and define a user-consequence-based budget for the named agent-step sequence. Functional hosted CI is separate.

Verification: The adoption decision and observed real workflow outcomes must be recorded. Synthetic demonstrations and ordinary Git PR merges alone do not establish the requested evidence.

Failure handling and cleanup: Stop the pilot on unexpected mutation or unsafe recovery. If Git reports a merge conflict, no landing receipt has been recorded; inspect git status and preserve evidence before using ordinary git merge --abort to return to the clean pre-merge state. If a commit exists but metadata publication fails, retain that commit and use the documented provenance/retention repair procedure instead of rerunning the commit as if it never happened. cst push retries a moved remote three times; if it still reports stale-input, or refuses with conflict-blocked, run cst fetch origin and cst metadata status, inspect the conflicting refs, and dispose of each parked conflict deliberately; do not force push. Preserve diagnostic evidence and do not rewrite shared history to manufacture evidence.

Completion: attach the evidence/decision to issue #19, resolve its human-action label when satisfied, update the private board, and point the Human TODO entry to the completed outcome.

Publish only evidence suitable for the public issue/wiki. Redact private paths, repository content, and credentials from shared output. Sensitive vulnerability findings belong in a draft security advisory.

Back to Human TODO · Benchmark host baselines

Clone this wiki locally