UPSTREAM.md

Upstream maintenance

This repository derives from pstack in https://github.com/cursor/plugins. The locked source is version 0.15.2 at commit 889ec4b68fa5aab0e867dad71ec3fdf386ae48f3.

The delivered repository contains only the modified Codex version. Do not push a raw upstream branch or snapshot commit. Do not keep an upstream remote in the delivered checkout.

Codex-owned execution policy

skills/poteto-mode/references/codex-agent-runtime.md, skills/poteto-mode/references/codex-parallelism.md, and skills/poteto-mode/references/codex-run-evidence.md are local extensions, not upstream source files. The runtime contract is the single loading point for scheduling, lightweight run evidence and skills/poteto-mode/references/codex-delivery-flow.md. The optional codex-run-record-tools.md reference retains structured receipt instructions without loading them for every implementation. Keep execution preferences there instead of duplicating them across upstream skills. Model routing remains in the existing registry, and workflow acceptance and verification requirements remain authoritative. The Codex-owned skills/setup-pstack/references/model-defaults.json holds bundled model choices and panel sizes; preserve it during upstream refreshes. The installer and runtime resolver omit obsolete default markers when bundled panels shrink, preserving explicit lanes and their policy records. Keep the upgrade regression in tests/setup-receipt.test.mjs; a separate adapter cannot fix validation before registry loading.

Preserve these extensions during upstream refreshes. Review their semantics against changed workflows, including dependencies, ownership, and required gates. Keep their loading and behavioral checks in tests/codex-parallelism.test.mjs and evals/cases/codex-parallelism.json.

For a live behavioral check, generate scenarios without reference answers using node scripts/grade-parallelism-eval.mjs --inputs. Give those scenarios to a fresh agent through the runtime contract. Request a JSON array with id, dispatch, blocked, close, invalidate, coordinator, and canFinish for each scenario. The evaluation plans actions only; it must not execute them. Save the response and run node scripts/grade-parallelism-eval.mjs <answers.json>. Offline tests validate loading and grading, not model behavior. Retain live results separately and repeat them when scheduling semantics change.

The Codex-owned run tools are scripts/run-record.mjs, scripts/lib/run-record.mjs, scripts/render-run-report.mjs, and scripts/benchmark-runs.mjs. Preserve them and their tests/run-*.test.mjs checks during refreshes. They capture local evidence and produce reports; they neither perform external closeout actions nor replace required verification. Project-specific release helpers belong in the target project, outside this plugin.

The standalone prompt refresh extension consists of skills/setup-pstack/scripts/refresh-agent-prompts.mjs, skills/setup-pstack/references/agent-prompt-refresh.md, and tests/agent-prompt-refresh.test.mjs. Its small loading reference belongs in the existing Codex model adapter. Preserve it during refreshes and check compatibility with the installer receipt schema; prompt refresh must retain user configuration and expose, rather than silently adopt, model-registry drift.

The existing Codex installer also rejects preserved-unverified records before rewriting files. This small guard belongs at the write boundary in manage-agents.mjs: a separate refresh helper cannot prevent a later installer from discarding preserved configuration.

The narrow edits to Figure it out, Show me your work and Opening a PR remove conflicting requirements for duplicate per-unit logs, automatic standalone trail review and user-prompt-only feedback collection. A separate extension cannot resolve those direct requirements on its own. Preserve their explicit loading links and standalone user-requested audit behavior during refreshes. Workflow evaluation cases exercise these transitions without reducing verification or permission gates.

The optional assignment tools (scripts/assignment-record.mjs, scripts/lib/assignment-record.mjs, tests/assignment-record.test.mjs) and skills/poteto-mode/references/codex-assignments.md are Codex-owned. The parallelism adapter loads their usage only when complex handoffs benefit from a record. They check declared readiness and result revisions without starting agents or granting integration authority.

skills/poteto-mode/references/codex-verified-execution.md documents the Codex-owned run tools' reconstructable snapshots, proof milestones, exact-checkout preflight and selective freshness rules. Its loading points are delivery flow and the optional run-record manual. Keep native/provider proof semantics in the project harness; generic milestone checks cannot establish those facts alone.

The offline history tools (scripts/analyze-history.mjs, scripts/lib/history-analysis.mjs, tests/history-analysis.test.mjs) and skills/conversation-audit/references/history-analysis.md reconstruct audit facts from supported exports. They never scrape private stores or infer active time from gaps. Preserve the input-binding and overlap tests during refreshes.

The usage audit extension (scripts/audit-usage.mjs, scripts/lib/usage-audit.mjs, tests/usage-audit.test.mjs, and tests/fixtures/usage-audit/) is Codex-owned. The conversation-audit skill loads references/usage-attribution.md for usage questions; it reuses the history graph and reviewed dispatch projections. Preserve its caching, retry, attribution, privacy, and quarantine tests. Its OpenCodex attribution contract is a proposed upstream boundary, not installed instrumentation. It does not change runtime dispatch policy or model routing.

The Codex-owned codex-agent-continuity.md, scripts/lib/agent-continuity.mjs and tests/agent-continuity.test.mjs guard configuration when reusing agents. The runtime adapter and the Codex-owned codex-subagent-lifecycle.md reference both load it so a personal lifecycle skill cannot silently bypass the pstack continuation check. The lifecycle is a reference file, not a registered skill, so it never competes with a personal skill in the catalog. No default model or service tier is changed.

skills/poteto-mode/references/codex-user-input.md is a Codex-owned extension loaded by the runtime adapter before requesting user input. Preserve its pending-decision visibility, owned title restoration and unavailable-tool fallback during refreshes. Its behavioral cases live in evals/cases/workflow-efficiency.json.

Local upstream copy

An optional upstream clone may exist at .upstream/plugins. Check its commit before using it. Automated refreshes fetch into a temporary directory outside the project.

The tracked .gitignore preserves upstream exclusions and adds .upstream/ and .audit/ for local source copies and audit artifacts. The compatibility map marks this file as adapted. A separate reference cannot make Git apply these exclusions in fresh clones; preserve them during upstream refreshes.

Recreate the local copy after a fresh checkout of this repository:

git clone https://github.com/cursor/plugins .upstream/plugins
git -C .upstream/plugins switch --create locked-0.15.2 \
  889ec4b68fa5aab0e867dad71ec3fdf386ae48f3

Provenance files

• NOTICE records attribution and the source commit.
• upstream.lock.json records the 158 source paths, sizes, and SHA-256 hashes.
• compatibility/pstack-map.json assigns each source path a Codex path, classification, invariant, and validation.
• compatibility/report.md is the generated human-readable report.

Check the locked source

Prefer the persistent local copy when .upstream/plugins exists:

node scripts/import-upstream.mjs \
  --source .upstream/plugins/pstack \
  --verify-lock \
  --dry-run

node scripts/generate-compatibility-report.mjs \
  --check \
  --upstream-dir .upstream/plugins/pstack

The import command must report Verified 158 files.

When .upstream/plugins is absent, use the repository URL as a fallback. The import helper removes its temporary clone, and it never writes into the derived tree.

node scripts/import-upstream.mjs \
  --source https://github.com/cursor/plugins \
  --subdirectory pstack \
  --commit 889ec4b68fa5aab0e867dad71ec3fdf386ae48f3 \
  --verify-lock \
  --dry-run

This import command must also report Verified 158 files.

Review a newer source commit

Fetch the persistent local clone and list newer commits that changed pstack:

git -C .upstream/plugins fetch origin
git -C .upstream/plugins log --oneline \
  locked-0.15.2..origin/main -- pstack

Then review a candidate:

1. Check out the exact candidate commit in a separate local worktree or temporary clone.
2. Point scripts/generate-compatibility-report.mjs --upstream-dir at the candidate pstack directory.
3. Review every added, changed, deleted, or renamed path. Record a refreshDisposition in compatibility/pstack-map.json before adapting code.
4. Port behavior into the Codex tree. Do not copy host-specific installation or runtime claims.
5. Update the source metadata and hashes in upstream.lock.json only after review.
6. Regenerate compatibility/report.md and run the full release checks.
7. Delete the candidate worktree or temporary clone. Confirm that the delivered repository has no upstream remote or raw source branch.

To inspect a candidate without changing the committed report, run:

node scripts/generate-compatibility-report.mjs \
  --check \
  --upstream-dir /absolute/path/to/temporary/plugins/pstack

The command exits with blocking findings until every source delta has an explicit disposition. The import helper refuses to overwrite an existing output directory, and the inventory rejects symlinks.

Regenerate the report

After the lock and compatibility map agree, run:

node scripts/generate-compatibility-report.mjs
node scripts/generate-compatibility-report.mjs --check
node --test tests/upstream-provenance.test.mjs tests/compatibility-map.test.mjs

Review the generated diff. A complete report accounts for every locked path and has no unresolved source delta.

skills/poteto-mode/references/codex-audit-storage.md is a Codex-owned extension loaded by the runtime adapter before scratch allocation and at closeout. Preserve its evidence retention, inactivity checks, concurrent isolation, and run-record capture budgets during upstream refreshes.

Version 0.15.2 adaptation

See the path review for all 95 source deltas. The two deleted how critique references remain Codex-owned, along with their existing workflow and model role. Preserve them during future refreshes.

The two new principles use Codex invocation metadata. Their narrow corrections prevent an even actor census from disproving unrelated hypotheses and prevent assertion syntax from authorizing removal of required contracts. Separate extensions cannot correct those direct claims. The writing changes remove automatic reflection triggers and forced personality prose, keep detailed evidence linked from PR briefings, and label claims by evidence. The Codex-owned model defaults remain authoritative.