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.
Files changed (76) hide show
  1. package/CHANGELOG.md +280 -0
  2. package/LICENSE +21 -0
  3. package/README-ID.md +666 -0
  4. package/README.md +665 -2
  5. package/SKILL.md +264 -0
  6. package/adapters/git-worktree/v1/README.md +17 -0
  7. package/adapters/identity/v1/README.md +26 -0
  8. package/adapters/mcp/v1/README.md +56 -0
  9. package/adapters/storage-sqlite/v1/README.md +5 -0
  10. package/assets/banner.svg +275 -0
  11. package/assets/divider.svg +82 -0
  12. package/assets/footer.svg +174 -0
  13. package/assets/templates/BUG-HISTORY.md +18 -0
  14. package/assets/templates/CONTEXT.md +26 -0
  15. package/assets/templates/DECISIONS.md +8 -0
  16. package/assets/templates/MODULE-MAP.md +14 -0
  17. package/assets/templates/POLICY.json +15 -0
  18. package/assets/templates/PROJECT.md +42 -0
  19. package/conformance/v1/README.md +15 -0
  20. package/coordination/v1/README.md +14 -0
  21. package/coordination/v1/board.schema.json +59 -0
  22. package/coordination/v1/event.schema.json +26 -0
  23. package/coordination/v1/status.schema.json +49 -0
  24. package/evals/README.md +63 -0
  25. package/evals/evals.json +276 -0
  26. package/identity/v1/README.md +14 -0
  27. package/identity/v1/agent-identity.schema.json +95 -0
  28. package/identity/v1/identity-registry.schema.json +29 -0
  29. package/identity/v1/signed-payload.schema.json +42 -0
  30. package/intelligence/v1/README.md +19 -0
  31. package/intelligence/v1/dependency-graph.schema.json +82 -0
  32. package/intelligence/v1/impact-analysis.schema.json +51 -0
  33. package/intelligence/v1/reconciliation.schema.json +156 -0
  34. package/npm/bin/pakem.js +272 -0
  35. package/npm/check-version.js +26 -0
  36. package/package.json +58 -4
  37. package/policy/v1/README.md +15 -0
  38. package/policy/v1/policy.schema.json +20 -0
  39. package/protocol/v1/README.md +68 -0
  40. package/protocol/v1/capabilities.schema.json +17 -0
  41. package/protocol/v1/event.schema.json +114 -0
  42. package/protocol/v1/session.schema.json +51 -0
  43. package/references/artifacts.md +96 -0
  44. package/references/conventions.md +83 -0
  45. package/references/reviews.md +44 -0
  46. package/runtime/v1/README.md +21 -0
  47. package/runtime/v1/approval.schema.json +100 -0
  48. package/runtime/v1/checkpoint.schema.json +17 -0
  49. package/runtime/v1/hook-decision.schema.json +34 -0
  50. package/runtime/v1/hook-payload.schema.json +12 -0
  51. package/runtime/v1/task-evidence.schema.json +38 -0
  52. package/runtime/v1/work-report.schema.json +123 -0
  53. package/runtime/v1/workflow.schema.json +21 -0
  54. package/scripts/__pycache__/pakem.cpython-312.pyc +0 -0
  55. package/scripts/pakem.py +4911 -0
  56. package/scripts/pakem_core/__init__.py +3 -0
  57. package/scripts/pakem_core/__pycache__/__init__.cpython-312.pyc +0 -0
  58. package/scripts/pakem_core/__pycache__/coordination.cpython-312.pyc +0 -0
  59. package/scripts/pakem_core/__pycache__/git_worktree.cpython-312.pyc +0 -0
  60. package/scripts/pakem_core/__pycache__/identity.cpython-312.pyc +0 -0
  61. package/scripts/pakem_core/__pycache__/intelligence.cpython-312.pyc +0 -0
  62. package/scripts/pakem_core/__pycache__/mcp_server.cpython-312.pyc +0 -0
  63. package/scripts/pakem_core/__pycache__/protocol.cpython-312.pyc +0 -0
  64. package/scripts/pakem_core/__pycache__/reconcile.cpython-312.pyc +0 -0
  65. package/scripts/pakem_core/__pycache__/runtime.cpython-312.pyc +0 -0
  66. package/scripts/pakem_core/coordination.py +977 -0
  67. package/scripts/pakem_core/git_worktree.py +265 -0
  68. package/scripts/pakem_core/identity.py +494 -0
  69. package/scripts/pakem_core/intelligence.py +684 -0
  70. package/scripts/pakem_core/mcp_server.py +308 -0
  71. package/scripts/pakem_core/protocol.py +61 -0
  72. package/scripts/pakem_core/reconcile.py +119 -0
  73. package/scripts/pakem_core/runtime.py +457 -0
  74. package/scripts/run_evals.py +289 -0
  75. package/storage/v1/README.md +14 -0
  76. 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
+ }