Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
dc4c93f
set up claude
rafapereirabr Oct 20, 2026
999c975
bug in balancing_cost
rafapereirabr Oct 20, 2026
cd9f47d
minor bugs
rafapereirabr Oct 20, 2026
cfbd606
minor issue in doubly_constrained
rafapereirabr Oct 20, 2026
6ab633c
theil_t with zeros
rafapereirabr Oct 20, 2026
0904f09
update url to ipea and minor fixes
rafapereirabr Oct 20, 2026
a6831ad
dev version
rafapereirabr Oct 20, 2026
edffe51
bug fix in constrained_accessibility
rafapereirabr Oct 20, 2026
97a8833
dealing with observations with the same income in concentration_index
rafapereirabr Oct 20, 2026
9d65767
fix bug corner case of cumulative_interval
rafapereirabr Oct 20, 2026
538985a
corner cases of cumulative_cutoff
rafapereirabr Oct 20, 2026
7121263
update roxygen docs
rafapereirabr Oct 20, 2026
cbc9f44
corner cases in equity measures
rafapereirabr Oct 20, 2026
aad4d64
docs and tests
rafapereirabr Oct 20, 2026
813666e
fast merge_by_reference
rafapereirabr Oct 20, 2026
db02851
using cli
rafapereirabr Oct 20, 2026
1914c5a
optimize gravity
rafapereirabr Oct 20, 2026
ddc440b
docs
rafapereirabr Oct 20, 2026
6691885
optimize decay functions
rafapereirabr Oct 20, 2026
f1cc59b
vignettes
rafapereirabr Oct 21, 2026
c0ae940
optimize gravity
rafapereirabr Oct 21, 2026
51e82c9
docs
rafapereirabr Oct 21, 2026
233f964
docs of fgt_poverty
rafapereirabr Oct 21, 2026
196fc4f
optimize doubly_constrained
rafapereirabr Oct 21, 2026
ff72154
fgt vignette
rafapereirabr Oct 21, 2026
4de9265
optimize cost_to_closest and spatial_availability
rafapereirabr Oct 21, 2026
150aba1
fgt_poverty corner case
rafapereirabr Oct 21, 2026
8f58141
accessibility measures now treat NA values and missing ids in land_us…
rafapereirabr Oct 21, 2026
5e85126
docs
rafapereirabr Oct 21, 2026
01cdf19
optimize cumulative_cutoff
rafapereirabr Oct 21, 2026
24a79ea
news
rafapereirabr Oct 21, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 7 additions & 2 deletions .Rbuildignore
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
^.*\.Rproj$
^\.Rproj\.user$
^\.github$
^tests_rafa$
^tests/test_rafa$
^codecov\.yml$
^cran-comments\.md$
^CRAN-SUBMISSION$
Expand All @@ -11,4 +11,9 @@
^codemeta\.json$
^data-raw$
^\.pre-commit-config\.yaml$
^testing_constrained\.Rmd$
^\.claude$
^CLAUDE\.md$
^MEMORY\.md$
^templates$
^quality_reports$
^man/figures/decay_functions\.png$
82 changes: 82 additions & 0 deletions .claude/rules/orchestrator-protocol.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Orchestrator Protocol (contractor mode)

**After the user approves a plan, execute it autonomously:** implement, verify,
review, fix, and repeat until reviews come back dry. Return to the user only
for ambiguity, a decision that is theirs, or a blocker. Nothing in this loop
commits, pushes or opens PRs; that needs an explicit request (`/acc-commit`).

## The loop

```
Approved plan
│
1. IMPLEMENT smallest change that satisfies the plan; follow
│ r-package-conventions.md
2. VERIFY quality-gates.md Gate 1 (document, targeted tests, lint);
│ read the output; retry ≤ 2, then escalate
3. REVIEW parallel forked reviewers (lenses below), each returns
│ FINDINGs
4. REDUCE dedupe on location+finding; CRITICAL>0 → BLOCK,
│ MAJOR>0 → REVISE, else PASS
5. FIX critical → major; minors fixed if cheap and in scope
6. RE-VERIFY Gate 1 again (Gate 2 before a PR)
│
└─ converged? (2 consecutive rounds with 0 new CRITICAL/MAJOR)
yes → report no → back to 3 with fresh reviewers (cap 5 rounds)
```

## Review lenses for package code

Launch in **one message**, each as a separate fresh subagent (not `fork`) with only the diff,
the plan and the relevant files:

| Lens | Agent | Looks for |
|---|---|---|
| Correctness and methodology | `general-purpose` | Formula vs the cited paper; hand-computed toy example; active vs passive; `group_by` and multiple cutoffs/decay values; `fill_missing_ids`; ids missing from `land_use_data`; NA/zero/Inf costs and opportunities; marginals and convergence (constrained/balancing measures); population weighting (inequality/poverty); output class and column order |
| Performance | `general-purpose` | Avoidable copies, row loops, repeated joins, materialising the full cutoff × OD grid, complexity regressions; asks for `bench::mark` if a speed claim is made |
| Package and CRAN | `r-package-reviewer` (local; if absent, `general-purpose` with `r-package-conventions.md`) | Conventions, roxygen, NAMESPACE, tests (including "input data sets remain unchanged" and output-class tests), CRAN policy, back-compat |

Scale down for small changes: a docs-only change needs only the package lens.
Scale up for risky ones: add a second correctness reviewer with a different
fixture focus.

**FINDING format:**
`{lens, severity: CRITICAL|MAJOR|MINOR, location: file:line, finding, evidence, proposed_fix}`.
A CRITICAL must be backed by evidence (a failing input, a quoted line). When
the orchestrator introduces a CRITICAL that no lens raised, it re-verifies it
in a fresh fork before acting on it; if the fork can't ground it, it is
dropped.

## Guards

- **Two strikes:** if the same finding survives rounds N and N+2, stop patching
and escalate to the user. The design is probably wrong.
- **Scope:** a reviewer finding outside the plan's scope goes to the backlog,
not into the diff.
- **Pre-existing failures:** don't fix them as drive-bys (see
`quality-gates.md`).
- **Cost:** keep fan-outs at 3–4 agents. For anything larger, ask first.

## Check-in cadence

Contractor mode means no routine check-ins. Plans may still define explicit
checkpoints (stop, summarise, wait); honour them. While a maintainer is new to
this workflow, plans include a checkpoint at each phase boundary. Drop these
checkpoints once the maintainer says so. Escalate immediately for:
- an API or behaviour decision
- a new dependency
- a gate that can't be passed without changing the plan
- disagreement between reviewers that touches user-facing behaviour

## Report (end of execution)

What changed (files, one line each), gate results with the actual output
summarised, review rounds and what they caught, anything deferred to the
backlog, and open questions. Then update the session log and set the plan
Status to COMPLETED.

## Not automatic

The loop is always started by an approved plan or an explicit skill
invocation. No background daemons, and no unattended loops against shared
branches.
80 changes: 80 additions & 0 deletions .claude/rules/plan-first-workflow.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
# Plan-First Workflow

**For any non-trivial task, enter plan mode before writing code.** Non-trivial
means more than one file, a change to exported behaviour, a performance change,
or anything taking more than a few minutes. A typo or a one-line obvious fix is
not.

## The protocol

1. **Enter plan mode** (`EnterPlanMode`).
2. **Recall:** read `MEMORY.md` `[LEARN]` entries and the backlog in
`quality_reports/specs/` for anything relevant.
3. **Explore:** read the affected functions, their helpers, tests and callers.
Look for existing helpers to reuse before proposing new code.
4. **Clarify:** ask only about genuine decisions (API naming, behaviour
changes, new dependencies), at most 3–5 questions via `AskUserQuestion`. For
large or vague tasks, write a spec first (below).
5. **Draft the plan:** context, approach, files to change, tests to add,
verification, and an explicit list of what is *not* being changed.
6. **Adversarial plan review:** see the next section. Mandatory.
7. **Plan file:** the harness creates the plan file in `quality_reports/plans/`
when plan mode starts (`plansDirectory` in settings), and it is the only
file writable in plan mode. It is the plan of record. Write the draft there
with Status: DRAFT and revise it in place through the review rounds.
8. **Present:** once the reviewers reach consensus, call `ExitPlanMode`.
Include a short "review outcome" note: what the reviewers cut or changed.
9. **On approval:** rename the file to
`quality_reports/plans/YYYY-MM-DD_short-description.md`, set Status to
APPROVED, start the session log, and execute via `orchestrator-protocol.md`
(contractor mode).

## Adversarial plan review (mandatory)

Every plan is challenged by **two independent adversarial agents** before it is
shown to the user. They are fresh `Plan` subagents (read-only; not `fork`), launched
in parallel in one message, each given the draft plan and the relevant file
paths. They never see each other's output in the first round.

| Reviewer | Mandate |
|---|---|
| **Minimalist** | Make it smaller. Which steps, files, abstractions, arguments or dependencies are unnecessary? Can an existing helper do this? What is the smallest diff that fully solves the problem? Is anything gold-plating? |
| **Skeptic** | Make it right. What breaks? Edge cases (ids missing from `land_use_data`, NA/zero costs, empty results after a cutoff, `group_by` + multiple cutoffs/decay values, active vs passive, data.frame/tibble input), does it match the cited formula, caller mutation, performance regressions, back-compat for exported functions, CRAN issues, missing tests. |

Each returns findings as `{severity: CRITICAL|MAJOR|MINOR, finding, proposed_change}`
and a verdict: `APPROVE` or `REVISE`.

**Consensus loop:**
1. Revise the plan to address every CRITICAL/MAJOR finding (or write down why
it is rejected).
2. Re-run both reviewers on the revised plan, this time with the other
reviewer's previous findings attached so they can contest them.
3. **Consensus = both return APPROVE.** Stop and save.
4. **Cap: 3 rounds.** If they still disagree, present the plan with the
unresolved disagreement stated plainly as a decision for the user.

**Simplicity bias:** when the two reviewers conflict, prefer the option with
less code change, unless the Skeptic shows a correctness or CRAN failure.

## Requirements spec (large or ambiguous tasks)

Use it when the task is vague ("improve performance"), has several valid
interpretations, or touches the public API in several places. Write
`quality_reports/specs/YYYY-MM-DD_description.md`. Use
`templates/requirements-spec.md` if present; it is local to the maintainer's
setup.
- Mark requirements MUST / SHOULD / MAY.
- Give each aspect a clarity status: CLEAR / ASSUMED / BLOCKED.
- Get approval, then plan.

## Plans on disk

Plans survive context compression. Status values: DRAFT → APPROVED →
COMPLETED. Update the status when it changes.

## Session recovery

After compression or in a new session:
1. Read `CLAUDE.md` and the most recent plan in `quality_reports/plans/`.
2. Run `git log --oneline -10` and `git status`.
3. State the current task and next step before continuing.
18 changes: 18 additions & 0 deletions .claude/rules/prompt-shaping.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Prompt Shaping (standing habit)

**When a request is informal, dictated or ambiguous, shape it silently before
acting.** Resolve:

1. **Role:** whose expertise answers this (R package maintainer, data.table
performance engineer, transport-accessibility methodologist, technical
writer)?
2. **Task:** the single concrete deliverable, as verb + object.
3. **Context:** which functions, tests, fixtures, issues and prior decisions
(`MEMORY.md`, plans) bear on it.
4. **Constraints:** conventions, gates, CRAN, back-compat, performance.
5. **Output:** a diff, a plan, a report, a benchmark?
6. **Bookend:** at the end, restate the goal and confirm it was met.

Don't narrate this back. Ask (briefly, via `AskUserQuestion`) only when a
decision belongs to the user. Otherwise infer, and state the assumption in one
line.
70 changes: 70 additions & 0 deletions .claude/rules/quality-gates.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
paths:
- "R/**"
- "tests/**"
- "vignettes/**"
- "man/roxygen/**"
- "README.Rmd"
- "DESCRIPTION"
- "NEWS.md"
- "inst/**"
- "_pkgdown.yml"
---

# Quality gates (accessibility)

Gates are **pass/fail checks**, not scores. A task is "done" only when the gate
for its checkpoint passes and the output has actually been seen; "should work"
doesn't count.

## Gate 1: Task done / commit

All must hold for the files touched:

| Check | Command | Pass |
|---|---|---|
| Docs regenerated | `Rscript -e "devtools::document()"` then `git diff --stat man/ NAMESPACE` | No unexpected content drift (use `git diff`, not `git status`: with `core.autocrlf=true` EOL-only rewrites show as modified); intended changes staged with the source |
| Targeted tests | `Rscript -e "devtools::test(filter = '<fn>')"` for every touched function | 0 failures, 0 new warnings |
| Lint | `Rscript -e "lintr::lint('R/<file>.R')"` per changed file (no `.lintr`; defaults) | No new lints on changed lines |
| Correctness | new/changed measure | Test against a hand-computed toy example / the cited formula (conventions A8) |
| README | if `README.Rmd` changed: `rmarkdown::render("README.Rmd")` | `README.md` regenerated and staged with `README.Rmd` |
| NEWS | user-facing change | Bullet under `# accessibility (development version)` |
| codemeta | if `DESCRIPTION` changed: `Rscript -e "codemetar::write_codemeta()"` | `codemeta.json` regenerated and staged (or reason noted) |
| pkgdown index | if an `@export` was added or removed: `Rscript -e "pkgdown::check_pkgdown()"` | No missing or stale topics in `_pkgdown.yml` |
| Fixture data | if `inst/extdata/*.rds` changed | Regenerated by a `data-raw/` script, not edited by hand; reason recorded |
| Staging hygiene | `git diff --cached --name-only` | No `.RData`/`.Rhistory`; `.rds` only under `inst/extdata/` (regenerated); no workflow files except `CLAUDE.md` and `.claude/rules/` |
| Conventions | `.claude/rules/r-package-conventions.md` checklist | All items hold |

## Gate 2: Pull request

Gate 1, plus:

| Check | Command | Pass |
|---|---|---|
| Full suite | `Rscript -e "devtools::test()"` | 0 failures |
| CRAN check | `Rscript -e "devtools::check(args = '--as-cran')"` (background; several minutes) | 0 errors, 0 warnings; each NOTE triaged (pre-existing vs new) |
| Review loop | parallel review lenses (`orchestrator-protocol.md`) | Converged: 0 open CRITICAL/MAJOR |
| Package review | `r-package-reviewer` agent on changed files (local; if absent, apply the conventions checklist manually) | 0 CRITICAL/MAJOR |
| Performance | if the change claims or risks a speed change | `bench::mark` evidence recorded |

## Gate 3: Release (maintainer-driven)

Gate 2, plus `/acc-package-check` (full report), `devtools::check_win_devel()`
and/or R-hub, a reverse-dependency check, `cran-comments.md` updated, and
`_pkgdown.yml` covering all exports. Claude prepares; the maintainer bumps the
version and submits.

## Overrides

A gate may be skipped only on an explicit user instruction ("commit anyway"),
and the reason is recorded in the commit body and the session log. Never use
`git commit --no-verify`. The repo's `.pre-commit-config.yaml` hooks (README
rendered, codemeta synced, pkgdown reference index) run only where
`pre-commit install` has been run. That is why
Gate 1 checks README and staging explicitly instead of relying on the hooks.

## Pre-existing failures

If a gate fails for reasons unrelated to the change, don't fix it as a drive-by.
Report it, confirm it also fails on `main`, and add it to the backlog
(`quality_reports/specs/`).
Loading
Loading