Repository navigation
Human action 19
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.
-
Run
cst fetch originand start from the delivered base. It fetches the branches and brings origin's records in through a validated import. In a clean working checkout, usecst 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 newmain. -
Implement and review one coherent increment. Stage the intended files with
git add, inspectgit diff --cached, then runcst commit -m "<conventional subject>" --generated-by <agent> --json. Use the agent actually producing the work. Do not declare--reviewed-bybefore that review has happened. Save the Change-Id, commit, and declared provenance. Measure whole-process elapsed time separately from receipt fields. -
Push the work branch with
cst push -u origin <work-branch>(#269). It pushesrefs/notes/causetandrefs/causet/retentionfirst, 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-labandrefs/vcs-lab/retentionare gone from origin (ADR-0039 §6) and are never pushed again.The Windows checkout is the exception. Its
refs/causet/retentiondiverged from origin's before the rename (#159), andcst pushwould merge origin's into it and publish the diverged history. From there, push withcst push --no-records -u origin <work-branch>and thengit push origin refs/notes/causet, until the owner has looked atgit log --oneline refs/causet-remote/origin/retention..refs/causet/retention(after acst 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. UseServes #Nfor partial work so a merge does not close a larger evidence item prematurely. -
After review and checks pass, run
cst fetch originagain in the clean checkout holdingmain(cst pull --ff-onlyif it is behind). Confirm it matchesorigin/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 tomainbefore its landing. Stop on an unexpected source or target movement. -
Run
cst merge <work-branch> --compact -m "<landing subject>" --jsonin that cleanmaincheckout. Keep the source parent; do not use--hard-squashin this pilot. Measure the whole invocation and retain the receipt. Compare the resulting tree with the reviewed candidate and confirm the two parents. -
Run
cst provenance <landing-commit> --jsonandcst 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 thenmainwithcst push origin main(the Windows checkout uses the step 3 exception). -
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.
-
Before the next independent increment, start a fresh branch from updated
origin/main, or fast-forward a clean retained working branch withcst git merge --ff-only origin/main(cst mergeis 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.
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:
- 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 andvlab/ws/<work-name>compatibility branch. - Work in that path. Before a handoff, record HEAD and
git diff --cached, runcst 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. - Commit the reviewed work with the attributed commit procedure above. Create a second clean review workspace from the intended target with the same
workspace createsyntax and a different name/path. - In the review workspace, run
cst forecast vlab/ws/<work-name> --json. Inspect classifications, blockers, and predicted tree. If it is complete and acceptable, runcst 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. - Compare the forecast's predicted tree, receipt result tree, and
git rev-parse 'HEAD^{tree}'. Validate the actual change and runcst 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. - 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> --jsonreleases its worktree while retaining workspace identity and branch/checkpoint refs. Preserve failures and use the operation's--abortbefore 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.