Find useful improvements. Keep the working history with the harness. View the portfolio in one place.
- I don't understand any of this: Show me the visual map — a direct, illustrated introduction to the VSM approach.
- Web overview: opensiro.com
- How do I contribute? Contribute to OpenSiro with AI
- Contribution protocol: How Upstream works
- Published versions: GitHub Releases
You can follow a real improvement from source-backed investigation to an external PR and its observed status without learning the internal OpenSiro control structure. The contribution guide provides a copy-paste route for working with an AI agent.
Treat this README as the public handoff surface, then continue with the current shared START_HERE.md. For already tracked work use shared TODO.md; for new, unclassified, cross-repository or authority-sensitive work use CONTRIBUTOR_START.md.
If the bootstrap resolves Upstream work here, AGENTS.md, PROTOCOL.md, and docs/FORK_METADATA.md govern local contribution workflow. Verified fork-local .opensiro/ records, original third-party sources, and external PR facts remain authoritative in their respective owners. External-publication consent is required for each specific third-party action; this README grants no additional permission.
Upstream is the operational S1 domain of OpenSiro VSM OSS. It coordinates source-backed contributions to external AI harnesses without implementing a second VSM organization.
Protocol: v0.16.0 · How work proceeds · Fork metadata · Architecture · History · Releases
GitHub Releases publish tagged snapshots of the Upstream contribution protocol, not releases of third-party harnesses. The current protocol is v0.16.0; see its change package, changelog, and versioning rules. A release does not certify completion of historical migration, deployed value, external PR acceptance, or VSM autonomy.
Release cadence: protocol changes can accumulate in the Unreleased changelog without a new SemVer number for each PR. Only after the owner agrees a complete bundle do we finalize the numbered change package and publish one tag/Release at a verified commit. A VERSION on main may be newer than the latest published Release. For the current combined set, review the v0.16.0 release candidate, which covers the upgrade rules and activity updates since the published v0.13.0 baseline; it is not yet an approved or published release.
The new repository started its own history with v0.12.0. The predecessor's v0.1.0–v0.11.0 history stays with upstream-old; no tags or GitHub Releases are implied for that old history.
- Find: establish an original-source need and decide whether to explore a real improvement.
- Improve: implement and run native tests in a verified opensiro-contributions working fork.
- Offer: submit an external PR after the exact required approval; original maintainers decide what to merge.
- Observe: read the original PR status and update the related fork-local record. OpenSiro may keep working, watch, go dormant or archive the project; no compulsory maintenance TTL.
The human view is what happened, what is happening, what is next, and can I pause it? Each fork stores detailed records in .opensiro/ on its separate opensiro/meta branch, never in product/default/external PR branches.
| Data | Source of truth | What Upstream presents |
|---|---|---|
| Original product behavior and external PR reviews/merge status | Original upstream GitHub repository | Source-linked, dated live PR observation |
| Working product code, native tests and branch commits | opensiro-contributions matching fork | Links and status |
| OpenSiro attention, each improvement, decisions and operational transaction history | .opensiro/ on fork opensiro/meta |
Lightweight derived aggregate, not copied logs |
| Pre-fork intake / exceptional cross-fork migration decisions | A minimal Upstream issue | Research or coordination link, without pretending a fork exists |
| Organization-wide selected work, S2–S5 and metrics contract | VSM OSS Organization | No duplicate scheduler, VSM control plane or KPI |
Full architecture · Fork-local structure and owner STOP/RESUME · Migration programme #2
Fork-level attention: ACTIVE / WATCHING / DORMANT / ARCHIVED. These describe our discretionary effort, not the external PR. A project may be dormant indefinitely and may be reactivated. A human's PAUSE / STOP / RESUME decision is an attributable fork-local event; the executor must check it before a new effectful step. A committed file does not instantly kill an already executing process.
PR status is a separate, source-owned observation: OPEN (including draft as a qualifier), MERGED, CLOSED_UNMERGED or UNKNOWN. Green tests, a merge or an accepted PR do not alone prove deployed user value. We presently prioritize this simple public PR lifecycle telemetry; no public usefulness score has been established.
Source-linked issue decision watch: issue #22 adds source-linked fork-local `issue_watch` metadata and a six-hour public read-only GitHub Actions scan using the built-in `GITHUB_TOKEN`, with no additional secret or configuration. Read-only results appear in the run summary and artifacts as observations, not delivered alerts. Only optional durable fork-local event/cursor writes require `UPSTREAM_ISSUE_WATCH_ENABLED=true` and a separately scoped fork credential. No issue-watching mode creates external PRs, replies or maintainer decisions.
As of 2026-11-16 12:00 UTC, the 42 distinct original-repository PRs linked from 61 migrated improvement records: 11 merged, 24 open, 7 closed without merge, of which 0 have an explicit GitHub APPROVED review. These categories are source-observed PR lifecycle facts, not independent-improvement counts or deployed-benefit claims.
Full dated statistics, day-by-day counts, coverage and on-demand refresh instructions. Each square contains three independently shaded stripes: green published, blue merged, amber closed without merge; a purple dot marks a closed PR with a GitHub APPROVED review (currently 0). The SVG uses original event dates rather than metadata backfill commits and is a static, manually refreshable view, not a live counter.
upstream roadmap OWNER/REPO is a plan-only, read-only-by-default contribution route. It maps a pinned general assessment against current original code, issues, PR heads and unresolved user tasks, then proposes the smallest useful composable-first improvements. If the last successful Index review is more than 30 days old, recommend a source-pinned re-assessment before relying on old VSM grades; this is advisory, not a roadmap blocker, and a pending reassessment does not replace accepted evidence. It may finish with a draft architecture issue and no code changes. OpenSiro tests whether VSM-informed organizational specification (a hypothesis, not a mandate) can lower harness development/integration/maintenance cost versus simpler native alternatives; no savings are claimed without measurement. Maintainers may pursue product-native PRs, challenge/improve Profile or Skills, or try an optional domain-scoped fork.
Roadmap procedure · external issue draft · existing Upgrade. Public third-party communication still needs exact current-conversation approval.
upstream upgrade is a one-harness, end-to-end engineering route (FULL CYCLE). When no source is specified, run bounded preselection, choose one eligible original harness, then lock the entire run to that source. Within that harness, investigate additional real functional hypotheses if early ones fail; never switch to another original harness in the same invocation. The goal is real code on a correctly parented opensiro-contributions product branch, source-native tests and a fork-local PR for human review containing the exact prospective external PR. Creating even that public fork PR requires its own current-conversation approval; without approval, show the exact diff/compare and PR body without claiming a PR exists. An external PR is never posted without separate owner approval. Rights, CLA/DCO, DORMANT/PAUSE/STOP, lack of a qualified improvement, and unrun tests remain honest, source-local stop reasons; this is not a background agent or mandatory patch quota.
| Route | Meaning |
|---|---|
upstream upgrade |
One source → research → implementation → native tests → review PR in opensiro-contributions → human decision; no automatic external publication |
upstream upgrade OWNER/REPO or upstream upgrade <contribution-id> |
Same complete cycle, always restricted to the named original harness |
upstream upgrade VSM derived & informed only S5 (or another explicit S1–S5 function, optionally OWNER/REPO) |
Function-scoped one-harness full cycle: grounded need for that function before unspecified-source selection; after locking, pursue only same-harness, same-function evidence-backed hypotheses; normal native tests, fork-local review and publication gates remain unchanged. |
upstream upgrade batch 10 |
Ten distinct original harnesses, S1/S2/S3/S3*/S4/S5 source-backed dispositions each, focused native tests only where needed; not ten PRs, fixes or a new frozen cohort |
upstream batch [N] |
Separate technical/repair screening mode; it is not an alias for upgrade |
Function-scoped selection: an explicit function qualifier first narrows bounded read-only preselection to a real source-native user/agent outcome and the correct VSM decision/feedback right. It does not authorize adding S5 just because the Index reports S5 = —. For S5, identify legitimate ultimate-policy authority, an actual identity/policy issue, its decision, and observed return into later operation; static policy text, a guardrail or routine approval is insufficient. After selection, no other original and no other function may be substituted to avoid an honest blocked/no-change result. Function-first and closure gate.
Single-upgrade finish: show the actual review PR inside opensiro-contributions/<fork> once explicitly authorized and created, with original project/base, product head SHA, tested diff, native evidence, target-template-compliant prospective external title/body and current AI disclosure. A missing public fork-PR approval yields an exact read-only compare and draft, not a fictional PR URL. READY_FOR_HUMAN_PR_APPROVAL — NOT PUBLISHED is the reviewed-and-tested external publication handoff, never permission to open the original-repository PR. A source-local no-change or blocker ends this one-harness run; a new original requires a new user command. Batch modes stay chat-scoped research. Full protocol.
Resume without relying on chat history: Use the source-only Upgrade handoff generator with current fork-local contribution/state and verified GitHub SHAs, then check the exact draft body before any publication request. Missing five-link context or a later owner STOP blocks publication; re-read first-party GitHub and require new exact consent. This does not itself create or approve a PR.
Mandatory URL evidence: include clickable opensiro-contributions/<fork> working fork, product branch, exact commit, fork-local review PR and pinned .opensiro/ contribution record links both in the owner handoff and the proposed external PR body (inside its AI disclosure). The exact disclosure form and body-link preflight are requirements, not optional examples. A newly submitted external PR without its real fork-local review link is PR_BLOCKED_NO_WRITE; older published PRs without one must explicitly say NOT_CREATED, never fabricate prior review. Approval of public fork-local PR creation and later third-party publication remain separate.
All modes are operator phrases, not executable CLI commands. Functional opportunity, VSM/Index chronology, need/mechanism/counterfactual/scope, original-work alternative and native benefit must be distinguished. DORMANT / PAUSE allows no automatic engineering restart, and outward public third-party communication still requires exact current-conversation owner approval. v0.14.0 upgrade procedure.
Metadata coverage is part of Upgrade completion: before a single-source upstream upgrade can finish as READY_FOR_HUMAN_PR_APPROVAL, verify the correct working fork has .opensiro/state.json and its one stable improvement record on opensiro/meta. If the branch is confirmed absent, create it with the existing authorized GitHub tools, read back the exact commit and verify the contribution appears in the aggregate. Do not invent ALLOW, change a PAUSE/STOP, or write to product branches. An already opened external PR is linked to its canonical contribution, not opened again. Chat-only batches still do not create metadata merely for reports.
Formalities before popularity: for each new original-source candidate, first read the pinned source and actual license grant/text, contributor policy, CLA/DCO, issue/assignment requirements and available public access evidence. Reuse the existing read-only historical preflight rather than inventing a new runner. Only then rank sources screenable for read-only research by contributors; a license badge or a readable repository is not authorization to modify or publish. A named source bypasses popularity ranking, not this first screen.
Availability and rights requiring a person are deferred to a distinct Human gate — license, formalities & availability issue form, with first-party evidence and the exact requested decision. Search and reuse an existing matching request; create an internal issue only for a real decision that must be tracked, not for each batch or candidate. Read-only research may proceed where lawful and feasible, but no code/fork/external PR write is implied. Unknown evidence stays INSUFFICIENT_EVIDENCE, and DORMANT / PAUSE remains effective. Full preflight order.
For unassigned upstream upgrade, prioritize popular original harnesses only during bounded preselection (unique contributors first, stars as labeled fallback), then bind exactly one original harness before deep research. After binding, never rotate to another project within that invocation. For explicit multi-source research batches, retain first-pass coverage and the optional modest 1×–2× linear popularity weighting or uniform selection. Count actual independent contribution IDs rather than external PR URLs. No PR quota follows from ranking.
Batches live in the chat: upstream upgrade batch 10 and upstream batch 10 return source-linked per-project tables and a compact summary in the conversation. Do not create a batch issue, PR, frozen manifest, branch or scheduler just to report research. Reuse existing fork-local .opensiro/ records and historical native tests. An authorized real improvement may separately update its existing contribution record; PAUSE still prevents effectful work. Protocol.
A one-shot, read-only standard-library Python tool now derives a source-linked view from verified opensiro-contributions/* forks' opensiro/meta branches. It reads .opensiro/state.json, .opensiro/contributions/*.json, and the original external repositories' live PR APIs. Nothing is written back to forks, original PRs or Upstream; no scheduled sync, background service, extra ledger or mandatory maintenance TTL.
# Read two already verified pilot forks
python3 scripts/aggregate.py --format markdown \\
--repo opensiro-contributions/Citadel \\
--repo opensiro-contributions/agent-fleet
# Entire accessible public organization (can require authenticated API quota)
GH_TOKEN=... python3 scripts/aggregate.py --format json > snapshot.json
# On-demand state changes between two independently captured observations
python3 scripts/aggregate.py --format markdown --compare snapshot.json
# Alternative read-only views
python3 scripts/aggregate.py --format csv
python3 scripts/aggregate.py --only-active --format markdown
python3 scripts/aggregate.py --no-prs --format json--format is json, markdown or csv. --repo may be repeated to limit API reads; --only-active filters out WATCHING/DORMANT/ARCHIVED, not the current GitHub status of their PRs. The CLI reads an optional GH_TOKEN or GITHUB_TOKEN environment variable (never embeds it in output). A first-party external PR with state=closed and non-null merged_at is MERGED; closed without merged_at is CLOSED_UNMERGED; open (including draft) is OPEN; lookup failures and unverified links are UNKNOWN. The JSON output includes an observation timestamp and exact fork meta HEAD/blob SHAs. --compare reports known PR-status transitions relative to an earlier saved JSON report; it does not create an ongoing change log.
Automated activity dashboard refresh (derived-data direct commit): `Refresh Upstream external PR dashboard` runs every six hours, by manual dispatch, or after relevant source changes. It tests the native code, reads all verified fork metadata and original GitHub PR/review facts, then commits only `docs/ACTIVITY.md`, `docs/activity.svg` and `docs/activity-sources.json` directly to `main` after a complete scan. No new review PR or PR-creation permission is required for generated snapshots. Repeated unchanged observations create no commit; GitHub API errors fail closed, and non-force pushes respect concurrent updates and branch rules. The complete source receipt is preserved as a short-lived workflow artifact. This is derived telemetry, not an outcome or deployed-benefit KPI; source forks and third-party PRs remain read-only.
Contribution origin: every new fork-local improvement uses schema v2 origin classification with one of ASSESSMENT_DERIVED, ASSESSMENT_INFORMED, GENERAL_UPSTREAM or INSUFFICIENT and source-backed evidence. Historical v1 records with no class are still readable but explicitly reported as UNCLASSIFIED_LEGACY; neither GitHub PR count nor green native tests proves a VSM-derived improvement.
Coverage caveat: this is a partial, metadata-backed portfolio projection, not a reconstruction of the entire upstream-old portfolio. A source project without opensiro/meta is counted as missing metadata, not as having no contributions; historical inventory completion and deployed usefulness are not claimed. GitHub API failures remain explicit warnings, and incomplete scans exit nonzero. A merged PR alone is not a verified benefit or the Organization's verified_external_outcomes KPI.
Start from Organization START_HERE → ECOSYSTEM → AGENTS.md, the original source and the verified fork meta branch. Use Organization TODO.md for shared selection; never create a second scheduler. upstream discover / upstream continue <source or contribution> / upstream status are conversational routes, not installed commands or an autonomous service.
External-public consent: before any outward public third-party issue/comment/review/PR or public fork-local proposal, show the owner the exact target/action/final content and verified diff, and obtain explicit current-conversation consent. The active protocol gate preserves the historical gate. Neither this internal architecture approval nor passing tests grants external publication/CLA/merge rights.
Previous batches, issues, original evidence, registries, watcher scripts and protocol through v0.11.0 belong to opensiro/upstream-old. Migration guide · migration programme #2.
Migration status (2026-11-16): the bounded one-time historical backfill is closed with a source-linked reconciliation: 60 verified fork-local metadata destinations, 61 distinct contribution records, and explicit security/unmapped/skipped exceptions. This does not assert exhaustive migration of research-only history. The live outcome exporter and website sync are not migrated. Current Organization verified_external_outcomes is unclaimed for this new source, not zero. No migration percentage or live PR inventory is claimed merely because v0.13.0 docs exist. Old and new evidence must not be silently mixed.