pakem-cli 0.0.0-stage → 1.2.1

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 +271 -0
  2. package/LICENSE +21 -0
  3. package/README-ID.md +665 -0
  4. package/README.md +664 -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 +150 -0
  35. package/npm/check-version.js +26 -0
  36. package/package.json +55 -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
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "pakem-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.2.1",
4
+ "description": "Agent work discipline with verifiable finish gates: sessions, plans, specs, and gates that can fail.",
5
+ "bin": {
6
+ "pakem": "npm/bin/pakem.js"
7
+ },
8
+ "files": [
9
+ "SKILL.md",
10
+ "README.md",
11
+ "README-ID.md",
12
+ "CHANGELOG.md",
13
+ "LICENSE",
14
+ "assets/",
15
+ "scripts/",
16
+ "references/",
17
+ "adapters/",
18
+ "protocol/",
19
+ "intelligence/",
20
+ "runtime/",
21
+ "policy/",
22
+ "coordination/",
23
+ "identity/",
24
+ "storage/",
25
+ "conformance/",
26
+ "evals/",
27
+ "npm/"
28
+ ],
29
+ "scripts": {
30
+ "prepack": "node npm/check-version.js"
31
+ },
32
+ "engines": {
33
+ "node": ">=18"
34
+ },
35
+ "keywords": [
36
+ "agent",
37
+ "coding-agent",
38
+ "skill",
39
+ "claude",
40
+ "codex",
41
+ "cursor",
42
+ "workflow",
43
+ "verification"
44
+ ],
45
+ "license": "MIT",
46
+ "publishConfig": {
47
+ "access": "public"
48
+ },
49
+ "repository": {
50
+ "type": "git",
51
+ "url": "git+https://github.com/Matsumiko/pakem.git"
52
+ },
53
+ "homepage": "https://github.com/Matsumiko/pakem",
54
+ "bugs": {
55
+ "url": "https://github.com/Matsumiko/pakem/issues"
56
+ }
57
+ }
@@ -0,0 +1,15 @@
1
+ # Pakem Policy v1
2
+
3
+ `POLICY.json` controls what a compatible host runtime may allow automatically.
4
+
5
+ - `autonomy`: `manual`, `assisted`, or `guarded_autonomous`.
6
+ - `maxAutonomousRisk`: highest risk level that may proceed without an approval when no category-specific rule requires one.
7
+ - `approvalRequiredFor`: categories that always require explicit approval.
8
+ - `deniedCategories`: categories the runtime must deny.
9
+ - `approvalTtlSeconds`: lifetime for a one-use, workflow-bound approval (30–86400 seconds).
10
+
11
+ Categories: `read`, `write`, `command`, `destructive`, `deploy`, `security`, `policy_change`, `gate_change`.
12
+
13
+ Approval is an auditable local record, not cryptographic identity or a secure human-authentication mechanism. A host agent/runtime MUST mediate `policy approve` through a genuine user-confirmation channel and MUST NOT let the agent self-approve. The CLI cannot prove who invoked it. Approval is one-use, bound to workflow ID, category, risk, and target, and expires.
14
+
15
+ The policy engine does not execute commands, edit source code, deploy, or start agents. It returns `allow`, `require_approval`, or `deny`; the host runtime remains responsible for enforcing the decision.
@@ -0,0 +1,20 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:policy:v1",
4
+ "title": "Pakem Policy v1",
5
+ "type": "object",
6
+ "required": ["schemaVersion", "autonomy", "maxAutonomousRisk", "approvalRequiredFor", "deniedCategories", "approvalTtlSeconds"],
7
+ "properties": {
8
+ "schemaVersion": {"const": 1},
9
+ "autonomy": {"enum": ["manual", "assisted", "guarded_autonomous"]},
10
+ "maxAutonomousRisk": {"enum": ["low", "medium", "high", "critical"]},
11
+ "approvalRequiredFor": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/category"}},
12
+ "deniedCategories": {"type": "array", "uniqueItems": true, "items": {"$ref": "#/$defs/category"}},
13
+ "approvalTtlSeconds": {"type": "integer", "minimum": 30, "maximum": 86400},
14
+ "description": {"type": "string"}
15
+ },
16
+ "$defs": {
17
+ "category": {"enum": ["read", "write", "command", "destructive", "deploy", "security", "policy_change", "gate_change"]}
18
+ },
19
+ "additionalProperties": false
20
+ }
@@ -0,0 +1,68 @@
1
+ # Pakem Protocol v1.0 — Stable Contract
2
+
3
+ Pakem Protocol is the tool-, model-, language-, and transport-independent
4
+ contract for project workflow state and events. Version **1.0 is frozen** for
5
+ its event envelope and session compatibility rules. Future optional features
6
+ are discovered through capability negotiation; they do not silently alter the
7
+ v1 event envelope.
8
+
9
+ ## Compatibility
10
+
11
+ - `protocol` is always `pakem`; `protocol_version` is `1.0`.
12
+ - Event records are append-only JSON objects, one per line (JSONL).
13
+ - Unknown session fields may be preserved. Existing sessions without
14
+ `schemaVersion` remain valid.
15
+ - The event envelope is strict. Event-specific extensions belong inside
16
+ `payload` until a later protocol version defines otherwise.
17
+ - One exception is reserved and additive: `integrity: {prev, hash}` (capability
18
+ `events.integrity.v1`). It is optional on every event; readers that ignore it
19
+ still parse the ledger, and events written before 1.2.0 remain valid. Strict
20
+ validators must use the current `event.schema.json`. Chain verification and
21
+ sealing are local CLI features, not a new protocol version: `prev` links to the
22
+ previous event's `hash`, and a `ledger.sealed` event carries an Ed25519 envelope
23
+ over the chain head at that point.
24
+ - Timestamps are ISO 8601 with an explicit UTC offset.
25
+ - `session_id` may be null for project-level events.
26
+ - Capability support is not authorization to perform side effects.
27
+
28
+ ## Capability negotiation
29
+
30
+ `pakem protocol negotiate --peer-version 1.0 --capability events.v1` returns
31
+ whether the peer is compatible and the intersection of supported capabilities.
32
+ Supported capabilities include `events.v1`, `sessions.v1`,
33
+ `context.snapshot.v1`, `runtime.v1`, `intelligence.graph.v1`,
34
+ `intelligence.impact.v1`, `coordination.v1`, `coordination.review.v1`,
35
+ `git.worktree.v1`, `mcp.stdio.2026-07-28`, `identity.ed25519.v1`,
36
+ `identity.delegation.v1`, `coordination.sqlite.v1`, `events.integrity.v1`, and
37
+ `conformance.v1`. See
38
+ `capabilities.schema.json`. Unknown optional capabilities do not invalidate
39
+ an otherwise compatible protocol version; they are reported separately.
40
+
41
+ ## Event envelope
42
+
43
+ See `event.schema.json`. Every event contains `protocol`, `protocol_version`,
44
+ `event_id`, `event`, `occurred_at`, `session_id`, `actor`, and `payload`.
45
+
46
+ ## Session data
47
+
48
+ See `session.schema.json`. Unknown fields are preserved for forward-compatible
49
+ session metadata. Session state is not proof of task correctness.
50
+
51
+ ## Trust and identity
52
+
53
+ `actor.type` and `actor.name` are attribution fields, not credentials. Agent
54
+ IDs in a local coordination board are cooperative metadata, not authenticated
55
+ identities. Pakem 1.1 can register Ed25519 public identities and verify signed
56
+ attestations/delegation tokens. A host runtime must still bind a verified token
57
+ to the actual caller, enforce audience/actions/expiry/revocation, and provide
58
+ anti-replay protection. Private keys stay outside the project; public registry
59
+ integrity must be rooted in a trusted checkout/commit. MCP `clientInfo` is
60
+ self-reported and must not be used for authorization.
61
+
62
+ ## Runtime boundary
63
+
64
+ Pakem stores workflow state and provides policy decisions. Agent execution,
65
+ model selection, deployment, and external side effects belong to the host
66
+ agent/runtime and its permission system. `session.finished`, a submitted event,
67
+ or an approval receipt does not by itself prove correctness or authorize a
68
+ side effect. Verification evidence must be attached to relevant results.
@@ -0,0 +1,17 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:protocol:v1:capabilities",
4
+ "title": "Pakem Protocol v1 Capabilities",
5
+ "type": "object",
6
+ "required": ["protocol", "version", "capabilities"],
7
+ "properties": {
8
+ "protocol": {"const": "pakem"},
9
+ "version": {"const": "1.0"},
10
+ "capabilities": {
11
+ "type": "array",
12
+ "items": {"type": "string", "minLength": 1},
13
+ "uniqueItems": true
14
+ }
15
+ },
16
+ "additionalProperties": false
17
+ }
@@ -0,0 +1,114 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:protocol:v1:event",
4
+ "title": "Pakem Protocol v1 Event",
5
+ "description": "A portable, append-only workflow event emitted by a Pakem-compatible agent or runtime.",
6
+ "type": "object",
7
+ "required": [
8
+ "protocol",
9
+ "protocol_version",
10
+ "event_id",
11
+ "event",
12
+ "occurred_at",
13
+ "session_id",
14
+ "actor",
15
+ "payload"
16
+ ],
17
+ "properties": {
18
+ "protocol": {
19
+ "const": "pakem"
20
+ },
21
+ "protocol_version": {
22
+ "const": "1.0"
23
+ },
24
+ "event_id": {
25
+ "type": "string",
26
+ "minLength": 1
27
+ },
28
+ "event": {
29
+ "type": "string",
30
+ "enum": [
31
+ "bug.recorded",
32
+ "decision.recorded",
33
+ "handover.created",
34
+ "integrity.repinned",
35
+ "policy.approval.granted",
36
+ "policy.decision",
37
+ "runtime.checkpoint.created",
38
+ "runtime.hook.dispatched",
39
+ "runtime.recovered",
40
+ "runtime.state.transitioned",
41
+ "runtime.workflow.initialized",
42
+ "session.abandoned",
43
+ "session.finish_blocked",
44
+ "session.finished",
45
+ "session.resumed",
46
+ "session.started",
47
+ "session.step_recorded",
48
+ "spec.approved",
49
+ "task.added",
50
+ "task.completed",
51
+ "task.dropped",
52
+ "verification.completed",
53
+ "team.agent.registered",
54
+ "team.task.created",
55
+ "team.task.assigned",
56
+ "team.task.claimed",
57
+ "team.task.heartbeat",
58
+ "team.task.released",
59
+ "team.task.handed_off",
60
+ "team.task.submitted",
61
+ "team.task.reviewed",
62
+ "team.task.blocked",
63
+ "team.task.unblocked",
64
+ "ledger.sealed"
65
+ ]
66
+ },
67
+ "occurred_at": {
68
+ "type": "string",
69
+ "format": "date-time"
70
+ },
71
+ "session_id": {
72
+ "type": [
73
+ "string",
74
+ "null"
75
+ ]
76
+ },
77
+ "actor": {
78
+ "type": "object",
79
+ "required": [
80
+ "type",
81
+ "name"
82
+ ],
83
+ "properties": {
84
+ "type": {
85
+ "type": "string",
86
+ "enum": [
87
+ "agent",
88
+ "user",
89
+ "system"
90
+ ]
91
+ },
92
+ "name": {
93
+ "type": "string",
94
+ "minLength": 1
95
+ }
96
+ },
97
+ "additionalProperties": false
98
+ },
99
+ "integrity": {
100
+ "description": "Additive hash chain (1.2.0). Older events without this field remain valid; a new chain starts after the last event that has no integrity data.",
101
+ "type": "object",
102
+ "required": ["prev", "hash"],
103
+ "properties": {
104
+ "prev": {"type": ["string", "null"]},
105
+ "hash": {"type": "string", "pattern": "^[0-9a-f]{64}$"}
106
+ },
107
+ "additionalProperties": false
108
+ },
109
+ "payload": {
110
+ "type": "object"
111
+ }
112
+ },
113
+ "additionalProperties": false
114
+ }
@@ -0,0 +1,51 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "urn:pakem:protocol:v1:session",
4
+ "title": "Pakem Session v1",
5
+ "description": "Portable baseline for a Pakem session. Additional properties are allowed for forward-compatible extensions.",
6
+ "type": "object",
7
+ "required": [
8
+ "id",
9
+ "goal",
10
+ "status",
11
+ "startedAt",
12
+ "steps"
13
+ ],
14
+ "properties": {
15
+ "schemaVersion": {
16
+ "type": "integer",
17
+ "minimum": 1
18
+ },
19
+ "id": {
20
+ "type": "string",
21
+ "minLength": 1
22
+ },
23
+ "goal": {
24
+ "type": "string",
25
+ "minLength": 1
26
+ },
27
+ "status": {
28
+ "type": "string",
29
+ "enum": [
30
+ "active",
31
+ "finished",
32
+ "abandoned"
33
+ ]
34
+ },
35
+ "startedAt": {
36
+ "type": "string",
37
+ "format": "date-time"
38
+ },
39
+ "finishedAt": {
40
+ "type": "string",
41
+ "format": "date-time"
42
+ },
43
+ "nextStep": {
44
+ "type": "string"
45
+ },
46
+ "steps": {
47
+ "type": "array"
48
+ }
49
+ },
50
+ "additionalProperties": true
51
+ }
@@ -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.