@piagent/platform 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (159) hide show
  1. package/.gitattributes +7 -0
  2. package/AGENTS.md +31 -0
  3. package/CHANGELOG.md +296 -0
  4. package/CODE_OF_CONDUCT.md +36 -0
  5. package/CONTRIBUTING.md +66 -0
  6. package/LICENSE +21 -0
  7. package/README.md +588 -0
  8. package/SECURITY.md +38 -0
  9. package/adapters/backend-api/profile.json +88 -0
  10. package/adapters/be-readonly-fe/profile.json +120 -0
  11. package/adapters/data/profile.json +88 -0
  12. package/adapters/devops/profile.json +92 -0
  13. package/adapters/docs/profile.json +74 -0
  14. package/adapters/fullstack/profile.json +94 -0
  15. package/adapters/generic/profile.json +95 -0
  16. package/adapters/mobile/profile.json +87 -0
  17. package/adapters/node-typescript/profile.json +76 -0
  18. package/adapters/python/profile.json +75 -0
  19. package/adapters/web-frontend/profile.json +101 -0
  20. package/catalog/capabilities.json +206 -0
  21. package/docs/architecture.md +64 -0
  22. package/docs/auto-delegation-policy.md +192 -0
  23. package/docs/capability-packs.md +234 -0
  24. package/docs/command-reference-vietnamese.md +484 -0
  25. package/docs/context-window-policy.md +85 -0
  26. package/docs/distribution-standard.md +229 -0
  27. package/docs/herdr-workflow.md +58 -0
  28. package/docs/mcp-and-tools.md +316 -0
  29. package/docs/memory-policy.md +164 -0
  30. package/docs/model-options.md +165 -0
  31. package/docs/oauth-providers.md +53 -0
  32. package/docs/operator-manual-vietnamese.md +1080 -0
  33. package/docs/package-architecture-notes.md +101 -0
  34. package/docs/project-adapters.md +174 -0
  35. package/docs/project-onboarding.md +135 -0
  36. package/docs/publishing-for-teams.md +64 -0
  37. package/docs/quality-benchmark.md +74 -0
  38. package/docs/quickstart-vietnamese.md +350 -0
  39. package/docs/release-install-policy.md +223 -0
  40. package/docs/runtime-harness-standard.md +118 -0
  41. package/docs/runtime-policy-design.md +132 -0
  42. package/docs/runtime-quality-baseline.md +257 -0
  43. package/docs/security-redaction-benchmark.md +56 -0
  44. package/docs/security-threat-model.md +66 -0
  45. package/docs/subagent-orchestration-capabilities.md +104 -0
  46. package/docs/subagents-and-multiagent.md +346 -0
  47. package/docs/task-implementation-contract.md +200 -0
  48. package/docs/team-onboarding.md +333 -0
  49. package/docs/usage-observability.md +130 -0
  50. package/docs/vercel-docs-site.md +115 -0
  51. package/docs/workflow-recipes.md +125 -0
  52. package/docs-site/assets/piagent-logo.svg +35 -0
  53. package/docs-site/favicon.svg +18 -0
  54. package/docs-site/index.html +1613 -0
  55. package/docs-site/vercel.json +24 -0
  56. package/evals/fixtures/action-proposal.invalid.json +34 -0
  57. package/evals/fixtures/action-proposal.valid.json +34 -0
  58. package/evals/fixtures/capability-pack.invalid.json +123 -0
  59. package/evals/fixtures/capability-pack.valid.json +123 -0
  60. package/evals/fixtures/capability-recipe.invalid.json +81 -0
  61. package/evals/fixtures/capability-recipe.valid.json +82 -0
  62. package/evals/fixtures/context-index.invalid.json +25 -0
  63. package/evals/fixtures/context-index.valid.json +25 -0
  64. package/evals/fixtures/eval-scenario.invalid.json +40 -0
  65. package/evals/fixtures/eval-scenario.valid.json +45 -0
  66. package/evals/fixtures/project-profile.invalid.json +88 -0
  67. package/evals/fixtures/project-profile.valid.json +95 -0
  68. package/evals/fixtures/task-contract.invalid.json +73 -0
  69. package/evals/fixtures/task-contract.valid.json +74 -0
  70. package/evals/golden/enforcement-decisions.json +329 -0
  71. package/evals/scenarios/capability-resolution.json +45 -0
  72. package/package.json +132 -0
  73. package/packages/piagent-core/README.md +147 -0
  74. package/packages/piagent-core/capabilities/capability-core.js +1023 -0
  75. package/packages/piagent-core/capabilities/capability-sources.js +265 -0
  76. package/packages/piagent-core/extensions/guard-io.js +45 -0
  77. package/packages/piagent-core/extensions/guard-shell-analysis.ts +558 -0
  78. package/packages/piagent-core/extensions/guard-types.ts +406 -0
  79. package/packages/piagent-core/extensions/piagent-guard.ts +5760 -0
  80. package/packages/piagent-core/extensions/policy-core.js +1070 -0
  81. package/packages/piagent-core/extensions/redaction-core.js +4 -0
  82. package/packages/piagent-core/extensions/runtime-evidence.js +215 -0
  83. package/packages/piagent-core/package.json +46 -0
  84. package/packages/piagent-core/policies/base-policy.json +249 -0
  85. package/packages/piagent-core/prompts/be-to-fe.md +82 -0
  86. package/packages/piagent-core/prompts/commit.md +27 -0
  87. package/packages/piagent-core/prompts/discuss.md +35 -0
  88. package/packages/piagent-core/prompts/memory-policy.md +52 -0
  89. package/packages/piagent-core/prompts/model-options.md +68 -0
  90. package/packages/piagent-core/prompts/onboard-project.md +147 -0
  91. package/packages/piagent-core/prompts/piagent-commands.md +68 -0
  92. package/packages/piagent-core/prompts/plan.md +35 -0
  93. package/packages/piagent-core/prompts/platform-improve.md +69 -0
  94. package/packages/piagent-core/prompts/pr.md +26 -0
  95. package/packages/piagent-core/prompts/review.md +38 -0
  96. package/packages/piagent-core/prompts/scout.md +50 -0
  97. package/packages/piagent-core/prompts/task.md +69 -0
  98. package/packages/piagent-core/security/sensitive-data.js +187 -0
  99. package/packages/piagent-core/skills/piagent-ops/SKILL.md +44 -0
  100. package/packages/piagent-core/skills/piagent-source-cache/SKILL.md +59 -0
  101. package/packages/piagent-core/skills/piagent-source-cache/checkout-source-repo.sh +144 -0
  102. package/packages/piagent-core/subagents/piagent-oracle.md +29 -0
  103. package/packages/piagent-core/subagents/piagent-planner.md +46 -0
  104. package/packages/piagent-core/subagents/piagent-reviewer.md +48 -0
  105. package/packages/piagent-core/subagents/piagent-scout.md +37 -0
  106. package/packages/piagent-core/subagents/piagent-worker.md +44 -0
  107. package/packs/engineering-base/pack.json +123 -0
  108. package/packs/engineering-base/recipes/bounded-change.json +82 -0
  109. package/packs/web-delivery/pack.json +72 -0
  110. package/packs/web-delivery/recipes/verified-web-change.json +57 -0
  111. package/schemas/action-proposal.schema.json +90 -0
  112. package/schemas/capability-pack.schema.json +190 -0
  113. package/schemas/capability-recipe.schema.json +72 -0
  114. package/schemas/context-index.schema.json +258 -0
  115. package/schemas/eval-scenario.schema.json +67 -0
  116. package/schemas/project-profile.schema.json +555 -0
  117. package/schemas/task-contract.schema.json +314 -0
  118. package/scripts/audit-runtime-host.sh +78 -0
  119. package/scripts/bootstrap-local.sh +25 -0
  120. package/scripts/capability-catalog.mjs +290 -0
  121. package/scripts/check-runtime-advisories.mjs +114 -0
  122. package/scripts/configure-mcp.sh +301 -0
  123. package/scripts/configure-model-scope.sh +143 -0
  124. package/scripts/configure-subagents.sh +241 -0
  125. package/scripts/import-agent-instructions.mjs +199 -0
  126. package/scripts/init-project.sh +369 -0
  127. package/scripts/install-global.sh +532 -0
  128. package/scripts/link-project.sh +25 -0
  129. package/scripts/migrate-project-state.mjs +176 -0
  130. package/scripts/pi-auto.sh +79 -0
  131. package/scripts/pi-model-catalog.sh +154 -0
  132. package/scripts/pi-session-stats.sh +135 -0
  133. package/scripts/piagent-cli.mjs +53 -0
  134. package/scripts/profile-doctor.sh +238 -0
  135. package/scripts/quality-benchmark.sh +185 -0
  136. package/scripts/redaction-benchmark.mjs +227 -0
  137. package/scripts/runtime-policy-smoke.sh +48 -0
  138. package/scripts/setup.sh +425 -0
  139. package/scripts/team-doctor.sh +461 -0
  140. package/scripts/verify-local.sh +540 -0
  141. package/scripts/verify-release-identity.mjs +85 -0
  142. package/scripts/verify-vercel-link.mjs +64 -0
  143. package/templates/global/mcp.json +9 -0
  144. package/templates/global/settings.json +37 -0
  145. package/templates/project/.mcp.json +9 -0
  146. package/templates/project/.pi/context-index.json +25 -0
  147. package/templates/project/.pi/gitignore.template +22 -0
  148. package/templates/project/.pi/mcp.json +9 -0
  149. package/templates/project/.pi/memory/MEMORY.md +11 -0
  150. package/templates/project/.pi/memory/memory_summary.md +9 -0
  151. package/templates/project/.pi/piagent-profile.json +107 -0
  152. package/templates/project/.pi/project-context.md +30 -0
  153. package/templates/project/.pi/settings.json +17 -0
  154. package/templates/project/.pi/task-contract.template.json +74 -0
  155. package/templates/project/.pi/tech-context/README.md +7 -0
  156. package/templates/project/.pi/tech-stack.json +10 -0
  157. package/templates/project/AGENTS.md +34 -0
  158. package/templates/project/REVIEW_GUIDELINES.md +23 -0
  159. package/types/pi-runtime-shims.d.ts +13 -0
package/.gitattributes ADDED
@@ -0,0 +1,7 @@
1
+ *.sh text eol=lf
2
+ *.mjs text eol=lf
3
+ *.ts text eol=lf
4
+ *.js text eol=lf
5
+ *.json text eol=lf
6
+ *.md text eol=lf
7
+ docs-site/*.html text eol=lf
package/AGENTS.md ADDED
@@ -0,0 +1,31 @@
1
+ # Pi Agent Platform — Agent Instructions
2
+
3
+ ## Mission
4
+
5
+ This repository builds reusable Pi agent infrastructure for multiple projects and teams.
6
+
7
+ ## Non-negotiables
8
+
9
+ - Do not commit OAuth tokens, API keys, `auth.json`, sessions, caches, or local trust files.
10
+ - Keep project-specific business logic out of `packages/piagent-core`.
11
+ - Put reusable profile families in `adapters/<profile>/profile.json`.
12
+ - Keep project-specific/private examples out of public commits; put them in the target project's own repo or `examples/private/`.
13
+ - Prefer docs and policy schemas over prompt-only enforcement.
14
+ - Any destructive or external-provider action must be explicitly confirmed by the human operator.
15
+ - Treat Pi project trust as code execution trust, not as a sandbox.
16
+
17
+ ## File ownership
18
+
19
+ - Core Pi package: `packages/piagent-core/`
20
+ - Global docs: `docs/`
21
+ - Reusable profiles: `adapters/`
22
+ - Project-specific examples: `examples/`
23
+ - Project bootstrap templates: `templates/`
24
+ - Local scripts: `scripts/`
25
+
26
+ ## Engineering style
27
+
28
+ - Keep code small, boring, and auditable.
29
+ - Avoid hidden magic in prompts. If behavior must be enforced, put it in extension/tool-call guard.
30
+ - Source code and identifiers: English.
31
+ - Human-facing long-form docs may be Vietnamese; reusable workflow prompts and command names stay English.
package/CHANGELOG.md ADDED
@@ -0,0 +1,296 @@
1
+ # Changelog
2
+
3
+ This file records release-facing changes for Pi Agent Platform. Copy the relevant version block into GitHub Releases when publishing a tag.
4
+
5
+ ## v1.0.0 - 2026-07-25
6
+
7
+ Breaking release. The `company` namespace is replaced by `piagent` with no alias layer, and `apiVersion` becomes a stable contract. Existing projects convert their local state with one migration command; both names never work at once.
8
+
9
+ ### Added
10
+
11
+ - Added `capabilitySources` to project profiles so a project can use capability packs it does not own without forking the platform. A source is either a directory inside the project or an exact npm or git release vendored into it.
12
+ - Added `piagent-capabilities vendor`, the only command that reaches the network. It fetches a declared remote source into `.pi/capability-vendor/`, refuses a tree containing symbolic links or no packs, and reports digests for review before the result is committed.
13
+ - Added `piagent-migrate` to convert `.pi/company-profile.json`, its lock, and `.pi/company-state/` to the new names. Dry-run by default, with an explicit flag to write and a separate flag to remove the old files.
14
+ - Added `piagent-import-instructions` to import `CLAUDE.md`, `.claude/rules/`, `.cursor/rules/`, and `.github/copilot-instructions.md` into `AGENTS.md`. Dry-run by default, with a deterministic conflict report; imported text is quoted as data and never alters protected paths, permission profile, or verify commands.
15
+ - Added skill wiring for `.claude/skills` and `.codex/skills` at project scope and their home-directory equivalents at global scope, plus doctor checks that report skill directories present on disk but not declared, and instruction files written for other agents.
16
+ - Added a golden enforcement suite covering protected paths, protected paths reached through the shell, destructive shell decisions, verification evidence, context budget ceilings, and secret redaction, with a valid and an invalid fixture for every shipped schema.
17
+ - Added contributor documentation: `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, pull-request and issue templates.
18
+ - Added a tag-driven publish workflow with npm provenance and pinned action revisions.
19
+
20
+ ### Changed
21
+
22
+ - **Breaking.** Renamed the namespace to `piagent` throughout: tools `company_*` to `piagent_*`, commands `pi-company-*` to `piagent-*`, package `pi-agent-platform` to `@piagent/platform`, `packages/pi-company-core/` to `packages/piagent-core/`, environment variables `PI_COMPANY_*` to `PIAGENT_*`, and project state to `.pi/piagent-profile.json`, `.pi/piagent-profile.lock.json`, and `.pi/piagent-state/`. There is no alias layer; a session started against unconverted state warns and names the migration command.
23
+ - **Breaking.** Promoted the manifest `apiVersion` from `piagent/v1alpha1` to `piagent/v1`. This is the point at which external packs can pin it, so it is a contract from here on.
24
+ - The capability lock now records where each pack came from, so a pack that moves between sources reads as a substitution rather than an update.
25
+ - The package is now published rather than private, scoped as `@piagent/platform` with public access and provenance.
26
+ - Split shell and external-action classification, shared types, and filesystem helpers out of the guard into their own modules. Behaviour is unchanged.
27
+ - Onboarding now names instruction files written for other agents, states plainly that their rules are not in effect, and offers the import; anything inside them is treated as data.
28
+
29
+ ### Fixed
30
+
31
+ - Fixed a capability policy that declares only some of its allow-lists: the missing lists now deny, instead of failing with an internal error.
32
+ - Fixed capability source resolution under a symlinked project parent, where a contained directory could be misread as escaping the project.
33
+ - Excluded maintainer working notes from the published tarball. The `files` allowlist takes precedence over `.npmignore`, so the exclusions live in `files`.
34
+ - Fixed the package manifest declaring its extension entry points as a directory glob. Pi calls the default export of every path the field matches, so once the guard's helpers moved into modules beside it, the glob offered Pi two modules that export helpers and no extension factory. The manifest now names the guard, and the package still carried the old `@pi-agent/core` name the namespace rename was meant to retire.
35
+ - Fixed the verify workflow, which had been unparseable since the runtime-platform step was added and so had not run at all. A single-line `run:` value containing `": "` ends the YAML scalar early; GitHub reports that as an instant failure with no job, so the gate was absent while still appearing present. The local gate now refuses that shape.
36
+
37
+ ### Security
38
+
39
+ - The runtime host audit now names the one advisory it accepts instead of running at a blanket severity threshold. `GHSA-mh99-v99m-4gvg` (`brace-expansion`, denial of service) is accepted with its reasoning recorded in `scripts/check-runtime-advisories.mjs`: the Pi host publishes an `npm-shrinkwrap.json` that pins the affected version, a published shrinkwrap takes precedence over consumer overrides, and every released host carries a high `brace-expansion` advisory, so no host version and no change in this repository can resolve it. Every other high or critical advisory still fails the audit, the entry expires on a review date, and it fails once the advisory stops being reported so it cannot outlive the problem.
40
+
41
+ ## Unreleased
42
+
43
+ ### Added
44
+
45
+ - Added solo-first orchestration policy for bounded subagent usage, review lenses, Field Guide status, and model-role guidance.
46
+ - Added `company_orchestration_policy` and `/company-orchestration` for compact local orchestration status without a model follow-up.
47
+ - Added task-contract fields for `workPlan`, `reviewLenses`, and `orchestration` snapshots.
48
+ - Added select-style profile tech setup via `/profile setup` and `/profile tech setup`, including fullstack FE/BE/database selections.
49
+ - Added `company_profile_tech_options`, `company_profile_tech_apply`, and `company_profile_tech_context_record` for Context7-ready tech stack manifests and concise per-tech snapshots.
50
+
51
+ ### Changed
52
+
53
+ - Updated `/task`, `/plan`, `/review`, subagent prompts, and team docs to prefer one parent agent plus bounded scout/planner/reviewer usage instead of broad swarm-style delegation.
54
+ - Updated onboarding/docs to treat profile family and project tech stack as explicit operator selections instead of long model explanations.
55
+ - Tightened `/profile` status/list output around the single namespace and next exact command so the default path stays compact.
56
+ - Clarified runtime support across macOS Apple Silicon, macOS Intel, Linux x64/ARM64, native Windows, and WSL2, and made installer/doctor output report the current runtime surface.
57
+
58
+ ### Fixed
59
+
60
+ - Hardened orchestration config normalization so malformed numeric settings fall back safely instead of producing invalid policy state.
61
+ - Fixed tag CI verification by fetching the annotated release tag ref before checking tag object type and peeled commit identity.
62
+ - Added profile-doctor and team-doctor warnings for legacy `shellProtectedPaths`-only entries, clarifying that those paths block shell access only and must move to `protectedPaths` or `readOnlyPaths` for write protection.
63
+
64
+ ## v0.4.8 - 2026-07-22
65
+
66
+ ### Added
67
+
68
+ - Added release/install policy docs covering stable, exact, dev, local, update, and rollback flows.
69
+ - Added `pi-company-install` channel options and dry-run preview for stable, exact, dev, and local installs.
70
+ - Added a package-root dispatcher for global `pi-company-*` terminal commands.
71
+ - Added `readOnlyPaths` to project profiles for read-only contract areas such as backend code in `be-readonly-fe`.
72
+ - Added regression tests for untrusted project profiles, profile-apply confirmation, shell/exec aliases, external-provider write confirmation, BE-readonly/FE-write paths, package distribution, and installer edge cases.
73
+ - Added tag-triggered CI verification with immutable GitHub Action revisions on both Ubuntu and macOS.
74
+ - Added release identity verification across root/core manifests, package lock, capability lock, changelog, docs badge, tag, and checked-out commit.
75
+ - Added a separate high-severity dependency audit for the exact Pi host and pinned optional add-ons instead of relying only on the helper package lock.
76
+ - Added a public threat model and `SECURITY.md` with private vulnerability reporting, supported-version, disclosure, and scope guidance.
77
+ - Added weekly Dependabot checks for npm and GitHub Actions plus pinned CodeQL v4 analysis for JavaScript/TypeScript and workflow code.
78
+ - Added a fail-closed Vercel project-link preflight so a stale local `.vercel` link cannot silently deploy docs to the wrong project.
79
+
80
+ ### Changed
81
+
82
+ - Clarified public docs comparison with Codex CLI and Claude Code: Pi Company Platform brings similar governance concepts into Pi and packages them for team workflows.
83
+ - Reworded security docs to describe the guard as an application-level policy enforcement layer, not a complete security boundary or OS sandbox.
84
+ - Split install guidance so production/team setup uses pinned `v0.4.8` or resolved commit sources, while latest is reserved for personal/sandbox use.
85
+ - Clarified that redaction benchmarks and internal review are not equivalent to an external security audit.
86
+ - Raised the supported Node.js runtime contract to `>=22.19.0`.
87
+ - Raised the pinned Pi Coding Agent and Pi AI compatibility from `0.80.10` to `0.81.1`, retaining exact `typebox` compatibility and removing the known high-severity transitive finding present in the previous host tree.
88
+ - Updated CI to verify on Ubuntu and macOS with Node.js 22.19.0.
89
+ - Documented the three-component Pi-host/helper/Pi-package lifecycle, exact rollback flow, supported operating systems, and post-tag Vercel promotion gate.
90
+ - Made setup install or upgrade to the exact Pi host required by the release and made package installation reject an incompatible host version.
91
+ - Expanded runtime dependency verification from the Pi host alone to the exact host plus all pinned optional add-ons.
92
+
93
+ ### Fixed
94
+
95
+ - Hardened local profile loading so `.pi/company-profile.json` is ignored until the project is trusted, unless an operator explicitly sets `PI_COMPANY_PROFILE`.
96
+ - Hardened `pi-company-install --stable` so it resolves the release tag to a commit SHA before install and fails closed when resolution is unavailable.
97
+ - Bound the deterministic capability lock to `packages/pi-company-core/policies/base-policy.json`.
98
+ - Fixed `be-readonly-fe` so backend paths are readable through safe path tools but remain blocked for writes and shell access.
99
+ - Applied shell protected-path checks consistently to `bash`, `shell`, and `exec` tool aliases.
100
+ - Inspected complete structured shell invocations, including `command`/`cmd` plus `args`, and rejected conflicting, malformed, oversized, or unbounded carriers before execution.
101
+ - Added a generic human confirmation gate for external-provider write or ambiguous tools while preserving known safe reads such as `get_release`.
102
+ - Rejected conflicting installer package selectors before any install command can run; the first explicit CLI selector now cleanly overrides environment defaults.
103
+ - Routed global commands through a package-root dispatcher and converted missing shell-runner failures into controlled errors.
104
+ - Isolated runtime-evidence test ledgers so test runs no longer leave new `pi-ledger-*` temporary directories.
105
+ - Decoded the extension module URL before locating its package policy so installs under paths containing spaces or other URL-encoded characters load the intended policy.
106
+ - Made project init resilient to npm package tarballs that omit its `.pi/.gitignore` dotfile by shipping an explicit fallback template.
107
+ - Prevented project init from creating `.pi/.npmignore`, which could override repository ignore rules and re-include local Pi auth, trust, ledger, or database state in an npm package.
108
+ - Applied provider confirmation and path policy to the default serialized MCP proxy carrier, including bounded JSON parsing and fail-closed malformed/deep payload handling.
109
+ - Closed MCP path-policy bypasses across common aliases such as `filename`, `rootPath`, `source`, `cwd`, and `workingDirectory`; copy sources now use read scope while destinations use write/read-only scope, without treating provider metadata as a local path.
110
+ - Applied protected-path checks to camelCase patch carriers and shell proxy variants such as `run`, `execute_process`, and command-bearing aliases before an operator confirmation can allow execution.
111
+ - Added confirmation gates for shell-launched GitHub CLI writes and non-read-only HTTP client operations, including wrappers, executable aliases, line continuations, dynamic command construction, `xargs`, and FTP/SFTP quote commands, while keeping recognized reads and argument-only substitutions non-interactive.
112
+ - Made every packaged `pi-company-* --help` command succeed without requiring a project path or creating project state.
113
+
114
+ ### Security
115
+
116
+ - Project-local profiles are not trusted before Pi project trust is active.
117
+ - Capability locks now detect base policy tampering, not only runtime source-file changes.
118
+ - Tool-based profile apply requires operator confirmation before writing `.pi/company-profile.json` and `.pi/company-profile.lock.json`.
119
+ - External provider writes are treated as human-gated actions even under `trusted-full-access`.
120
+ - Unknown MCP/provider actions fail closed to operator confirmation; explicit safe reads remain non-interactive.
121
+ - Release tags are verified in CI, installer stable channels resolve tags to commit SHAs, and dependency setup actions are pinned by commit SHA.
122
+ - Tag CI binds stable resolution to the exact release commit and rejects environment attempts to substitute the helper's package-derived release tag.
123
+ - Tag CI now requires an annotated tag whose peeled commit is the exact verified release commit; repository ruleset requirements are documented for immutable `v*` tags.
124
+ - Release CI includes redaction, release identity, dependency, CodeQL, package-content, and cross-platform policy gates; Actions are pinned to reviewed commit SHAs.
125
+
126
+ ### Verification
127
+
128
+ - `npm run verify`: pass.
129
+ - `npm test`: 224/224 pass.
130
+ - `npm run typecheck`: pass.
131
+ - `npm run smoke`: pass.
132
+ - Helper dependency audit (`npm audit --audit-level=high`): 0 vulnerabilities.
133
+ - Exact Pi 0.81.1 host + pinned add-on audit (`npm run audit:runtime`): 0 high/critical findings; npm reports 11 moderate dependency paths across two upstream advisory families (`@hono/node-server` encoded-backslash traversal on Windows and `protobufjs` parser DoS).
134
+ - `npm run benchmark:redaction`: pass.
135
+ - `npm pack --dry-run --json`: 144 packaged files; required runtime files present and local trust/secret state excluded; all 12 installed terminal binaries pass `--help` from the built artifact.
136
+ - Docs browser/runtime check: 0 duplicate IDs, broken anchors, broken images, unsafe blank targets, or console errors; mobile viewport has no horizontal overflow.
137
+
138
+ ## v0.4.7 - 2026-07-22
139
+
140
+ ### Added
141
+
142
+ - Added `/commit` as a guarded local commit workflow:
143
+ - inspect status and diff before staging;
144
+ - stage explicit reviewed files only;
145
+ - run relevant verification before commit;
146
+ - never push from `/commit`.
147
+ - Added `/pr` as a guarded pull request preparation workflow:
148
+ - inspect branch, status, upstream, and remote;
149
+ - require a clean committed branch before PR work;
150
+ - require explicit operator confirmation before `git push` or GitHub write actions.
151
+ - Added an exec-policy confirmation rule for broad Git staging, including `git add .`, `git add -A`, `git add --all`, `git add -- .`, `git add :/`, and `git -C <repo> add .`.
152
+ - Added regression tests for the new Git workflow prompts and broad-staging policy.
153
+ - Added canonical public docs metadata for `https://piagent.io.vn`.
154
+
155
+ ### Changed
156
+
157
+ - Install docs now default to latest:
158
+ - `pi install git:github.com/Vt-mmm/pi_agent`
159
+ - `pi update --extensions`
160
+ - Pinned install examples use placeholders such as `vX.Y.Z` and `x.y.z` instead of hardcoding an old release.
161
+ - Runtime smoke verification now reads the current package version from `package.json` instead of hardcoding a tag.
162
+ - Docs site, README, package metadata, and Vercel docs now point to `https://piagent.io.vn`.
163
+
164
+ ### Security
165
+
166
+ - Git remains a normal guarded capability, not a privileged `/git` bypass.
167
+ - Broad staging requires confirmation so unrelated or private files are not committed silently.
168
+ - Protected paths, sensitive-output redaction, capability lock integrity, and destructive/external confirmation gates remain active in every permission profile.
169
+
170
+ ### Verification
171
+
172
+ - `npm run verify`: pass.
173
+ - `bash scripts/runtime-policy-smoke.sh`: pass.
174
+ - `npm test`: 185/185 pass.
175
+ - `npm run typecheck`: pass.
176
+
177
+ ## v0.4.6 - 2026-07-22
178
+
179
+ ### Added
180
+
181
+ - Added the static HTML documentation site under `docs-site/`.
182
+ - Added Vercel static-site configuration and deployment documentation.
183
+ - Added project logo, favicon, GitHub link, and Facebook link to the docs site.
184
+
185
+ ### Changed
186
+
187
+ - Streamlined command documentation for lower-token daily usage.
188
+ - Removed the `SHIP` sidebar section from the docs site.
189
+ - Centered the docs layout and tightened the visual structure for wide screens.
190
+ - Documented latest global install and pinned project setup separately.
191
+
192
+ ### Verification
193
+
194
+ - `git diff --check`: pass.
195
+ - Package verification remains covered by `npm run verify`.
196
+
197
+ ## v0.4.5 - 2026-07-22
198
+
199
+ ### Added
200
+
201
+ - Added direct profile commands that apply immediately without model follow-up:
202
+ - `/profile`
203
+ - `/profile`
204
+ - `/profile list`
205
+ - `/profile <profile>`
206
+ - `/profile auto`
207
+ - Added short profile aliases such as `fe`, `be`, `full`, `be-fe`, and TypeScript-oriented aliases.
208
+
209
+ ### Changed
210
+
211
+ - `/company-status` and `/company-memory` now return concise local summaries instead of prompting verbose model/tool follow-up.
212
+ - Profile status output is intentionally compact to reduce token burn in routine checks.
213
+
214
+ ### Security
215
+
216
+ - Direct profile apply still regenerates the deterministic capability lock and does not relax protected paths, secret redaction, or capability integrity checks.
217
+
218
+ ## v0.4.4 - 2026-07-21
219
+
220
+ ### Added
221
+
222
+ - Added session-local permission slash commands:
223
+ - `/permission-status`
224
+ - `/read-only`
225
+ - `/workspace-write`
226
+ - `/full-access`
227
+ - `/full-access <task>`
228
+
229
+ ### Changed
230
+
231
+ - Permission resolution precedence is explicit: launch environment override, then session command, then project profile, then policy default.
232
+ - `/full-access <task>` switches the session and forwards the task text as the next request.
233
+
234
+ ### Security
235
+
236
+ - `trusted-full-access` remains guarded. It relaxes selected autonomy checks for trusted workspace work but does not disable protected paths, secret redaction, capability lock integrity, or destructive/external confirmations.
237
+
238
+ ## v0.4.3 - 2026-07-21
239
+
240
+ ### Added
241
+
242
+ - Added runtime permission profiles:
243
+ - `read-only`;
244
+ - `workspace-write`;
245
+ - `trusted-full-access`.
246
+ - Added `PI_COMPANY_PERMISSION_PROFILE` for trusted one-run permission override.
247
+
248
+ ### Security
249
+
250
+ - Invalid permission override values fail closed.
251
+ - The profile system is a runtime policy layer, not an operating-system sandbox.
252
+
253
+ ## v0.4.2 - 2026-07-21
254
+
255
+ ### Added
256
+
257
+ - Added sensitive-data redaction benchmark coverage for contextual secrets, benign preservation, structured payloads, and large output.
258
+ - Added release gates for redaction recall and false-positive control.
259
+
260
+ ### Changed
261
+
262
+ - Improved sensitive-data redaction for common credential shapes and nested structured data.
263
+ - Kept unlabeled high-entropy strings observational instead of redacting indiscriminately.
264
+
265
+ ### Verification
266
+
267
+ - Frozen-tree redaction baseline: 52/52 contextual cases detected, 0/30 benign false positives, 8/8 structured sensitive values redacted, and 7/7 structured benign values preserved.
268
+
269
+ ## v0.4.1 - 2026-07-21
270
+
271
+ ### Fixed
272
+
273
+ - Hardened shell secret protection against glob expansion targeting protected files.
274
+ - Hardened shell protection for bare-word aliases and symlinks resolving to protected paths.
275
+ - Added sensitive bash output redaction before tool results reach the model.
276
+ - Covered attached redirections such as `cat<.env` and similar shell forms.
277
+
278
+ ### Security
279
+
280
+ - Static shell protection is stronger, but the guard still does not claim to be an OS sandbox.
281
+ - Protected-path blocking and output redaction are separate defense layers.
282
+
283
+ ## v0.4.0 - 2026-07-21
284
+
285
+ ### Added
286
+
287
+ - Added governed capability packs with deterministic catalog generation.
288
+ - Added profile capability resolution and `.pi/company-profile.lock.json`.
289
+ - Added lock integrity checks for package source, artifact digests, capability scope, and runtime enforcement files.
290
+ - Added atomic profile/lock write behavior with rollback on failure.
291
+
292
+ ### Security
293
+
294
+ - Lock tampering fails closed.
295
+ - Core protected paths include `.pi/settings.json` and `.pi/company-profile.lock.json`.
296
+ - Capability scope can only narrow access; protected paths remain denied before allow-scope checks.
@@ -0,0 +1,36 @@
1
+ # Code of conduct
2
+
3
+ ## Our pledge
4
+
5
+ We want participation in this project to be a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
6
+
7
+ ## Standards
8
+
9
+ Behavior that helps:
10
+
11
+ - being respectful of differing viewpoints and experience levels
12
+ - accepting constructive feedback gracefully
13
+ - focusing on what is best for the project
14
+ - showing empathy toward other participants
15
+
16
+ Behavior that is not acceptable:
17
+
18
+ - sexualized language or imagery, and unwelcome sexual attention
19
+ - trolling, insulting or derogatory comments, and personal or political attacks
20
+ - public or private harassment
21
+ - publishing others' private information without explicit permission
22
+ - other conduct that would reasonably be considered inappropriate in a professional setting
23
+
24
+ ## Scope
25
+
26
+ This applies in project spaces — issues, pull requests, discussions — and when someone is representing the project in public.
27
+
28
+ ## Enforcement
29
+
30
+ Report unacceptable behavior to the maintainer through [GitHub private vulnerability reporting](https://github.com/Vt-mmm/piagent/security/advisories/new) or a direct message. Reports will be reviewed and investigated, and the reporter's identity will be kept confidential.
31
+
32
+ Maintainers may remove, edit, or reject contributions that violate this code, and may temporarily or permanently ban any contributor for behavior they consider inappropriate, threatening, offensive, or harmful.
33
+
34
+ ## Attribution
35
+
36
+ Adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4.
@@ -0,0 +1,66 @@
1
+ # Contributing
2
+
3
+ Thanks for considering a contribution.
4
+
5
+ This platform is a governance layer for the [Pi coding agent](https://github.com/badlogic/pi-mono): project profiles, capability packs, protected paths, tool policy, and verification evidence. It runs as a Pi package and is not intended to run outside Pi — proposals that add non-Pi execution surfaces (standalone policy CLIs, hook adapters for other agents, CI-only enforcement) are out of scope.
6
+
7
+ ## Before you start
8
+
9
+ - Open an issue first for anything beyond a typo or a doc fix. It is cheaper to align on approach than to rework a finished branch.
10
+ - Security issues do not go in issues or pull requests. Follow [SECURITY.md](SECURITY.md).
11
+
12
+ ## Setup
13
+
14
+ Requires Node.js `>=22.19.0`.
15
+
16
+ ```bash
17
+ npm install
18
+ npm run verify
19
+ ```
20
+
21
+ `npm run verify` runs the full local gate. Individual checks:
22
+
23
+ ```bash
24
+ npm test # node --test over tests/
25
+ npm run typecheck # tsc --noEmit
26
+ npm run capabilities:check # capability catalog is in sync
27
+ npm run doctor # environment and project wiring
28
+ ```
29
+
30
+ ## Adding an adapter profile
31
+
32
+ Adapters are the most common contribution and the easiest place to start. An adapter is a single JSON file describing how the agent should behave in one kind of repository — which paths are protected, which context files must be read, which commands verify a change.
33
+
34
+ 1. Create `adapters/<name>/profile.json`. Copy the closest existing profile and adjust; `adapters/generic/profile.json` is the safest baseline.
35
+ 2. Validate against [`schemas/project-profile.schema.json`](schemas/project-profile.schema.json).
36
+ 3. Keep `verifyCommands` real. They must be commands that actually exist in that ecosystem and actually fail on a broken change — a verification command that always passes is worse than none.
37
+ 4. Set `protectedPaths` from what the ecosystem genuinely must not have rewritten: lockfiles, generated code, migration history, credential files.
38
+ 5. Regenerate the catalog and run the gate:
39
+
40
+ ```bash
41
+ npm run capabilities:catalog
42
+ npm run verify
43
+ ```
44
+
45
+ Adapters currently live in this repository. Open an issue if you want to discuss distributing one outside it.
46
+
47
+ ## Changing enforcement code
48
+
49
+ Guard, policy, capability, and redaction changes need a test that fails before the change and passes after. State in the pull request what the failure mode was.
50
+
51
+ Do not weaken an existing test to make a change pass. If a test encodes the wrong rule, say so explicitly and change the rule deliberately.
52
+
53
+ ## Documentation
54
+
55
+ Update `docs/` only when behavior, setup, commands, architecture, or security posture actually changed. Internal refactors do not need a docs entry.
56
+
57
+ ## Commits and pull requests
58
+
59
+ - Conventional commit format: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
60
+ - Describe the invariant a change protects, not the plan or phase it came from.
61
+ - Never commit secrets, `.env` files, tokens, private keys, or personal data.
62
+ - One logical change per pull request.
63
+
64
+ ## License
65
+
66
+ Contributions are licensed under the MIT License, as in [LICENSE](LICENSE).
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Vt-mmm
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.