diff --git a/AGENTS.md b/AGENTS.md index 837e995..9b31d01 100644 --- a/AGENTS.md +++ b/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 diff --git a/vendor/README.md b/vendor/README.md index 11b327c..143ec67 100644 --- a/vendor/README.md +++ b/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. diff --git a/vendor/pstack.lock.json b/vendor/pstack.lock.json index f6c6aca..2fcac3f 100644 --- a/vendor/pstack.lock.json +++ b/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": { diff --git a/vendor/pstack/skills/principle-boundary-discipline/SKILL.md b/vendor/pstack/skills/principle-boundary-discipline/SKILL.md index dfe9a6f..49a9ef3 100644 --- a/vendor/pstack/skills/principle-boundary-discipline/SKILL.md +++ b/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.