github-workflow — GitHub Issues + Project tracking

GitHub Issues are the canonical record for pohunek work: scope, design proposals and decisions, acceptance criteria, plans, verification evidence, blockers, and handoffs. The Pohunek Project (owner zajca, repository zajca/pohunek) tracks delivery status. Local files are not competitors: NEXT.md is never required — a pre-existing untracked one is a read-only migration source at most — and SiYuan notes are optional pointers.

One config, no hardcoded IDs

Read .github/agent-workflow.json once per session before the first write. It names the repository, the default project, the valid status options (Todo, In Progress, Done) and their meaning, and how issue bodies vs comments are used. Do not hardcode project numbers, field IDs, or status IDs anywhere else; resolve the Project's field/status option IDs at run time with gh project view/gh project field-list. There is no Review or Blocked status: represent review findings and blockers as issue comments while status stays In Progress. Being tracked as Todo for a design-proposal issue does not imply the proposed design is accepted — acceptance is an explicit decision recorded on the issue.

Public contributions and authority

The contributionPolicy in .github/agent-workflow.json records the accepted permission and review route; it is guidance, not a runtime permission grant. Normal GitHub controls remain in force, and automatic reservation enforcement does not exist before the coordination service is delivered. An authenticated GitHub principal is accountable; agent and run IDs correlate activity but do not establish identity. Public issues, dependency links, reservation evidence, and pull requests must be enough to understand the work without access to the private Project.

An outside contributor may propose work, request an eligible reservation, work in a fork they are authorized to use, and submit a pull request with evidence. A contributor does not need private Project access or maintainer credentials. These actions grant no repository write access, private Project, host, or credential access, model budget, review, merge, release, or privileged-label authority. The repository owner's standing authorization for owner agents never transfers to an outside contributor. A contribution request does not authorize spending another person's credentials or budget.

An agent acting for the repository owner keeps only the owner's existing standing issue and Project authorization and any separately authorized task scope. It must honor recorded reservation scope and conflicts. Commits, pushes, and releases still require their own authorization; this policy grants none.

Until the coordination service in #805–#811 is delivered, only a maintainer may explicitly record a manual reservation in public issue evidence after reconciling active work, the principal's outstanding reservations, comments, and pull requests. A request, label, assignee, or unanswered comment is not a grant, and a manual record is not an atomic lease. Automatic admission starts only when the service authenticates principals and transactionally enforces the published eligibility, capacity, WIP, expiry, anti-hoarding, and assignment-transition rules; changing an agent or run ID cannot reset a principal's allowance. GitHub labels, assignees, and Project fields are projections, never locks, and the service grants no general merge or release authority. Numeric limits are owned by #805 and must not be invented here.

A recognized holder works only within the granted scope and current authenticated generation; once the service exists it may renew, submit, release, or request transfer. It cannot expand scope, transfer ownership unilaterally, release a successor's assignment, or count submission as acceptance. Submission and review retain custody. Expiry or abandonment starts reconciliation of linked pull requests, branches, candidate evidence, and pending effects before an explicit release, adoption, cancellation, or transfer; it never silently frees or reassigns the work. A stale holder cannot mutate a successor's assignment. A custody handoff preserves the holder, generation when available, issue/spec revision, exact commit or pull request, actual checks, unresolved effects, and the next permitted action; acknowledging it does not transfer custody.

zajca triages, routes, resolves disputes, and integrates contributions after the required gates and independent review under existing authorization; product or authority changes require the applicable owner decision. An available independent reviewer examines the relevant code, contract, and evidence for the area, assesses the exact candidate against the issue criteria, and records findings without needing an implementation reservation. No permanently staffed area reviewer or response time commitment is promised. If an independent reviewer is unavailable, the candidate remains unaccepted; the maintainer records that state and retries routing when capacity exists. The submitter, author, executor, or manager cannot supply independent approval, including through another session used to author or direct the change; a fresh review-only session that did not author the change supplies the technical review (the marker). Starting that session with a review-only briefing is not directing the change. The technical review gate is an opus-pr-review:v1 marker comment authored by zajca that names the exact pull request head (<!-- opus-pr-review:v1:<repo>#<N>@<40-char sha>:high=<h>:medium=<m>:low=<l> -->). GO is high=0 and medium=0; a review with only LOW findings passes and each LOW finding becomes a follow-up issue. A marker from any other author, for another head, or from an interrupted run is not approval, and no label is needed. For an outside contribution the route per head is: the maintainer approves the workflow runs, the maintainer's manager requests the Opus review, and the marker arrives as a comment on the pull request. If no marker has arrived some hours after green CI, the contributor mentions the maintainer on the pull request. The marker is the technical gate only: merging an outside contribution also needs the maintainer's explicit approval. An outside contributor never receives the credential that posts the marker. Only the designated independent review session posts the marker: a fresh Opus high effort session that did not author the change, started by the maintainer's manager (the coordinator or operator) or, when no manager is named, by the delivering agent per deliver-issue Phase 5. The authoring agent never posts or imitates a marker. Review grants no merge authority; release remains separately authorized. A fork head is never dispatched, run through a ref such as refs/pull/<N>/head, or rerun by an agent in this repository; the forkHeads rule of contributionPolicy.reviewAndIntegration has the maintainer's route.

Unsolicited competing pull requests remain welcome and use the same criteria. A reservation neither guarantees a merge nor prevents fork work; choosing a different candidate requires an explicit integration and custody decision. Conflicts must be disclosed. An appeal cites the decision, policy/spec revision, and new evidence on the issue or pull request through the maintainer route. An appeal or handoff acknowledgment alone does not change custody, transfer the work, or grant acceptance.

Permission walkthrough checks

Use these checks when reviewing a contribution path; all outcomes must follow the contributionPolicy in .github/agent-workflow.json:

Standing authorization — never ask whether to file

The repository owner has durably pre-authorized these GitHub writes on the configured repository and default project (authorization in .github/agent-workflow.json): creating issues, editing your own body sections, commenting, native sub-issue/dependency links, and adding items to the project or changing their status. This authorization overrides any generic "confirm outward-facing actions first" default. Do them without asking, then report the links in your summary.

• Never ask "should I file an issue?" or offer a follow-up instead of filing it. A verified out-of-scope finding, or a verified defect/gap you notice incidentally while doing other work, gets its issue filed (dedup first).
• The only question left is which issue applies when competing matches or a genuinely ambiguous scope make that unclear — never whether to file.
• It does not widen anything else: dedup, the no-trivial-issues rule, the Done/closure bar, and the ban on destructive project edits still apply, and commits/pushes still need the owner's explicit request.

Route plugin work to the plugin repository

pluginRouting in .github/agent-workflow.json decides where an issue is filed. Core issues are only for core capabilities:

• Work on one plugin (a fix, a feature, an upstream bump) is an issue in that plugin's repository (pohunekd/plugin-<name>, or the author's <owner>/pohunek-plugin-<name>). Until an official runtime leaves runtime-packages/, its work stays in this repository.
• Admitting, updating or revoking a plugin is a pull request, with its tracking issue, in pohunekd/pohunek-plugin-index. That repository exists from a later release; until then admission work is a core issue under #1609.
• A capability a plugin needs from core is a core issue that names the plugin.
• Only the owner creates pohunekd/* repositories: propose one in an issue and wait for the grant. Never open an issue in a repository the task does not authorize.

Gate meaningful work on an issue first

No meaningful work starts without something on the triage record. Before starting it: resolve the issue (below), deduplicate against existing issues (paginated, open + recently closed), and then:

• No matching issue and the user gave a concrete new scope → auto-create the issue and add it to the configured project without a further ask. Do not require the user to say "file an issue".
• Multiple plausible matching issues (competing candidates) or a genuinely ambiguous scope → ask which issue/scope applies; do not pick a probable one.
• One unique match → reuse it (update scope/DoD, add a progress comment).

Explicit issue URL/number from the task or user always wins once verified to exist and be open.

Create or update — deduplicate first

Search for a matching actionable issue before creating one (open and recently closed, paginated: gh search issues / gh issue list --search, following pages until results stop growing). If one matches, update it instead of opening a near-duplicate; link a genuinely distinct older issue when related. Create a new issue only for meaningful, actionable work — a design proposal with a decision, a milestone/feature/fix with scope and acceptance criteria, or a verified follow-up discovered during work. Never file an issue per trivial tool call, quick task, or in-flight detail; those belong in comments on the issue already covering the work.

Automated follow-up issues: when work produces a verified out-of-scope finding (a real gap discovered and evidenced outside the current DoD), file a follow-up issue for it automatically (dedup first). Never move an unmet original DoD item into a follow-up to claim the current issue done — the issue stays open at In Progress until its own DoD is met.

Issue body vs comments

• Body (long-lived, structured): full scope; accepted decisions with rationale; definition-of-done items with stable IDs (D1, D2, ...); dependencies (linked issues/APIs, including parent/sub-issue links); the plan, including the PR stack slice plan (ordered slices → DoD items, per pullRequests in .github/agent-workflow.json) and, once opened, the ordered PR links. Preserve user-written sections when editing — edit or extend your own sections, read the body first.
• Comments (append-only): progress, verification evidence (exact commands and their results), handoffs between agents, blockers, and the reason for any status change. Never overwrite or delete another author's comment.

Public contribution readiness

Use .github/ISSUE_TEMPLATE/work-item.yml for new public work proposals and .github/pull_request_template.md to report a candidate. The vocabulary and label names live in publicContribution in .github/agent-workflow.json. Keep issue scope, stable D1…Dn criteria, dependencies, likely entry points, capability, size, prerequisites, focused checks, and a proposed review route in the public issue; do not require private Project access.

Readiness is separate from delivery status. ready means only that the issue is eligible for consideration: its scope and checks are actionable, named dependencies and prerequisites are resolved, an available review route is identified, and no active recognized assignment or linked active PR makes immediate work misleading. It is not proof of vacancy or a reservation grant. design-needed means a decision or contract needed to implement remains open; blocked names a dependency or external prerequisite that prevents starting. Maintainers manage the public readiness:* labels manually. Todo, In Progress, and Done keep the meanings in statusSemantics; do not infer readiness from a Project status.

Reservations, the review route, and integration authority follow Public contributions and authority. Do not invent a claim command or imply that a public label locks work.

Use the capability classes and S/M/L size meanings in the config as scope cues, not model-brand gates or time promises. Keep readiness labels separate from capability labels and delivery status. Link native dependency relations when available; a textual Depends on #N alone does not prove the relation.

In the PR template, bind every criterion and check result to the exact candidate SHA and base. Record exact commands as passed, failed, skipped (with reason), or unverified; list remaining criteria and unresolved work. Update the evidence whenever the candidate changes. Review and submission do not grant merge or release authority.

Project membership and status

Actionable tracked work joins the configured default project and stays there from "work accepted" to "verified completion". After any update, verify from the API response (or a follow-up read) that the item actually exists in the project with the intended status. Existing topic projects stay available as additional views; do not remove items from them and do not migrate anything destructively. Only sync a topic project when the task explicitly covers it.

Done, issue closure, and status consistency

• Any change to the repository — code, scripts, harness files, documentation, skills, or configuration — reaches Done plus issue closure only via the same bar: verified landing on the remote default branch with every DoD item met with evidence. Publishing a change someone cannot verify on the remote default branch is not a landing, whatever kind of file it touched.
• A local merge without an authorized push is not a landing: the issue stays open at In Progress with a comment recording the local merge commit as evidence. The push it needs is still governed by the standing "commit/ push only when asked" rule; no local merge widens that authorization.
• Only pure planning/investigation with no repository change (research, design decisions, issue-held plans) can complete on issue-held artifact and evidence alone — the artifact IS the issue — before any landing.
• Never close an issue whose DoD is partially met, and never set Done merely because something was written locally or a PR was opened.

Safe persistence

• Read before you write; never blind-overwrite a body or project field.
• Verify every mutation from its API response or a follow-up read (gh issue view, the GraphQL item object) before claiming it landed.
• Search with pagination; do not treat the first page as the whole inventory.
• After an ambiguous mutation (timeout, ambiguous error), stop: read back the current state before any retry, and never retry blindly. When verifying project membership after a write, do not rely on gh project item-list — it can be stale; prefer the mutation's returned project item ID: a direct GraphQL node(id: $projectV2ItemId) lookup (reading project, content, and fieldValueByName), or the issue's projectItems. If targeted reads still disagree, report synchronization as unverified and do not repeat the mutation until its outcome is known.
• A permission, authentication, or network error blocks sync: report which GitHub write could not happen and stop claiming progress; do not falsely say "recorded" and do not work around permissions by other means.
• Writes you may make within an owner-authorized task: issues on the configured repository, comments, and project add/status updates relevant to that task. Never widen authorization (no unrelated auth changes, no team / relay grants) and never perform destructive project edits (deleting fields, statuses, or views, removing items).

Usable safe gh command patterns

These are the shapes to start from; check gh <cmd> --help for exact flags before a first use. Multiline text always goes through a file:

# read before write, with the repository resolved from the config
gh issue view "$issue_number" --repo "$repository" --json number,title,state,body,comments,projectItems
gh issue create --repo "$repository" --title "$issue_title" --body-file body.md
gh issue edit "$issue_number" --repo "$repository" --body-file body.md   # full replacement, read first
gh issue comment "$issue_number" --repo "$repository" --body-file note.md
# Preserve native parent/sub-issue and blocking relationships, plus readable links.
#   parent: a sub-issue via the documented REST sub-issues endpoint
#   (POST /repos/{owner}/{repo}/issues/{issue_number}/sub_issues) or GraphQL
#   addSubIssue, against the parent issue. Use the supported issue-dependency
#   API for blocking relationships and include "Depends on #N" in the body.
#   If a relationship write is unavailable, record it as pending; a text link
#   alone is not proof that the native relationship exists. Confirm any `gh`
#   wrapper's local --help before preferring it over the endpoints above.

For project-item readback, bind the returned item ID and the status field name discovered from the project's fields:

gh api graphql -f projectV2ItemId="$project_item_id" -f statusField="$status_field_name" -f query='
query($projectV2ItemId: ID!, $statusField: String!) {
  node(id: $projectV2ItemId) {
    ... on ProjectV2Item {
      id
      project { number title }
      content { ... on Issue { number repository { nameWithOwner } state } }
      fieldValueByName(name: $statusField) {
        ... on ProjectV2ItemFieldSingleSelectValue { name }
      }
    }
  }
}'

Issue numbers here are placeholders ($issue_number, $repository): none of these examples is meant to run against a live issue without filling them in from the resolved task.

Body rewrites: read the current body, apply your edits to your own sections, write the full new body to a scratch file, gh issue edit N --body-file, then read back and diff to confirm the intended sections survived; remove the scratch file.

Handoff comments (stopping or leaving the work)

When a task ends — completed, blocked, or handed to another agent/session — leave one handoff comment on the issue with, at minimum:

• the branch and worktree paths the work lives in;
• the HEAD revision (or, for pure planning/investigation, the issue-held artifact itself);
• what scope was covered and what explicitly remains;
• the exact checks run with their real exit results, including any skipped or failed checks and why;
• remaining work / open blockers;
• for runs that spawn more agents: the worker run IDs.

A handoff is the resume point: the next read of the issue must be enough to continue without local-only memory.

Runtime discipline

Read the issue's current body and comments before resuming any interrupted work; rely on the issue, not memory, for state. When a decision revises an accepted design constraint in docs/architecture.md or docs/design/, the issue must state that revision explicitly — accepted docs stay authoritative until deliberately revised.