pakem-cli 0.0.0-stage → 1.3.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.
- package/CHANGELOG.md +280 -0
- package/LICENSE +21 -0
- package/README-ID.md +666 -0
- package/README.md +665 -2
- package/SKILL.md +264 -0
- package/adapters/git-worktree/v1/README.md +17 -0
- package/adapters/identity/v1/README.md +26 -0
- package/adapters/mcp/v1/README.md +56 -0
- package/adapters/storage-sqlite/v1/README.md +5 -0
- package/assets/banner.svg +275 -0
- package/assets/divider.svg +82 -0
- package/assets/footer.svg +174 -0
- package/assets/templates/BUG-HISTORY.md +18 -0
- package/assets/templates/CONTEXT.md +26 -0
- package/assets/templates/DECISIONS.md +8 -0
- package/assets/templates/MODULE-MAP.md +14 -0
- package/assets/templates/POLICY.json +15 -0
- package/assets/templates/PROJECT.md +42 -0
- package/conformance/v1/README.md +15 -0
- package/coordination/v1/README.md +14 -0
- package/coordination/v1/board.schema.json +59 -0
- package/coordination/v1/event.schema.json +26 -0
- package/coordination/v1/status.schema.json +49 -0
- package/evals/README.md +63 -0
- package/evals/evals.json +276 -0
- package/identity/v1/README.md +14 -0
- package/identity/v1/agent-identity.schema.json +95 -0
- package/identity/v1/identity-registry.schema.json +29 -0
- package/identity/v1/signed-payload.schema.json +42 -0
- package/intelligence/v1/README.md +19 -0
- package/intelligence/v1/dependency-graph.schema.json +82 -0
- package/intelligence/v1/impact-analysis.schema.json +51 -0
- package/intelligence/v1/reconciliation.schema.json +156 -0
- package/npm/bin/pakem.js +272 -0
- package/npm/check-version.js +26 -0
- package/package.json +58 -4
- package/policy/v1/README.md +15 -0
- package/policy/v1/policy.schema.json +20 -0
- package/protocol/v1/README.md +68 -0
- package/protocol/v1/capabilities.schema.json +17 -0
- package/protocol/v1/event.schema.json +114 -0
- package/protocol/v1/session.schema.json +51 -0
- package/references/artifacts.md +96 -0
- package/references/conventions.md +83 -0
- package/references/reviews.md +44 -0
- package/runtime/v1/README.md +21 -0
- package/runtime/v1/approval.schema.json +100 -0
- package/runtime/v1/checkpoint.schema.json +17 -0
- package/runtime/v1/hook-decision.schema.json +34 -0
- package/runtime/v1/hook-payload.schema.json +12 -0
- package/runtime/v1/task-evidence.schema.json +38 -0
- package/runtime/v1/work-report.schema.json +123 -0
- package/runtime/v1/workflow.schema.json +21 -0
- package/scripts/__pycache__/pakem.cpython-312.pyc +0 -0
- package/scripts/pakem.py +4911 -0
- package/scripts/pakem_core/__init__.py +3 -0
- package/scripts/pakem_core/__pycache__/__init__.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/coordination.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/git_worktree.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/identity.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/intelligence.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/mcp_server.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/protocol.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/reconcile.cpython-312.pyc +0 -0
- package/scripts/pakem_core/__pycache__/runtime.cpython-312.pyc +0 -0
- package/scripts/pakem_core/coordination.py +977 -0
- package/scripts/pakem_core/git_worktree.py +265 -0
- package/scripts/pakem_core/identity.py +494 -0
- package/scripts/pakem_core/intelligence.py +684 -0
- package/scripts/pakem_core/mcp_server.py +308 -0
- package/scripts/pakem_core/protocol.py +61 -0
- package/scripts/pakem_core/reconcile.py +119 -0
- package/scripts/pakem_core/runtime.py +457 -0
- package/scripts/run_evals.py +289 -0
- package/storage/v1/README.md +14 -0
- package/storage/v1/team-storage.schema.json +27 -0
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Project artifacts: choose, don't collect
|
|
2
|
+
|
|
3
|
+
> **The decision source is `pakem audit` output.** This file explains the reasoning, canonical choices, and catalog; it is not a second audit list. If they differ, `audit` wins.
|
|
4
|
+
|
|
5
|
+
Read it when `pakem audit` shows gaps, when you are about to hand over, or when the user asks "which files should exist". Do not load it for ordinary coding tasks.
|
|
6
|
+
|
|
7
|
+
Principle: **an empty file is worse than a missing file.** Artifacts exist because there is a real risk to prevent, not because they are on a list.
|
|
8
|
+
|
|
9
|
+
## How to choose
|
|
10
|
+
|
|
11
|
+
Three questions, in order:
|
|
12
|
+
|
|
13
|
+
1. Without this, would the next session/agent have to guess? → **REQUIRED**
|
|
14
|
+
2. Without this, can the "finished" claim not be proven again? → **REQUIRED**
|
|
15
|
+
3. If absent, is the risk greater than the cost of creating and maintaining it? → **RECOMMENDED**
|
|
16
|
+
|
|
17
|
+
Everything else is **NOT NEEDED**. For the RECOMMENDED ones, defer with an honest reason (in `pakem step` or `PROJECT.md`), not with an empty file.
|
|
18
|
+
|
|
19
|
+
## Map by failure mode
|
|
20
|
+
|
|
21
|
+
### Power outage, terminal closed, model stops mid-run
|
|
22
|
+
|
|
23
|
+
| Need | Artifact/action |
|
|
24
|
+
|---|---|
|
|
25
|
+
| Last position | `pakem step "<selesai>" --next "<berikutnya>"` as often as possible |
|
|
26
|
+
| History | `.pakem/sessions/*.json` (atomic, do not commit) |
|
|
27
|
+
| Context | `.pakem/CONTEXT.md` + `PROJECT.md` |
|
|
28
|
+
| Decisions | `docs/adr/` when the decision is expensive to reverse |
|
|
29
|
+
| Repo check | small git commits; `pakem start` compares HEAD + changed files |
|
|
30
|
+
|
|
31
|
+
Rule: record a `step` every time you stop for more than a few minutes, before a risky operation, and before handing off a task. A session without steps = a resume without granularity.
|
|
32
|
+
|
|
33
|
+
### New person joins / handover
|
|
34
|
+
|
|
35
|
+
| Need | Artifact |
|
|
36
|
+
|---|---|
|
|
37
|
+
| Start | `README.md` (setup, run, test) + `.env.example` |
|
|
38
|
+
| Code map | `.pakem/MODULE-MAP.md`, `ARCHITECTURE.md` if the system is large |
|
|
39
|
+
| Rationale | `docs/adr/` |
|
|
40
|
+
| Status & remaining work | **one** `HANDOVER.md` (status, access, contacts, what is unfinished, risks) |
|
|
41
|
+
| Access | a section in `HANDOVER.md`; `docs/ACCESS.md` only if the access is complex |
|
|
42
|
+
| Honest condition | `KNOWN_ISSUES` and `TECH_DEBT` sections in `HANDOVER.md`, not two separate files |
|
|
43
|
+
| Terminology | `GLOSSARY.md` only if the domain really is unfamiliar |
|
|
44
|
+
|
|
45
|
+
### Incident / system down
|
|
46
|
+
|
|
47
|
+
`RUNBOOK.md` (symptom → check → action → escalation), `docs/MONITORING.md` (dashboards, alerts, who gets paged), `INCIDENTS.md` or `docs/postmortems/` after the first incident. Do not create them before there is a production system.
|
|
48
|
+
|
|
49
|
+
### Release / deploy
|
|
50
|
+
|
|
51
|
+
The same `verify` as CI, lockfile, `.env.example`, `.gitattributes`, `CHANGELOG.md`, `DEPLOYMENT.md` (including rollback), `RUNBOOK.md`. Pick one CI system. `.github/workflows/` is only needed once there is a deploy target or a team; `pakem ci` generates a workflow that runs `pakem check` (verify stays the single source).
|
|
52
|
+
|
|
53
|
+
### Public / community repo
|
|
54
|
+
|
|
55
|
+
`LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, PR/issue templates. `SUPPORT.md`, `GOVERNANCE.md`, `MAINTAINERS.md`, `FUNDING.yml` only once the community actually exists.
|
|
56
|
+
|
|
57
|
+
### Sensitive data / compliance
|
|
58
|
+
|
|
59
|
+
`SECURITY.md`, `docs/THREAT_MODEL.md` or `docs/SECURITY_CHECKLIST.md`, secret/dependency scans, `PRIVACY.md`/`docs/COMPLIANCE.md` if there is personal data. Set `sensitive: true` in `PROJECT.md` so the security checklist in `conventions.md` is active.
|
|
60
|
+
|
|
61
|
+
### Library / API
|
|
62
|
+
|
|
63
|
+
`examples/`, `openapi.yaml` or `docs/api/`, `CITATION.cff` only for research/academic projects.
|
|
64
|
+
|
|
65
|
+
## Canonical choices (never both)
|
|
66
|
+
|
|
67
|
+
| Concern | Use | Don't also create |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| ADR | `docs/adr/` | `docs/decisions/` |
|
|
70
|
+
| New ESLint | `eslint.config.js` (flat) | `.eslintrc` |
|
|
71
|
+
| Dependency updates | `.github/dependabot.yml` | `renovate.json` (pick one) |
|
|
72
|
+
| Env | `.env.example` | `.env.*.example` without a real difference |
|
|
73
|
+
| Lockfile | one, matching the package manager | a second lockfile / ignoring it for an app |
|
|
74
|
+
| CI | one system | GitHub Actions + GitLab CI at the same time |
|
|
75
|
+
| Handover | one `HANDOVER.md` with sections | separate `ACCESS` + `KNOWN_ISSUES` + `TECH_DEBT` + `HANDOVER` |
|
|
76
|
+
| Runtime version | `.nvmrc` or `.node-version` | both |
|
|
77
|
+
| Container | `Dockerfile` + `docker-compose.yml` | dev/prod variants before you need them |
|
|
78
|
+
| API docs | `openapi.yaml` for HTTP | a `docs/api/` that copies the same content |
|
|
79
|
+
|
|
80
|
+
## Never create automatically
|
|
81
|
+
|
|
82
|
+
`FUNDING.yml`, `GOVERNANCE.md`, `MAINTAINERS.md`, `CITATION.cff`, `CODEOWNERS`, `labeler.yml`, `release.yml`, `sonar-project.properties`, `codeclimate.yml`, `devbox.json`/`flake.nix`, `k8s/`, `helm/`, `terraform/`, `ansible/`, `docs/postmortems/`, `docs/PRD.md`, `docs/SRS.md`, `docs/SLA.md`, `docs/STAKEHOLDERS.md`, `THIRD_PARTY_LICENSES.md`, `CLA.md`, `PRIVACY.md`, `docs/COMPLIANCE.md`, `docs/BACKUP_RESTORE.md`.
|
|
83
|
+
|
|
84
|
+
Create them only when the trigger appears: the first deploy, the first public release, the first incident, the first external contributor, the first handover, or the first personal data.
|
|
85
|
+
|
|
86
|
+
## Related Pakem commands
|
|
87
|
+
|
|
88
|
+
- `pakem audit` — sorts REQUIRED/RECOMMENDED/NOT NEEDED by `type`, `exposure`, `deploy`, `handover`, `sensitive`, and repo contents. Read-only; creates no files.
|
|
89
|
+
- `pakem doctor` — checks the setup (config, placeholder, git, hooks, adapters, sessions) before blaming the code.
|
|
90
|
+
- `pakem ci` — generates a CI workflow that runs `pakem check`, so `verify` is not duplicated.
|
|
91
|
+
- `pakem audit --json` — for agents that want to process the results.
|
|
92
|
+
- `pakem spec` / `pakem spec --approve` — spec container + approval; `finish` rejects drafts.
|
|
93
|
+
- `pakem plan add/done/drop` — small tasks with files+verify; `finish` rejects open tasks.
|
|
94
|
+
- `pakem adr "judul"` — one decision, one ADR.
|
|
95
|
+
- `pakem bug ...` — one bug, one entry; do not rewrite it in `KNOWN_ISSUES` without a reason.
|
|
96
|
+
- `pakem finish` — continuity/verification gate; prints `[WARN] risk:` for gaps matching the flags, without failing the session. It does not judge documentation completeness.
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Pakem conventions
|
|
2
|
+
|
|
3
|
+
Read only when needed. General principle: **proportional**. Structure follows the size and type of the project, not the other way around.
|
|
4
|
+
|
|
5
|
+
## Project artifacts
|
|
6
|
+
|
|
7
|
+
Do not create empty documents to make the repo look complete. Run `pakem audit` to sort REQUIRED / RECOMMENDED / NOT NEEDED; do the REQUIRED ones, defer the RECOMMENDED ones with a reason. Canonical choices and the list of files that must not be created automatically are in `references/artifacts.md`.
|
|
8
|
+
|
|
9
|
+
## Modularization (`app` and `library` projects)
|
|
10
|
+
|
|
11
|
+
- One module, one responsibility. If the name needs the word "and", split it.
|
|
12
|
+
- Thin entry points: they only wire modules together, with no business logic.
|
|
13
|
+
- One-way dependencies (e.g. handlers to services to repositories). No circular imports.
|
|
14
|
+
- Reasonable bounds: files above ~300 lines or functions above ~50 lines are a signal to split, not an absolute law.
|
|
15
|
+
- The structure of `tests/` mirrors the structure of the source.
|
|
16
|
+
- Small projects: do not force 10 folders. Three clear files are better than an empty layered structure.
|
|
17
|
+
- Every new module is recorded in `MODULE-MAP.md` with its path in backticks.
|
|
18
|
+
|
|
19
|
+
## When tests are mandatory
|
|
20
|
+
|
|
21
|
+
- Mandatory: there is logic, state, parsing, or integration (app, service, library).
|
|
22
|
+
- May be skipped with a reason: one-off scripts, simple conversions, research projects. For `oneoff`, `verify` must still prove something (run the script on a sample input, then check that the output exists and is not empty).
|
|
23
|
+
- Bug test: every bug that gets fixed should have a test that fails before the fix.
|
|
24
|
+
- New tests go into the existing test folder. Do not create both `test/` and `tests/`; pick one and stay consistent.
|
|
25
|
+
|
|
26
|
+
## When to write an ADR
|
|
27
|
+
|
|
28
|
+
Write an ADR when a decision (a) has real alternatives, (b) is expensive to reverse, or (c) will be questioned by others later. Examples: choosing a database, framework, auth pattern, state strategy. One decision, one file via `pakem adr "judul"`. Do not write an ADR for trivial choices (variable names, import order).
|
|
29
|
+
|
|
30
|
+
Accepted decisions are not re-debated without new information. If there is new information, write a new ADR that supersedes it and change its status.
|
|
31
|
+
|
|
32
|
+
## When to write research
|
|
33
|
+
|
|
34
|
+
`docs/research/` is used when exploration results will be used again, so they are not repeated. One topic per file: question, sources, findings, conclusion.
|
|
35
|
+
|
|
36
|
+
## BUG-HISTORY format
|
|
37
|
+
|
|
38
|
+
Add via `pakem bug "title" --symptom ... --cause ... --fix ... --prevent ...`. New entries go on top automatically, each entry:
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
## BUG-NNN - short title (date)
|
|
42
|
+
- Symptom:
|
|
43
|
+
- Root cause:
|
|
44
|
+
- Fix:
|
|
45
|
+
- Prevention / test:
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Check this file before fixing a bug: if the symptom looks similar, read the old root cause first.
|
|
49
|
+
|
|
50
|
+
## Project hygiene
|
|
51
|
+
|
|
52
|
+
- README: how to set up, run, and test; sized proportionally.
|
|
53
|
+
- One command each for setup, run, and test (Makefile or `scripts/`), recorded in PROJECT.md. That test command is exactly the content of `verify`.
|
|
54
|
+
- Config: `.env.example` exists, `.env` is in `.gitignore`, no secrets in code.
|
|
55
|
+
- Dependencies: versions pinned (lockfile). Adding a large dependency is recorded with its reason in an ADR.
|
|
56
|
+
- Linter and formatter from the start so style stays consistent across sessions and across agents.
|
|
57
|
+
- Git: `.gitignore` matching the stack, small commits with clear messages.
|
|
58
|
+
- Errors and logging: one convention, recorded in PROJECT.md under the Conventions section.
|
|
59
|
+
|
|
60
|
+
## Security checklist (active when `sensitive: true` in PROJECT.md)
|
|
61
|
+
|
|
62
|
+
This is the only security checklist. `references/reviews.md` only points here; do not copy it.
|
|
63
|
+
|
|
64
|
+
For projects with auth, payments, or personal data:
|
|
65
|
+
|
|
66
|
+
- [ ] Input from outside is validated at the system boundary
|
|
67
|
+
- [ ] Queries use parameters, not string concat
|
|
68
|
+
- [ ] Passwords are hashed with a suitable algorithm; never logged
|
|
69
|
+
- [ ] Secrets come only from the environment or a secret manager
|
|
70
|
+
- [ ] Authorization is checked server-side on every action, not just in the UI
|
|
71
|
+
- [ ] Personal data does not appear in logs, errors, or analytics
|
|
72
|
+
- [ ] Dependencies are checked for vulnerabilities before release
|
|
73
|
+
- [ ] There are tests for failure paths (access denied, malicious input)
|
|
74
|
+
|
|
75
|
+
Put the relevant ticks into the Definition of done section in PROJECT.md.
|
|
76
|
+
|
|
77
|
+
## Ambiguous requirements
|
|
78
|
+
|
|
79
|
+
Order: (1) ask the user if the answer significantly changes direction, (2) if not, take the most reasonable assumption and record it via `pakem step "Asumsi: ..."`. Never choose silently.
|
|
80
|
+
|
|
81
|
+
## Resume after a disconnection
|
|
82
|
+
|
|
83
|
+
`pakem start` shows the active session along with `lastPosition` and `nextStep`. Briefly verify that the repo state matches the notes (e.g. `git status`), then continue from `nextStep`. If the notes no longer match, record the correction via `step` before continuing.
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
# Review lens: frontend & backend
|
|
2
|
+
|
|
3
|
+
Read before `finish` or before opening a PR, **only if** the project has a UI or `sensitive: true` in `PROJECT.md`. These are thinking lenses, not gates and not a replacement for human review.
|
|
4
|
+
|
|
5
|
+
Base rule: do not claim "already reviewed" without evidence that can be run. Write in `finish --summary` what was checked and which commands were run.
|
|
6
|
+
|
|
7
|
+
## Frontend: consistency
|
|
8
|
+
|
|
9
|
+
What is checked, as relevant:
|
|
10
|
+
|
|
11
|
+
- **Visual source of truth** — color/spacing/typography tokens and existing components. Do not create new patterns when existing components can be used.
|
|
12
|
+
- **Complete states** — loading, empty, error, disabled, and retry. Many UI bugs are born from states that were never designed.
|
|
13
|
+
- **Responsive** — layout at small, medium, and large widths; not just desktop.
|
|
14
|
+
- **Accessibility** — form labels, keyboard focus, tab order, contrast, `alt`, ARIA only when needed.
|
|
15
|
+
- **Visible performance** — images, bundle, and layout shift; measure, do not guess.
|
|
16
|
+
- **Text consistency** — terminology, capitalization, date/number format follow `STYLEGUIDE.md` or the conventions in `PROJECT.md`.
|
|
17
|
+
|
|
18
|
+
How to prove it:
|
|
19
|
+
|
|
20
|
+
- `verify` must include lint + typecheck; add e2e/visual tests if they already exist.
|
|
21
|
+
- For visual changes, run the app and look at the surface; screenshot/URL in the summary.
|
|
22
|
+
- Do not add a large UI/animation library without an ADR.
|
|
23
|
+
|
|
24
|
+
What is **not** Pakem's job: judging design taste. Pakem only ensures that consistency can be checked and is not forgotten.
|
|
25
|
+
|
|
26
|
+
## Backend: security
|
|
27
|
+
|
|
28
|
+
Do not duplicate the checklist. The single source is `conventions.md` section **Security checklist** (active when `sensitive: true`) — server-side authorization, boundary validation, parameterized queries, secrets, PII, password hashing, fail closed, resource limits, secret/dependency scans, and failure-path tests.
|
|
29
|
+
|
|
30
|
+
During review, focus on evidence, not on repeating the list:
|
|
31
|
+
|
|
32
|
+
- Name the commands that were run (tests, scans, curl) in the summary.
|
|
33
|
+
- For endpoints, test at minimum: success, invalid input, no auth, wrong auth.
|
|
34
|
+
- Do not write an empty `SECURITY.md`; better to have none than a false claim.
|
|
35
|
+
|
|
36
|
+
## When to stop
|
|
37
|
+
|
|
38
|
+
Fix only findings relevant to the current change. Do not expand the scope into a full security audit without user approval. Findings outside scope are recorded as `KNOWN_ISSUES`/`TECH_DEBT` (optionally as a section of `HANDOVER.md`), not fixed silently.
|
|
39
|
+
|
|
40
|
+
## Relation to Pakem
|
|
41
|
+
|
|
42
|
+
- `sensitive: true` → the security checklist in `conventions.md` is active, and `finish` warns about a missing `SECURITY.md`/threat model/scan.
|
|
43
|
+
- `audit` shows artifact gaps; `reviews.md` shows what is checked when those artifacts are used.
|
|
44
|
+
- `finish` remains evidence-based: `verify` commands and the summary, not claims.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
# Pakem Autonomous Runtime v1
|
|
2
|
+
|
|
3
|
+
A deterministic workflow state machine, checkpoint/recovery format, policy decision contract, and lifecycle-hook surface for host coding agents.
|
|
4
|
+
|
|
5
|
+
## Workflow states
|
|
6
|
+
|
|
7
|
+
`planning -> ready -> executing -> verifying -> completed`, with `blocked`, `failed`, and `recovering` branches. Only documented transitions are accepted. State changes are atomic and revisioned. Active workflows cannot be replaced by `runtime init --new`; a workflow must first enter `completed` or `failed`.
|
|
8
|
+
|
|
9
|
+
## Checkpoints and recovery
|
|
10
|
+
|
|
11
|
+
Checkpoints capture the workflow state plus a Git HEAD/working-tree snapshot. Recovery restores workflow metadata into `recovering` and reports repository drift. It NEVER resets files, checks out commits, reverts changes, reruns commands, or restores source code. A human/host agent must inspect code and repo status before resuming.
|
|
12
|
+
|
|
13
|
+
## Lifecycle hooks
|
|
14
|
+
|
|
15
|
+
Standard hooks: `session.start`, `task.before`, `task.after`, `verification.before`, `session.finish`, `handover`. `hook-payload.schema.json` describes input payload metadata and `hook-decision.schema.json` describes the machine-readable output. Hook dispatch evaluates policy and emits a compact receipt. It does not execute the requested action. Receipts hash payload/target content to avoid copying arbitrary prompts, commands, or secrets into the ledger.
|
|
16
|
+
|
|
17
|
+
## Host integration contract
|
|
18
|
+
|
|
19
|
+
The host runtime calls `pakem runtime hook <event> --payload-file ... --json` before an action, inspects `decision`, and proceeds only for `allow`. `require_approval` must pause for user confirmation via a trusted host channel, then obtain a one-use approval with `pakem policy approve ...`. `deny` must stop the action. The host must never self-approve on behalf of the agent.
|
|
20
|
+
|
|
21
|
+
The CLI is an initial reference adapter. Protocols and schemas are language-neutral; other implementations may be written in TypeScript, Rust, or another language.
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:approval",
|
|
4
|
+
"title": "Pakem Policy Approval Store v1",
|
|
5
|
+
"description": "One-use approval records granted by an operator through a trusted host channel. Hosts must verify scope, expiry, and single use before acting.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": [
|
|
8
|
+
"schemaVersion",
|
|
9
|
+
"approvals"
|
|
10
|
+
],
|
|
11
|
+
"properties": {
|
|
12
|
+
"schemaVersion": {
|
|
13
|
+
"const": 1
|
|
14
|
+
},
|
|
15
|
+
"approvals": {
|
|
16
|
+
"type": "array",
|
|
17
|
+
"maxItems": 500,
|
|
18
|
+
"items": {
|
|
19
|
+
"type": "object",
|
|
20
|
+
"required": [
|
|
21
|
+
"approvalId",
|
|
22
|
+
"category",
|
|
23
|
+
"risk",
|
|
24
|
+
"scopeHash",
|
|
25
|
+
"reason",
|
|
26
|
+
"grantedAt",
|
|
27
|
+
"expiresAt",
|
|
28
|
+
"consumedAt"
|
|
29
|
+
],
|
|
30
|
+
"properties": {
|
|
31
|
+
"approvalId": {
|
|
32
|
+
"type": "string",
|
|
33
|
+
"pattern": "^[a-f0-9]{32}$"
|
|
34
|
+
},
|
|
35
|
+
"category": {
|
|
36
|
+
"type": "string",
|
|
37
|
+
"enum": [
|
|
38
|
+
"read",
|
|
39
|
+
"write",
|
|
40
|
+
"command",
|
|
41
|
+
"destructive",
|
|
42
|
+
"deploy",
|
|
43
|
+
"security",
|
|
44
|
+
"policy_change",
|
|
45
|
+
"gate_change"
|
|
46
|
+
]
|
|
47
|
+
},
|
|
48
|
+
"risk": {
|
|
49
|
+
"type": "string",
|
|
50
|
+
"enum": [
|
|
51
|
+
"low",
|
|
52
|
+
"medium",
|
|
53
|
+
"high",
|
|
54
|
+
"critical"
|
|
55
|
+
]
|
|
56
|
+
},
|
|
57
|
+
"targetHash": {
|
|
58
|
+
"type": [
|
|
59
|
+
"string",
|
|
60
|
+
"null"
|
|
61
|
+
],
|
|
62
|
+
"pattern": "^[a-f0-9]{64}$"
|
|
63
|
+
},
|
|
64
|
+
"scopeHash": {
|
|
65
|
+
"type": "string",
|
|
66
|
+
"pattern": "^[a-f0-9]{64}$"
|
|
67
|
+
},
|
|
68
|
+
"workflowId": {
|
|
69
|
+
"type": [
|
|
70
|
+
"string",
|
|
71
|
+
"null"
|
|
72
|
+
],
|
|
73
|
+
"minLength": 1
|
|
74
|
+
},
|
|
75
|
+
"reason": {
|
|
76
|
+
"type": "string",
|
|
77
|
+
"minLength": 1,
|
|
78
|
+
"maxLength": 500
|
|
79
|
+
},
|
|
80
|
+
"grantedAt": {
|
|
81
|
+
"type": "string",
|
|
82
|
+
"format": "date-time"
|
|
83
|
+
},
|
|
84
|
+
"expiresAt": {
|
|
85
|
+
"type": "string",
|
|
86
|
+
"format": "date-time"
|
|
87
|
+
},
|
|
88
|
+
"consumedAt": {
|
|
89
|
+
"type": [
|
|
90
|
+
"string",
|
|
91
|
+
"null"
|
|
92
|
+
]
|
|
93
|
+
}
|
|
94
|
+
},
|
|
95
|
+
"additionalProperties": false
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
"additionalProperties": false
|
|
100
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:checkpoint",
|
|
4
|
+
"title": "Pakem Runtime Checkpoint v1",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": ["schemaVersion", "checkpointId", "workflowId", "label", "createdAt", "workflow", "repository"],
|
|
7
|
+
"properties": {
|
|
8
|
+
"schemaVersion": {"const": 1},
|
|
9
|
+
"checkpointId": {"type": "string", "minLength": 1},
|
|
10
|
+
"workflowId": {"type": "string", "minLength": 1},
|
|
11
|
+
"label": {"type": "string"},
|
|
12
|
+
"createdAt": {"type": "string", "format": "date-time"},
|
|
13
|
+
"workflow": {"$ref": "urn:pakem:runtime:v1:workflow"},
|
|
14
|
+
"repository": {"type": "object", "required": ["head", "status"], "properties": {"head": {"type": ["string", "null"]}, "status": {"type": ["array", "null"], "items": {"type": "string"}}, "additionalProperties": true}}
|
|
15
|
+
},
|
|
16
|
+
"additionalProperties": false
|
|
17
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:hook-decision",
|
|
4
|
+
"title": "Pakem Lifecycle Hook Decision v1",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": ["protocol", "runtime_version", "hook", "decision", "allowed", "requiresApproval", "reason", "category", "risk", "receipt"],
|
|
7
|
+
"properties": {
|
|
8
|
+
"protocol": {"const": "pakem"},
|
|
9
|
+
"runtime_version": {"const": 1},
|
|
10
|
+
"hook": {"enum": ["session.start", "task.before", "task.after", "verification.before", "session.finish", "handover"]},
|
|
11
|
+
"decision": {"enum": ["allow", "require_approval", "deny"]},
|
|
12
|
+
"allowed": {"type": "boolean"},
|
|
13
|
+
"requiresApproval": {"type": "boolean"},
|
|
14
|
+
"reason": {"type": "string"},
|
|
15
|
+
"category": {"enum": ["read", "write", "command", "destructive", "deploy", "security", "policy_change", "gate_change"]},
|
|
16
|
+
"risk": {"enum": ["low", "medium", "high", "critical"]},
|
|
17
|
+
"approvalId": {"type": "string"},
|
|
18
|
+
"receipt": {
|
|
19
|
+
"type": "object",
|
|
20
|
+
"required": ["hook", "occurredAt", "decision", "category", "risk", "reason"],
|
|
21
|
+
"properties": {
|
|
22
|
+
"hook": {"type": "string"},
|
|
23
|
+
"occurredAt": {"type": "string", "format": "date-time"},
|
|
24
|
+
"decision": {"enum": ["allow", "require_approval", "deny"]},
|
|
25
|
+
"category": {"type": "string"},
|
|
26
|
+
"risk": {"type": "string"},
|
|
27
|
+
"targetHash": {"type": ["string", "null"]},
|
|
28
|
+
"reason": {"type": "string"}
|
|
29
|
+
},
|
|
30
|
+
"additionalProperties": false
|
|
31
|
+
}
|
|
32
|
+
},
|
|
33
|
+
"additionalProperties": false
|
|
34
|
+
}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:hook-payload",
|
|
4
|
+
"title": "Pakem Lifecycle Hook Payload v1",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"properties": {
|
|
7
|
+
"category": {"enum": ["read", "write", "command", "destructive", "deploy", "security", "policy_change", "gate_change"]},
|
|
8
|
+
"risk": {"enum": ["low", "medium", "high", "critical"]},
|
|
9
|
+
"target": {"type": "string", "maxLength": 240}
|
|
10
|
+
},
|
|
11
|
+
"additionalProperties": true
|
|
12
|
+
}
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:task-evidence",
|
|
4
|
+
"title": "Pakem Task Evidence v1",
|
|
5
|
+
"description": "Verify evidence per task plan. One entry per task; `status: waived` means the task was finished without running verify and the reason is recorded.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["schema_version", "tasks"],
|
|
8
|
+
"properties": {
|
|
9
|
+
"schema_version": {"const": "pakem.task-evidence/v1"},
|
|
10
|
+
"tasks": {
|
|
11
|
+
"type": "object",
|
|
12
|
+
"maxProperties": 500,
|
|
13
|
+
"additionalProperties": {"$ref": "#/$defs/entry"}
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"$defs": {
|
|
17
|
+
"entry": {
|
|
18
|
+
"type": "object",
|
|
19
|
+
"required": ["command", "status", "exit", "at", "files"],
|
|
20
|
+
"properties": {
|
|
21
|
+
"command": {"type": "string"},
|
|
22
|
+
"status": {"enum": ["pass", "fail", "waived"]},
|
|
23
|
+
"exit": {"type": ["integer", "null"]},
|
|
24
|
+
"at": {"type": "string"},
|
|
25
|
+
"reason": {"type": "string"},
|
|
26
|
+
"durationMs": {"type": "integer", "minimum": 0},
|
|
27
|
+
"outputHash": {"type": "string"},
|
|
28
|
+
"files": {
|
|
29
|
+
"type": "object",
|
|
30
|
+
"description": "Content fingerprint of scope files at the time verify ran; used to detect stale evidence.",
|
|
31
|
+
"additionalProperties": {"type": "string"}
|
|
32
|
+
}
|
|
33
|
+
},
|
|
34
|
+
"additionalProperties": false
|
|
35
|
+
}
|
|
36
|
+
},
|
|
37
|
+
"additionalProperties": false
|
|
38
|
+
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:work-report",
|
|
4
|
+
"title": "Pakem Work Report v1",
|
|
5
|
+
"description": "Per-project work roll-up: sessions, tasks from PLAN.md, verify evidence per task, and event ledger status. The numbers come from artifacts that can be re-inspected, not from agent narration.",
|
|
6
|
+
"type": "object",
|
|
7
|
+
"required": ["schema_version", "generated_at", "scope", "sessions", "tasks", "ledger", "totals"],
|
|
8
|
+
"additionalProperties": false,
|
|
9
|
+
"properties": {
|
|
10
|
+
"schema_version": {"const": "pakem.work-report/v1"},
|
|
11
|
+
"generated_at": {"type": "string", "format": "date-time"},
|
|
12
|
+
"scope": {
|
|
13
|
+
"type": "object",
|
|
14
|
+
"required": ["session", "limit"],
|
|
15
|
+
"additionalProperties": false,
|
|
16
|
+
"properties": {
|
|
17
|
+
"session": {"type": ["string", "null"], "description": "Session filter applied; null when all sessions are included"},
|
|
18
|
+
"limit": {"type": ["integer", "null"], "minimum": 1}
|
|
19
|
+
}
|
|
20
|
+
},
|
|
21
|
+
"sessions": {
|
|
22
|
+
"type": "array",
|
|
23
|
+
"description": "Newest sessions first.",
|
|
24
|
+
"items": {
|
|
25
|
+
"type": "object",
|
|
26
|
+
"required": ["id", "goal", "agent", "status", "started_at", "finished_at",
|
|
27
|
+
"duration_ms", "steps", "events", "gate_failures", "warnings", "fabricated_verify"],
|
|
28
|
+
"additionalProperties": false,
|
|
29
|
+
"properties": {
|
|
30
|
+
"id": {"type": "string", "minLength": 1},
|
|
31
|
+
"goal": {"type": "string"},
|
|
32
|
+
"agent": {"type": "string"},
|
|
33
|
+
"status": {"type": "string"},
|
|
34
|
+
"started_at": {"type": ["string", "null"]},
|
|
35
|
+
"finished_at": {"type": ["string", "null"]},
|
|
36
|
+
"duration_ms": {
|
|
37
|
+
"type": ["integer", "null"],
|
|
38
|
+
"minimum": 0,
|
|
39
|
+
"description": "Wall-clock time of the session. Sessions not yet closed are counted up to generated_at."
|
|
40
|
+
},
|
|
41
|
+
"steps": {"type": "integer", "minimum": 0},
|
|
42
|
+
"events": {"type": "integer", "minimum": 0},
|
|
43
|
+
"gate_failures": {"type": "integer", "minimum": 0},
|
|
44
|
+
"warnings": {"type": "integer", "minimum": 0},
|
|
45
|
+
"fabricated_verify": {"type": "boolean"}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
},
|
|
49
|
+
"tasks": {
|
|
50
|
+
"type": "array",
|
|
51
|
+
"description": "One entry per task in PLAN.md, including tasks that were dropped.",
|
|
52
|
+
"items": {
|
|
53
|
+
"type": "object",
|
|
54
|
+
"required": ["task_id", "state", "text", "scope", "verify_status",
|
|
55
|
+
"verify_duration_ms", "verified_at", "waived_reason", "evidence_files"],
|
|
56
|
+
"additionalProperties": false,
|
|
57
|
+
"properties": {
|
|
58
|
+
"task_id": {"type": "string", "minLength": 1},
|
|
59
|
+
"state": {"enum": ["open", "done", "dropped"]},
|
|
60
|
+
"text": {"type": "string"},
|
|
61
|
+
"scope": {"type": "array", "items": {"type": "string"}},
|
|
62
|
+
"verify_status": {"type": ["string", "null"], "enum": ["pass", "fail", "waived", null]},
|
|
63
|
+
"verify_duration_ms": {"type": ["integer", "null"], "minimum": 0},
|
|
64
|
+
"verified_at": {"type": ["string", "null"]},
|
|
65
|
+
"waived_reason": {"type": ["string", "null"]},
|
|
66
|
+
"evidence_files": {
|
|
67
|
+
"type": "array",
|
|
68
|
+
"items": {"type": "string"},
|
|
69
|
+
"description": "Files whose content fingerprint was recorded at the last verify."
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
},
|
|
74
|
+
"ledger": {
|
|
75
|
+
"type": "object",
|
|
76
|
+
"required": ["files", "events", "seals", "head", "ok", "problems"],
|
|
77
|
+
"additionalProperties": false,
|
|
78
|
+
"properties": {
|
|
79
|
+
"files": {"type": "integer", "minimum": 0},
|
|
80
|
+
"events": {"type": "integer", "minimum": 0},
|
|
81
|
+
"seals": {"type": "integer", "minimum": 0},
|
|
82
|
+
"head": {"type": ["string", "null"]},
|
|
83
|
+
"ok": {"type": "boolean"},
|
|
84
|
+
"problems": {
|
|
85
|
+
"type": "array",
|
|
86
|
+
"items": {
|
|
87
|
+
"type": "object",
|
|
88
|
+
"required": ["file", "line", "reason"],
|
|
89
|
+
"additionalProperties": false,
|
|
90
|
+
"properties": {
|
|
91
|
+
"file": {"type": "string"},
|
|
92
|
+
"line": {"type": "integer", "minimum": 0},
|
|
93
|
+
"reason": {"type": "string"}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
},
|
|
99
|
+
"totals": {
|
|
100
|
+
"type": "object",
|
|
101
|
+
"required": ["sessions", "duration_ms", "events", "tasks", "tasks_done", "tasks_open",
|
|
102
|
+
"tasks_dropped", "verified", "verify_failed", "waived", "unproven_done"],
|
|
103
|
+
"additionalProperties": false,
|
|
104
|
+
"properties": {
|
|
105
|
+
"sessions": {"type": "integer", "minimum": 0},
|
|
106
|
+
"duration_ms": {"type": "integer", "minimum": 0},
|
|
107
|
+
"events": {"type": "integer", "minimum": 0},
|
|
108
|
+
"tasks": {"type": "integer", "minimum": 0},
|
|
109
|
+
"tasks_done": {"type": "integer", "minimum": 0},
|
|
110
|
+
"tasks_open": {"type": "integer", "minimum": 0},
|
|
111
|
+
"tasks_dropped": {"type": "integer", "minimum": 0},
|
|
112
|
+
"verified": {"type": "integer", "minimum": 0},
|
|
113
|
+
"verify_failed": {"type": "integer", "minimum": 0},
|
|
114
|
+
"waived": {"type": "integer", "minimum": 0},
|
|
115
|
+
"unproven_done": {
|
|
116
|
+
"type": "integer",
|
|
117
|
+
"minimum": 0,
|
|
118
|
+
"description": "Tasks marked [x] without valid verify evidence — the task-verify gate rejects them."
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
{
|
|
2
|
+
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
|
3
|
+
"$id": "urn:pakem:runtime:v1:workflow",
|
|
4
|
+
"title": "Pakem Runtime Workflow State v1",
|
|
5
|
+
"type": "object",
|
|
6
|
+
"required": ["schemaVersion", "workflowId", "state", "revision", "createdAt", "updatedAt", "checkpointIds", "lastTransition"],
|
|
7
|
+
"properties": {
|
|
8
|
+
"schemaVersion": {"const": 1},
|
|
9
|
+
"workflowId": {"type": "string", "minLength": 1},
|
|
10
|
+
"state": {"enum": ["initialized", "planning", "ready", "executing", "verifying", "blocked", "recovering", "completed", "failed"]},
|
|
11
|
+
"goal": {"type": "string"},
|
|
12
|
+
"revision": {"type": "integer", "minimum": 1},
|
|
13
|
+
"createdAt": {"type": "string", "format": "date-time"},
|
|
14
|
+
"updatedAt": {"type": "string", "format": "date-time"},
|
|
15
|
+
"activeSessionId": {"type": ["string", "null"]},
|
|
16
|
+
"currentTaskId": {"type": ["string", "null"]},
|
|
17
|
+
"checkpointIds": {"type": "array", "items": {"type": "string"}},
|
|
18
|
+
"lastTransition": {"type": "object", "required": ["from", "to", "reason", "at"], "properties": {"from": {"type": ["string", "null"]}, "to": {"type": "string"}, "reason": {"type": "string"}, "at": {"type": "string", "format": "date-time"}}, "additionalProperties": true}
|
|
19
|
+
},
|
|
20
|
+
"additionalProperties": true
|
|
21
|
+
}
|
|
Binary file
|