principles 0.0.1

data/lib/principles/data/schemas/assessment-answer.schema.json

@@ -0,0 +1,332 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "assessment-answer.schema.json",
+  "title": "Assessment answer",
+  "description": "What an agent answers an audit's assessment request with: the request's id and basis, an assessment of each member and of the set, a recent decision, and any findings. Fields this tool does not read are refused, to catch a misspelt field (D29). The rules across fields, such as which members exist, stay in Models::AssessmentAnswer.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "request_id",
+    "basis",
+    "member_assessments",
+    "collective_assessment",
+    "recent_decision",
+    "findings"
+  ],
+  "properties": {
+    "request_id": {
+      "type": "string"
+    },
+    "basis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "base_commit",
+        "last_completed_revision"
+      ],
+      "properties": {
+        "base_commit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "pattern": "\\A[0-9a-f]{40}([0-9a-f]{24})?\\z",
+          "description": "A full commit sha, as start-audit gave it, or null outside git. This tool refuses anything else before running git."
+        },
+        "last_completed_revision": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The revision of the principle's last completed audit record when start-audit printed the request, or null when there was none. The request id binds it."
+        }
+      }
+    },
+    "member_assessments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "member_id"
+        ],
+        "description": "A fresh assessment, with assessment, delivery and evidence, or the marker carried_forward: true for a member the request carries forward (D49). Models::MemberAssessments refuses an entry that is neither.",
+        "properties": {
+          "member_id": {
+            "type": "string"
+          },
+          "carried_forward": {
+            "const": true
+          },
+          "assessment": {
+            "type": "string"
+          },
+          "delivery": {
+            "type": "string",
+            "description": "observed or not_observed; Models::AssessmentAnswer refuses any other with invalid_delivery."
+          },
+          "observation": {
+            "type": "string"
+          },
+          "observed_at": {
+            "type": ["string", "null"],
+            "minLength": 1,
+            "description": "On an observed delivery only, when the agent saw what observation describes, if that was before this audit; omitted or null, it is this audit's time, so the agent never types a clock time (#716). Models::MemberSighting refuses it on not_observed, one not a UTC time to the second as audited_at is, such as 2026-11-01T09:30:00Z, and one after the answer (#699), and refuses an observation repeated word for word from the last full audit as observation_repeats_last_audit unless it is that audit's date or null (#680, #716)."
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "path"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "path": {
+                  "type": "string"
+                },
+                "heading": {
+                  "type": "string"
+                },
+                "starting_at": {
+                  "type": "string"
+                },
+                "ending_at": {
+                  "type": "string"
+                },
+                "query": {
+                  "type": "string"
+                }
+              }
+            }
+          },
+          "check_result": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "command"
+            ],
+            "description": "A member check's result as the agent reports it: the command, exactly as the map names it, its exit_status or, when it could not be run, not_run_reason, and review_basis, one line saying what the review before the run rested on, which an exit_status for a check the stored record did not run needs (D63). Models::AssessmentAnswer refuses any other combination with invalid_check_result.",
+            "properties": {
+              "command": {
+                "type": "string"
+              },
+              "exit_status": {
+                "type": "integer"
+              },
+              "not_run_reason": {
+                "type": "string"
+              },
+              "review_basis": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "collective_assessment": {
+      "type": "string"
+    },
+    "recent_decision": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "unavailable_reason": {
+          "type": "string"
+        },
+        "assessment": {
+          "type": "string"
+        },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "path"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "path": {
+                "type": "string"
+              },
+              "heading": {
+                "type": "string"
+              },
+              "starting_at": {
+                "type": "string"
+              },
+              "ending_at": {
+                "type": "string"
+              },
+              "query": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "loading_decisions": {
+      "description": "One decision for each member the request lists in loads_to_check_against_activation (#355). Which decision each needs, and its reason, is checked by Models::LoadsToCheck.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["member_id", "decision"],
+        "properties": {
+          "member_id": { "type": "string" },
+          "decision": { "type": ["string", "null"] },
+          "reason": { "type": "string" },
+          "as": { "type": "string" }
+        }
+      }
+    },
+    "prior_finding_decisions": {
+      "description": "One decision for each finding the request lists in prior_findings (D35). Which decision each needs, and its reason, is checked by Models::PriorFindings.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["finding_id", "decision"],
+        "properties": {
+          "finding_id": { "type": "string" },
+          "decision": { "type": ["string", "null"] },
+          "reason": { "type": "string" },
+          "as": { "type": "string" },
+          "problem": { "type": "string" },
+          "action": { "type": "string" },
+          "first_raised_at": {
+            "type": "string",
+            "description": "On a still_holds decision, an earlier time the finding was first raised: the audited_at of the record that raised_in holds, which Models::FirstRaisedClaim checks (D53)."
+          },
+          "raised_in": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{40}([0-9a-f]{24})?$",
+            "description": "The full sha of the commit whose audit record, at .principles/audits/ID.json or the earlier .memeplex/audits/ID.json, left this finding open at first_raised_at (D53)."
+          },
+          "waits_on": {
+            "type": ["string", "null"],
+            "description": "On a still_holds decision that leaves the finding deferred, a new one line saying whom it waits on and to decide what; null drops the one it carried. Leaving it out keeps it (D52)."
+          },
+          "recorded_at": {
+            "x-type-refusal-advice": {
+              "keys": [
+                "heading",
+                "starting_at"
+              ],
+              "says": "plus starting_at (or heading) when the file holds more than this finding"
+            },
+            "type": ["object", "null"],
+            "required": ["path"],
+            "additionalProperties": false,
+            "properties": {
+              "path": { "type": "string" },
+              "heading": { "type": "string" },
+              "starting_at": { "type": "string" },
+              "ending_at": { "type": "string" },
+              "query": { "type": "string" }
+            }
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["path"],
+              "additionalProperties": false,
+              "properties": {
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "starting_at": { "type": "string" },
+                "ending_at": { "type": "string" },
+                "query": { "type": "string" }
+              }
+            }
+          },
+          "problem_evidence": {
+            "description": "On a still_holds decision, pointers to where the problem is: for a finding marked evidence_not_kept, its evidence, which the record keeps (D64); for one whose record keeps evidence, each the new place of the kept item named by replaces, its position in the finding's evidence, which must no longer be found (D70). Models::StillHoldsRestatement refuses any other.",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["path"],
+              "additionalProperties": false,
+              "properties": {
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "starting_at": { "type": "string" },
+                "ending_at": { "type": "string" },
+                "query": { "type": "string" },
+                "replaces": { "type": "integer" }
+              }
+            }
+          }
+        }
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "x-unread-field-advice": {
+          "recorded_at": "give it in this finding's disposition, in the correction answer this assessment leads to"
+        },
+        "required": [
+          "id",
+          "member_ids",
+          "problem",
+          "consequence",
+          "proposed_action",
+          "evidence"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "member_ids": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "problem": {
+            "type": "string"
+          },
+          "consequence": {
+            "type": "string"
+          },
+          "proposed_action": {
+            "type": "string"
+          },
+          "evidence": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": [
+                "path"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "path": {
+                  "type": "string"
+                },
+                "heading": {
+                  "type": "string"
+                },
+                "starting_at": {
+                  "type": "string"
+                },
+                "ending_at": {
+                  "type": "string"
+                },
+                "query": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/lib/principles/data/schemas/audit-record.schema.json

@@ -0,0 +1,277 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "audit-record.schema.json",
+  "title": "Audit record",
+  "description": "A principle's committed audit record, .principles/audits/ID.json: what the last audit began from, each member's hash when it was assessed, and each finding's outcome. Fields this schema does not name are allowed, so an older version can read a record a newer one wrote (D29).",
+  "type": "object",
+  "required": ["principle_id", "status", "map_version", "base_commit", "audited_at", "members", "findings"],
+  "properties": {
+    "principle_id": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["open", "completed"] },
+    "map_version": { "type": "string", "minLength": 1 },
+    "base_commit": { "type": ["string", "null"] },
+    "audited_at": { "type": "string", "minLength": 1 },
+    "members": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["sha256"],
+        "properties": {
+          "sha256": { "type": "string", "minLength": 1 },
+          "key": { "type": "string", "minLength": 1, "description": "The member's key in the map, when it differs from the id this entry is filed under, because the member has moved." },
+          "assessment": {
+            "description": "The member's assessment as a full audit's agent gave it, which the next full audit may carry forward while the member and what it was judged on are unchanged (D49).",
+            "type": "object",
+            "required": ["assessment", "delivery", "evidence", "evidence_sha256", "assessed_at", "entry_sha256", "loads_sha256"],
+            "properties": {
+              "assessment": { "type": "string", "minLength": 1 },
+              "delivery": { "type": "string", "minLength": 1 },
+              "observation": { "type": "string" },
+              "observed_at": { "type": "string", "minLength": 1, "description": "On an observed delivery, when the sighting its observation describes was: the time the agent gave, or else when the assessment was made. Carrying it forward keeps this; a record written before it was kept has none (#680)." },
+              "evidence": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "required": ["path"],
+                  "properties": {
+                    "path": { "type": "string", "minLength": 1 },
+                    "heading": { "type": "string" },
+                    "starting_at": { "type": "string" },
+                    "ending_at": { "type": "string" },
+                    "query": { "type": "string" }
+                  }
+                }
+              },
+              "evidence_sha256": { "type": "array", "items": { "type": "string", "minLength": 1 }, "description": "The hash of each evidence item's text when it was assessed, in the same order." },
+              "assessed_at": { "type": "string", "minLength": 1, "description": "When the assessment was made; carrying it forward keeps this." },
+              "entry_sha256": { "type": "string", "minLength": 1, "description": "A digest of the member's map entry when it was assessed: its path, locator, role and check." },
+              "loads_sha256": { "type": "string", "minLength": 1, "description": "A digest of when the member loaded when it was assessed, without file sizes." }
+            }
+          },
+          "changed_during_last_audit": { "const": true, "description": "The member changed during this audit, as a fix in its correction changes it, so no assessment read the text recorded here and none is kept." },
+          "check_result": {
+            "description": "The result the agent reported for the member's check, as of base_commit. This tool never ran it (D30).",
+            "type": "object",
+            "required": ["command"],
+            "properties": {
+              "command": { "type": "string", "minLength": 1 },
+              "exit_status": { "type": "integer" },
+              "not_run_reason": { "type": "string", "minLength": 1 },
+              "review_basis": { "type": "string", "minLength": 1 },
+              "review_basis_since": { "type": "string", "minLength": 1, "description": "When an earlier audit first kept this review_basis, carried while the check and the line are unchanged. Absent means this record's audited_at; only principles writes it (D63, D52)." }
+            }
+          },
+          "loading_accepted": {
+            "description": "The agent's accepted decision that the member loads as it does under the principle's activation, with its reason and the loads it accepted (#355).",
+            "type": "object",
+            "required": ["reason", "loads"],
+            "properties": {
+              "reason": { "type": "string", "minLength": 1 },
+              "loads": {
+                "type": "object",
+                "description": "When each host loads the member's file and how big it is, as show-principle derived it at the assessment. Each field is named, so show-audit prints it back.",
+                "properties": {
+                  "claude_code": {
+                    "type": "object",
+                    "properties": {
+                      "when": {
+                        "type": "string"
+                      },
+                      "file_bytes": {
+                        "type": "integer"
+                      },
+                      "estimated_tokens": {
+                        "type": "integer"
+                      },
+                      "member_bytes": {
+                        "type": "integer"
+                      },
+                      "member_tokens": {
+                        "type": "integer"
+                      },
+                      "context": {
+                        "type": "string"
+                      },
+                      "skill_part": {
+                        "type": "string"
+                      },
+                      "invoked_by": {
+                        "type": "string"
+                      },
+                      "description": {
+                        "type": "object",
+                        "properties": {
+                          "files": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "paths_field": {
+                            "type": "array",
+                            "items": {
+                              "type": "string"
+                            }
+                          },
+                          "when": {
+                            "type": "string"
+                          },
+                          "file_bytes": {
+                            "type": "integer"
+                          },
+                          "estimated_tokens": {
+                            "type": "integer"
+                          },
+                          "member_bytes": {
+                            "type": "integer"
+                          },
+                          "member_tokens": {
+                            "type": "integer"
+                          },
+                          "not_derived": {
+                            "type": "string"
+                          }
+                        }
+                      },
+                      "files": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "paths_field": {
+                        "type": "array",
+                        "items": {
+                          "type": "string"
+                        }
+                      },
+                      "not_derived": {
+                        "type": "string"
+                      },
+                      "frontmatter_refused": {
+                        "type": "string"
+                      },
+                      "named_in_hooks": {
+                        "type": "array",
+                        "items": {
+                          "type": "object",
+                          "properties": {
+                            "settings": {
+                              "type": "string"
+                            },
+                            "event": {
+                              "type": "string"
+                            },
+                            "matcher": {
+                              "type": "string"
+                            },
+                            "command": {
+                              "type": "string"
+                            },
+                            "args": {
+                              "type": "array",
+                              "items": {
+                                "type": "string"
+                              }
+                            }
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "acknowledgements": {
+            "description": "Changes a one-member audit judged to keep the member's meaning since the last full audit, oldest first (D33).",
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["from_sha256", "to_sha256", "commit", "reason", "acknowledged_at"],
+              "properties": {
+                "from_sha256": { "type": "string", "minLength": 1 },
+                "to_sha256": { "type": "string", "minLength": 1 },
+                "commit": { "type": "string", "minLength": 1 },
+                "reason": { "type": "string", "minLength": 1 },
+                "acknowledged_at": { "type": "string", "minLength": 1 },
+                "deferred_findings": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+                "accepted_findings": { "type": "array", "items": { "type": "string", "minLength": 1 } }
+              }
+            }
+          }
+        }
+      }
+    },
+    "judged_against": { "type": "string", "minLength": 1, "description": "A digest of the principle's description and the question this tool asked, which every assessment in the record answered (D49)." },
+    "principles_package": {
+      "description": "On the sticking-to-your-principles record only: the version of principles its audit ran under, and a digest of the passage that version proposes for setup, as printed, by key: entry_file_passage, or, in a record a release before D71 wrote, one key for each passage form it proposed, which its next full audit compares with the version running then (D68).",
+      "type": "object",
+      "required": ["version", "passage_sha256"],
+      "properties": {
+        "version": { "type": "string", "minLength": 1 },
+        "passage_sha256": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }
+      }
+    },
+    "base_members": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1 } },
+    "last_completed": { "type": "object", "required": ["principle_id", "status", "audited_at", "members", "findings"] },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "member_ids"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "member_ids": { "type": "array", "items": { "type": "string" } },
+          "problem": { "type": "string", "description": "The finding's problem as the assessment stated it, at audit time (D34)." },
+          "evidence": {
+            "type": "array",
+            "description": "The evidence the assessment raised the finding with, as the answer located it (D64). Absent from a finding recorded before it was kept.",
+            "items": {
+              "type": "object",
+              "required": ["path"],
+              "additionalProperties": false,
+              "properties": {
+                "path": { "type": "string" },
+                "heading": { "type": "string" },
+                "starting_at": { "type": "string" },
+                "ending_at": { "type": "string" },
+                "query": { "type": "string" }
+              }
+            }
+          },
+          "first_raised_at": { "type": "string", "minLength": 1, "description": "When an earlier audit first raised this finding, kept or raised again since (D35). Absent means this record's audited_at." },
+          "raised_in": { "type": "string", "minLength": 1, "description": "The commit whose record a full audit cited for an earlier first_raised_at, checked to leave this finding open then (D53)." },
+          "action": { "type": "string", "minLength": 1 },
+          "waits_on": { "type": "string", "minLength": 1, "description": "On a deferred finding, the one line its answer gave saying whom it waits on and to decide what (D52)." },
+          "waits_on_since": { "type": "string", "minLength": 1, "description": "When an earlier audit asked waits_on, carried since. Absent means this record's audited_at; only principles writes it (D52)." },
+          "recorded_at": {
+            "type": "object",
+            "required": ["path"],
+            "properties": {
+              "path": { "type": "string", "minLength": 1 },
+              "heading": { "type": "string" },
+              "starting_at": { "type": "string" },
+              "ending_at": { "type": "string" },
+              "query": { "type": "string" }
+            }
+          },
+          "repointed": {
+            "type": "array",
+            "description": "Each repoint of recorded_at since the full audit that kept this finding: where it pointed, where it points, when and why (D59). Only principles writes it.",
+            "items": {
+              "type": "object",
+              "required": ["from", "to", "at", "reason"],
+              "properties": {
+                "from": { "type": ["object", "null"] },
+                "to": { "type": "object" },
+                "at": { "type": "string", "minLength": 1 },
+                "reason": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}