Framework Upstream Auto Update

Framework Upstream Auto-Update

Trigger

• Daily cron (see config.json crons entry daily-framework-upstream-auto-update).
• Ad hoc if [ORCHESTRATOR] or a user asks for an upstream check.

Owner

[AGENT_NAME] owns upstream framework health for the cortextos workspace. Bug fix application authority should be documented in your MEMORY.md or deployment config. Feature-level changes always route to [ORCHESTRATOR], who routes to the user for approval.

Inputs

• Framework repo: the cortextos workspace root (the CTX_ROOT parent — the git repo, not the state dir)
• Upstream: upstream/main (verify with git remote -v if unsure)
• Current local state: local main can run ahead of upstream (your local fixes may flow upstream). Do NOT try to "sync" ahead-commits downward.

Procedure

Step 1 — Fetch and inspect

cd /path/to/cortextos
cortextos bus check-upstream

Read the output. If it reports no new commits, skip to Step 7 (log noop and stop).

If there are new commits, list them:

git fetch upstream main
git log --oneline HEAD..upstream/main

Step 2 — Classify each commit

For each new commit, read the subject and the diff:

git show --stat <sha>
git show <sha>

Classification buckets:

Step 3 — Check touched paths (HARD GUARDRAIL)

For EVERY new commit, scan the diff for touched paths. If ANY of the new commits touch any of these paths, do NOT auto-apply anything, flag the whole batch to [ORCHESTRATOR], and stop:

• orgs/ — multi-tenant configuration, never auto-merge
• **/.env* — credentials and secrets
• **/memory/ (agent memory subfolders)
• **/MEMORY.md (agent-level long-term memory)
• community/skills/ — community skill catalog changes that affect running agents
• community/agents/ — community agent templates that affect running agents

When flagging: collect the commit SHAs, commit messages, and touched paths, and send them to [ORCHESTRATOR] via cortextos bus send-message [ORCHESTRATOR] normal '<summary>'. Do not apply.

Step 4 — Apply safe bugfix / docs / chore commits

If all new commits are pure bugfix or docs/chore AND none touch the guardrail paths:

cd /path/to/cortextos
CORTEXTOS_CONFIRM_UPSTREAM_MERGE=yes cortextos bus check-upstream --apply

The CORTEXTOS_CONFIRM_UPSTREAM_MERGE=yes env var is required. Without it, check-upstream --apply returns {"status": "error", "error": "Refusing to auto-merge upstream..."} as a safety gate. The env var is the "I have reviewed the diff and I trust the changes" signal. Set it inline, not exported, so it does not leak into subsequent unrelated commands.

After applying:

cd /path/to/cortextos
npm install
npm audit --audit-level=moderate
npm run build
npm test

Security gate (v2): npm audit --audit-level=moderate runs AFTER npm install and BEFORE the build/test gate. If it reports any moderate+ vulnerability:

• BLOCK the merge — do NOT proceed to build/test
• Record the audit output (advisory IDs, affected packages, severity)
• Report to [ORCHESTRATOR]: "Upstream merge blocked by npm audit: [advisory IDs]. Packages: [list]. Severity: [level]. Manual resolution required."
• The merge stays unapplied until the vulnerability is resolved (upstream fix, manual override, or dep pin)

This gate catches security regressions where upstream merges silently downgrade a dependency that was previously patched (e.g. carrying a pinned old version that reintroduces a known CVE).

Build and test must also succeed. If either fails, DO NOT revert silently — report the failure to [ORCHESTRATOR] with the full error output and wait for instructions. The framework remains in its applied state; [ORCHESTRATOR] will decide whether to revert or patch.