@piagent/platform 1.1.6 → 1.1.7

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
 
+## v1.1.7 - 2026-07-28
+
+A platform update is one global install. It was not behaving like one: every project that selected capability packs stopped working after a release until its profile was reapplied by hand, and the policy a release corrected never reached a project that had already onboarded.
+
+### Changed
+
+- A capability lock that is behind the installed platform is re-pinned instead of refusing the session. The lock pinned two different things and gave them one answer. What the project consented to — which packs, from where, and how far they may reach — still blocks: a grant that widens, a protection that disappears, a pack that changes identity. Which build produced the resolution — package version, runtime file digests, artifact content — moves on every release, and blocking on it put a per-project chore behind a global update while not defending against the case it resembles, since the code that verifies the lock is itself one of the files the lock pins. A build move with an unchanged grant is recorded and reported.
+
+- Artifact content is part of the build, not part of consent. Adapter policy files, base policy, prompts, skills, subagents and recipes all ship as pack artifacts, so pinning their bytes meant a corrected policy could never reach a project referencing it. Nothing is given up: which artifacts a pack provides is declared in its manifest and the manifest digest is still pinned, so an artifact that appears, disappears or moves still blocks — and a policy artifact that weakens still blocks, because the permissions it resolves to are compared directionally.
+
+- A project profile can name the adapter it takes its policy from instead of copying it. `{"extends": "web-frontend", "projectId": ..., "displayName": ...}` keeps the project's identity and overrides in the project, and resolves the rest from the installed platform at runtime. Any key the project states replaces the adapter's key whole; a profile without `extends` keeps working exactly as before, self-contained. `init-project.sh` and `/onboard-project` write this form when the profile comes from a built-in adapter, so onboarding stays the one per-project step and updating stays global.
+
+  A profile naming an adapter that is not installed refuses rather than falling back to something weaker.
+
 ## v1.1.6 - 2026-07-27
 
 Monorepo fixes found auditing how the platform scopes itself to a project. Every case was reproduced against a real directory tree before it was changed.

package/README.md

@@ -283,7 +283,7 @@ This repository intentionally excludes:
 
 ## Maturity
 
-The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.1.6` or a reviewed commit.
+The current package version is read from package metadata and release tags. Personal machines may follow the unpinned package source when accepting ongoing updates; production/team quickstarts and committed project settings should pin an explicit tag such as `v1.1.7` or a reviewed commit.
 
 Ready for:
 

package/docs/capability-packs.md

@@ -153,6 +153,7 @@ Pack không thể cấp thêm quyền cho chính nó:
 - Doctor phát hiện catalog hoặc lock stale.
 - Generated output dùng temporary file cùng thư mục, `fsync`, rồi atomic rename.
 - Lock gắn với declared package-source identifier, package version, catalog và digest của các runtime enforcement file đang cài. Đây là integrity binding của runtime quan sát được, không phải chứng minh nguồn gốc cryptographic của package archive.
+- Lock drift được phân loại hai nhánh, xem `## Lock drift` bên dưới.
 - Optional runtime package được cài bằng exact version; installer đối chiếu registry integrity với digest đã phê duyệt trước khi cài.
 - Khi cập nhật profile, lock được ghi trước; nếu profile không thể ghi thì lock được rollback. Process interruption tạo trạng thái mismatch fail-closed thay vì áp dụng profile thiếu lock.
 
@@ -166,6 +167,26 @@ Pack không thể cấp thêm quyền cho chính nó:
 - `validate-action` chỉ kiểm tra contract, thời hạn và secret indicator; không authorize action, không đối chiếu requested permission với profile/lock và không đọc artifact để xác minh digest/size.
 - External action vẫn cần human confirmation và executor riêng trước khi có side effect.
 
+## Lock drift
+
+Lock pin hai thứ khác nhau, và khi lệch thì câu trả lời cũng khác nhau.
+
+**Consent — project phải đồng ý lại, session bị chặn (`blocked`):**
+
+- `schemaVersion` của lock, `core.apiVersion`, `core.packageSource`;
+- `profile` — `projectId`, `mode`, tên file, digest của document project tự lưu;
+- `packs` — name, version, origin, source, owner, lifecycle và digest của manifest. Manifest khai luôn `provides`, nên artifact xuất hiện thêm, biến mất hoặc đổi path đều nằm ở nhánh này;
+- permission theo hướng: granting key (`capabilities`, `filesystemRead`, `filesystemWrite`, `networkDomains`, `externalActions`) chặn khi **thêm**; restricting key (`protectedPaths`, `readOnlyPaths`, `shellProtectedPaths`) chặn khi **mất**.
+
+**Build — platform đổi bản, lock được ghi lại và báo, session chạy tiếp (`repin`):**
+
+- `core.packageVersion`, `core.runtimeFiles`, `core.packageDigest`;
+- nội dung artifact (`artifacts[].digest`).
+
+Vì sao nội dung artifact nằm ở nhánh build: adapter policy file, base policy, prompt, skill, subagent và recipe đều ship dạng artifact. Pin bytes của chúng nghĩa là bản sửa policy không bao giờ tới được project đang tham chiếu — đúng thứ mà việc ship policy tập trung tồn tại để làm. Không mất gì khi bỏ pin: danh sách artifact nằm trong manifest và manifest digest vẫn được pin ở `packs`, còn policy artifact bị nới lỏng vẫn chặn vì permission sau resolve được so trực tiếp theo hướng.
+
+Việc pin build cũng chưa bao giờ chống được trường hợp nó trông giống: code kiểm tra lock chính là một trong các file mà lock pin, nên thứ gì sửa được platform đã cài thì sửa luôn được checker.
+
 ## Lifecycle
 
 | Trạng thái | Ý nghĩa |

package/docs/command-reference-vietnamese.md

@@ -419,8 +419,8 @@ Các lệnh này chạy ngoài Pi.
 | Command | Dùng khi nào |
 |---|---|
 | `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0` | Cài Pi CLI tương thích với release hiện tại. |
-| `npm install -g --ignore-scripts @piagent/platform@1.1.6` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.6` | Cài pinned release khi cần reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.7` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.7` | Cài pinned release khi cần reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
 | `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
 | `piagent-update` | Full update một lệnh: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. Thêm `--project <path>` để chạy doctor sau. |

package/docs/distribution-standard.md

@@ -14,9 +14,9 @@ Repo này phải chạy được cho nhiều project/domain khác nhau. Vì vậ
 
 | Use case | Package source |
 |---|---|
-| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.6` |
+| Team pinned release | `git:github.com/Vt-mmm/piagent@v1.1.7` |
 | Personal/sandbox dev | `git:github.com/Vt-mmm/piagent` |
-| Registry distribution | `npm:@piagent/platform@1.1.6` |
+| Registry distribution | `npm:@piagent/platform@1.1.7` |
 | Enterprise npm (fork under another scope) | `npm:@your-scope/platform@x.y.z` |
 | Local platform dev | `/path/to/piagent` |
 
@@ -26,7 +26,7 @@ Latest tiện cho máy cá nhân muốn nhận cập nhật nhanh. Pin tag/commi
 
 | Channel | Command | Target | Policy |
 |---|---|---|---|
-| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.6` | Install the Pi package matching the helper. |
+| `stable` | `bash scripts/install-global.sh --stable` | Helper release tag resolved to commit SHA, currently `v1.1.7` | Install the Pi package matching the helper. |
 | `exact` | `bash scripts/install-global.sh --version vX.Y.Z --resolve-tag` | Requested tag resolved to commit SHA | Pi-package-only rollout, rollback, and incident recovery. |
 | `dev` | `bash scripts/install-global.sh --dev` | Moving Git source | Personal/sandbox only; do not commit into project settings. |
 | `local` | `bash scripts/install-global.sh --local` | Current checkout path | Platform development only. |
@@ -53,7 +53,7 @@ Root `package.json` có `pi` manifest trỏ tới:
 Do đó team có thể:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.1.6
+pi install git:github.com/Vt-mmm/piagent@v1.1.7
 ```
 
 Không cần biết internal folder `packages/piagent-core`. Source không pin chỉ dành cho personal/sandbox như bảng channel ở trên.
@@ -65,12 +65,12 @@ Team nên install global package một lần:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-`pi install git:github.com/Vt-mmm/piagent@v1.1.6` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.1.6`.
+`pi install git:github.com/Vt-mmm/piagent@v1.1.7` vẫn hợp lệ nếu chỉ cần cài Pi package. Lệnh đó không tự tạo các binary terminal `piagent-*`; muốn có helper global thì dùng `npm install -g --ignore-scripts @piagent/platform@1.1.7`.
 
 Support matrix hiện tại: macOS Apple Silicon + Bash và Linux x64 + Bash đã được verify; macOS Intel + Bash và Linux ARM64 + Bash là supported target cần chạy smoke trước rollout; native Windows chưa phải target rollout team; WSL2 experimental. Chi tiết và version runtime nằm trong [release/install policy](release-install-policy.md).
 
@@ -103,7 +103,7 @@ Nếu muốn commit sẵn `.pi/piagent-profile.json` vào repo hoặc bootstrap
 ```bash
 bash scripts/setup.sh /path/to/project \
   --profile be-readonly-fe \
-  --package-source git:github.com/Vt-mmm/piagent@v1.1.6 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.7 \
   --mcp-preset core \
   --subagents-preset safe
 ```

package/docs/operator-manual-vietnamese.md

@@ -18,12 +18,12 @@ Support matrix release hiện tại: macOS Apple Silicon + Bash và Linux x64 +
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
 
-Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.1.6`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
+Khi seed `.pi/settings.json` cho team/repo cần audit lặp lại, giữ package source dạng pinned tag như `git:github.com/Vt-mmm/piagent@v1.1.7`. Máy cá nhân có thể dùng `git:github.com/Vt-mmm/piagent` để theo latest.
 
 Nếu đang ở source checkout của platform, dùng helper theo channel để preview trước khi đổi:
 
@@ -99,7 +99,7 @@ install package once
 
 ```bash
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -281,7 +281,7 @@ Không phải daily default. Dùng khi muốn tạo sẵn `.pi` files cho projec
 bash /path/to/piagent/scripts/setup.sh /path/to/project \
   --project-only \
   --profile auto \
-  --package-source git:github.com/Vt-mmm/piagent@v1.1.6 \
+  --package-source git:github.com/Vt-mmm/piagent@v1.1.7 \
   --mcp-preset core \
   --subagents-preset safe
 ```
@@ -854,8 +854,8 @@ Watchdog là optional adversarial reviewer ở cuối turn, không bật mặc
 
 | Command | Dùng để |
 |---|---|
-| `npm install -g --ignore-scripts @piagent/platform@1.1.6` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
-| `pi install git:github.com/Vt-mmm/piagent@v1.1.6` | Install pinned release cho reproducible team setup. |
+| `npm install -g --ignore-scripts @piagent/platform@1.1.7` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
+| `pi install git:github.com/Vt-mmm/piagent@v1.1.7` | Install pinned release cho reproducible team setup. |
 | `pi install git:github.com/Vt-mmm/piagent` | Install latest platform package cho máy cá nhân/sandbox. |
 | Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Full update: đồng bộ host, terminal helper và Pi package. Mỗi release pin một Pi host chính xác; lấy đúng version của release đang cài trong [release/install policy](release-install-policy.md). |
 | Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá lại dependency findings của host cũ trước khi hạ version. |
@@ -952,7 +952,7 @@ Mở lại Pi session sau khi install.
 Cài lại terminal helper đúng release rồi kiểm tra `PATH`:
 
 ```bash
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 command -v piagent-install
 ```
 

package/docs/project-adapters.md

@@ -70,6 +70,29 @@ Path policy fields have distinct meanings:
 
 Glob trong các field này neo từ project root, nên `backend/**` chỉ khớp backend nằm ở root. Với monorepo, phải liệt kê đúng vị trí thật (`packages/api/**`, `services/*/**`). Không dùng `**/api/**`: nó khớp luôn `packages/web/src/api/` — thư mục HTTP client của frontend — và biến chính phần được phép sửa thành read-only.
 
+## Profile theo reference (`extends`)
+
+Profile ở trên là dạng self-contained: project ghi toàn bộ policy. Dạng này đóng băng policy tại thời điểm onboard — platform sửa adapter thì project cũ vẫn giữ bản copy cũ mãi.
+
+`extends` biến policy thành reference. Project chỉ giữ phần thuộc về project, phần còn lại lấy từ adapter trong platform đang cài:
+
+```json
+{
+  "schemaVersion": 1,
+  "extends": "web-frontend",
+  "projectId": "my-project",
+  "displayName": "My Project"
+}
+```
+
+Quy tắc:
+
+- `extends` trỏ tới một thư mục trong `adapters/` của platform đang cài. Tên không tồn tại → guard refuse, không fallback im lặng.
+- Mọi key project tự khai **thay thế nguyên key** của adapter, không merge từng phần tử. Khai `protectedPaths` nghĩa là project sở hữu list đó và không nhận thay đổi từ adapter nữa.
+- Không khai `extends` thì profile giữ nguyên hành vi cũ, self-contained.
+
+`scripts/init-project.sh` và `/onboard-project` ghi dạng `extends` khi profile đến từ built-in adapter. Update platform sau đó không cần chạm vào project nào.
+
 ## Monorepo và workspace
 
 Một project = một thư mục mở `pi`. Guard đọc profile tại `<cwd>/.pi/piagent-profile.json` và không đi ngược lên tìm, nên mở `pi` ở thư mục cha chứa nhiều project sẽ bỏ qua profile của từng project con và chạy unprofiled.

package/docs/publishing-for-teams.md

@@ -49,6 +49,7 @@ pi install /path/to/piagent
 - `1.1.4`: nhận diện secret dạng CLI option (`--token`, `--password`, `--api-key`) và Authorization header ở mọi vị trí argument.
 - `1.1.5`: thêm `piagent-update` — một lệnh update cả Pi host, terminal helper và Pi package đúng thứ tự.
 - `1.1.6`: `be-readonly-fe` giữ được backend read-only trong monorepo, detect FE/BE đọc cả workspace, và rule detect gộp về một chỗ.
+- `1.1.7`: update global không còn chặn project đang chạy — lock chỉ block khi grant thật sự đổi, và profile dạng `extends` nhận policy từ platform đang cài thay vì giữ bản copy lúc onboard.
 
 ## Không publish
 

package/docs/release-install-policy.md

@@ -10,7 +10,7 @@ This file is the canonical install, update, rollback, and release checklist. Oth
 
 All supported environments require Node.js `>=22.19.0` and Pi Coding Agent `0.82.0`. The Pi host is installed as a Node CLI; Pi Agent Platform still defines its own release matrix because the terminal helpers and shell policy rely on Bash/POSIX behavior.
 
-| Surface | Status for v1.1.6 | Rollout guidance |
+| Surface | Status for v1.1.7 | Rollout guidance |
 |---|---|---|
 | macOS Apple Silicon (`darwin/arm64`) + Bash | Verified for this release. | Safe default for team rollout after normal project smoke tests. |
 | Linux x64 + Bash | Verified in GitHub Actions. | Safe default for CI/server usage after normal project smoke tests. |
@@ -33,7 +33,7 @@ These three components are versioned independently. A full install, update, or r
 
 | Channel | Source shape | Mutability | Use when |
 |---|---|---:|---|
-| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.6` | Fixed after resolution | Default for team rollout. |
+| `stable` | `git:github.com/Vt-mmm/piagent@<resolved-commit-sha>` from `v1.1.7` | Fixed after resolution | Default for team rollout. |
 | `exact` | Tag, reviewed commit, or a tag resolved with `--resolve-tag` | Fixed when using a commit SHA | Pi-package-only roll forward, rollback, or reproduction. |
 | `dev` | `git:github.com/Vt-mmm/piagent` | Moving | Personal machine or sandbox only. |
 | `local` | `/path/to/piagent` | Local workspace | Platform development and dry-run validation. |
@@ -53,7 +53,7 @@ Use this flow when the team needs both terminal commands and the Pi package:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -61,8 +61,8 @@ piagent-install --stable
 The stable preview and apply output includes:
 
 ```text
-currentRelease: v1.1.6 (helper package version)
-tag: v1.1.6
+currentRelease: v1.1.7 (helper package version)
+tag: v1.1.7
 resolvedCommit: <40-char-sha>
 source: git:github.com/Vt-mmm/piagent@<40-char-sha>
 ```
@@ -79,7 +79,7 @@ bash scripts/install-global.sh --stable
 Use this only when terminal commands are not needed:
 
 ```bash
-pi install git:github.com/Vt-mmm/piagent@v1.1.6
+pi install git:github.com/Vt-mmm/piagent@v1.1.7
 ```
 
 Direct `pi install` does not create `piagent-*` commands on `PATH`.

package/docs/security-threat-model.md

@@ -21,7 +21,7 @@ This document covers the packaged guard, project profiles, capability locks, ins
 - The operator, operating-system account, Pi host, and explicitly trusted project repository are trusted to execute code.
 - Project-local Pi resources are loaded only after Pi project trust or an explicit operator override.
 - A human remains available to approve destructive and external-provider actions.
-- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.1.6, and WSL2 is experimental/unverified.
+- Supported release verification covers macOS Apple Silicon + Bash, Linux x64 + Bash, Node.js `>=22.19.0`, and the exact Pi host version declared by the release. macOS Intel + Bash and Linux ARM64 + Bash are supported targets that need local smoke verification before broad rollout. Native Windows is not a team-rollout target for v1.1.7, and WSL2 is experimental/unverified.
 - Registry, GitHub, model-provider, MCP-provider, and Vercel controls are external dependencies. Their account security and platform guarantees are not replaced by this repository.
 
 ## Threat actors and failure modes

package/docs/team-onboarding.md

@@ -9,7 +9,7 @@ Một thành viên mới không cần biết local path của maintainer. Luồn
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 piagent-install --stable
 cd /path/to/project
 pi
@@ -42,7 +42,7 @@ Mặc định team dùng stable helper:
 ```bash
 node --version  # >= 22.19.0
 npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.82.0
-npm install -g --ignore-scripts @piagent/platform@1.1.6
+npm install -g --ignore-scripts @piagent/platform@1.1.7
 piagent-install --stable --dry-run
 piagent-install --stable
 ```
@@ -70,7 +70,7 @@ piagent-update --check
 piagent-update --project /path/to/project
 ```
 
-`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.1.6`.
+`--check` chỉ báo version, không đụng gì. Lên đúng một bản cụ thể thì `piagent-update --version 1.1.7`.
 
 Sequence thủ công vẫn dùng được, và bắt buộc theo thứ tự này — `piagent-install` **fail** nếu Pi host lệch bản pin, nó không tự nâng host:
 

package/docs-site/index.html

@@ -798,7 +798,7 @@
         <span>Pi Agent Platform</span>
       </a>
       <div class="top-actions">
-        <span class="pill"><span class="pill-dot"></span>v1.1.6 docs</span>
+        <span class="pill"><span class="pill-dot"></span>v1.1.7 docs</span>
         <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Mở GitHub repository">
           <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
             <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
@@ -934,7 +934,7 @@
               <article class="step">
                 <div>
                   <h3>Cài — hai lệnh</h3>
-                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.6</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
+                  <p>Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: <span class="inline-code">piagent-setup</span> tự cài đúng bản <span class="inline-code">0.82.0</span> mà release <span class="inline-code">v1.1.7</span> đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo <span class="inline-code">.pi/</span>, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm <span class="inline-code">--no-mcp</span>, <span class="inline-code">--no-subagents</span>, <span class="inline-code">--no-herdr</span> hoặc <span class="inline-code">--global-only</span> để bỏ bớt.</p>
                   <div class="table-wrap compact-table">
                     <table>
                       <thead>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/platform",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "license": "MIT",
   "publishConfig": {
     "access": "public",

package/packages/piagent-core/capabilities/capability-core.js

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { containsSensitiveText } from "../security/sensitive-data.js";
+import { resolveProjectProfileDocument } from "./project-profile.js";
 
 const API_VERSION = "piagent/v1";
 const CORE_API_VERSION = 1;
@@ -785,6 +786,9 @@ function buildCoreIntegrity(root) {
     // capability-sources.js decides which external trees become readable packs,
     // so tampering with it changes which code the profile can grant.
     "packages/piagent-core/capabilities/capability-sources.js",
+    // project-profile.js decides which document is enforced when a project takes
+    // its policy from an adapter, so it selects the protected paths themselves.
+    "packages/piagent-core/capabilities/project-profile.js",
     "packages/piagent-core/security/sensitive-data.js",
     "packages/piagent-core/extensions/piagent-guard.ts",
     // guard-io.js loads the project profile and guard-shell-analysis.ts decides
@@ -904,7 +908,7 @@ export function resolveCapabilityProfileDocument(root, profile, options = {}) {
       projectId: profile.projectId,
       mode: profile.mode,
       file: profileFile,
-      digest: sha256(stableJson(profile))
+      digest: sha256(stableJson(options.storedProfile ?? profile))
     },
     packs: [...selected.values()].map((pack) => ({
       name: pack.name,
@@ -927,25 +931,118 @@ export function resolveCapabilityProfileDocument(root, profile, options = {}) {
 
 export function resolveCapabilityProfile(root, profilePath, options = {}) {
   const profileAbsolute = fs.realpathSync(profilePath);
-  const profile = readJsonFile(profileAbsolute);
+  const stored = readJsonFile(profileAbsolute);
+  const { profile } = resolveProjectProfileDocument(fs.realpathSync(root), stored);
   return resolveCapabilityProfileDocument(root, profile, {
     profileFile: path.basename(profileAbsolute),
+    // The lock records the document the project owns. A profile that takes its
+    // policy from an adapter is meant to follow that adapter, so digesting the
+    // resolved document instead would turn every platform correction into a
+    // lock the project has to re-agree to by hand.
+    storedProfile: stored,
     packageSource: options.packageSource,
     extraRoots: options.extraRoots
   });
 }
 
+// A lock pins two different things and they deserve different answers when they
+// stop matching.
+//
+// What the project consented to: which packs, from where, and how far they may
+// reach. Granting more than that, or covering less than that, is a change the
+// project has to agree to, so it blocks.
+//
+// Which build of the platform produced the resolution: its version, the digests
+// of its runtime files, and the content of the artifacts its packs ship. That
+// moves on every release. Blocking on it put a per-project chore behind a global
+// update — every project on a profile that selects packs stopped working until
+// its profile was reapplied — while not actually defending against the case it
+// resembles: the code that verifies the lock is itself one of the files the lock
+// pins, so anything able to rewrite the installed platform can rewrite the check
+// along with it. A build move with an unchanged grant is re-pinned and reported,
+// not refused.
+//
+// Artifact content sits on the build side deliberately. Adapter policy files,
+// base policy, prompts, skills, subagents, and recipes all ship as artifacts, so
+// pinning their bytes means a policy correction cannot reach a project that
+// references it — which is the whole point of shipping policy centrally. Nothing
+// is given up by that: which artifacts a pack provides is declared in its
+// manifest, and the manifest digest is pinned in `packs`, so an artifact that
+// appears, disappears, or moves still blocks. A policy artifact that weakens
+// blocks too, because the permissions it resolves to are compared directly
+// below.
+const GRANTING_PERMISSIONS = ["capabilities", "filesystemRead", "filesystemWrite", "networkDomains", "externalActions"];
+const RESTRICTING_PERMISSIONS = ["protectedPaths", "readOnlyPaths", "shellProtectedPaths"];
+
+function consentedShape(document) {
+  return {
+    schemaVersion: document?.schemaVersion,
+    apiVersion: document?.core?.apiVersion,
+    packageSource: document?.core?.packageSource,
+    profile: document?.profile,
+    packs: document?.packs
+  };
+}
+
+function consentDrift(expected, actual) {
+  const before = consentedShape(actual);
+  const after = consentedShape(expected);
+  return Object.keys(after)
+    .filter((key) => stableJson(after[key]) !== stableJson(before[key]))
+    .map((key) => `${key} no longer matches the locked value`);
+}
+
+function permissionDrift(expected, actual) {
+  const locked = actual?.permissions ?? {};
+  const resolved = expected?.permissions ?? {};
+  const drift = [];
+
+  for (const key of GRANTING_PERMISSIONS) {
+    const agreed = new Set(locked[key] ?? []);
+    const added = (resolved[key] ?? []).filter((item) => !agreed.has(item));
+    if (added.length > 0) drift.push(`${key} would grant ${added.join(", ")}`);
+  }
+  // A protection that disappears is a weakening even though the list shrank.
+  for (const key of RESTRICTING_PERMISSIONS) {
+    const kept = new Set(resolved[key] ?? []);
+    const dropped = (locked[key] ?? []).filter((item) => !kept.has(item));
+    if (dropped.length > 0) drift.push(`${key} would stop covering ${dropped.join(", ")}`);
+  }
+  return drift;
+}
+
+export function classifyCapabilityLock(expected, actual) {
+  const expectedDigest = sha256(stableJson(expected));
+  const actualDigest = sha256(stableJson(actual));
+  if (crypto.timingSafeEqual(Buffer.from(expectedDigest), Buffer.from(actualDigest))) {
+    return { status: "current", reasons: [], expectedDigest, actualDigest };
+  }
+
+  const reasons = [...consentDrift(expected, actual), ...permissionDrift(expected, actual)];
+  if (reasons.length > 0) return { status: "blocked", reasons, expectedDigest, actualDigest };
+
+  return {
+    status: "repin",
+    reasons: [`platform build moved to ${expected?.core?.packageVersion ?? "an unknown version"}`],
+    expectedDigest,
+    actualDigest
+  };
+}
+
 export function verifyCapabilityLock(root, profilePath, lockDocument, options = {}) {
   const expected = resolveCapabilityProfile(root, profilePath, {
     packageSource: options.packageSource,
     extraRoots: options.extraRoots
   });
-  const expectedText = stableJson(expected);
-  const actualText = stableJson(lockDocument);
+  const classification = classifyCapabilityLock(expected, lockDocument);
   return {
-    ok: crypto.timingSafeEqual(Buffer.from(sha256(expectedText)), Buffer.from(sha256(actualText))),
-    expectedDigest: sha256(expectedText),
-    actualDigest: sha256(actualText),
+    // `ok` stays the question callers were already asking: may this project run?
+    // A re-pinnable lock may, and the caller is told so through `status`.
+    ok: classification.status !== "blocked",
+    status: classification.status,
+    reasons: classification.reasons,
+    expectedDigest: classification.expectedDigest,
+    actualDigest: classification.actualDigest,
     expected
   };
 }

package/packages/piagent-core/capabilities/project-profile.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// A project profile can either state its whole policy or name the adapter it
+// takes that policy from.
+//
+// Stating the whole policy freezes it. The adapters ship with the platform and
+// are corrected by it, but a project that copied one at onboarding time keeps
+// the copy forever, so a global update leaves every existing project on the old
+// rules. `extends` makes the policy a reference instead: the project keeps the
+// parts that are about the project, and the installed platform supplies the
+// rest.
+//
+// Profiles written before this existed carry no `extends` and keep working
+// exactly as they did, self-contained.
+
+const ADAPTER_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export class ProjectProfileError extends Error {}
+
+export function adapterProfileFile(platformRoot, name) {
+  if (typeof name !== "string") return undefined;
+  const trimmed = name.trim();
+  // The name indexes a directory inside the installed platform, so it is
+  // restricted to a plain slug rather than sanitised after the fact.
+  if (!ADAPTER_NAME.test(trimmed)) return undefined;
+  const candidate = path.join(platformRoot, "adapters", trimmed, "profile.json");
+  return fs.existsSync(candidate) ? candidate : undefined;
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve a stored project profile document against the installed adapters.
+ * Returns the document to enforce, plus the adapter it came from when one was
+ * named. Any key the project states replaces the adapter's key whole — there is
+ * no per-entry merging of lists, because a half-merged protectedPaths is harder
+ * to reason about than a stated one.
+ */
+export function resolveProjectProfileDocument(platformRoot, stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) {
+    return { profile: stored, base: undefined };
+  }
+  if (stored.extends === undefined) return { profile: stored, base: undefined };
+
+  const file = adapterProfileFile(platformRoot, stored.extends);
+  if (!file) {
+    throw new ProjectProfileError(
+      `project profile extends "${String(stored.extends)}", which is not an adapter in the installed platform`
+    );
+  }
+  const adapter = readJson(file);
+  if (!adapter) throw new ProjectProfileError(`adapter profile is unreadable: ${file}`);
+
+  const { extends: base, ...overrides } = stored;
+  return { profile: { ...adapter, ...overrides }, base };
+}
+
+export function readProjectProfileDocument(platformRoot, profilePath) {
+  const stored = readJson(profilePath);
+  if (stored === undefined) return { stored: undefined, profile: undefined, base: undefined };
+  const { profile, base } = resolveProjectProfileDocument(platformRoot, stored);
+  return { stored, profile, base };
+}
+
+/**
+ * The document a project stores when it takes its policy from an adapter: what
+ * identifies this project, and nothing the platform already knows.
+ */
+export function buildExtendingProfile(base, projectId, displayName) {
+  return {
+    schemaVersion: 1,
+    extends: base,
+    projectId,
+    displayName
+  };
+}

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -40,9 +40,11 @@ import {
   redactSensitiveText
 } from "./redaction-core.js";
 import { detectProfileName } from "./project-shape.js";
+import { buildExtendingProfile, resolveProjectProfileDocument } from "../capabilities/project-profile.js";
 import {
   resolveCapabilityProfileDocument,
   verifyCapabilityLock,
+  writeJsonAtomic,
   writeProfileLockAtomic
 } from "../capabilities/capability-core.js";
 import { resolveCapabilitySourceRoots } from "../capabilities/capability-sources.js";
@@ -417,6 +419,10 @@ const DEFAULT_POLICY: BasePolicy = {
   orchestrationPolicy: DEFAULT_ORCHESTRATION_POLICY
 };
 
+// Which platform supplies the adapters is fixed by where this file is installed,
+// so it is resolved once here rather than threaded through every profile load.
+const PLATFORM_ROOT = findPlatformRoot(path.dirname(fileURLToPath(import.meta.url)));
+
 function loadPolicy(extensionDir: string): BasePolicy {
   const root = findPackageRoot(extensionDir);
   return readJsonFile<BasePolicy>(path.join(root, "policies", "base-policy.json")) ?? DEFAULT_POLICY;
@@ -433,17 +439,38 @@ function fallbackProfile(cwd: string, mode = "unprofiled"): ProjectProfile {
   };
 }
 
+// A profile that names an adapter this platform does not have cannot be
+// enforced, and the unprofiled shape carries no readOnlyPaths — falling back to
+// it would quietly hand write access to whatever the profile was protecting. The
+// session stays readable and says why instead.
+function unresolvedProfile(cwd: string, reason: string): ProjectProfile {
+  return {
+    ...fallbackProfile(cwd, "unresolved-profile-base"),
+    permissionProfile: "read-only",
+    unresolvedReason: reason
+  } as ProjectProfile;
+}
+
+function resolveStoredProfile(stored: ProjectProfile | undefined, cwd: string, missingMode: string): ProjectProfile {
+  if (!stored) return fallbackProfile(cwd, missingMode);
+  try {
+    return resolveProjectProfileDocument(PLATFORM_ROOT, stored).profile as ProjectProfile;
+  } catch (error) {
+    return unresolvedProfile(cwd, error instanceof Error ? error.message : String(error));
+  }
+}
+
 function loadProfile(cwd: string, projectTrusted = false): ProjectProfile {
   const explicit = process.env.PIAGENT_PROFILE;
   if (explicit && explicit.trim().length > 0) {
-    return readJsonFile<ProjectProfile>(explicit) ?? fallbackProfile(cwd, "explicit-profile-unreadable");
+    return resolveStoredProfile(readJsonFile<ProjectProfile>(explicit), cwd, "explicit-profile-unreadable");
   }
 
   if (!projectTrusted) {
     return fallbackProfile(cwd, "unprofiled-global-package");
   }
 
-  return readJsonFile<ProjectProfile>(path.join(cwd, ".pi", "piagent-profile.json")) ?? fallbackProfile(cwd, projectTrusted ? "unprofiled" : "unprofiled-global-package");
+  return resolveStoredProfile(readJsonFile<ProjectProfile>(path.join(cwd, ".pi", "piagent-profile.json")), cwd, "unprofiled");
 }
 
 function loadProfileFromContext(ctx: ExtensionContext): ProjectProfile {
@@ -530,6 +557,7 @@ function capabilitySourceRoots(
 type ProjectCapabilityState = {
   ok: boolean;
   reason?: string;
+  repinned?: string;
   filesystemRead?: string[];
   filesystemWrite?: string[];
 };
@@ -539,8 +567,18 @@ function verifyProjectCapabilityState(extensionDir: string, cwd: string, project
   if (!projectTrusted) return { ok: true };
   const profilePath = projectProfilePath(cwd);
   if (!fs.existsSync(profilePath)) return { ok: true };
-  const profile = readJsonFile<ProjectProfile>(profilePath);
-  if (!profile || !Array.isArray(profile.capabilityPacks)) return { ok: true };
+  // Which packs a project selects can come from the adapter it extends, so the
+  // question has to be asked of the resolved document. Asking the stored one
+  // would skip the lock entirely for every project that references an adapter.
+  const stored = readJsonFile<ProjectProfile>(profilePath);
+  if (!stored) return { ok: true };
+  let profile: ProjectProfile;
+  try {
+    profile = resolveProjectProfileDocument(PLATFORM_ROOT, stored).profile as ProjectProfile;
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
   const lockPath = path.join(cwd, ".pi", "piagent-profile.lock.json");
   if (!fs.existsSync(lockPath)) return { ok: false, reason: "Capability lock is missing. Reapply the project profile." };
   const lock = readJsonFile<Record<string, unknown>>(lockPath);
@@ -550,13 +588,30 @@ function verifyProjectCapabilityState(extensionDir: string, cwd: string, project
       packageSource: projectPackageSource(cwd),
       extraRoots: capabilitySourceRoots(cwd, profile)
     });
-    return verification.ok
-      ? {
-          ok: true,
-          filesystemRead: verification.expected.permissions.filesystemRead,
-          filesystemWrite: verification.expected.permissions.filesystemWrite
-        }
-      : { ok: false, reason: "Capability lock does not match the active profile, package source, or installed platform." };
+    if (verification.status === "blocked") {
+      return {
+        ok: false,
+        reason: `Capability lock does not match what this project agreed to: ${verification.reasons.join("; ")}. Reapply the project profile.`
+      };
+    }
+    const granted = {
+      filesystemRead: verification.expected.permissions.filesystemRead,
+      filesystemWrite: verification.expected.permissions.filesystemWrite
+    };
+    if (verification.status !== "repin") return { ok: true, ...granted };
+
+    // The grant is unchanged and only the platform build moved. Record the new
+    // build instead of stopping the session, which is what turned every release
+    // into a chore in every project.
+    try {
+      writeJsonAtomic(lockPath, verification.expected);
+    } catch (error) {
+      return {
+        ok: false,
+        reason: `Capability lock is behind the installed platform and could not be rewritten: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    return { ok: true, repinned: verification.reasons.join("; "), ...granted };
   } catch (error) {
     return { ok: false, reason: `Capability validation failed: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -2854,12 +2909,18 @@ function buildTechStackManifest(profileName: string, selectedOptions: TechOption
   };
 }
 
+// `profile` is the document the project stores. When it names an adapter, the
+// lock is resolved against that adapter but still records the stored document,
+// so a later platform correction is not a lock the project has to re-agree to.
 function writeProfileDocumentWithLock(extensionDir: string, cwd: string, profile: ProjectProfile): ProjectProfile {
   const target = projectProfilePath(cwd);
-  const capabilityLock = resolveCapabilityProfileDocument(findPlatformRoot(extensionDir), profile, {
+  const platformRoot = findPlatformRoot(extensionDir);
+  const resolved = resolveProjectProfileDocument(platformRoot, profile).profile as ProjectProfile;
+  const capabilityLock = resolveCapabilityProfileDocument(platformRoot, resolved, {
     profileFile: "piagent-profile.json",
+    storedProfile: profile,
     packageSource: projectPackageSource(cwd),
-    extraRoots: capabilitySourceRoots(cwd, profile)
+    extraRoots: capabilitySourceRoots(cwd, resolved)
   });
   fs.mkdirSync(path.dirname(target), { recursive: true });
   writeProfileLockAtomic(target, profile, path.join(cwd, ".pi", "piagent-profile.lock.json"), capabilityLock);
@@ -2909,7 +2970,7 @@ function writeTechStackSelection(
   };
   writeProfileDocumentWithLock(extensionDir, cwd, profile);
   ensureProjectContextPlaceholder(cwd);
-  return { profile, manifest };
+  return { profile: resolveProjectProfileDocument(findPlatformRoot(extensionDir), profile).profile as ProjectProfile, manifest };
 }
 
 function normalizeTechSelections(cwd: string, profileName: string, selections: Record<string, unknown> = {}, fillRecommended = true): {
@@ -3033,20 +3094,24 @@ function buildProfileFromAdapter(extensionDir: string, cwd: string, profileName:
   const profile = readJsonFile<ProjectProfile>(source);
   if (!profile) throw new Error(`Profile unreadable: ${profileName}`);
   const projectName = path.basename(cwd);
-  return {
-    ...profile,
-    projectId: projectId ? slugify(projectId) : slugify(projectName),
-    displayName: displayName?.trim() || titleize(projectName)
-  };
+  // The project records which adapter it follows, not a copy of that adapter's
+  // rules. A copy stops receiving corrections the moment it is written.
+  return buildExtendingProfile(
+    profileName,
+    projectId ? slugify(projectId) : slugify(projectName),
+    displayName?.trim() || titleize(projectName)
+  ) as ProjectProfile;
 }
 
 function writeProfileFromAdapter(extensionDir: string, cwd: string, profileName: string, overwrite = false, projectId?: string, displayName?: string): ProjectProfile {
   const target = projectProfilePath(cwd);
   if (fs.existsSync(target) && !overwrite) throw new Error(".pi/piagent-profile.json already exists. Pass overwrite=true to replace it.");
-  const personalized = buildProfileFromAdapter(extensionDir, cwd, profileName, projectId, displayName);
-  writeProfileDocumentWithLock(extensionDir, cwd, personalized);
+  const stored = buildProfileFromAdapter(extensionDir, cwd, profileName, projectId, displayName);
+  writeProfileDocumentWithLock(extensionDir, cwd, stored);
   ensureProjectContextPlaceholder(cwd);
-  return personalized;
+  // Store the reference, hand back the document it resolves to: callers report
+  // and trace what is now in force, not the four lines that point at it.
+  return resolveProjectProfileDocument(findPlatformRoot(extensionDir), stored).profile as ProjectProfile;
 }
 
 function readTask(cwd: string, taskId: string): TaskContract | undefined {
@@ -3659,6 +3724,9 @@ export default function piagentGuard(pi: ExtensionAPI) {
     const permissionHint = ` permission=${permissionProfile.mode}`;
     ctx.ui.notify(`Piagent Pi guard loaded: ${name}${profileHint}${permissionHint}${contextHint}`, preflight.recommendation === "fresh-session" ? "warning" : "info");
     if (!capabilityState.ok) ctx.ui.notify(capabilityState.reason ?? "Capability validation failed.", "warning");
+    if (capabilityState.repinned) {
+      ctx.ui.notify(`Capability lock re-pinned: ${capabilityState.repinned}. The capabilities this project grants are unchanged.`, "info");
+    }
     const legacyWarning = legacyProjectStateWarning(ctx.cwd);
     if (legacyWarning) ctx.ui.notify(legacyWarning, "warning");
     if (permissionProfile.warning) ctx.ui.notify(permissionProfile.warning, "warning");
@@ -4675,10 +4743,12 @@ export default function piagentGuard(pi: ExtensionAPI) {
       entry.context7.digest = snapshot.digest;
       manifest.updatedAt = nowIso();
       fs.writeFileSync(techStackPath(ctx.cwd), `${JSON.stringify(manifest, null, 2)}\n`);
-      const profile = loadProfileFromContext(ctx);
-      if (profile.techStack) {
-        profile.techStack.updatedAt = manifest.updatedAt;
-        writeProfileDocumentWithLock(extensionDir, ctx.cwd, profile);
+      // Write back the document the project stores, not the resolved one: saving
+      // the resolved copy would inline the adapter and stop it following.
+      const stored = readJsonFile<ProjectProfile>(projectProfilePath(ctx.cwd));
+      if (stored?.techStack) {
+        stored.techStack.updatedAt = manifest.updatedAt;
+        writeProfileDocumentWithLock(extensionDir, ctx.cwd, stored);
       }
       appendTrace(ctx.cwd, { event: "profile_tech_context_record", techId, role: entry.role, libraryId: snapshot.resolvedLibraryId });
       appendSessionTrace(pi, { event: "profile_tech_context_record", techId, role: entry.role, libraryId: snapshot.resolvedLibraryId });

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "type": "module",
   "private": true,
   "license": "MIT",

package/schemas/project-profile.schema.json

@@ -6,19 +6,37 @@
   "required": [
     "schemaVersion",
     "projectId",
-    "displayName",
-    "mode",
-    "rootMarkers",
-    "protectedPaths",
-    "requiredContext",
-    "verifyCommands",
-    "mcpCapabilities"
+    "displayName"
   ],
+  "if": {
+    "required": [
+      "extends"
+    ]
+  },
+  "then": {
+    "description": "A profile that names an adapter stores identity plus overrides. Every policy field it omits comes from the installed adapter at runtime, so none of them are required here."
+  },
+  "else": {
+    "required": [
+      "mode",
+      "rootMarkers",
+      "protectedPaths",
+      "requiredContext",
+      "verifyCommands",
+      "mcpCapabilities"
+    ]
+  },
   "properties": {
     "schemaVersion": {
       "type": "integer",
       "const": 1
     },
+    "extends": {
+      "description": "Name of a built-in adapter under adapters/ in the installed platform. Its profile is the base; every other key in this file replaces the adapter's key of the same name.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
     "projectId": {
       "type": "string",
       "minLength": 1,

package/scripts/capability-catalog.mjs

@@ -20,6 +20,10 @@ import {
   validateCapabilitySources,
   vendorRemoteSource
 } from "../packages/piagent-core/capabilities/capability-sources.js";
+import {
+  buildExtendingProfile,
+  resolveProjectProfileDocument
+} from "../packages/piagent-core/capabilities/project-profile.js";
 
 const platformRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const catalogPath = path.join(platformRoot, "catalog", "capabilities.json");
@@ -28,7 +32,7 @@ function usage() {
   process.stdout.write(`Usage:
   piagent-capabilities catalog [--check | --write]
   piagent-capabilities resolve --profile <profile.json> [--output <lock.json>] [--package-source <source>]
-  piagent-capabilities apply-profile --profile <source.json> --target <piagent-profile.json> [--package-source <source>] [--force]
+  piagent-capabilities apply-profile --profile <source.json> --target <piagent-profile.json> [--extends <adapter>] [--package-source <source>] [--force]
   piagent-capabilities doctor [--profile <profile.json>] [--lock <lock.json>] [--package-source <source>]
   piagent-capabilities vendor --profile <profile.json> [--source <name>]
   piagent-capabilities validate-source --package-source <source>
@@ -58,7 +62,7 @@ function parseArguments(values) {
       output.flags.set(value, true);
       continue;
     }
-    if (!["--profile", "--output", "--target", "--lock", "--file", "--package-source", "--source"].includes(value)) throw new CapabilityValidationError(`unknown option ${value}`);
+    if (!["--profile", "--extends", "--output", "--target", "--lock", "--file", "--package-source", "--source"].includes(value)) throw new CapabilityValidationError(`unknown option ${value}`);
     if (output.flags.has(value)) throw new CapabilityValidationError(`duplicate option ${value}`);
     const next = values[index + 1];
     if (!next || next.startsWith("--")) throw new CapabilityValidationError(`${value} requires a value`);
@@ -157,7 +161,7 @@ function runResolve(flags) {
 }
 
 function runApplyProfile(flags) {
-  assertAllowedFlags(flags, new Set(["--profile", "--target", "--package-source", "--force"]));
+  assertAllowedFlags(flags, new Set(["--profile", "--extends", "--target", "--package-source", "--force"]));
   const source = requireExistingFile(flags.get("--profile"), "--profile");
   const targetValue = flags.get("--target");
   if (!targetValue) throw new CapabilityValidationError("--target is required");
@@ -166,17 +170,27 @@ function runApplyProfile(flags) {
   const parent = fs.realpathSync(path.dirname(target));
   const normalizedTarget = path.join(parent, path.basename(target));
   if (fs.existsSync(normalizedTarget) && !flags.has("--force")) throw new CapabilityValidationError("target profile already exists; pass --force to replace it");
-  const profile = readJson(source);
+  const adapter = readJson(source);
+  const base = flags.get("--extends");
+  // With --extends the project records which adapter it follows and keeps only
+  // its own identity, so a later platform correction reaches it. Without it the
+  // source document is copied whole, which is what a caller supplying its own
+  // profile file wants.
+  const stored = base === undefined
+    ? adapter
+    : buildExtendingProfile(base, adapter.projectId, adapter.displayName);
+  const profile = resolveProjectProfileDocument(platformRoot, stored).profile;
   const packageSource = flags.get("--package-source") ?? "workspace";
   const lock = resolveCapabilityProfileDocument(platformRoot, profile, {
     profileFile: path.basename(normalizedTarget),
+    storedProfile: stored,
     packageSource,
     extraRoots: profile.capabilitySources === undefined
       ? undefined
       : resolveCapabilitySourceRoots(projectRootForProfile(normalizedTarget), profile.capabilitySources)
   });
   const lockTarget = path.join(parent, "piagent-profile.lock.json");
-  writeProfileLockAtomic(normalizedTarget, profile, lockTarget, lock);
+  writeProfileLockAtomic(normalizedTarget, stored, lockTarget, lock);
   process.stdout.write(`${JSON.stringify({ ok: true, profile: normalizedTarget, lock: lockTarget, packs: lock.packs.length })}\n`);
 }
 
@@ -210,11 +224,18 @@ function runDoctor(flags) {
       const verification = verifyCapabilityLock(platformRoot, profile, readJson(lockFile), { packageSource, extraRoots });
       report.lock = {
         path: lockFile,
-        current: verification.ok,
+        current: verification.status === "current",
+        status: verification.status,
+        reasons: verification.reasons,
         expectedDigest: verification.expectedDigest,
         actualDigest: verification.actualDigest
       };
-      if (!verification.ok) throw new CapabilityValidationError("capability lock is stale or has been modified");
+      // A re-pinnable lock is behind the installed build but grants exactly what
+      // it agreed to, so it is reported rather than treated as a failure. The
+      // guard rewrites it on the next session.
+      if (verification.status === "blocked") {
+        throw new CapabilityValidationError(`capability lock no longer matches what the project agreed to: ${verification.reasons.join("; ")}`);
+      }
     }
   } else if (flags.has("--lock")) {
     throw new CapabilityValidationError("--lock requires --profile");

package/scripts/init-project.sh

@@ -219,6 +219,13 @@ if [[ "$FORCE_PROFILE" == true || ! -f "$PROFILE_TARGET" ]]; then
     --target "$PROFILE_TARGET"
     --package-source "$PACKAGE_SOURCE"
   )
+  # A built-in adapter is referenced, not copied, so a later platform correction
+  # reaches this project. A caller supplying its own profile file still gets that
+  # file written whole.
+  if [[ "$PROFILE_PATH" == "$PLATFORM_ROOT/adapters/"*"/profile.json" ]]; then
+    adapter_name="${PROFILE_PATH#"$PLATFORM_ROOT/adapters/"}"
+    apply_profile_args+=(--extends "${adapter_name%/profile.json}")
+  fi
   if [[ "$FORCE_PROFILE" == true ]]; then
     apply_profile_args+=(--force)
   fi

package/scripts/install-global.sh

@@ -15,7 +15,7 @@ Package source examples:
   # Installs the stable tag after resolving it to a commit SHA.
 
   # Pin a specific release:
-  scripts/install-global.sh --version v1.1.6 --resolve-tag
+  scripts/install-global.sh --version v1.1.7 --resolve-tag
 
   # Preview the planned install/update without changing user config:
   scripts/install-global.sh --stable --dry-run
@@ -127,7 +127,7 @@ detect_runtime_surface() {
       printf 'native-windows/%s (not release-gated; terminal helpers require Bash semantics)' "$arch_name"
       ;;
     *)
-      printf '%s/%s (outside v1.1.6 release matrix)' "$os_name" "$arch_name"
+      printf '%s/%s (outside v1.1.7 release matrix)' "$os_name" "$arch_name"
       ;;
   esac
 }
@@ -135,7 +135,7 @@ detect_runtime_surface() {
 warn_runtime_surface_if_needed() {
   local surface="$1"
   case "$surface" in
-    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.6 release matrix"*)
+    *"supported target"*|*"experimental"*|*"not release-gated"*|*"outside v1.1.7 release matrix"*)
       echo "WARN: runtime surface is $surface." >&2
       echo "WARN: For team rollout, run piagent-doctor plus the project smoke/verify suite on this machine before relying on it." >&2
       ;;

package/scripts/profile-doctor.sh

@@ -19,12 +19,22 @@ if [[ ! -f "$PROFILE_PATH" ]]; then
   exit 1
 fi
 
-node --input-type=module - "$PROJECT_PATH" "$PROFILE_PATH" <<'NODE'
+PLATFORM_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+node --input-type=module - "$PROJECT_PATH" "$PROFILE_PATH" "$PLATFORM_ROOT" <<'NODE'
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [projectPath, profilePath, platformRoot] = process.argv.slice(2);
+const stored = JSON.parse(fs.readFileSync(profilePath, "utf8"));
 
-const [projectPath, profilePath] = process.argv.slice(2);
-const profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
+// A profile that names an adapter is checked as the document that will actually
+// be enforced, not as the few lines the project happens to store.
+const { resolveProjectProfileDocument } = await import(
+  pathToFileURL(path.join(platformRoot, "packages", "piagent-core", "capabilities", "project-profile.js")).href
+);
+const profile = resolveProjectProfileDocument(platformRoot, stored).profile;
 
 const errors = [];
 const warnings = [];

package/scripts/runtime-policy-smoke.sh

@@ -25,11 +25,20 @@ bash "$ROOT/scripts/profile-doctor.sh" "$PROJECT" >/dev/null
 bash "$ROOT/scripts/quality-benchmark.sh" "$PROJECT" --init >/dev/null
 bash "$ROOT/scripts/quality-benchmark.sh" "$PROJECT" --record --scenario smoke --surface pi --result pass --tokens 1 --verify "test -s README.md" >/dev/null
 
-node --input-type=module - "$PROJECT/.pi/piagent-profile.json" "$PROJECT/.pi/benchmarks/quality-runs.jsonl" <<'NODE'
+node --input-type=module - "$PROJECT/.pi/piagent-profile.json" "$PROJECT/.pi/benchmarks/quality-runs.jsonl" "$ROOT" <<'NODE'
 import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
 
-const [profilePath, benchmarkPath] = process.argv.slice(2);
-const profile = JSON.parse(fs.readFileSync(profilePath, "utf8"));
+const [profilePath, benchmarkPath, platformRoot] = process.argv.slice(2);
+const stored = JSON.parse(fs.readFileSync(profilePath, "utf8"));
+
+// A project that names an adapter stores identity and overrides only. The policy
+// the runtime enforces is the resolved document, so that is what gets checked.
+const { resolveProjectProfileDocument } = await import(
+  pathToFileURL(path.join(platformRoot, "packages", "piagent-core", "capabilities", "project-profile.js")).href
+);
+const profile = resolveProjectProfileDocument(platformRoot, stored).profile;
 for (const capability of ["filesystem-readonly", "filesystem-write", "shell", "memory"]) {
   if (!profile.mcpCapabilities.includes(capability)) {
     throw new Error(`missing capability ${capability}`);

package/scripts/team-doctor.sh

@@ -137,7 +137,7 @@ function runtimeMatrixStatus() {
     surface: `${platform}/${arch}`,
     status: "outside-release-matrix",
     teamRolloutReady: false,
-    note: "This runtime is outside the documented v1.1.6 support matrix."
+    note: "This runtime is outside the documented v1.1.7 support matrix."
   };
 }
 
@@ -313,7 +313,12 @@ if (foreignAgentConfig.length > 0) {
 const projectProfilePath = path.join(projectPath, ".pi", "piagent-profile.json");
 let projectProfile = null;
 if (fs.existsSync(projectProfilePath)) {
-  const profile = readJson(projectProfilePath);
+  // Check the document that will be enforced. A profile that names an adapter
+  // stores only its own identity and overrides.
+  const { resolveProjectProfileDocument } = await import(
+    pathToFileURL(path.join(platformRoot, "packages", "piagent-core", "capabilities", "project-profile.js")).href
+  );
+  const profile = resolveProjectProfileDocument(platformRoot, readJson(projectProfilePath)).profile;
   projectProfile = profile;
   for (const field of ["schemaVersion", "projectId", "displayName", "mode"]) {
     if (profile[field] === undefined || profile[field] === "") errors.push(`project profile missing ${field}`);
@@ -333,7 +338,11 @@ if (fs.existsSync(projectProfilePath)) {
       try {
         const lock = readJson(projectLockPath);
         const verification = verifyCapabilityLock(platformRoot, projectProfilePath, lock, { packageSource: projectPackageSource });
-        if (!verification.ok) errors.push("project capability lock is stale or does not match the configured package source");
+        if (verification.status === "blocked") {
+          errors.push(`project capability lock no longer matches what the project agreed to: ${verification.reasons.join("; ")}`);
+        } else if (verification.status === "repin") {
+          warnings.push(`project capability lock is behind the installed platform and will be re-pinned on the next Pi session (${verification.reasons.join("; ")})`);
+        }
       } catch (error) {
         errors.push(`project capability lock validation failed: ${error instanceof Error ? error.message : String(error)}`);
       }