Fix orchestrator implementation-swarm allowlist and add agent onboarding

[AlexMikhalev]

Summary

• recognise implementation-swarm via the orchestrator KG-driven allowlist
• document ADF fleet allowlist remediation and binary provenance evidence
• add an AI Agent Onboarding Quickstart and link it from README and mdBook summary

Validation

• pre-commit checks passed for the latest documentation commit
• mdbook test docs completed without errors when adding the onboarding guide
• release/autoupdate validation for terraphim-clients v1.21.8 completed separately

Notes

• This branch also has an existing Gitea PR: terraphim/terraphim-ai#3065

[github-actions]

Documentation Preview

Your documentation changes have been deployed to:
https://cb40c395.terraphim-docs.pages.dev

This preview will be available until the PR is closed.

[AlexMikhalev]

Summary

This PR updates ADF auto-merge author recognition to use a KG-backed recognised-agent allowlist, records the remediation/provenance plan, and adds an AI-agent onboarding quickstart to the public documentation.

• KG-backed allowlist: agent_allowlist_kg loads recognised fleet logins from recognised_agents.md, with an environment override and embedded fallback.
• Auto-merge policy wiring: poll_pending_reviews now injects the loaded allowlist into AutoMergeCriteria, while pr_review keeps policy evaluation pure and I/O-free.
• Documentation: the ADF remediation artefacts and onboarding quickstart make the operational workflow and agent handoff expectations clearer.

The architecture is generally sound: the filesystem boundary is isolated in one loader module, the policy functions remain pure, and the new documentation is discoverable from both README and mdBook summary. The main issue is test drift: one gate-evaluation test still checks the pre-change orchestrator.toml guidance, so the PR as submitted can fail when that test is exercised.

Confidence Score: 3/5

• Safe to merge with caution after fixing the stale test assertion.
• I found 1 P1 correctness/CI issue and no P0 issues. The implementation direction is clean, but the stale assertion directly contradicts the new allowlist location and should be fixed before merge.
• Files requiring attention: crates/terraphim_orchestrator/src/pr_poller.rs.

Important Files Changed

Filename	Overview
crates/terraphim_orchestrator/src/agent_allowlist_kg.rs	New KG loader for recognised agent logins. The I/O boundary is isolated and parsing is unit-tested.
crates/terraphim_orchestrator/kg/recognised_agents.md	New KG concept backing the allowlist. Contains the intended implementation-swarm entry.
crates/terraphim_orchestrator/src/pr_review.rs	Extends auto-merge criteria with a caller-provided recognised-login set and keeps author policy pure. No issue found.
crates/terraphim_orchestrator/src/pr_poller.rs	Evaluates PR gates using the shared author-rejection helper, but one test still expects the old config-file hint. Needs attention.
crates/terraphim_orchestrator/src/auto_merge_impl.rs	Loads the KG allowlist once per pending-review poll and passes it into gate evaluation. No issue found.
crates/terraphim_workspace/src/lib.rs	Adjusts the path-inside-root test to use the canonicalised manager root. No issue found.
docs/src/howto/ai-agent-onboarding-quickstart.md	Adds practical onboarding guidance for AI agents, including search, Gitea, quality gates, and release checks. No issue found.
README.md / docs/src/SUMMARY.md	Link the new onboarding guide from top-level and mdBook navigation. No issue found.

Diagram

%%{init: {"theme": "neutral"}}%%
flowchart TD
    A[Reconcile tick] --> B[poll_pending_reviews]
    B --> C[load_recognised_agents]
    C --> D{ADF_RECOGNISED_AGENTS_KG or kg/recognised_agents.md readable?}
    D -->|yes| E[Parse synonyms:: logins]
    D -->|no| F[Use embedded recognised_agents.md]
    E --> G[AutoMergeCriteria.recognised_agent_logins]
    F --> G
    G --> H[evaluate_pr_gates]
    H --> I{PR author recognised or adf- prefix?}
    I -->|yes| J[Continue status and gate-result checks]
    I -->|no| K[HumanReviewNeeded with allowlist hint]
    J --> L{All required contexts and gate results pass?}
    L -->|yes| M[Enqueue AutoMerge]
    L -->|no| N[Awaiting/Stale/Human review outcome]
    C:::new
    E:::new
    G:::new
    classDef new fill:#d4edda,stroke:#28a745;

Loading

Inline Findings

P1 crates/terraphim_orchestrator/src/pr_poller.rs, line 730: Stale assertion still expects the old allowlist location

The implementation intentionally moved the operator hint from orchestrator.toml to the KG allowlist file via agent_author_rejection_reason, which now says to add the login to crates/terraphim_orchestrator/kg/recognised_agents.md. This test still asserts that the reason contains orchestrator.toml, so it no longer matches the production behaviour introduced by this PR.

Consequence: the gate-evaluation test will fail when run, and it also documents the wrong remediation path for operators. Update the assertion to match the new KG-backed allowlist location, for example:

assert!(
    reason.contains("kg/recognised_agents.md"),
    "reason must point to the KG allowlist file, got: {reason}"
);

Comments Outside Diff (0)

_{Last reviewed commit: 92c2f82 | Reviews (1)}

[AlexMikhalev]

Addressed the structural review finding in 58ad974. The stale test assertion now checks for , matching the KG-backed allowlist hint emitted by . Also applied rustfmt formatting in the same file.

Validation:

• Commit pre-commit hook passed: Rust formatting, cargo check, clippy, build, and tests.

Note: direct focused cargo commands for remain awkward in this checkout because the crate is not an active workspace member and package resolution is ambiguous without the hook-driven workspace path.

[github-actions]

Documentation Preview

Your documentation changes have been deployed to:
https://ee780277.terraphim-docs.pages.dev

This preview will be available until the PR is closed.

[AlexMikhalev]

Correction to the previous validation note: addressed the structural review finding in commit 58ad974. The stale pr_poller.rs test assertion now checks for kg/recognised_agents.md, matching the KG-backed allowlist hint emitted by agent_author_rejection_reason. Also applied rustfmt formatting in the same file.

Validation:

• rustfmt --edition 2021 --check crates/terraphim_orchestrator/src/pr_poller.rs
• Commit pre-commit hook passed: Rust formatting, cargo check, clippy, build, and tests.

Note: direct focused cargo commands for terraphim_orchestrator remain awkward in this checkout because the crate is not an active workspace member and package resolution is ambiguous without the hook-driven workspace path.