PAGS.

flowchart RL
  T["T-014 · task"] -->|indented under| R["R-003 · outcome"]
  T -->|follows| D["D-012 · decision"]
  D2["D-019 · newer decision"] -->|replaces| D
  R -->|must fit within| C["CHARTER"]
  D -->|reshapes| A["ARCHITECTURE"]
  E["D-015 · exception"] -->|bends a rule in| AG["AGENTS.md"]

flowchart TD
  S([Session starts]) --> N[Read the Now block in WORK.md]
  N --> K[Classify the change]
  K --> L[Look up its row in the change table]
  L --> Q{Inside approved scope?}
  Q -- No --> P[Write a proposal]
  P --> H{Maintainer approves?}
  H -- Not yet --> W([Record it in the Now block and stop])
  H -- Yes --> REC[Record who approved and when]
  REC --> T
  Q -- Yes --> T[Create or update the task]
  T --> DQ{Hard to reverse?}
  DQ -- Yes --> D[Record a decision]
  DQ -- No --> I
  D --> I[Make the smallest coherent change]
  I --> V[Run tests and pags check]
  V --> VQ{All green?}
  VQ -- No --> I
  VQ -- Yes --> U[Update records and archive finished entries]
  U --> NB[Rewrite the Now block]
  NB --> END([Session ends])

sequenceDiagram
  participant A as Agent
  participant R as Records
  participant M as Maintainer
  A->>R: Draft R-004 as proposed
  A->>M: Share the proposal and ask for approval
  M-->>A: Yes, approve R-004
  A->>R: Mark R-004 approved, add approved-by: sam 2026-09-27
  A->>R: Create T-022 for R-004
  Note over A,M: The agent never marks its own proposal approved

flowchart LR
  X["Existing code that breaks the new rules"] --> Q{"What is it?"}
  Q -->|We accept it| L["Accepted legacy"] --> A1["ARCHITECTURE · A- accepted"]
  Q -->|We plan to change it| M["Planned migration"] --> A2["WORK · R- outcome"]
  Q -->|Allowed for now| E["Temporary exception"] --> A3["DECISIONS · exception until date"]
  Q -->|It is simply wrong| B["Defect"] --> A4["WORK · T- under Unplanned"]

flowchart TD
  A(["Run scripts/install-pags.py"]) --> B["Detect from commit count and non-doc files"]
  B --> C{"New or existing project?"}
  C -->|New| G["Greenfield starter set"]
  C -->|Existing| BF["Brownfield set, including ARCHITECTURE"]
  G --> P["Preview every file it will touch"]
  BF --> P
  P --> F{"AGENTS.md or README.md already there?"}
  F -->|Yes| MS["Insert a marked PAGS section, keep the rest"]
  F -->|No| NW["Create from template"]
  MS --> AP["Apply after you confirm"]
  NW --> AP
  AP --> CK["Install .pags/check.py"]
  CK --> MF["Write .pags/manifest with version and template hashes"]
  MF --> CL["Add CLAUDE.md that imports AGENTS.md"]
  CL --> NX(["Print next steps for this project type"])

flowchart LR
  E["Edit code and records"] --> C["git commit"]
  C --> H["pre-commit runs pags check"]
  H --> CI["CI runs pags check and tests"]
  CI --> M(["Merge"])
  H -. fails .-> E
  CI -. fails .-> E