Proposal: Contributor Quest Mechanics

How capOS can later use the adventure game as a playful interface for real open-source development work without confusing game rewards with repository authority.

Purpose

The current adventure proposal makes capability ideas playable inside capOS. This follow-up uses the same fiction and authority vocabulary to encourage real-world contributions to capOS itself.

An in-game officer, quartermaster, guild broker, temple witness, or academy scribe can issue “outer-world quests” such as:

Outer-world quest: fix https://github.com/<org>/<repo>/issues/123
Proof: merged PR linked to the issue and passing required checks
Reward: bug-hunter seal, review-lantern cloak clasp, +1 cohort standing

The goal is to make useful project work more visible and more fun:

• fix bugs,
• reproduce failures,
• write tests,
• improve docs,
• review security-sensitive changes,
• reduce flaky QEMU harnesses,
• triage issues,
• mentor new contributors,
• write design notes,
• run release checklists.

This must not become a substitute for maintainership, code review, or security policy. Real maintainers still decide what merges. The game records recognized contributions after normal project workflow has already accepted them.

Design Goals

• Make contribution paths discoverable for people who arrive through the demo.
• Reward real project progress without giving game systems repository power.
• Keep rewards mostly cosmetic, narrative, reputational, or convenience-level.
• Use full issue and PR URLs, commit hashes, and review records as evidence.
• Let maintainers mint or revoke recognition through explicit authority.
• Avoid incentives that make people spam issues, rush reviews, or optimize for game points over project quality.
• Preserve privacy: public contributions can be celebrated; private identity links require explicit consent.

Non-Goals

• No automatic merge, close, label, or assignment authority from the game.
• No token handling inside the game client.
• No paid bounty, token, cryptocurrency, or transferable reward system.
• No leaderboard that pressures security reviewers or maintainers into rushed public rankings.
• No reward that grants kernel, shell, broker, or repository authority.
• No reward that lets a player mutate another player’s profile or inventory.

Core Loop

The player sees an in-game quest board after the ordinary Aurelian campaign has enough profile state to matter.

1. A trusted quest issuer publishes a bounded list of outer-world quests.
2. The player claims or follows one quest, such as a GitHub issue.
3. The player does the work outside the game through normal GitHub and review workflow.
4. A maintainer or verifier records the accepted proof: merged PR, linked issue closure, accepted docs patch, reproduced bug log, or completed review.
5. The game mints an in-world mark, badge, decorative item, state, title, or bounded perk.
6. Debrief text explains what real contribution was recognized and why.

The game should phrase this as imperial frontier logistics rather than as a raw task tracker:

Quest Board: Outer Works

Issue 123: repair the failing run-adventure transcript.
Need: one merged fix and one reviewer witness.
Reward: Lanternwright badge, smoke-runner sash, cohort standing +1.

Reward Types

Rewards should be valuable enough to feel visible, but not strong enough to turn project contribution into a grind.

Badges

Badges are durable profile marks:

• bug-hunter: fixed a confirmed defect.
• smoke-runner: repaired or improved a QEMU proof path.
• doc-cartographer: improved docs, backlog, roadmap, or proposal clarity.
• review-witness: completed a substantive review accepted by a maintainer.
• security-sentinel: closed or helped validate a security finding.
• first-boot-guide: helped a new contributor get a local boot/test flow.
• release-quartermaster: completed release or dependency audit work.

Badges are evidence-backed, not self-declared. A badge record includes the proof URL or commit hash, issuer, timestamp, and short reason.

States

States are temporary profile or expedition conditions:

• on outer patrol: player has claimed or followed an issue.
• awaiting witness: contribution submitted, waiting for review/verification.
• maintainer witnessed: accepted proof exists, reward can be minted.
• needs reproduction: player is gathering logs or QEMU transcript evidence.
• blocked by design: task needs a proposal or maintainer decision first.

States should expire or be explicitly cleared. Stale states must not block the player from ordinary game progress.

Decorative Items

Decorative items are visible in the game world without granting project power:

• review lantern,
• smoke-runner sash,
• warded keyboard,
• cartographer map case,
• broken-panic trophy,
• issue-forged signet,
• release quartermaster ledger,
• first-boot camp banner.

Decorative items can appear in status, profile views, housing, tavern dialogue, party banners, or debrief records.

Perks

Perks must stay bounded and low-risk:

• title choices in chat or debrief text,
• cosmetic room decorations,
• additional flavor dialogue from NPCs,
• small convenience options inside adventure missions,
• access to optional lore logs or museum rooms,
• non-combat party banner effects.

Avoid perks that create an optimal gameplay path only available to frequent contributors. The point is recognition and orientation, not a second economy.

Quest Types

First Contribution

Real-world task:

• make a first accepted contribution to capOS,
• pass the relevant checks,
• respond to review without needing maintainer rescue,
• leave the touched docs, tests, or code in a maintainable state.

Game framing:

• receive a recruit’s field mark,
• cross the first gate under supervision,
• return with a witnessed service record.

Reward examples:

• first-gate badge,
• recruit sash,
• academy standing,
• optional mentor thank-you record.

This quest should reward the first accepted contribution once, not every small patch. It exists to make the contributor path visible and to recognize the friction of getting a local toolchain, QEMU proof, review loop, and project style working for the first time.

Bug Hunts

Real-world task:

• fix a confirmed GitHub issue,
• add regression coverage,
• preserve or improve relevant QEMU transcript assertions.

Game framing:

• track a breach,
• seal a faulty gate,
• prove the fix with a witness log.

Reward examples:

• bug-hunter badge,
• broken-panic trophy,
• cohort standing.

Smoke Runner Work

Real-world task:

• improve make run-* smoke stability,
• add missing transcript assertions,
• reduce brittle sleeps,
• preserve password/log redaction.

Game framing:

• run the frontier signal route,
• repair a proof beacon,
• return with a clean gate log.

Reward examples:

• smoke-runner sash,
• transcript lantern,
• scout standing.

Documentation Cartography

Real-world task:

• improve WORKPLAN.md, backlog files, roadmap, proposal status, runnable demo docs, or research grounding,
• remove stale status claims,
• clarify next-step sequencing.

Game framing:

• update the imperial route map,
• reconcile witness records,
• mark safe roads for new operators.

Reward examples:

• doc-cartographer badge,
• map-case decoration,
• academy scribe title.

This should include small docs corrections, but the higher reward tier should require work that materially improves future contributors’ ability to navigate the project: clearer milestone state, sharper backlog decomposition, better runbook steps, or removal of misleading/stale status text.

Accepted Design Proposal

Real-world task:

• submit a design proposal that maintainers accept,
• ground it in existing project docs and relevant research when needed,
• update proposal indexes and any affected roadmap/backlog status,
• respond to review by narrowing unsafe scope or documenting tradeoffs.

Game framing:

• present a plan before the imperial council,
• have temple witnesses validate the authority chain,
• receive a sealed charter for future field work.

Reward examples:

• charter-writer badge,
• council seal,
• strategy-table decoration,
• design-witness title.

“Accepted” means the proposal is merged or explicitly recorded as accepted in the repository. Drafts, brainstorms, and abandoned proposals can still receive ordinary participation flavor, but they should not mint the accepted-design badge.

Security Witnessing

Real-world task:

• review trust-boundary changes,
• close a REVIEW_FINDINGS.md item,
• add proof coverage for hostile input,
• update security docs when a boundary changes.

Game framing:

• testify before the temple annex,
• certify relic custody,
• expose a forged writ.

Reward examples:

• security-sentinel badge,
• temple witness seal,
• lawful-custody title.

Mentorship And Onboarding

Real-world task:

• help a contributor get local builds, tests, QEMU, or docs working,
• improve setup notes based on observed friction,
• pair on a first small patch.

Game framing:

• guide a new recruit through the gate yard,
• issue safe training writs,
• staff the frontier academy.

Reward examples:

• first-boot-guide badge,
• recruit banner,
• academy standing.

Evidence Model

Each recognized contribution should produce a bounded ContributionEvidence record:

quest_id
kind
full_issue_url
full_pr_url
commit_hash
issuer
subject_profile
summary
accepted_at
reward_ids
revoked

The evidence record is not a legal identity document. It is a project-visible game record that says a maintainer or authorized verifier recognized a public contribution.

Use full URLs for GitHub issues and PRs. Do not rely on shorthand issue numbers without repository identity.

Capability Mapping

The game must never turn a decorative badge into OS or repository authority. If a future broker uses contributor standing, it must be for game/social features unless a separate security design explicitly says otherwise.

Service Architecture

Keep this out of the core adventure service until the base game is stable.

Target split:

flowchart TD
    GitHub[GitHub / Forge] --> Importer[Quest Importer]
    Maintainer[Maintainer Session] --> Witness[Contributor Witness]
    Importer --> Board[Quest Board]
    Witness --> Rewards[Reward Mint]
    Rewards --> Profile[AdventureProfileService]
    Rewards --> Ledger[AdventureLedger]
    Client[Adventure Client] --> Board
    Client --> Profile

Initial implementation can be manual:

• a checked-in or manifest-provided quest list,
• maintainer-issued proof records,
• no network calls from capOS to GitHub,
• no tokens in the demo VM.

Reward records use the adventure persistence split:

• quest definitions and fixture issue lists are content/catalog data;
• claims and temporary states are profile state;
• accepted proof, issuer, timestamp, reward mint, and reward revocation are append-only ledger records;
• badge, title, decoration, and cosmetic summary fields are applied to AdventureProfileService only after a matching ledger record exists.

Later implementation can add a ForgeConnector service with narrow read-only authority:

• list selected issues by repository and label,
• fetch merged PR metadata,
• verify commit hashes or check statuses,
• never mutate GitHub state.

Any mutating forge integration, such as labels or comments, requires a separate security proposal and must not be hidden inside the game service.

Abuse And Incentive Controls

The system should discourage low-quality contribution farming.

• Rewards are maintainer-witnessed, not automatically minted from activity.
• Repeated trivial fixes should not produce unbounded badges.
• Security review rewards should avoid public speed rankings.
• Issue claiming inside the game must not block real contributors on GitHub.
• Reward descriptions should name quality criteria: tests, docs, review, and accepted project value.
• Maintainers can revoke or amend mistaken rewards with an audit note.
• Public profiles should allow hiding or unlinking personal identity details.

Privacy And Identity

Players may want to keep game profiles and GitHub identities separate.

Rules:

• Linking a game profile to a GitHub account must be explicit.
• Public GitHub evidence can be recorded as a URL without exposing private tokens or session state.
• Private email addresses, tokens, and local machine paths must never appear in reward records.
• The game can show “verified public contribution” without requiring the player to reveal more than the accepted public artifact.
• If OIDC or passkeys later connect identity, use the user/session/policy proposals rather than adding identity shortcuts to the game.

Command Surface

Candidate commands after the base adventure command surface exists:

quests
quest inspect <quest-id>
quest follow <quest-id>
quest evidence <quest-id>
badges
badge inspect <badge-id>
decorate <slot> with <item-id>
title set <title-id>
profile share <public|private>

Maintainership commands must be separate and authority-gated:

quest publish <quest-id>
quest witness <quest-id> for <profile> with <proof-url>
reward mint <reward-id> for <profile>
reward revoke <reward-id> for <profile>

These are typed service calls, not shell-special strings.

Implementation Phases

Phase A: Manual Recognition

• Add this proposal to the proposal index and docs summary.
• Define bounded quest, evidence, badge, state, decoration, and perk data records.
• Store accepted proof and reward mint/revocation as append-only AdventureLedger records, then derive visible profile badges from those records.
• Add a small checked-in sample quest list using full GitHub issue URLs.
• Add manual witness records in test content.
• Show badges/decorations in profile/status output.
• Add QEMU proof that a witnessed quest mints a cosmetic badge and that an unwitnessed claim does not.

Phase B: Game Integration

• Add an in-game quest board location after the Aurelian campaign.
• Add NPC dialogue that points contributors toward real project workflows: reproduce, test, document, review, and submit.
• Add debrief text that ties accepted contribution evidence to in-world recognition.
• Keep all rewards non-authority unless a separate reviewed design grants narrow game-only authority.

Phase C: Forge Read Model

• Add a read-only forge import path for selected repositories and labels.
• Verify merged PRs, issue links, check statuses, and commit hashes without storing tokens in game state.
• Add host tests for malformed URLs, cross-repository ambiguity, oversized metadata, and stale proof records.
• Add QEMU smoke using fixed fixture data rather than live network calls.

Phase D: Community Events

• Model release weeks, bug hunts, docs sprints, and review days as bounded seasonal quest boards.
• Add group recognition for cohorts without ranking individuals by raw activity count.
• Add opt-in public profile export for contributor showcases.

Open Questions

• Who can witness rewards before durable maintainer identity exists inside capOS?
• How should reward revocation be displayed without creating public shaming mechanics?
• Can issue labels be imported read-only without making GitHub availability a boot or smoke-test dependency?
• What is the smallest useful “perk” that feels meaningful while remaining non-authoritative?
• Should a local-only demo use fictional fixture issue URLs, real capOS issue URLs, or both?

Design Grounding

Grounding files for this proposal:

• docs/proposals/aurelian-frontier-proposal.md
• docs/backlog/aurelian-frontier.md
• docs/proposals/storage-and-naming-proposal.md
• docs/proposals/interactive-command-surface-proposal.md
• docs/proposals/user-identity-and-policy-proposal.md
• docs/proposals/oidc-and-oauth2-proposal.md
• docs/proposals/security-and-verification-proposal.md
• docs/security/trust-boundaries.md
• WORKPLAN.md
• REVIEW_FINDINGS.md

No docs/research/ report is directly applicable at this stage. This proposal is community workflow and game-design planning layered on existing project proposal documents, not a new OS/runtime architecture claim.