refactor(pstack): preserve upstream source and generate portable package

.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
       "name": "pstack",
       "source": {
         "source": "local",
-        "path": "./pstack"
+        "path": "./portable/pstack"
       },
       "policy": {
         "installation": "AVAILABLE",

.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   "plugins": [
     {
       "name": "pstack",
-      "source": "./pstack",
+      "source": "./portable/pstack",
       "description": "Upstream pstack workflows adapted for Claude Code and Codex."
     }
   ]

.gitattributes

@@ -0,0 +1,3 @@
+pstack/** -whitespace
+README.md -whitespace
+portable/pstack/** -whitespace linguist-generated=true

.github/workflows/validate-pstack-portable.yml

@@ -4,13 +4,21 @@ on:
   push:
     paths:
       - 'pstack/**'
+      - 'portable/**'
+      - 'README.md'
+      - 'README_PORTABLE.md'
+      - '.gitattributes'
       - 'tools/portable/**'
       - '.claude-plugin/**'
       - '.agents/plugins/**'
       - '.github/workflows/*pstack*.yml'
   pull_request:
     paths:
       - 'pstack/**'
+      - 'portable/**'
+      - 'README.md'
+      - 'README_PORTABLE.md'
+      - '.gitattributes'
       - 'tools/portable/**'
       - '.claude-plugin/**'
       - '.agents/plugins/**'
@@ -24,6 +32,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: '3.12'

README.md

@@ -1,5 +1,3 @@
-> **yxhta/pstack:** Claude Code・Codexでの導入と上流同期は [README_PORTABLE.md](README_PORTABLE.md) を参照してください。以下は本家のREADMEです。
-
 # Cursor plugins
 
 Official Cursor plugins for popular developer tools, frameworks, and SaaS products. Each plugin is a standalone directory at the repository root with its own `.cursor-plugin/plugin.json` manifest.

README_PORTABLE.md

@@ -36,24 +36,34 @@ codex plugin add pstack@yxhta-pstack
 
 Start with `/pstack:poteto-mode` on Claude Code. On Codex, select the installed `pstack:poteto-mode` skill or ask to use poteto-mode. Run setup-pstack to configure roles. Missing roles inherit the session model; multi-model diversity needs models that your runtime actually exposes. No startup hook or automatic routing is installed.
 
-For a skills-only installation, clone this repository and keep it in place, then link each directory under `pstack/skills/` into your runtime's user skill directory. Install all skill directories together so the shared runtime adaptation and other relative references stay reachable. Existing skill names such as `swarm` and `architect` may collide: inspect existing installations before replacing them.
+For a skills-only installation, clone this repository and keep it in place, then link each directory under `portable/pstack/skills/` into your runtime's user skill directory. Install all skill directories together so the shared runtime adaptation and other relative references stay reachable. Existing skill names such as `swarm` and `architect` may collide: inspect existing installations before replacing them.
 
-Read [compatibility.md](pstack/compatibility.md) for the tool mappings, paths, and limitations. Cursor-only `make-bot-ui`, Benny automations, cloud workers, and transcript parsers are not ported. Optional cursor-team-kit dependencies are not included. Installation and structural validation do not establish that every workflow runs correctly; check a real task in each runtime.
+Read [runtime adaptation](tools/portable/assets/skills/poteto-mode/references/runtime-adaptation.md) for the tool mappings, paths, and limitations. Cursor-only `make-bot-ui`, Benny automations, cloud workers, and transcript parsers are not ported. Optional cursor-team-kit dependencies are not included. Installation and structural validation do not establish that every workflow runs correctly; check a real task in each runtime.
 
 ## Upstream updates
 
-The **Sync pstack upstream** GitHub Actions workflow checks daily and can be run manually. It merges upstream main into a dedicated branch, reapplies the small entry-point adaptation, records the upstream SHA, validates it, and opens a PR. It never merges into main automatically. The complete repository history is retained because this is a GitHub fork, but the PR body distinguishes pstack changes from unrelated upstream plugin changes.
+The **Sync pstack upstream** GitHub Actions workflow checks daily and can be run manually. It merges upstream main into a dedicated branch, records the upstream SHA, regenerates the portable package, validates it, and opens a PR. It never merges into main automatically. The complete repository history is retained because this is a GitHub fork. The PR body separates raw pstack paths from other changed paths, which include generated output, fork tooling, and other upstream plugins.
 
 Enable GitHub Actions in this fork and allow Actions to create pull requests under **Settings → Actions → General**. Scheduled workflows may be disabled by GitHub after prolonged inactivity; run or re-enable the workflow when needed. If Actions is not allowed to create PRs, supply a suitably scoped repository secret `UPSTREAM_SYNC_TOKEN`; do not commit credentials. A PR opened with the default GITHUB_TOKEN does not trigger other PR workflows, so the sync job runs validation itself.
 
-Only one sync PR is kept open. Review and merge or close it before the next update. A merge conflict or validation failure fails the workflow with logs instead of overwriting the local adaptation. Resolve the conflicting upstream change on a branch and run the checks below. New upstream skills receive the same adaptation automatically.
+The sync script requires a clean dedicated checkout at the latest `origin` default branch. Only one sync PR is kept open. Review and merge or close it before the next update. A merge conflict or validation failure fails the workflow with logs instead of overwriting the local adaptation. Resolve the conflicting upstream change on a branch and run the checks below. New upstream skills receive the same adaptation automatically.
 
 ```sh
 python3 tools/portable/prepare.py
 python3 tools/portable/validate.py
 python3 -m unittest discover -s tools/portable -p 'test_*.py'
 git diff --check
-claude plugin validate ./pstack
+claude plugin validate ./portable/pstack
 ```
 
-Upstream-owned files receive only a runtime-adaptation link after their frontmatter and normalized skill names. Runtime-specific manifests, agents, scripts, this guide, and the runtime adaptation are maintained separately. The compatibility.md file links to the canonical adaptation inside poteto-mode; portable agent references are refreshed from upstream by prepare.py. Change behavior in runtime-adaptation.md only to adapt the runtime; keep policy changes explicit and separate. Preserve the upstream MIT license and attribution.
+The raw `pstack/` tree and root `README.md` match `tools/portable/upstream.json` byte for byte, including executable modes. Do not edit these source paths. The generator copies the complete upstream package to `portable/pstack/`, adds runtime mappings, and normalizes skill names there. It copies agents, licenses, scripts, and references. It rejects input symlinks and overlay collisions instead of overwriting unfamiliar upstream files.
+
+Edit fork-owned inputs under `tools/portable/assets/` and rerun `python3 tools/portable/prepare.py`. Never edit `portable/pstack/` by hand. The generated package is committed intentionally so every installation works without a build. `python3 tools/portable/prepare.py --check` detects missing, stale, modified, or mode-changed output. Root marketplaces point to this single package. Source files remain unpatched when upstream changes a skill header.
+
+Native plugin versions include the upstream pin and a digest of the package contents and executable modes. Adapter-only changes receive a new version without a manual bump. Template version fields are excluded from the digest.
+
+Git whitespace checks apply to fork-owned inputs. `.gitattributes` exempts the upstream source paths and generated package so upstream whitespace remains intact. Source integrity and generation checks cover those paths.
+
+Use `$sync-pstack-upstream` on Codex or `/sync-pstack-upstream` on Claude Code to review and integrate upstream changes from a source checkout. A native Claude plugin exposes `/pstack:sync-pstack-upstream`. The skill reads the recorded pin and full upstream diff, reviews changed runtime assumptions, regenerates, verifies, and prepares a PR. It does not merge automatically. Consumer installation updates still use `npx skills update`.
+
+Mechanical merge conflicts in raw `pstack/` are avoided by keeping it pristine. Conflicts in root marketplaces or fork-owned automation can still occur. Semantic changes to upstream workflows still require review and actual execution on the affected runtime. Automated sync PRs report this review gap rather than claiming complete runtime compatibility.