Extend boundary discipline to module ownership and shared changes (#2)

Co-authored-by: Paperclip <[email protected]>

AGENTS.md

@@ -9,10 +9,12 @@
 - Keep host-specific manifests and adapters small. Document unsupported behavior;
   do not invent agent APIs or equate a manifest passing validation with a workflow
   working in every client. See `docs/compatibility.md`.
-- Treat `vendor/pstack` as a verbatim upstream snapshot. Keep local packaging and
-  provenance outside it. For an intentional upstream update, replace the snapshot
-  from the chosen revision, review the diff, and regenerate `vendor/pstack.lock.json`.
-  Preserve licenses and authorship. Do not add a nested `.git`, submodule, or subtree.
+- Keep the upstream base of `vendor/pstack` traceable. Record deliberate local
+  patches in `vendor/README.md` and `vendor/pstack.lock.json`, preserving the base
+  revision and original file hashes. For an upstream update, review the diff,
+  reconcile local patches, and regenerate the lock. Keep packaging and provenance
+  outside the snapshot. Preserve licenses and authorship. Do not add a nested
+  `.git`, submodule, or subtree.
 - Keep installation repeatable and preserve unrelated user files. Do not replace
   an entire agent skills directory or silently overwrite a conflicting skill.
 - Run `python3 scripts/verify_vendor.py` and `git diff --check` for repository

vendor/README.md

@@ -7,9 +7,10 @@ files: no nested repository, Git submodule, or subtree integration.
 
 `pstack.lock.json` records every imported file's SHA-256 hash and executable bit.
 Run `python3 scripts/verify_vendor.py` from the repository root to detect changed,
-missing, or extra snapshot files. The snapshot currently has no local modifications.
-The lock records the state of this import; it is not a cryptographic signature
-of upstream authorship.
+missing, or extra snapshot files. The lock records the installed snapshot,
+including the local patches listed below; it is not a cryptographic signature
+of upstream authorship. `revision` identifies the upstream base, while
+`local_patches` records each patched file and its original upstream hash.
 
 Keep `pstack/LICENSE`, `NOTICE.md`, `UPSTREAM.md`, and `metadata/` intact. The
 Paperclip fork itself records its earlier import from Cursor and its portability
@@ -26,3 +27,14 @@ import history. That history deliberately is not included here, so use our outer
 snapshot verifier for preservation. Run upstream history-dependent checks in an
 upstream clone. The upstream installation documentation and scripts are otherwise
 preserved unchanged.
+
+## Local patches
+
+- **2026-10-21 — `skills/principle-boundary-discipline/SKILL.md`:** expand the
+  principle to cover module ownership, justification of shared changes, delivery
+  scope, and verification across consumers. Preserve its explicit invocation
+  policy. This is an intentional local addition requested by the library owner.
+
+Reconcile these patches during upstream updates rather than silently discarding
+or attributing them to upstream. The vendored upstream metadata remains the
+imported baseline; this file and the outer lock record our subsequent patches.

vendor/pstack.lock.json

@@ -3,7 +3,15 @@
   "revision": "37d2ddde97aaef8017ccef811e682948f421062d",
   "imported_on": "2026-10-10",
   "directory": "vendor/pstack",
-  "strategy": "verbatim tracked-file snapshot; no nested Git repository, submodule, or subtree",
+  "strategy": "tracked-file snapshot with documented local patches; no nested Git repository, submodule, or subtree",
+  "local_patches": [
+    {
+      "path": "skills/principle-boundary-discipline/SKILL.md",
+      "applied_on": "2026-10-21",
+      "reason": "Add module ownership, shared-change justification, delivery scope, and consumer verification guidance.",
+      "upstream_sha256": "62ac2862c2caa22dd14531f51c9c6bb445ceb198ca98a687e25b4d47c1f10a28"
+    }
+  ],
   "files": {
     ".github/workflows/validate.yml": {
       "sha256": "06c2ba3fccc5ff4cd2a2a0f29520f9be3ca9ef0cb12404de3ebc7c2f77c382d8",
@@ -582,7 +590,7 @@
       "executable": false
     },
     "skills/principle-boundary-discipline/SKILL.md": {
-      "sha256": "62ac2862c2caa22dd14531f51c9c6bb445ceb198ca98a687e25b4d47c1f10a28",
+      "sha256": "b03dfb2db7018a0ce1c6eded5177cce6e25d48d3300588e09b0adc392f5810d2",
       "executable": false
     },
     "skills/principle-boundary-discipline/agents/openai.yaml": {

vendor/pstack/skills/principle-boundary-discipline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: principle-boundary-discipline
-description: "Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions."
+description: "Apply when changing module contracts, provider integrations, validation, error handling, or framework adapters. Keep special-purpose policy with its owner, shared contracts narrow, and validation at system boundaries."
 disable-model-invocation: true
 ---
 
@@ -29,6 +29,46 @@ Code organization:
 - Prompt construction: structured state in, string out
 - Scoring and assessment: pure transforms from state to results
 
+**Module ownership and shared changes:**
+
+Before a substantive change crosses modules, identify the behavior's owner,
+the existing contract callers should use, and why that contract is insufficient.
+Use the task's existing plan or review description; this does not require a new
+document or approval step.
+
+- Keep provider protocols, payload interpretation, workarounds, and feature-specific
+  sequencing in their owning module. Shared code consumes normalized domain
+  contracts. A small registration table or dispatch branch may select the provider
+  and delegate its behavior.
+- Reuse existing extension points before adding the smallest typed contract the
+  concrete workflow needs. Moving a function or renaming an interface does not
+  remove a dependency on private implementation details. Do not pass the whole
+  service context just to make extraction easy.
+- For each substantive change outside the owning module, explain the shared
+  capability, affected existing consumers, and behavior when the new feature is
+  absent or disabled. Group related files by responsibility; declarations,
+  branding, and registration can remain in their established locations.
+- Ask whether removing or substituting the provider would leave a coherent shared
+  contract. One consumer can justify a general capability; hypothetical reuse or
+  a second fixture alone does not. Preserve meaningful provider differences and
+  avoid speculative frameworks.
+- Review delivery scope separately from code ownership. A correctly factored
+  platform capability may need an independently reviewable slice or an explicit
+  dependency in a PR stack. Keep tests and docs with their behavior, preserve
+  requested features, and respect the user's delivery constraints.
+- Keep authorization, isolation, audit, transaction, and resource ownership
+  invariants with their existing owners. Trusting validated types does not replace
+  checks of current authority or state. Provider isolation must not bypass them.
+- Verify the changed contract through the new consumer and relevant existing
+  consumers, including feature absence or disablement where behavior could change.
+  Test observable outcomes. Identifier searches, line counts, and passing CI do not
+  establish sound boundaries by themselves.
+
+Apply these checks to changed behavior; an unrelated fix does not require a
+subsystem rewrite.
+
 **The tests:**
 - "Is this data crossing a system boundary right now?" If not, validation is redundant.
 - "Can this be a pure function that the shell just calls?" If yes, extract it.
+- "Does the shared layer understand a provider protocol, or only select its implementation?" Delegate protocol behavior to the owner.
+- "Why must this change live outside the feature, and what does it change for existing consumers?" Explain both ownership and delivery scope.