From fa576bbc19e000207c9a865f6a9f28431ddfdc9f Mon Sep 17 00:00:00 2001 From: santxkoz Date: Sat, 4 Jul 2026 11:53:45 +0700 Subject: [PATCH] docs: add repo work ledger --- AGENTS.md | 64 ++++++++++++------- WORK_LEDGER/AREAS.md | 24 +++++++ WORK_LEDGER/README.md | 37 +++++++++++ WORK_LEDGER/TEMPLATE.md | 16 +++++ .../WORK_LOG/README.md | 27 +++----- 5 files changed, 126 insertions(+), 42 deletions(-) create mode 100644 WORK_LEDGER/AREAS.md create mode 100644 WORK_LEDGER/README.md create mode 100644 WORK_LEDGER/TEMPLATE.md diff --git a/AGENTS.md b/AGENTS.md index 7836ddf7f..9685b2d73 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -356,48 +356,66 @@ Suggested commit cadence: 3. stage only the intended files 4. commit before starting the next distinct chunk -### Daily work log and push checkpoints - -Use a daily work log when work touches a major workspace such as `docs/`, -`docs/topics/`, `uet_history/`, `thailand_proposals/`, `services_and_experiments/`, -or another top-level project area. - -Write the log under `docs/UET_Documentation_Details/WORK_LOG/` using one file per -day, such as `2026-07-04.md`. The log is not a replacement for topic -`UPDATE_LOG.md`; it is the repo-level operating trace that shows what moved that -day and what still needs a commit, push, or PR. - -Add one work-log entry after each completed section of work. A section can be a -research pass, source cleanup, documentation repair, result artifact review, -history migration, service experiment change, or any coherent batch that a future -reviewer should be able to reconstruct without reading the whole diff first. +### Repo work ledger and push checkpoints + +Use the repo work ledger for every major UET workspace, not only research. The +ledger lives at `WORK_LEDGER/` because it records the operating history of the +whole repository. + +Before starting a substantial section of work, classify it with +`WORK_LEDGER/AREAS.md`. Common areas include: + +- `research-core` for numbered research topics under `docs/topics/` +- `research-standards` for `docs/topics/For Work/` and research operating rules +- `theory-history` for theory notes and archives under `uet_history/` +- `book-writing` for long-form book or publishable narrative work +- `thai-policy` for proposals under `thailand_proposals/` +- `services-tools` for services, experiments, MCP, GraphQL, or automation tools +- `repo-ops` for GitHub Actions, manifests, repository hygiene, and agent rules +- `raw-private` for local-only source material that may be unsafe to publish + +Write one daily ledger file under `WORK_LEDGER/YYYY/`, such as +`WORK_LEDGER/2026/2026-07-04.md`. The ledger is not a replacement for topic +`UPDATE_LOG.md`; it is the repo-level trace that shows what moved that day and +what still needs a commit, push, or PR. + +Add one ledger entry after each completed section of work. A section can be a +research pass, theory/book drafting pass, history migration, policy proposal +revision, service/tool change, documentation repair, result artifact review, or +any coherent batch that a future reviewer should be able to reconstruct without +reading the whole diff first. Each entry should record: - timestamp or short section label +- area id from `WORK_LEDGER/AREAS.md` - workspace or topic touched - files or artifact groups changed - verifier, audit, or review actually run, if any +- public-safety status: `safe`, `partial`, `private`, or `blocked` - what remains uncommitted, private, or unsafe to publish -- next commit or push action +- next commit, push, PR, or manifest action -Do not let work logs become another place for vague progress claims. Keep them -short, factual, and tied to actual files or artifacts. +Do not let ledger entries become another place for vague progress claims. Keep +them short, factual, and tied to actual files or artifacts. Checkpoint rule: -- if 10 work-log entries exist for the current unpushed work, stop expanding scope +- if 10 ledger entries exist for the current unpushed work, stop expanding scope - inspect `git status` and stage only the intended files - commit the safe coherent unit - push the branch the same day whenever network and repository policy allow it - if the work is not ready for `main`, open or update a draft PR instead of leaving the branch local-only -- if files are unsafe to publish, commit a manifest or log note that names the +- if files are unsafe to publish, commit a manifest or ledger note that names the excluded class without publishing the raw/private content -Do not start an eleventh work-log entry until the checkpoint decision is made. -If a push is blocked, record the blocker and the exact next action in the daily -work log before continuing. +Do not start an eleventh ledger entry until the checkpoint decision is made. If +a push is blocked, record the blocker and the exact next action in the daily +ledger before continuing. + +Legacy location note: `docs/UET_Documentation_Details/WORK_LOG/` should point to +`WORK_LEDGER/` instead of becoming a second competing log location. For multi-wave hardening, a good unit is: diff --git a/WORK_LEDGER/AREAS.md b/WORK_LEDGER/AREAS.md new file mode 100644 index 000000000..8ae1b9c08 --- /dev/null +++ b/WORK_LEDGER/AREAS.md @@ -0,0 +1,24 @@ +# UET Work Areas + +Use these area ids in `WORK_LEDGER/YYYY/YYYY-MM-DD.md` entries before starting a +substantial section of work. + +| Area id | Primary paths | Use for | +| --- | --- | --- | +| `research-core` | `docs/topics/`, `docs/meta/` | Numbered UET research topics, topic status, verifier artifacts, evidence gates | +| `research-standards` | `docs/topics/For Work/`, `AGENTS.md` | Research workflow rules, claim discipline, AI-agent operating standards | +| `documentation-system` | `docs/UET_Documentation_Details/`, `README.md`, `CONTRIBUTING.md` | Project documentation architecture, public explanation, style guidance | +| `theory-history` | `uet_history/1_raw/`, `uet_history/theory/`, `uet_history/equations/` | Theory notes, historical source organization, recovered idea archives | +| `book-writing` | `uet_history/3_publish/books/` | Long-form book structure, chapters, publishable narrative drafts | +| `thai-policy` | `thailand_proposals/` | Thailand proposal work, policy framing, public-project concepts, source manifests | +| `services-tools` | `services_and_experiments/` | Local services, experiments, MCP, GraphQL, search, embeddings, automation tools | +| `result-artifacts` | `Result/`, topic `Result/` folders | Small reproducible outputs, reports, figures, verifier outputs | +| `repo-ops` | `.github/`, `.gitignore`, `_config.yml`, root manifests | CI, GitHub Pages, branch hygiene, repo recovery, public-safe publishing rules | +| `raw-private` | local-only raw assets, transcripts, chat exports, audio, PDFs | Source material that needs review or manifest treatment before public commit | + +## Classification Rule + +If a task touches more than one area, record the primary area first and list the +secondary area in the entry body. If the work contains private or raw material, +mark public safety as `partial`, `private`, or `blocked` even when some markdown +outputs are safe to commit. \ No newline at end of file diff --git a/WORK_LEDGER/README.md b/WORK_LEDGER/README.md new file mode 100644 index 000000000..beb7220a3 --- /dev/null +++ b/WORK_LEDGER/README.md @@ -0,0 +1,37 @@ +# UET Repo Work Ledger + +This folder is the repo-level operating ledger for all UET work, not only +research topics. + +Use it to keep daily progress visible across: + +- research topics and standards +- theory history and book writing +- Thailand policy proposals +- services, experiments, MCP, GraphQL, and tooling +- repository operations, GitHub Actions, manifests, and agent rules +- raw/private source handling decisions + +The ledger answers one question: what work moved today, what can be published, +and what still needs a commit, push, PR, or manifest? + +## Daily Files + +Use one file per day under the year folder: + +```text +WORK_LEDGER/2026/2026-07-04.md +``` + +Each completed section of work should add one short entry. If 10 entries exist +for unpushed work, stop expanding scope and make a checkpoint before continuing. + +## Relationship To Other Logs + +- `WORK_LEDGER/` records repo-wide daily operating history. +- Topic `UPDATE_LOG.md` files record research-state changes for that topic. +- Manifests record what was included, excluded, private, duplicated, or too large. +- Git commits and PRs are the durable public evidence that work actually moved. + +Do not use this ledger to upgrade research claims or replace artifacts. Use it +to prevent work from disappearing into local-only branches. \ No newline at end of file diff --git a/WORK_LEDGER/TEMPLATE.md b/WORK_LEDGER/TEMPLATE.md new file mode 100644 index 000000000..74623fa64 --- /dev/null +++ b/WORK_LEDGER/TEMPLATE.md @@ -0,0 +1,16 @@ +# YYYY-MM-DD Work Ledger + +## HH:MM - short section title + +Area: `area-id` +Paths: `path/or/group`, `another/path` +Work: short factual description of what changed +Verification: command, review, or `not run` +Public-safety: `safe | partial | private | blocked` +Commit status: `not committed | committed locally | pushed branch | PR opened | merged` +Next action: exact next commit, push, PR, manifest, or cleanup step + +Notes: +- Keep this factual and tied to actual files or artifacts. +- Do not use ledger text to upgrade research claims. +- If this is the 10th unpushed entry, checkpoint before adding another entry. \ No newline at end of file diff --git a/docs/UET_Documentation_Details/WORK_LOG/README.md b/docs/UET_Documentation_Details/WORK_LOG/README.md index e112c8344..646cfdc53 100644 --- a/docs/UET_Documentation_Details/WORK_LOG/README.md +++ b/docs/UET_Documentation_Details/WORK_LOG/README.md @@ -1,23 +1,12 @@ -# UET Work Log +# UET Work Log Legacy Location -This folder records daily operating checkpoints for work that spans major UET -workspaces. +The repo-wide work log now lives at [`WORK_LEDGER/`](../../../WORK_LEDGER/). -Use one file per day, named like `2026-07-04.md`. +Do not create a second daily log stream here. This folder remains only as a +pointer for older documentation that mentioned `docs/UET_Documentation_Details/WORK_LOG/`. -Each completed work section should add a short entry with: +Use: -- timestamp or section label -- workspace or topic touched -- files or artifact groups changed -- verifier, audit, or review run, if any -- what remains uncommitted, private, or unsafe to publish -- next commit or push action - -This log does not replace topic-level `UPDATE_LOG.md` files. Topic logs describe -research state changes. This folder tracks daily repository work so progress -does not sit invisible in local branches. - -After 10 entries for unpushed work, stop expanding scope and make a checkpoint: -inspect status, stage only intended files, commit the safe unit, and push or open -a draft PR. If publishing is blocked, record the blocker here before continuing. \ No newline at end of file +- [`WORK_LEDGER/README.md`](../../../WORK_LEDGER/README.md) for the operating rule +- [`WORK_LEDGER/AREAS.md`](../../../WORK_LEDGER/AREAS.md) for area classification +- `WORK_LEDGER/YYYY/YYYY-MM-DD.md` for daily repo-wide ledger entries \ No newline at end of file