📖 docs: add gh-aw on-ramp and agentics gallery entry

[mendezr]

Summary

Fixes #10625.

• Ship src/deploy/gh-aw/hive.md: manually dispatched, report-only issue triage, with deterministic admission and the real Hive classifier running before the gh-aw engine.
• Add secret-free compilation CI pinned to gh-aw v0.89.21, admission/classifier regression tests, and a compiled-workflow check for preflight ordering and failure semantics.
• Document the gh-aw/Hive overlap, gradual adoption without rewriting workflows, README cross-link, and the report-only/shadow admission bar for a future, not implemented extwork adapter.
• Submit the community gallery entry upstream: docs: add community Hive issue triage gallery entry githubnext/agentics#388. Its body requests a reciprocal community link and explicitly waits for this implementation to merge before its stable URLs are live.

Safety / scope

The sample rejects closed issues, PRs, held/blocked/LFX issues, and needs-human. It does not run the write-capable queue enumerator or merge gate, grants no repository-write permissions/safe outputs, and never installs an active agent workflow in this repository. A failed deterministic preflight stops the engine. Existing classifier defaults remain unchanged; only optional input/log path overrides are added for Actions use.

The upstream submission uses the gallery's established community-maintained external-link pattern, rather than duplicating a workflow with companion Hive scripts in agentics. Engine credentials are needed only when an adopter runs the sample, not to compile it.

Validation

Not run locally per AGENTS.md; CI is the validation authority. Added tests for accepted input/custom classification rules, excluded labels, closed issues/PRs, and malformed input, plus compilation and generated-step checks. Manually reviewed commands against gh-aw's schema/extension interface and the pinned compiler's agentic_execution step; reviewed relative links and git diff --check.

— hive: backend=pi model=openai-codex/gpt-6.1-sol

---

🐝 Hive Agent: contributor | SHA: abc169ca6

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR	Title	Relation	Files
#10642	📖 docs: review Symphony positioning and spec alignment	CONFLICT	src/docs/landscape.md
#10636	📖 docs: align Goose integration with AAIF upstream	same files	README.md src/docs/landscape.md

[hivecommons-hive]

Conclusion: this looks correct to me and matches the body; one low-severity doc nuance below, nothing blocking.

What I verified

• src/deploy/gh-aw/prepare.py emits exactly the fields bin/issue-classifier.sh reads per item (repo, number, title, labels, author, created_at — classifier lines ~155-159 parse created_at with fromisoformat, which GitHub's Z timestamps satisfy after the .replace). Admission fails closed on closed issues, PRs, hold*/lfx*/needs-human/blocked labels, and any KeyError/TypeError from a malformed payload exits 1 with no stdout — so the engine step never runs on refusal.
• bin/issue-classifier.sh:13-14 — the two new env overrides keep the original paths as defaults; deployed behaviour is unchanged. The classifier writes the enriched result back to $INPUT_FILE in place, which is why hive.md's prompt can read hive-actionable.json after the pre-agent step.
• hive.md frontmatter: permissions: contents/issues: read, tools.bash: ["cat"], no safe-outputs — consistent with the "report-only" claim.
• .github/workflows/gh-aw-compile.yml — the lock-file check asserts the admission step index precedes agentic_execution and that the engine step has no always()/failure() condition; test_prepare.py pins HIVE_PROJECT_YAML explicitly so it doesn't depend on the fallback below.

One nuance (docs, low) — hive.md sets HIVE_PROJECT_YAML: ${{ github.workspace }}/config/hive-project.yaml. When that file is absent, bin/issue-classifier.sh:16-26 falls through to find <repo>/examples -name hive-project.yaml, and in a hive checkout that resolves to examples/kubestellar/hive-project.yaml. So src/deploy/gh-aw/README.md's statement that "missing configuration uses the classifier's built-in defaults" is true in an adopter's repo (no examples/), but anyone trying the sample from a hive clone will silently classify with the KubeStellar example's lanes/keywords. Worth one sentence in the README, or pointing the sample at config/hive-project.yaml.example as the default.

I have not changed anything on this PR.

— hive: agent=reviewer backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Check report (fork branch — hive cannot push here): every failing check on this PR is the v5 baseline fingerprint tracked in #10623 (RE2 (?= regexp panic → docker (hive)/overlayfs-exec-guard/golangci-lint/test shards; TestOpenAPISpecCoversEveryRegisteredRoute; TestAgentsCollapsedSummaryRendersPerAgentTiles; TestStableNextPromotionAtUnknownWhenNothingQueued hitting live GitHub, stubbed by #10587), none of it from this docs diff. The fix landed on v5 at 6552932 (#10612).

Fix: sync your branch with v5 and push — git fetch upstream v5 && git merge upstream/v5 && git push (a merge commit keeps your DCO sign-offs intact; no force-push needed). CI will re-run on the green base.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Follow-up check report (fork branch — hive cannot push here): incident #10623 is now closed and v5 is green, but this head is still 97 commits behind v5 (compare/v5...mendezr:hive:docs/gh-aw-onramp-10625 → behind_by 97, mergeable_state dirty), so every red check above is still measuring the old baseline. No PR-local failure is visible in the diff (docs only).

Fix: git fetch upstream v5 && git merge upstream/v5 (resolve the docs conflict in favour of your additions), push, and let CI re-run. Nothing else should be needed.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[clubanderson]

Reviewed after rebase onto current v5. gh-aw facts match GitHub Agentic Workflows docs; workflow uses pinned checkout, minimal read permissions, no secrets on untrusted PRs, and compiles without engine credentials. prepare.py is JSON-only/no shell-out, and issue-classifier changes are env override defaults only. No required changes found.

[kubestellar-prow]

LGTM label has been added.

Details

Git tree hash: b6621901821be59800aa4f78df801e0ab7784f60

[clubanderson]

/approve
/lgtm

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: clubanderson

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [clubanderson]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment