@tiic-tech/openworkflow 0.1.0 → 0.1.2

package/references/gh-operation-governance.md

@@ -0,0 +1,114 @@
+# Gh Operation Governance
+
+This reference classifies `gh` and GitHub operations for OpenWorkflow dogfood
+work. It is a governance contract, not an implementation plan.
+
+## Preconditions
+
+Any gh-dependent workflow requires:
+
+- explicit user authorization
+- a configured `gh` CLI or GitHub connector
+- a known repository remote
+- clear source-of-truth mode for Issues and PRs
+- local audit evidence for remote-impacting operations
+
+If these preconditions are missing, OW should use local planning artifacts and
+avoid remote mutation.
+
+## Operation Tiers
+
+### Local-Only Git Automation
+
+Local-only git automation is not a gh operation. It is governed by
+`references/git-version-control-governance.md` and may cover local branch
+creation or checkout, local selected-change commits, and local
+`PR_READY_SUMMARY.md` generation after preview and validation.
+
+Local-only automation must not push, create remote PRs, edit Issues, mutate
+labels, or merge. The moment an operation reaches a remote or authenticated
+GitHub target, it enters one of the gh tiers below.
+
+### Read-Only
+
+Read-only operations inspect remote state and do not mutate GitHub.
+
+Examples:
+
+- list or view issues
+- list or view PRs
+- inspect labels, milestones, assignees, or review state
+- read CI/check status
+- resolve issue or PR URLs for local linkage
+
+Read-only operations may be used for analysis when the user has authorized gh
+access or explicitly provided the remote data.
+
+### Evidence-Writing
+
+Evidence-writing operations add audit breadcrumbs but do not change the core
+truth of an Issue or PR.
+
+Examples:
+
+- add a comment linking an Issue to a plan id or PR
+- add a non-destructive label that marks decomposition state
+- update a draft PR body with OW-generated summary text
+
+These operations require explicit user approval for the specific action. A CLI
+boolean such as `--allow-draft-pr` is never approval by itself; write-mode draft
+PR pilots must also name explicit local approval evidence with
+`--approval-evidence`. The local OW artifact remains the audit record and should
+capture the remote URL, timestamp, operation kind, and summary of the mutation.
+
+### High-Risk Mutation
+
+High-risk mutations change remote state in ways that can affect collaboration,
+delivery, or user trust.
+
+Examples:
+
+- create or close an Issue
+- edit an Issue body
+- close or reopen a PR
+- create a PR
+- push a branch
+- merge a PR
+- force-push
+- remove labels, milestones, or assignments used by humans
+
+These operations require a `HIGH_RISK_DECISION_REPORT.md` until OW has an
+approved remote operation model. Approval must name the concrete action and
+guardrails.
+
+Merge-readiness conflict probes are not merge approval. A read-only checkpoint
+may name conflict files and required evidence, but conflict resolution requires
+an isolated worktree, explicit operation-level approval, validation reruns, and
+local audit evidence before any later merge operation.
+
+## Audit Requirements
+
+For any evidence-writing or high-risk mutation, record locally:
+
+- remote target URL or number
+- operation type
+- user approval source
+- local plan id and candidate id
+- branch name when relevant
+- base branch when relevant
+- body or checkpoint digest when relevant
+- commit hash when relevant
+- timestamp
+- result or remote URL after mutation
+- rollback guidance
+
+Do not rely on remote comments alone as the OW audit record.
+
+## Relationship To Issues And PRs
+
+GitHub Issues may be the source of truth for issue bodies and comments when the
+user configures GitHub mode. OW local artifacts should store linkage and audit
+metadata, not duplicate issue bodies as authoritative text.
+
+PR-ready summaries are local handoff artifacts. Opening or updating a remote PR
+is a separate gh operation and must follow the tiers above.

package/references/git-automation-governance.md

@@ -0,0 +1,324 @@
+# Git Automation Governance
+
+## Purpose
+
+OpenWorkflow git automation has two policy modes:
+
+- `managed`: OW may automate local branch, local commit, and local PR-ready
+  summary actions while asking for approval at remote-impacting boundaries.
+- `autonomous`: OW may eventually run the full git lifecycle without stepwise
+  approval, but only after a separate high-risk candidate defines exact
+  operations, evidence, rollback, and safety limits.
+
+G015 implements the managed command shell. It does not implement autonomous
+push, PR creation, PR merge, or GitHub Issue mutation.
+
+## Managed Mode
+
+Managed mode can:
+
+- create or check out the local feat branch recorded in
+  `queue_policy.branch_boundary`
+- create local selected-change commits when validation evidence exists
+- create local follow-up evidence commits
+- generate local `PR_READY_SUMMARY.md`
+- recommend when remote PR or merge review is appropriate
+
+Managed mode must gate:
+
+- `git push`
+- `gh pr create`, `gh pr edit`, and `gh pr merge`
+- `gh issue create`, `gh issue edit`, and `gh issue close`
+- destructive operations such as reset, rebase, force-push, or branch deletion
+
+When a user approves a remote operation, the agent must be able to reconstruct
+the correct operation sequence from local evidence even when a branch contains
+hundreds or thousands of local commits. Managed mode should prepare a remote
+operation plan before execution:
+
+1. confirm clean working tree and current validation evidence
+2. identify the feat branch and target base
+3. list ordered local commits from the approved base to HEAD, or fall back to
+   commit evidence recorded in `CANDIDATE_CHANGES.yaml`
+4. push the feat branch to the approved remote branch
+5. create or update the PR using the local `PR_READY_SUMMARY.md`
+6. wait for checks and resolve conflicts against the target base
+7. merge only after user approval and repository protection checks pass
+8. record remote URL, PR id, merge commit, and rollback guidance
+
+## Autonomous Mode
+
+Autonomous mode is a future high-risk capability. Before implementation, OW
+must define:
+
+- explicit configuration that enables autonomous mode
+- exact allowed git and gh operations
+- evidence required before and after every operation
+- rollback or recovery guidance for each mutation class
+- repository protection checks and branch constraints
+- refusal behavior for unclean state, unknown remote state, and failed
+  validation
+
+G016 defines the contract for this mode. It does not make autonomous remote
+mutation executable.
+
+### Enablement Contract
+
+Autonomous mode must be enabled by an explicit local configuration. It must not
+be inferred from conversation wording or from the existence of a candidate
+queue.
+
+Minimum configuration shape:
+
+```yaml
+git_automation:
+  mode: managed # managed | autonomous
+  autonomous:
+    enabled: false
+    target_remote: origin
+    target_base: main
+    allowed_operations:
+      local_branch: true
+      local_commit: true
+      push: false
+      draft_pr: false
+      ready_pr: false
+      merge: false
+      issue_mutation: false
+    required_validation:
+      - npm run validate
+    evidence_dir: changes/<plan_id>/git-automation/
+    conflict_policy: stop
+    rollback_policy: record_recovery_plan
+```
+
+The only default-safe autonomous operations are local branch, local commit, and
+local summary generation. Push, PR creation or update, merge, and Issue
+mutation must each be explicitly allowed by configuration and supported by the
+current operation contract.
+
+### Operation Matrix
+
+| Operation | Default | Required gate | Evidence |
+| --- | --- | --- | --- |
+| Local branch create or checkout | allowed | branch boundary and clean tree | before branch, after branch, command preview |
+| Local selected-change commit | allowed | validation evidence and allowed paths | dirty paths, commit message, commit hash |
+| Local PR-ready summary | allowed | queue exists | output path and validation summary |
+| Push feat branch | denied | autonomous push enabled, clean tree, target remote and base known | before ref, after ref, ordered commits |
+| Draft PR create or update | denied | push completed, PR summary exists | PR URL, payload digest, branch and base |
+| Ready PR create or update | denied | validation current, blockers absent | PR URL, validation, review notes |
+| Merge PR | denied | checks pass, protection satisfied or waiver recorded | merge method, merge commit, rollback path |
+| Issue mutation | denied | separate Issue operation policy | target issue, payload digest, before and after state |
+| Reset, rebase, force-push, destructive branch deletion | denied | separate high-risk report only | exact command and recovery plan |
+
+### Autonomous Run Record
+
+Every autonomous run must produce an operation record before and after mutation.
+The preflight record must be written before any remote action and include:
+
+- operation id
+- requested mode and allowed operation set
+- plan id, candidate ids, and source queue
+- current branch, branch boundary, target remote, and target base
+- local HEAD and target base ref
+- ordered local commits from base to HEAD
+- dirty paths and rejected paths
+- validation commands and status
+- PR-ready summary path and digest when relevant
+- remote state snapshot when available
+- planned commands or API calls
+- refusal criteria evaluated
+
+The completion record must include:
+
+- commands or API calls that actually ran
+- before and after refs
+- pushed branch or remote ref
+- PR URL and id when created or updated
+- merge method and merge commit when merged
+- conflict-resolution notes when conflicts were encountered
+- rollback or recovery instructions
+- validation status after operation
+- final status: `completed`, `refused`, `failed`, or `needs_human`
+
+### Merge Readiness
+
+Autonomous merge is not allowed unless all configured gates pass:
+
+- local validation is current
+- remote checks are passing or explicitly waived
+- PR branch is up to date with target base or the conflict policy has handled it
+- PR-ready summary is current after the last local commit
+- no candidate in the queue is blocked unless explicitly excluded from the PR
+- high-risk reports are resolved or intentionally deferred
+- repository protection is satisfied or the waiver is recorded
+
+When any gate is unknown, autonomous mode must stop with status `needs_human`.
+
+### Conflict Policy
+
+The default conflict policy is `stop`. Autonomous conflict resolution can only
+run when a later high-risk candidate defines exact file classes, resolution
+rules, validation requirements, and rollback behavior.
+
+Allowed conflict policies:
+
+- `stop`: stop and emit conflict evidence.
+- `manual_resolution_required`: prepare instructions and wait for human or
+  agent-directed resolution.
+- `policy_driven_resolution`: future high-risk mode only.
+
+### Rollback And Recovery
+
+Rollback guidance must be recorded before any remote mutation. The recovery path
+depends on operation class:
+
+- Push: name the previous remote ref and recovery command or PR-based revert
+  strategy.
+- PR create or update: record PR URL, previous body digest when available, and
+  close or edit-back guidance.
+- Merge: record merge commit, revert command or follow-up revert PR plan, and
+  affected target branch.
+- Issue mutation: record before state, after state, target issue URL, and edit
+  recovery guidance.
+
+Rollback must not rely on force-push by default.
+
+### Implementation Path
+
+The safe implementation path is:
+
+1. Design-only autonomous contract.
+2. Read-only autonomous simulator that produces full plans and evidence without
+   remote mutation.
+3. Remote read-only PR-ready planning that inspects remote state and produces
+   an executable operation plan without mutation.
+4. Narrow autonomous pilot for one remote operation class, starting with draft
+   PR creation or update.
+5. Branch push, ready-for-review transition, merge, and Issue mutation only as
+   later high-risk candidates.
+6. Full autonomous lifecycle only after the simulator and pilots prove evidence,
+   conflict, and rollback behavior.
+
+### Approved Narrow Pilot Sequence
+
+G018 approves the staged B -> C path:
+
+- **B: remote read-only plus PR-ready remote plan.** The next implementation
+  candidate is G019. It may read remote refs and PR metadata, compare them to
+  local evidence, and write a local plan. It must not push, create or edit PRs,
+  merge, or mutate Issues.
+- **C: draft PR remote mutation pilot.** The follow-up candidate is G020. It is
+  limited to draft PR creation or managed-section update after G019 proves the
+  evidence model. It must still deny merge, ready-for-review transition, Issue
+  mutation, force-push, reset, rebase, and destructive branch deletion.
+
+The recommended first mutation class is draft PR creation or update because the
+result is reviewable and reversible by closing or editing the PR. It remains a
+remote mutation and therefore requires explicit configuration, current simulator
+evidence, target identity checks, payload preview, before/after evidence, and a
+rollback plan.
+
+## Evidence
+
+Every git operation should record enough evidence to reconstruct what happened:
+
+- operation id or command invocation
+- plan id and candidate id when applicable
+- current branch and branch boundary
+- dirty paths included or rejected
+- command preview
+- validation evidence
+- before and after commit or ref state when applicable
+- ordered local commits for remote push, PR, and merge planning
+- output artifact path when generated
+- refusal reason when blocked
+
+Remote operations require separate operation-level approval until autonomous
+mode is explicitly designed and accepted.
+
+## Read-Only Autonomous Simulator
+
+The simulator is the required bridge between design-only autonomous contracts
+and any autonomous remote pilot. It must be impossible for simulator mode to
+push, create or update PRs, merge, mutate Issues, resolve conflicts, or change
+refs.
+
+Simulator input:
+
+- source `CANDIDATE_CHANGES.yaml`
+- target base or base ref
+- target remote when remote metadata is available
+- optional `PR_READY_SUMMARY.md` path
+
+Simulator output:
+
+- clean-tree and branch-boundary status
+- ordered local commits from base to HEAD
+- commit evidence from the queue
+- validation evidence discovered in the queue
+- PR-ready summary status
+- remote branch and base metadata when readable
+- simulated push, PR, checks, merge, and rollback plan
+- blockers that must be resolved before any autonomous pilot
+
+The simulator is successful only when it can produce a complete plan without
+missing branch, commit, validation, PR-summary, or rollback evidence. Unknown
+remote metadata is a warning when local evidence is otherwise complete; stale
+or conflicting remote metadata is a blocker for later execution candidates.
+
+## Remote Read-Only PR-Ready Plan
+
+`openworkflow git-automation remote-plan` is the approved B step after the
+simulator. It reads remote state and emits a local JSON plan. It must not push,
+create PRs, edit PRs, close PRs, merge, mutate Issues, or alter refs.
+
+Remote-plan input:
+
+- source `CANDIDATE_CHANGES.yaml`
+- target remote
+- target base
+- optional target branch
+- optional base ref for ordered local commits
+- optional `PR_READY_SUMMARY.md` path
+
+Remote-plan output:
+
+- target identity: remote URL, target branch, target base, current branch, and
+  queue branch boundary
+- local state: local HEAD, dirty paths, ordered local commits, queue commit
+  evidence, validation evidence, and PR-ready summary status
+- remote state: target branch head and base head when readable
+- optional PR metadata from `gh pr list` when available
+- blockers, warnings, read-only operation plan, and rollback guidance
+
+Remote-plan is successful only when the target remote and base are readable,
+the working tree is clean, the branch boundary matches, validation evidence is
+present, and `PR_READY_SUMMARY.md` exists. Missing branch head is a warning
+because a later approved push or draft PR pilot may create it; missing base head
+is a blocker.
+
+## Draft PR Pilot
+
+`openworkflow git-automation draft-pr` is the approved C pilot after remote
+read-only planning. It is disabled by default: without `--write` it only emits a
+payload preview, and with `--write` it still refuses unless `--allow-draft-pr`
+is present.
+
+Draft-pr input:
+
+- the same target identity inputs as `remote-plan`
+- `PR_READY_SUMMARY.md` as the managed PR body source
+- optional PR title
+- explicit `--write --allow-draft-pr` for mutation
+
+Draft-pr guarantees:
+
+- dry-run returns `mutation_performed: false`
+- mutation is limited to `gh pr create --draft` or a managed draft PR body edit
+- remote branch and target base must already be readable
+- the PR body is wrapped in an OpenWorkflow managed section and digest
+- rollback guidance is included before mutation
+
+Draft-pr must not push, merge, mark ready for review, mutate Issues, force-push,
+reset, rebase, or destructively delete branches.

package/references/git-version-control-governance.md

@@ -0,0 +1,227 @@
+# Git Version Control Governance
+
+This reference defines OpenWorkflow's git governance hierarchy for dogfood
+development. It is a planning and audit contract, not an automation mandate.
+
+## Hierarchy
+
+Use these boundaries when planning and implementing work:
+
+- Atom task: an implementation checklist item inside one selected change.
+- Selected change: one commit-sized implementation unit.
+- `CANDIDATE_CHANGES.yaml`: one feature-sized planning queue.
+- Feat branch: the git branch that owns one candidate queue.
+- Pull request: the integration review boundary for one feat branch.
+- Merge or release: the boundary where accepted PR work enters the target line.
+
+An Issue is an intent, problem, request, bug, or external tracking source. It
+can decompose into one or more candidate queues, and one candidate queue can
+reference one or more Issues. An Issue is not automatically a selected change.
+Use `references/issue-governance.md` for local and GitHub-backed
+source-of-truth rules.
+
+## Commit Boundary
+
+A selected candidate should normally complete as one coherent git commit. The
+commit should include:
+
+- selection artifacts under `changes/<plan_id>/<candidate-id>-<slug>/`
+- source, reference, or fixture edits owned by the selected candidate
+- queue status and completion evidence for that selected candidate
+- validation evidence in the queue or selected change artifact
+
+Commit messages should include the plan id and candidate id when practical:
+
+```text
+M71/G001 Formalize git governance hierarchy
+```
+
+If a candidate is discovered to be too broad for one commit, split or supersede
+it in the owning queue before implementation continues.
+
+## Feat Branch Boundary
+
+Each new `CANDIDATE_CHANGES.yaml` queue should have an owning branch. The branch
+name should be stable and scoped to the feat, for example:
+
+```text
+codex/m71-git-version-governance
+```
+
+The queue should record the branch in `queue_policy.branch_boundary` when the
+queue opts into branch governance. Work for selected candidates should happen on
+that branch unless the user explicitly approves an exception.
+
+For new branch-governed queues, the branch boundary should carry the same
+feat identity as the queue plan id, normally the leading milestone token such
+as `M114` in both `M114-engineering-quality-foundation` and
+`codex/m114-engineering-quality-foundation`. A branch boundary that names
+another plan id is not feat ownership even when it equals the current branch.
+If a queue must temporarily continue on an older branch, record an explicit
+`queue_policy.branch_identity_exception` with:
+
+- `mode: temporary_continuation_branch`
+- `approved: true`
+- `allowed_operations` limited to the specific local operations being allowed
+- `reason` explaining why the exception is temporary
+
+Queue maintenance can happen before strict branch validation exists, but the
+maintenance operation should record the current branch and reason when it
+touches a branch-governed queue from a different branch.
+
+New branch-governed queues should opt into
+`queue_policy.git_lifecycle_gate: strict`. In strict lifecycle mode, the queue
+must record a plan-owned `queue_policy.branch_boundary` before selected work is
+treated as ready. When the whole queue is marked `completed` or `done`, it must
+also record PR/publication evidence such as `DRAFT_PR_OPERATION_EVIDENCE.yaml`,
+or remain explicitly blocked/deferred before PR creation. This keeps the branch
+and PR boundary visible to low-context Agents instead of relying on chat
+memory.
+
+## Pull Request Boundary
+
+A pull request should normally represent one feat branch, not one atom task.
+Use `changes/<plan_id>/PR_READY_SUMMARY.md` to prepare the branch for review
+before any remote PR operation. The PR-ready summary should explain:
+
+- the owning candidate queue
+- completed selected changes and commit evidence
+- deferred, blocked, superseded, or high-risk candidates
+- validation commands and results
+- unresolved risks or follow-up queues
+
+Opening, editing, or merging PRs is not implied by either the planning contract
+or `PR_READY_SUMMARY.md`. Those remote operations are governed by
+`references/gh-operation-governance.md`.
+
+## Issue Boundary
+
+Issues sit before decomposition in the governance hierarchy:
+
+```text
+Issue -> CANDIDATE_CHANGES -> selected change -> commit -> branch -> PR
+```
+
+The arrow is not one-to-one. A single Issue can lead to multiple feat queues,
+and a single feat queue can aggregate several related Issues.
+
+When local issue artifacts are the source of truth, they are git-tracked
+planning artifacts. When GitHub Issues are the source of truth, local OW
+artifacts should record linkage such as issue URLs, plan ids, candidate ids,
+commit hashes, branch names, and PR refs.
+
+## Non-Destructive Git Policy
+
+OW skills may inspect git state as part of planning, selection, and audit.
+Examples include:
+
+- current branch
+- dirty working tree
+- recent commit hashes
+- tracked and untracked paths
+
+Skills must not perform destructive git operations unless the user explicitly
+requests that specific operation. Destructive or remote-impacting operations
+include:
+
+- reset, checkout, restore, clean, or rebase actions that discard work
+- branch deletion
+- forced push
+- push to a remote branch
+- PR creation, update, merge, or close
+- GitHub Issue creation, body edit, closure, or destructive label changes
+
+Local commits may be created when the user has authorized the dogfood workflow
+that treats each selected change as a commit. Remote mutation requires separate
+authorization and should be governed by a high-risk decision report until OW has
+an approved gh operation model. See `references/gh-operation-governance.md` for
+read-only, evidence-writing, and high-risk mutation tiers.
+
+## Approved Local Automation Boundary
+
+The M71 high-risk decision approved a narrowed local automation path. A future
+`ow:git-automation` command may automate local git actions only inside these
+boundaries:
+
+- create or check out the local feat branch recorded in
+  `queue_policy.branch_boundary`
+- commit one completed selected change as at least one local commit
+- generate a local `PR_READY_SUMMARY.md` for a fully implemented and validated
+  candidate queue
+
+Every local mutation mode must support preview or dry-run output before it
+changes the repository. The preview should show:
+
+- target plan id and candidate id when applicable
+- current branch and expected branch boundary
+- dirty paths that would be included or rejected
+- exact commit message or summary path when applicable
+- validation evidence required before mutation
+
+The command must refuse local mutation when:
+
+- the working tree contains unrelated dirty paths
+- the current branch conflicts with the queue's branch boundary
+- the queue branch boundary names another plan id and no explicit temporary
+  continuation exception allows the local operation
+- the selected change is not complete
+- required validation evidence is missing
+- the operation would require push, remote PR creation, Issue mutation, or merge
+
+Selected changes must not finish without a local commit. A selected change may
+produce multiple local commits when traceability requires a follow-up evidence
+commit. Do not amend solely to force a commit to contain its own hash. Treat the
+latest local HEAD produced for the selected change as the relationship anchor,
+and record the primary implementation commit hash when a follow-up evidence
+commit is used.
+
+The preferred local completion path is:
+
+```text
+openworkflow git-automation commit --root . --queue changes/<plan_id>/CANDIDATE_CHANGES.yaml --candidate <id> --message "<plan-id> <candidate-id> ..." --validation-evidence "<commands>" --commit-evidence --json
+```
+
+When `--commit-evidence` is used, the selected change should record
+`LOCAL_COMMIT_EVIDENCE.yaml` under its own selected-change folder and the queue
+completion should reference that repo-relative path. A checkpoint commit that
+batches multiple completed selected changes is not valid per-candidate evidence.
+
+Remote operations are outside the approved local boundary. Push, remote PR
+creation or update, Issue mutation, and merge require explicit operation-level
+approval and must follow `references/gh-operation-governance.md`.
+
+## Merge Readiness And Conflict Checkpoints
+
+Remote readiness may compute a structured merge checkpoint with read-only git
+commands such as `git merge-base`, `git merge-base --is-ancestor`, and
+`git merge-tree --write-tree`. This checkpoint may report target base, target
+branch, merge base, fast-forward state, conflict files, required validations,
+and stop reasons.
+
+The checkpoint is not permission to merge and must not run `git merge`, modify
+the user's working tree, auto-resolve conflicts, rebase, reset, force-push, or
+mark a PR ready. If conflicts are reported, future work must use an isolated
+worktree, explicit operation-level user approval, conflict-resolution evidence,
+validation reruns, and local audit evidence before any later approved merge.
+
+## Evidence
+
+When a selected change completes, the owning queue should record enough
+evidence to audit the work later:
+
+- selected change id
+- completion timestamp
+- changed paths or artifact paths
+- validation commands
+- commit hash when available
+
+New strict branch-governed queues should also record whether implementation
+files changed:
+
+- `implementation_changed_files: true` requires repo-relative
+  `LOCAL_COMMIT_EVIDENCE.yaml` in completion evidence.
+- `implementation_changed_files: false` requires `commit_not_required_reason`.
+
+Older queues may not contain all fields. They remain migration-mode artifacts
+until touched or intentionally opted into
+`queue_policy.selected_change_commit_gate: strict`.