feat(rpi): enable repository-backed shared work handoffs

[Katrien De Graeve (katriendg)]

Description

Added an optional shared-work-handoff RPI skill that projected explicitly selected local context into a minimized, checked-in continuation record for a named recipient. The handoff remained contextual evidence rather than canonical project authority, and publication, recipient response, revision reconciliation, and closure each required explicit actors and verified lifecycle transitions.

Handoff contract and storage

• Defined prepare, resume, and close intents with separate preview and finalize stages.
• Added a provider-neutral storage port and the initial repository-files adapter, with one Markdown record per handoff under .hve/handoffs/ by default.
• Required bounded source selection, disclosure authority, audience and actor identity, retention posture, optimistic concurrency, and post-publication commit and blob verification.
• Blocked publication when selected evidence was inaccessible or content required unsupported disclosure, retention, or physical-erasure guarantees.

RPI continuation and lifecycle

• Projected mode outcomes, supplied context, material issues and learnings, phase state, completion meaning, pause point, and the exact next action without publishing raw private workflow state.
• Bound recipient acceptance to one verified semantic revision and required explicit source-baseline selection when the source branch advanced or diverged.
• Preserved terminal-state exclusivity for adoption, closure without adoption, withdrawal, and supersession while keeping canonical adoption human-owned.

Documentation, packaging, and coverage

• Added the publisher-to-recipient guide and updated RPI, installation, utility-role, plugin, architecture, and generated reference documentation to distinguish workspace-local evidence from checked-in handoffs.
• Registered the skill in the plugin manifest.
• Added 11 advisory behavior-conformance scenarios for preparation, disclosure and erasure blocks, conflicts, recipient authority, RPI projection, source boundaries, branch advancement, closure, and later evidence reuse.

Related Issue(s)

Fixes #2815

Type of Change

Select all that apply:

Code & Documentation:

• Bug fix (non-breaking change fixing an issue)
• New feature (non-breaking change adding functionality)
• Breaking change (fix or feature causing existing functionality to change)
• Documentation update

Infrastructure & Configuration:

• GitHub Actions workflow
• Linting configuration (markdown, PowerShell, etc.)
• Security configuration
• DevContainer configuration
• Dependency update

AI Artifacts:

• Reviewed contribution with hve-builder and addressed all actionable findings
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• Copilot agent (.github/agents/*.agent.md)
• Copilot skill (.github/skills/*/SKILL.md)
• Copilot hook (.github/hooks/*/*.json)
• Eval spec added/updated for changed AI artifacts (evals/)

Note for AI Artifact Contributors:

• Agents: Research, indexing/referencing other project (using standard VS Code GitHub Copilot/MCP tools), planning, and general implementation agents likely already exist. Review .github/agents/ before creating new ones.
• Skills: Must include both bash and PowerShell scripts. See Skills.
• Model Versions: Contributions MUST target models listed in the model catalog (scripts/linting/model-catalog.json) whose provider appears in providerAllowlist and whose status is ga or preview. Run npm run lint:models to validate references.
• See Agents Not Accepted and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

/shared-work-handoff prepare preview provider=repository-files target=.hve/handoffs/cache-retry.md

Prepare a handoff from these explicit sources:
* Private working artifact: .copilot-tracking/research/2026-08-31/cache-retry-research.md
* Private working artifact: .copilot-tracking/plans/2026-08-31/cache-retry-plan.md
* Shared repository artifact: src/cache/retry.ts
* Shared repository artifact: tests/cache/retry.test.ts
* External reference: public retry guidance at <public URL>

Publisher: Developer A
Publisher role: publisher with disclosure authority
Recipient: Developer B
Conflict resolver: Cache maintainers
Canonical owner: Cache maintainers
Audience: repository contributors
Disclosure authority: approved for this audience
Sensitivity: repository-safe after minimization
Retention: repository history is acceptable
Review horizon: 7 days
Source branch: feature/cache-retry
Observed source revision: resolve the current HEAD commit
Source state: clean
Expected predecessor revision: none; this is the first publication

Render the exact proposed handoff and publication action. Do not commit, push,
publish, or call the handoff shared during preview. Summarize private working
artifacts without copying their paths or bodies into the handoff.

Execution Flow:

1. Validate the explicit intent, stage, provider, target, actors, audience, authority, retention posture, source selection, and expected revision.
2. Project the selected evidence into the minimized portable handoff template and report any blocking disclosure, erasure, path, or accessibility issue.
3. Render the exact repository mutation and publication action during preview without performing Git or GitHub writes.
4. After separately authorized publication, re-read the selected shared reference and verify handoff identity, semantic revision, predecessor evidence, commit, and blob before returning shared status.

Output Artifacts:

---
title: "Shared Work Handoff: <stable-id>"
description: Minimized continuation context for an explicitly named audience
handoff_id: "<stable-id>"
semantic_revision: 1
created_at: "<ISO 8601 timestamp>"
updated_at: "<ISO 8601 timestamp>"
expires_at: "<ISO 8601 timestamp>"
publisher: "Developer A"
intended_recipients:
	- "Developer B"
canonical_owner: "Cache maintainers"
conflict_resolver: "Cache maintainers"
sensitivity: "repository-safe after minimization"
retention: "repository history is acceptable"
authority: continuation-context
superseding_handoff: "none"
---

## Scope

* Objective: <minimized objective from explicitly selected sources>
* Current status: <current RPI mode and phase>
* Next action: <exact next RPI action>

## RPI Continuation

Success Indicators:

• Preview showed the exact proposed mutation without writing Git or GitHub state.
• Finalize returned shared status only after re-reading and verifying the selected repository object.
• Resume exposed source-revision drift and required an explicit continuation baseline before recipient acceptance.
• Close recorded exactly one authorized terminal disposition without granting canonical authority.

Review the expected two-person outcome in Follow a Developer A-to-Developer B Example. The walkthrough shows the rendered RPI continuation fields, a phase-1-of-4 pause, branch advancement, Developer B's baseline choice, and the next RPI action.

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

Automated validation covered artifact structure, packaging, documentation, YAML, spelling, diff hygiene, and focused advisory model behavior.

• npm run validate:skills passed for all 76 skill directories with no errors or warnings.
• npm run plugin:validate passed with plugin and catalog membership synchronized.
• npm run validate:docs passed 10 Jest suites (78 tests) and 11 Mermaid accessibility tests.
• npm run spell-check passed all 825 checked files after adding the intentional regex stems to the eval spec's cspell ignore header.
• npm run lint:yaml and git diff --check passed.
• npm run lint:md-links failed on external URLs in six unchanged files. The same lane prevented npm run validate:local from completing successfully.
• The handoff-only Vally run executed all 11 stimuli three times with gpt-5.6-luna. All 33 resulting trajectories passed every finalized grader during offline regrading.

The behavior-conformance additions remain advisory. The focused result verifies the calibrated handoff cases locally; the hosted full suite remains pending CI.

For manual reviewer verification, replace the illustrative source paths and public URL in the sample with repository-safe fixture sources, then run the /shared-work-handoff prepare preview call. Confirm that it renders, but does not publish, a prepared record containing mode history, supplied context, issues and learnings, the four-phase map, pause point, and exact next RPI action. Compare the result with the Developer A-to-Developer B walkthrough.

Checklist

Required Checks

• Documentation is updated (if applicable)
• Files follow existing naming conventions
• Changes are backwards compatible (if applicable)
• Tests added for new functionality (if applicable)

AI Artifact Contributions

• Used hve-builder review mode to review contribution
• Addressed all actionable findings from the hve-builder review
• Verified contribution follows common standards and type-specific requirements

Required Local Checks

The following local-safe validation commands must pass before merging:

• Local validation aggregate: npm run validate:local
• Documentation validation (if docs changed): npm run validate:docs
• Spell checking: npm run spell-check
• Link validation: npm run lint:md-links

Security Considerations

• This PR does not contain any sensitive or NDA information
• Any new dependencies have been reviewed for security issues
• Security-related scripts follow the principle of least privilege

Additional Notes

The new storage adapter is a declarative contract rather than an executable SDK or runtime provider. Behavior coverage is advisory and uses output-matches graders to exercise the documented boundaries.

Link validation could not confirm external references in .github/instructions/rai-planning/rai-license-posture.instructions.md, .github/skills/coding-standards/code-review/references/change-risk-model.md, .github/skills/project-planning/security-planning/references/data-classification.md, .github/skills/rai/rai-standards/references/eu-ai-act.md, .github/skills/rai/rai-standards/SKILL.md, and GOVERNANCE.md. None of those files changed in this PR.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.10%. Comparing base (c7ee5b9) to head (361fbdd).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2816      +/-   ##
==========================================
- Coverage   83.11%   83.10%   -0.01%     
==========================================
  Files         183      183              
  Lines       34165    34165              
  Branches       25       25              
==========================================
- Hits        28395    28394       -1     
- Misses       5767     5768       +1     
  Partials        3        3              

Flag	Coverage Δ
docusaurus	89.92% <ø> (ø)
pester	83.86% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Eval Execution

✅ Status: Passed — no merge-blocking failures (1 advisory assertion failure(s) present)

• Artifacts evaluated: 1
• Specs run: 1
• Assertions passed: 32
• Assertions failed (blocking): 0
• Assertions failed (advisory): 1
• Failed specs (merge-blocking): 0

Artifact	Kind	Status	Specs	Passed	Failed (blocking)	Failed (advisory)
shared-work-handoff	skill	⚠️ advisory-fail	1	32	0	1

Legend — ✅ clean · ⚠️ advisory failures only (non-blocking) · ⏭️ skipped · ❌ merge-blocking failure

Only Failed specs (merge-blocking) gates this PR. Advisory assertion failures are signal-quality checks captured during iteration; review them, but they do not block merge and may be acceptable.