icon yellow/blue

Asset/css/skeleton.css

@@ -1 +0,0 @@
-/* Skeleton plugin styles -- add CSS here. Loaded via template:layout:css. */

Asset/js/recoreco-modal.js

@@ -0,0 +1,143 @@
+/*
+ * RecoReco -- keep the "days before" field within one period of the selected frequency.
+ *
+ * The Recurring schedule modal is injected by AJAX, so we react to the frequency <select> both when
+ * it appears (MutationObserver) and when it changes (delegated event). Daily -> field disabled (0);
+ * weekly -> max 6; monthly -> max 27; yearly -> max 364. The server clamps too, so this is only the
+ * UI guard.
+ */
+(function () {
+    "use strict";
+
+    var CAPS = { daily: 0, weekly: 6, monthly_day: 27, monthly_dow: 27, yearly: 364 };
+
+    function apply(select) {
+        // "days before" ceiling / disable by frequency.
+        var input = document.querySelector('input[name="recoreco_days_before"]');
+        if (input) {
+            var max = CAPS.hasOwnProperty(select.value) ? CAPS[select.value] : 27;
+
+            if (max === 0) {
+                input.value = 0;
+                input.setAttribute("max", "0");
+                input.disabled = true;
+            } else {
+                input.disabled = false;
+                input.setAttribute("max", String(max));
+                if (parseInt(input.value, 10) > max) {
+                    input.value = max;
+                }
+            }
+        }
+
+        // The last-day/weekday checkbox only means something for monthly and yearly.
+        var lastday = document.querySelector(".recoreco-lastday");
+        if (lastday) {
+            var monthlyOrYearly = select.value === "monthly_day" || select.value === "monthly_dow" || select.value === "yearly";
+            lastday.style.display = monthlyOrYearly ? "" : "none";
+        }
+    }
+
+    // "Follow FinanceBuddy installments": when on, the current/limit fields mirror FinanceBuddy's
+    // live installment current/total and are disabled (so they do not post, keeping FinanceBuddy the
+    // single source of truth); when off, they restore RecoReco's own stored values.
+    function applyFollow(checkbox) {
+        var group = checkbox.closest(".recoreco-limit-group");
+        if (!group) { return; }
+
+        var count = group.querySelector('input[name="recoreco_count"]');
+        var limit = group.querySelector('input[name="recoreco_limit"]');
+        if (!count || !limit) { return; }
+
+        if (checkbox.checked) {
+            count.value = group.getAttribute("data-fb-current");
+            limit.value = group.getAttribute("data-fb-total");
+        } else {
+            count.value = group.getAttribute("data-rr-count");
+            limit.value = group.getAttribute("data-rr-limit");
+        }
+
+        count.disabled = checkbox.checked;
+        limit.disabled = checkbox.checked;
+    }
+
+    // Trigger column: it can never be the target, so hide+disable that option and reset to Any if it
+    // was selected; the invert checkbox only means something for a specific column.
+    function applyTrigger() {
+        var target = document.querySelector('select[name="recoreco_target_column"]');
+        var trigger = document.querySelector('select[name="recoreco_trigger_column"]');
+        var invert = document.querySelector('input[name="recoreco_trigger_invert"]');
+        if (!target || !trigger) { return; }
+
+        for (var i = 0; i < trigger.options.length; i++) {
+            var isTarget = trigger.options[i].value === target.value;
+            trigger.options[i].hidden = isTarget;
+            trigger.options[i].disabled = isTarget;
+        }
+        if (trigger.value === target.value) { trigger.value = "any"; }
+
+        if (invert) {
+            var invertDisabled = (trigger.value === "any");
+            invert.disabled = invertDisabled;
+            var invertLabel = invert.closest("label");
+            if (invertLabel) { invertLabel.style.opacity = invertDisabled ? "0.5" : ""; }
+        }
+    }
+
+    // Move-mode makes copies moot, so grey out "Link copies to the template" while it is checked
+    // (disabled -> it won't post, so the saved value is 0).
+    function applyMove() {
+        var move = document.querySelector('input[name="recoreco_move"]');
+        var link = document.querySelector('input[name="recoreco_link_copies"]');
+        if (!move || !link) { return; }
+
+        link.disabled = move.checked;
+        var label = link.closest("label");
+        if (label) { label.style.opacity = move.checked ? "0.5" : ""; }
+    }
+
+    // Italicize the card's current column in the target/trigger dropdowns, so you can see where it
+    // sits right now. (<option> styling is honored by Chrome/Firefox; Safari may ignore it.)
+    function applyCurrentItalic() {
+        var form = document.querySelector('form[data-recoreco-current]');
+        if (!form) { return; }
+
+        var current = form.getAttribute("data-recoreco-current");
+        var selects = form.querySelectorAll('select[name="recoreco_target_column"], select[name="recoreco_trigger_column"]');
+        for (var s = 0; s < selects.length; s++) {
+            for (var i = 0; i < selects[s].options.length; i++) {
+                if (selects[s].options[i].value === current) {
+                    selects[s].options[i].style.fontStyle = "italic";
+                }
+            }
+        }
+    }
+
+    document.addEventListener("change", function (e) {
+        if (e.target && e.target.name === "recoreco_frequency") {
+            apply(e.target);
+        }
+        if (e.target && e.target.name === "recoreco_follow_finance") {
+            applyFollow(e.target);
+        }
+        if (e.target && (e.target.name === "recoreco_target_column" || e.target.name === "recoreco_trigger_column")) {
+            applyTrigger();
+        }
+        if (e.target && e.target.name === "recoreco_move") {
+            applyMove();
+        }
+    });
+
+    if (window.MutationObserver) {
+        new MutationObserver(function () {
+            var select = document.querySelector('select[name="recoreco_frequency"]:not([data-recoreco-init])');
+            if (select) {
+                select.setAttribute("data-recoreco-init", "1");
+                apply(select);
+                applyTrigger();
+                applyMove();
+                applyCurrentItalic();
+            }
+        }).observe(document.body, { childList: true, subtree: true });
+    }
+})();

Asset/js/skeleton.js

@@ -1 +0,0 @@
-// Skeleton plugin script -- add JS here. Loaded via template:layout:js.

Console/RecoRecoCommand.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Console;
+
+use Kanboard\Console\BaseCommand;
+use Kanboard\Plugin\RecoReco\Model\RecoRecoModel;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+
+/**
+ * CLI entry point for the RecoReco engine. Run by cron (four times a day from v1.0). Can be run by
+ * hand to test: ./cli recoreco:run
+ */
+class RecoRecoCommand extends BaseCommand
+{
+    protected function configure()
+    {
+        $this
+            ->setName('recoreco:run')
+            ->setDescription('Spawn RecoReco calendar-scheduled cards whose occurrence is due');
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $model = new RecoRecoModel($this->container);
+        $count = $model->run();
+
+        $output->writeln('RecoReco: spawned '.$count.' card(s).');
+
+        return 0;
+    }
+}

Controller/ConfigController.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Controller;
+
+use Kanboard\Controller\BaseController;
+use Kanboard\Plugin\RecoReco\Model\RecoRecoModel;
+
+/**
+ * Global settings page for RecoReco.
+ *
+ * Admin-only for free: the application ACL is keyed by the SHORT controller name, and core maps
+ * 'ConfigController' => APP_ADMIN (AuthenticationProvider::getApplicationAccessMap), so every action
+ * on a controller named ConfigController requires an application administrator -- plugin included.
+ * Keep admin-only actions in THIS controller; a differently-named controller would default to
+ * APP_USER (any logged-in user).
+ */
+class ConfigController extends BaseController
+{
+    public function show()
+    {
+        $this->response->html($this->helper->layout->config('recoReco:config/show', array(
+            'title' => t('Settings').' &gt; '.t('RecoReco'),
+        )));
+    }
+
+    /**
+     * Run the scheduler now -- the same pass cron runs: spawn every template card whose occurrence
+     * is due, across all boards. Idempotent (an occurrence is never spawned twice), so it is safe to
+     * trigger at any time.
+     */
+    public function run()
+    {
+        $this->checkCSRFForm();
+
+        $count = (new RecoRecoModel($this->container))->run();
+
+        $this->flash->success(t('RecoReco: spawned %d card(s).', $count));
+        $this->response->redirect($this->helper->url->to('ConfigController', 'show', array('plugin' => 'RecoReco')));
+    }
+}

Controller/RecurrenceController.php

@@ -0,0 +1,193 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Controller;
+
+use Kanboard\Controller\BaseController;
+use Kanboard\Model\TaskModel;
+
+/**
+ * The "Recurring schedule" modal: configure a card's calendar recurrence and store it in task
+ * metadata. The CLI engine (RecoRecoModel) does the actual spawning.
+ *
+ * Gate: a card can only be enabled when it has a due date (the recurrence anchor), is not already a
+ * native-recurring card (mutually exclusive), and the board has a column other than the card's own
+ * (the copy must land elsewhere).
+ */
+class RecurrenceController extends BaseController
+{
+    public function edit(array $values = array(), array $errors = array())
+    {
+        $task = $this->getTask();
+        $columns = $this->targetColumns($task);
+        $meta = $this->taskMetadataModel->getAll($task['id']);
+
+        // The "Follow FinanceBuddy installments" option only appears when FinanceBuddy is enabled on
+        // this board (installed but not enabled means no installment data to follow).
+        $fb_enabled = (int) $this->projectMetadataModel->get($task['project_id'], 'financebuddy_enabled', 0) === 1;
+
+        if (empty($values)) {
+            $values = $this->getStoredValues($meta, $task, $columns, $fb_enabled);
+        }
+
+        $this->response->html($this->template->render('recoReco:recurrence/edit', array(
+            'task' => $task,
+            'values' => $values,
+            'errors' => $errors,
+            'columns_list' => $columns,
+            'all_columns' => $this->columnModel->getList($task['project_id']),
+            'frequency_list' => $this->getFrequencyList(),
+            'has_due_date' => ! empty($task['date_due']),
+            'is_native' => $task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE,
+            'has_target' => ! empty($columns),
+            'is_clone' => isset($meta['recoreco_clone']) && $meta['recoreco_clone'] == 1,
+            'source_id' => isset($meta['recoreco_source']) ? (int) $meta['recoreco_source'] : 0,
+            'fb_enabled' => $fb_enabled,
+            'fb_current' => isset($meta['financebuddy_installment_current']) ? $meta['financebuddy_installment_current'] : '',
+            'fb_total' => isset($meta['financebuddy_installment_total']) ? $meta['financebuddy_installment_total'] : '',
+        )));
+    }
+
+    public function save()
+    {
+        $task = $this->getTask();
+        $input = $this->request->getValues();
+        $columns = $this->targetColumns($task);
+
+        // A clone can never be made recurring (that would recurse). Guard even though the modal
+        // hides the form for clones.
+        $is_clone = (int) $this->taskMetadataModel->get($task['id'], 'recoreco_clone', 0) === 1;
+
+        // Only a plain card (a due date, not native-recurring, not a clone, a valid target) may enable.
+        $can_recur = ! empty($task['date_due'])
+            && $task['recurrence_status'] == TaskModel::RECURRING_STATUS_NONE
+            && ! $is_clone
+            && ! empty($columns);
+        $enabled = ($can_recur && isset($input['recoreco_enabled']) && $input['recoreco_enabled'] == 1) ? 1 : 0;
+
+        $frequency = isset($input['recoreco_frequency']) && array_key_exists($input['recoreco_frequency'], $this->getFrequencyList())
+            ? $input['recoreco_frequency']
+            : 'monthly_day';
+
+        // Keep the lead time under one period (else a copy's fire time crosses the prior occurrence).
+        $daysBefore = isset($input['recoreco_days_before']) && ctype_digit((string) $input['recoreco_days_before']) ? (int) $input['recoreco_days_before'] : 0;
+        $daysBefore = min($daysBefore, $this->maxDaysBefore($frequency));
+
+        $values = array(
+            'recoreco_enabled' => $enabled,
+            'recoreco_target_column' => $this->resolveTarget(isset($input['recoreco_target_column']) ? $input['recoreco_target_column'] : 0, $columns),
+            'recoreco_frequency' => $frequency,
+            'recoreco_last_day' => isset($input['recoreco_last_day']) ? 1 : 0,
+            'recoreco_days_before' => $daysBefore,
+            'recoreco_link_copies' => isset($input['recoreco_link_copies']) ? 1 : 0,
+        );
+
+        // Capture the anchor (the due date at enable time) -- the drift-free pattern.
+        if ($enabled) {
+            $values['recoreco_anchor'] = (int) $task['date_due'];
+        }
+
+        // Finite-plan limit. When FinanceBuddy is enabled on the board and "Follow" is on, RecoReco
+        // reads its installment total/current live at run time -- so nothing is stored here and the
+        // standalone limit/counter are left untouched (the modal greys them). Otherwise store the
+        // standalone limit (blank/0 = forever) and the 1-based progress counter (seedable).
+        $fb_enabled = (int) $this->projectMetadataModel->get($task['project_id'], 'financebuddy_enabled', 0) === 1;
+        $follow = $fb_enabled && isset($input['recoreco_follow_finance']) && $input['recoreco_follow_finance'] == 1;
+        $values['recoreco_follow_finance'] = $follow ? 1 : 0;
+
+        if (! $follow) {
+            $values['recoreco_limit'] = (isset($input['recoreco_limit']) && ctype_digit((string) $input['recoreco_limit'])) ? (int) $input['recoreco_limit'] : 0;
+            $values['recoreco_count'] = (isset($input['recoreco_count']) && ctype_digit((string) $input['recoreco_count']) && (int) $input['recoreco_count'] >= 1) ? (int) $input['recoreco_count'] : 1;
+        }
+
+        // Trigger column + move-mode (v1.9).
+        $allColumns = $this->columnModel->getList($task['project_id']);
+        $trig = isset($input['recoreco_trigger_column']) ? (string) $input['recoreco_trigger_column'] : 'any';
+        $values['recoreco_trigger_column'] = ($trig !== 'any' && array_key_exists((int) $trig, $allColumns)) ? (int) $trig : 'any';
+        $values['recoreco_trigger_invert'] = isset($input['recoreco_trigger_invert']) ? 1 : 0;
+        $values['recoreco_move'] = isset($input['recoreco_move']) ? 1 : 0;
+        if ($values['recoreco_move'] === 1) {
+            $values['recoreco_follow_finance'] = 0; // Follow-FinanceBuddy is N/A in move-mode
+        }
+
+        $this->taskMetadataModel->save($task['id'], $values);
+
+        // Reconcile the template's duplicate links with the setting right away.
+        $model = new \Kanboard\Plugin\RecoReco\Model\RecoRecoModel($this->container);
+        $model->syncCloneLinks($task['id'], $values['recoreco_link_copies'] == 1);
+
+        $this->flash->success(t('Recurring schedule saved.'));
+
+        return $this->response->redirect($this->helper->url->to('TaskViewController', 'show', array('task_id' => $task['id'])), true);
+    }
+
+    // Target columns: ALL of the project's columns. This used to exclude the card's own column (a
+    // duplicate copy "must move"), but move-mode legitimately rests the card IN the target, so the
+    // target must be any column -- otherwise a moved card's own target vanishes from the dropdown and
+    // a re-save would silently reset it. `target != trigger` is enforced in the modal instead.
+    private function targetColumns(array $task)
+    {
+        return $this->columnModel->getList($task['project_id']);
+    }
+
+    // A stored/posted target, if still a valid non-current column; otherwise the first one (or 0).
+    private function resolveTarget($candidate, array $columns)
+    {
+        $candidate = (int) $candidate;
+
+        if (array_key_exists($candidate, $columns)) {
+            return $candidate;
+        }
+
+        $keys = array_keys($columns);
+
+        return empty($keys) ? 0 : (int) $keys[0];
+    }
+
+    private function getStoredValues(array $meta, array $task, array $columns, $fb_enabled)
+    {
+        return array(
+            'recoreco_enabled' => isset($meta['recoreco_enabled']) ? (int) $meta['recoreco_enabled'] : 0,
+            'recoreco_target_column' => $this->resolveTarget(isset($meta['recoreco_target_column']) ? $meta['recoreco_target_column'] : 0, $columns),
+            'recoreco_frequency' => isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : 'monthly_day',
+            'recoreco_last_day' => isset($meta['recoreco_last_day']) ? (int) $meta['recoreco_last_day'] : 0,
+            'recoreco_days_before' => isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0,
+            'recoreco_link_copies' => isset($meta['recoreco_link_copies']) ? (int) $meta['recoreco_link_copies'] : 0,
+            // Follow defaults ON for a fresh card on a FinanceBuddy board; otherwise the stored choice.
+            'recoreco_follow_finance' => isset($meta['recoreco_follow_finance']) ? (int) $meta['recoreco_follow_finance'] : ($fb_enabled ? 1 : 0),
+            'recoreco_limit' => isset($meta['recoreco_limit']) ? (int) $meta['recoreco_limit'] : 0,
+            'recoreco_count' => isset($meta['recoreco_count']) ? (int) $meta['recoreco_count'] : 1,
+            'recoreco_move' => isset($meta['recoreco_move']) ? (int) $meta['recoreco_move'] : 0,
+            'recoreco_trigger_column' => isset($meta['recoreco_trigger_column']) ? $meta['recoreco_trigger_column'] : 'any',
+            'recoreco_trigger_invert' => isset($meta['recoreco_trigger_invert']) ? (int) $meta['recoreco_trigger_invert'] : 0,
+        );
+    }
+
+    private function getFrequencyList()
+    {
+        return array(
+            'yearly' => t('Yearly'),
+            'monthly_day' => t('Monthly by day'),
+            'monthly_dow' => t('Monthly by weekday'),
+            'weekly' => t('Weekly'),
+            'daily' => t('Daily'),
+        );
+    }
+
+    /**
+     * The largest allowed "days before" for a frequency -- kept strictly under one period so a
+     * copy's fire time never crosses the previous occurrence. Daily = 0 (disabled).
+     */
+    private function maxDaysBefore($frequency)
+    {
+        switch ($frequency) {
+            case 'daily':
+                return 0;
+            case 'weekly':
+                return 6;
+            case 'yearly':
+                return 364;
+            default: // monthly_day, monthly_dow
+                return 27;
+        }
+    }
+}

Helper/RecoRecoHelper.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Helper;
+
+use Kanboard\Core\Base;
+use Kanboard\Model\TaskModel;
+
+/**
+ * Board helper: which RecoReco icon a card should show.
+ *
+ * Single-icon rule -- RecoReco only renders when the card is NOT native-recurring
+ * (recurrence_status == NONE), so native's icon and RecoReco's icon can never appear together.
+ */
+class RecoRecoHelper extends Base
+{
+    /**
+     * @param  array $task A board task row (has recurrence_status and id).
+     * @return string 'template', 'clone', or '' (no RecoReco icon).
+     */
+    public function iconType(array $task)
+    {
+        if ((int) $task['recurrence_status'] !== TaskModel::RECURRING_STATUS_NONE) {
+            return '';
+        }
+
+        $meta = $this->taskMetadataModel->getAll($task['id']);
+
+        if (isset($meta['recoreco_enabled']) && $meta['recoreco_enabled'] == 1) {
+            return 'template';
+        }
+
+        if (isset($meta['recoreco_clone']) && $meta['recoreco_clone'] == 1) {
+            return 'clone';
+        }
+
+        return '';
+    }
+}

Model/OccurrenceCalculator.php

@@ -0,0 +1,206 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Model;
+
+/**
+ * Pure calendar math for RecoReco.
+ *
+ * Given an anchor due date (the drift-free pattern: it carries the day-of-month, the weekday, and
+ * the time), a frequency, and the "last day" flag, it computes occurrence datetimes. It has NO
+ * container dependencies, so it is unit-testable in isolation (Test/OccurrenceCalculatorTest.php).
+ *
+ * Occurrences are always computed from the anchor, never by marching a clamped date forward, so a
+ * "30th" schedule goes 30, 28/29, 30, 30... and never drifts.
+ */
+class OccurrenceCalculator
+{
+    const MAX_MONTHS = 120;
+    const MAX_YEARS = 20;
+
+    /**
+     * The earliest occurrence at/after $reference (when $inclusive) or strictly after it.
+     *
+     * @param  int    $anchor     Unix timestamp: the pattern.
+     * @param  string $frequency  daily | weekly | monthly_day | monthly_dow | yearly
+     * @param  bool   $lastDay
+     * @param  int    $reference  Unix timestamp.
+     * @param  bool   $inclusive
+     * @return int|null           Occurrence timestamp, or null for an unknown frequency.
+     */
+    public function occurrenceFrom($anchor, $frequency, $lastDay, $reference, $inclusive = false)
+    {
+        $anchor = (int) $anchor;
+        $reference = (int) $reference;
+        $lastDay = (bool) $lastDay;
+        $inclusive = (bool) $inclusive;
+
+        switch ($frequency) {
+            case 'daily':
+                return $this->daily($anchor, $reference, $inclusive);
+            case 'weekly':
+                return $this->weekly($anchor, $reference, $inclusive);
+            case 'monthly_day':
+                return $this->monthlyByDay($anchor, $lastDay, $reference, $inclusive);
+            case 'monthly_dow':
+                return $this->monthlyByWeekday($anchor, $lastDay, $reference, $inclusive);
+            case 'yearly':
+                return $this->yearly($anchor, $lastDay, $reference, $inclusive);
+            default:
+                return null;
+        }
+    }
+
+    private function daily($anchor, $reference, $inclusive)
+    {
+        $h = (int) date('G', $anchor);
+        $i = (int) date('i', $anchor);
+        $s = (int) date('s', $anchor);
+        $y = (int) date('Y', $reference);
+        $m = (int) date('n', $reference);
+        $d = (int) date('j', $reference);
+
+        for ($k = 0; $k < 3; $k++) {
+            $o = mktime($h, $i, $s, $m, $d + $k, $y);
+
+            if ($this->matches($o, $reference, $inclusive)) {
+                return $o;
+            }
+        }
+
+        return null;
+    }
+
+    private function weekly($anchor, $reference, $inclusive)
+    {
+        $h = (int) date('G', $anchor);
+        $i = (int) date('i', $anchor);
+        $s = (int) date('s', $anchor);
+        $w = (int) date('w', $anchor);
+        $y = (int) date('Y', $reference);
+        $m = (int) date('n', $reference);
+        $d = (int) date('j', $reference);
+
+        for ($k = 0; $k < 8; $k++) {
+            $o = mktime($h, $i, $s, $m, $d + $k, $y);
+
+            if ((int) date('w', $o) === $w && $this->matches($o, $reference, $inclusive)) {
+                return $o;
+            }
+        }
+
+        return null;
+    }
+
+    private function monthlyByDay($anchor, $lastDay, $reference, $inclusive)
+    {
+        $anchorDay = (int) date('j', $anchor);
+        $h = (int) date('G', $anchor);
+        $i = (int) date('i', $anchor);
+        $s = (int) date('s', $anchor);
+
+        $y = (int) date('Y', $reference);
+        $m = (int) date('n', $reference);
+
+        for ($k = 0; $k < self::MAX_MONTHS; $k++) {
+            $lastDom = (int) date('t', mktime(0, 0, 0, $m, 1, $y));
+            $day = $lastDay ? $lastDom : min($anchorDay, $lastDom);
+            $o = mktime($h, $i, $s, $m, $day, $y);
+
+            if ($this->matches($o, $reference, $inclusive)) {
+                return $o;
+            }
+
+            $this->nextMonth($m, $y);
+        }
+
+        return null;
+    }
+
+    private function monthlyByWeekday($anchor, $lastDay, $reference, $inclusive)
+    {
+        $h = (int) date('G', $anchor);
+        $i = (int) date('i', $anchor);
+        $s = (int) date('s', $anchor);
+        $w = (int) date('w', $anchor);
+        $k = intdiv((int) date('j', $anchor) - 1, 7) + 1; // 1..5: which occurrence of $w in the month
+
+        $y = (int) date('Y', $reference);
+        $m = (int) date('n', $reference);
+
+        for ($j = 0; $j < self::MAX_MONTHS; $j++) {
+            $day = $lastDay ? $this->lastWeekdayOfMonth($y, $m, $w) : $this->nthWeekdayOfMonth($y, $m, $w, $k);
+
+            if ($day !== null) {
+                $o = mktime($h, $i, $s, $m, $day, $y);
+
+                if ($this->matches($o, $reference, $inclusive)) {
+                    return $o;
+                }
+            }
+
+            $this->nextMonth($m, $y);
+        }
+
+        return null;
+    }
+
+    private function yearly($anchor, $lastDay, $reference, $inclusive)
+    {
+        $month = (int) date('n', $anchor);
+        $anchorDay = (int) date('j', $anchor);
+        $h = (int) date('G', $anchor);
+        $i = (int) date('i', $anchor);
+        $s = (int) date('s', $anchor);
+
+        $y = (int) date('Y', $reference);
+
+        for ($j = 0; $j < self::MAX_YEARS; $j++) {
+            $lastDom = (int) date('t', mktime(0, 0, 0, $month, 1, $y));
+            $day = $lastDay ? $lastDom : min($anchorDay, $lastDom);
+            $o = mktime($h, $i, $s, $month, $day, $y);
+
+            if ($this->matches($o, $reference, $inclusive)) {
+                return $o;
+            }
+
+            $y++;
+        }
+
+        return null;
+    }
+
+    // The day-of-month of the k-th weekday $w in month $m/$y, or null if that month has no k-th one.
+    private function nthWeekdayOfMonth($y, $m, $w, $k)
+    {
+        $firstDow = (int) date('w', mktime(0, 0, 0, $m, 1, $y));
+        $firstW = 1 + (($w - $firstDow + 7) % 7);
+        $day = $firstW + ($k - 1) * 7;
+        $lastDom = (int) date('t', mktime(0, 0, 0, $m, 1, $y));
+
+        return $day <= $lastDom ? $day : null;
+    }
+
+    // The day-of-month of the last weekday $w in month $m/$y.
+    private function lastWeekdayOfMonth($y, $m, $w)
+    {
+        $lastDom = (int) date('t', mktime(0, 0, 0, $m, 1, $y));
+        $lastDow = (int) date('w', mktime(0, 0, 0, $m, $lastDom, $y));
+
+        return $lastDom - (($lastDow - $w + 7) % 7);
+    }
+
+    private function matches($occurrence, $reference, $inclusive)
+    {
+        return $inclusive ? $occurrence >= $reference : $occurrence > $reference;
+    }
+
+    private function nextMonth(&$m, &$y)
+    {
+        $m++;
+
+        if ($m > 12) {
+            $m = 1;
+            $y++;
+        }
+    }
+}

Model/RecoRecoModel.php

@@ -0,0 +1,426 @@
+<?php
+
+namespace Kanboard\Plugin\RecoReco\Model;
+
+use Kanboard\Core\Base;
+use Kanboard\Model\TaskModel;
+
+/**
+ * The RecoReco engine: find enabled templates and spawn their due occurrences.
+ *
+ * Called by the recoreco:run CLI command (from cron, or from the identical "Run now" button). One
+ * run is one pass over every enabled template; running it five times a day instead of four is
+ * harmless -- see the idempotency note below.
+ *
+ * Per template there is a SINGLE algorithm (no first-run vs catch-up split):
+ *
+ *   1. Yield to native recurrence if the card became native-recurring (decision 13).
+ *   2. Walk occurrences forward from the cursor (the template due date), collecting every one whose
+ *      fire time (occurrence - days_before) has arrived (before this run's horizon). The first
+ *      occurrence still ahead of the horizon is the "next future" one.
+ *   3. Cap to the most recent MAX_BACKFILL: if more than that are due (a template set far in the
+ *      past), skip the OLDEST overflow and keep the newest ones -- contiguous, no gap.
+ *   4. Spawn each kept occurrence into the target column, dated to that occurrence.
+ *   5. Park the cursor on the next future occurrence and stop.
+ *
+ * Idempotency: after a run the cursor sits on a future occurrence, so a second run the same day
+ * collects nothing. As a belt-and-suspenders guard against a run overlapping cron on the same
+ * occurrence, spawn() is skipped when a clone for that (template, due) already exists (cloneExists).
+ */
+class RecoRecoModel extends Base
+{
+    // Most recent occurrences to actually spawn in one run. A template set far in the past spawns
+    // these newest ones and skips the older overflow (no gap), rather than flooding the board.
+    const MAX_BACKFILL = 12;
+
+    // Safety bound on the occurrence walk so a misbehaving calculator can never loop forever
+    // (1200 monthly steps is a century).
+    const MAX_ITERATIONS = 1200;
+
+    private $calc;
+
+    public function run($now = null)
+    {
+        $now = $now ?: time();
+        $horizon = $this->horizon($now);
+        $spawned = 0;
+
+        $task_ids = $this->db->table('task_has_metadata')
+            ->eq('name', 'recoreco_enabled')
+            ->eq('value', '1')
+            ->findAllByColumn('task_id');
+
+        foreach ($task_ids as $task_id) {
+            $spawned += $this->processTemplate((int) $task_id, $now, $horizon);
+        }
+
+        return $spawned;
+    }
+
+    /**
+     * The look-ahead horizon for this run: fire everything whose fire time is before it. Computed as
+     * "ceil now to the next 6h boundary, then +12h", which lands on the four daily runs:
+     * 05:58 -> 18:00, 11:58 -> 00:00, 17:58 -> 06:00, 23:58 -> 12:00. Gives a 12h look-ahead with a
+     * 6h overlap between runs, so a missed run is covered by its neighbour. Past-due occurrences are
+     * naturally included (their fire time is < now < horizon) -- that is the back-fill.
+     *
+     * @param  int $now
+     * @return int
+     */
+    private function horizon($now)
+    {
+        $startOfDay = mktime(0, 0, 0, (int) date('n', $now), (int) date('j', $now), (int) date('Y', $now));
+        $boundaryHour = (intdiv((int) date('G', $now), 6) + 1) * 6;
+
+        return $startOfDay + $boundaryHour * 3600 + 12 * 3600;
+    }
+
+    public function processTemplate($task_id, $now, $horizon)
+    {
+        $task = $this->taskFinderModel->getById($task_id);
+
+        if (empty($task)) {
+            return 0;
+        }
+
+        // Native wins: if the card became native-recurring, RecoReco yields (decision 13). Leave a
+        // visible trail in the task's activity stream, attributed to the card's owner (creator_id has
+        // a FK to users, so a system id like 0 would make the insert fail silently -- no user 0).
+        if ($task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE) {
+            $this->taskMetadataModel->save($task_id, array('recoreco_enabled' => 0));
+            $this->logger->info('RecoReco: disabled on task '.$task_id.' (now native-recurring)');
+            $this->projectActivityModel->createEvent(
+                (int) $task['project_id'],
+                $task_id,
+                (int) $task['creator_id'],
+                'recoreco.task.disable',
+                array('task' => array('id' => $task_id, 'title' => $task['title']))
+            );
+            return 0;
+        }
+
+        $meta = $this->taskMetadataModel->getAll($task_id);
+        $frequency = isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : '';
+
+        // All five frequencies are supported since v1.1; skip anything unknown.
+        if (! in_array($frequency, array('daily', 'weekly', 'monthly_day', 'monthly_dow', 'yearly'), true)) {
+            return 0;
+        }
+
+        // The anchor defines the recurrence PATTERN (which day-of-month, which weekday ordinal); the
+        // cursor (the template due date) is our POSITION in that pattern.
+        $anchor = isset($meta['recoreco_anchor']) ? (int) $meta['recoreco_anchor'] : 0;
+
+        if ($anchor <= 0) {
+            return 0;
+        }
+
+        $lastDay = isset($meta['recoreco_last_day']) && $meta['recoreco_last_day'] == 1;
+        $daysBefore = isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0;
+        $targetColumn = isset($meta['recoreco_target_column']) ? (int) $meta['recoreco_target_column'] : (int) $task['column_id'];
+        // Default off: only keep the duplicate link when explicitly turned on.
+        $linkCopies = isset($meta['recoreco_link_copies']) && $meta['recoreco_link_copies'] == 1;
+
+        // Finite-plan stop. RecoReco caps its own recurrence, either by its own limit (standalone) or
+        // by following FinanceBuddy. When follow is on, FinanceBuddy governs: the plan is finite only
+        // if the card has a numeric installment total, so an ordinary recurring bill (money but no
+        // installments) recurs forever -- and any stale standalone limit is ignored. In follow mode
+        // the numbers are read LIVE from FinanceBuddy (never copied), so a mid-plan start, a
+        // re-purchase, or an extend all just work by editing FinanceBuddy. A blank/0 limit means
+        // recur forever. The spawn loop below stops when counter > limit (1-based; counter ends on
+        // limit+1).
+        $followIntent = isset($meta['recoreco_follow_finance']) && $meta['recoreco_follow_finance'] == 1;
+        $fbTotal = isset($meta['financebuddy_installment_total']) ? (string) $meta['financebuddy_installment_total'] : '';
+        $fbHasTotal = $fbTotal !== '' && ctype_digit($fbTotal);
+        $follow = $followIntent && $fbHasTotal;
+
+        if ($followIntent) {
+            $limit = $fbHasTotal ? (int) $fbTotal : 0; // following FinanceBuddy; no total => forever
+        } else {
+            $limitRaw = isset($meta['recoreco_limit']) ? (string) $meta['recoreco_limit'] : '';
+            $limit = ($limitRaw !== '' && ctype_digit($limitRaw)) ? (int) $limitRaw : 0;
+        }
+
+        // Standalone progress counter (1-based "next occurrence"). Unused in follow mode, where the
+        // counter is FinanceBuddy's live installment_current instead.
+        $count = isset($meta['recoreco_count']) && ctype_digit((string) $meta['recoreco_count']) ? (int) $meta['recoreco_count'] : 1;
+
+        // Trigger gate (cross-cutting, both modes): fire only while the card is in a triggering column,
+        // and never while it sits in the target (Gate 2, uniform).
+        $col = (int) $task['column_id'];
+        $trig = isset($meta['recoreco_trigger_column']) ? $meta['recoreco_trigger_column'] : 'any';
+        $invert = isset($meta['recoreco_trigger_invert']) && $meta['recoreco_trigger_invert'] == 1;
+        $base = ($trig === 'any') ? true : ($invert ? ($col !== (int) $trig) : ($col === (int) $trig));
+
+        if (! ($base && $col !== $targetColumn)) {
+            return 0;
+        }
+
+        // Move-mode: relocate the single card to the target instead of spawning a clone. No back-fill,
+        // no clone metadata. Honors the standalone limit (save() forced follow=0, so $limit is it).
+        if (isset($meta['recoreco_move']) && $meta['recoreco_move'] == 1) {
+            $cursor = (int) $task['date_due'];
+
+            if ($cursor - $daysBefore * 86400 >= $horizon) {
+                return 0; // not due yet
+            }
+
+            if ($limit > 0 && $count > $limit) {
+                $this->completePlan($task, $task_id); // safety: re-armed after completion
+                return 0;
+            }
+
+            $this->taskPositionModel->movePosition($task['project_id'], $task_id, $targetColumn, 1, $task['swimlane_id'], false);
+
+            $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);
+            if ($next !== null && $next > $cursor) {
+                $this->setDue($task_id, $next); // advance one period
+            }
+
+            if ($limit > 0) {
+                $count++;
+                $this->setCount($task_id, $count);
+                if ($count > $limit) {
+                    $this->completePlan($task, $task_id);
+                }
+            }
+
+            return 1;
+        }
+
+        // Phase 1 -- walk forward from the cursor, collecting every occurrence whose fire time has
+        // arrived. The loop exits on the first occurrence still ahead of the horizon, which is then
+        // the "next future" one to park on.
+        $cursor = (int) $task['date_due'];
+        $due = array();
+        $iterations = 0;
+
+        while ($cursor - $daysBefore * 86400 < $horizon && $iterations < self::MAX_ITERATIONS) {
+            $due[] = $cursor;
+
+            $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);
+
+            if ($next === null || $next <= $cursor) {
+                break; // calculator cannot advance -- stop rather than loop
+            }
+
+            $cursor = $next;
+            $iterations++;
+        }
+
+        $nextFuture = $cursor;
+
+        // Phase 2 -- cap to the most recent MAX_BACKFILL, skipping the oldest overflow (no gap).
+        $skip = max(0, count($due) - self::MAX_BACKFILL);
+        $toSpawn = array_slice($due, $skip);
+
+        // Phase 3 -- spawn each kept occurrence, dated to that occurrence. Idempotent: skip any that
+        // this template has already spawned (survives a run overlapping cron on the same occurrence).
+        // Two guards enforce the finite-plan limit: the leading one catches an already-complete plan
+        // (a re-enabled done template, or a back-fill overshoot); the trailing one disables the
+        // instant this run's spawn completes the plan.
+        $spawned = 0;
+        $completed = false;
+
+        foreach ($toSpawn as $occurrence) {
+            $counter = $follow ? $this->financeCurrent($task_id) : $count;
+
+            if ($limit > 0 && $counter > $limit) {
+                $completed = true;
+                break;
+            }
+
+            if ($this->cloneExists($task_id, $occurrence)) {
+                continue;
+            }
+
+            // duplicate() copies the template's date_due onto the clone, so set it to this occurrence
+            // first, then spawn. spawn() fires the hook that lets FinanceBuddy advance its installment.
+            $this->setDue($task_id, $occurrence);
+            $this->spawn($task, $targetColumn);
+            $spawned++;
+
+            // Standalone advances its own counter (only meaningful with a limit set); follow mode
+            // relies on FinanceBuddy having advanced its installment during spawn().
+            if (! $follow && $limit > 0) {
+                $count++;
+                $this->setCount($task_id, $count);
+            }
+
+            $counter = $follow ? $this->financeCurrent($task_id) : $count;
+
+            if ($limit > 0 && $counter > $limit) {
+                $completed = true;
+                break;
+            }
+        }
+
+        // Phase 4 -- park the cursor on the next future occurrence. When the plan just completed,
+        // disable the template (its p(total+1) tombstone is already in place) and log it.
+        $this->setDue($task_id, $nextFuture);
+
+        if ($completed) {
+            $this->completePlan($task, $task_id);
+        }
+
+        // Reconcile the duplicate links with the setting (removes both new and old ones when off).
+        $this->syncCloneLinks($task_id, $linkCopies);
+
+        return $spawned;
+    }
+
+    /**
+     * Has this template already spawned a clone for the given occurrence? A clone records its source
+     * template (recoreco_source) and carries the occurrence as its due date, so the pair identifies
+     * it. This makes a repeated or overlapping run idempotent -- an occurrence is never spawned twice.
+     *
+     * @param  int $template_id
+     * @param  int $due
+     * @return bool
+     */
+    private function cloneExists($template_id, $due)
+    {
+        $clone_ids = $this->db->table('task_has_metadata')
+            ->eq('name', 'recoreco_source')
+            ->eq('value', (string) $template_id)
+            ->findAllByColumn('task_id');
+
+        if (empty($clone_ids)) {
+            return false;
+        }
+
+        return $this->db->table(TaskModel::TABLE)
+            ->in('id', $clone_ids)
+            ->eq('date_due', $due)
+            ->exists();
+    }
+
+    /**
+     * Reconcile a template's "is a duplicate of" links with the link-copies setting. When off, remove
+     * the links to THIS template's own RecoReco clones (identified by recoreco_source, so manual
+     * links are left untouched). When on, do nothing -- new spawns already carry the link.
+     *
+     * @param int  $template_id
+     * @param bool $linkCopies
+     */
+    public function syncCloneLinks($template_id, $linkCopies)
+    {
+        if ($linkCopies) {
+            return;
+        }
+
+        foreach ($this->taskLinkModel->getAll($template_id) as $link) {
+            $opposite = (int) $link['task_id'];
+
+            if ((int) $this->taskMetadataModel->get($opposite, 'recoreco_source', 0) === (int) $template_id) {
+                $this->taskLinkModel->remove($link['id']);
+            }
+        }
+    }
+
+    private function setDue($task_id, $due)
+    {
+        // Move the template's due date directly (no task events fired). This is the cursor.
+        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due));
+    }
+
+    /**
+     * FinanceBuddy's live "next installment to spawn" for a task (1-based), read fresh because
+     * FinanceBuddy advances it on every spawn. Defaults to 1 when absent or non-numeric. RecoReco
+     * only reads this key -- it never writes FinanceBuddy metadata.
+     *
+     * @param  int $task_id
+     * @return int
+     */
+    private function financeCurrent($task_id)
+    {
+        $current = $this->taskMetadataModel->get($task_id, 'financebuddy_installment_current', 1);
+
+        return ctype_digit((string) $current) ? (int) $current : 1;
+    }
+
+    private function setCount($task_id, $count)
+    {
+        $this->taskMetadataModel->save($task_id, array('recoreco_count' => (int) $count));
+    }
+
+    /**
+     * A finite plan reached its limit: disable the template and record it in the activity stream,
+     * attributed to the card owner (creator_id has a FK to users, so a system id would fail silently).
+     *
+     * @param array $task
+     * @param int   $task_id
+     */
+    private function completePlan(array $task, $task_id)
+    {
+        $this->taskMetadataModel->save($task_id, array('recoreco_enabled' => 0));
+        $this->logger->info('RecoReco: plan complete on task '.$task_id.' (recurrence disabled)');
+        $this->projectActivityModel->createEvent(
+            (int) $task['project_id'],
+            $task_id,
+            (int) $task['creator_id'],
+            'recoreco.task.complete',
+            array('task' => array('id' => $task_id, 'title' => $task['title']))
+        );
+    }
+
+    private function spawn(array $template, $targetColumn)
+    {
+        // The template's date_due is already the occurrence (setDue), so duplicate() copies it onto
+        // the clone. duplicate() copies fields + tags + links + subtasks, but NO metadata, so the
+        // clone is not a template.
+        $newId = $this->taskDuplicationModel->duplicate($template['id']);
+
+        if ($newId === false) {
+            $this->logger->error('RecoReco: duplicate failed for task '.$template['id']);
+            return false;
+        }
+
+        // duplicate() lands the clone in the source column; move it to the chosen target (top).
+        if ($targetColumn > 0 && $targetColumn != $template['column_id']) {
+            $this->taskPositionModel->movePosition($template['project_id'], $newId, $targetColumn, 1, $template['swimlane_id']);
+        }
+
+        // Reset the "[DUPLICATE]" prefix back to the source title (no events).
+        $this->taskModificationModel->update(array('id' => $newId, 'title' => $template['title']), false);
+
+        // Kanboard's duplicate() adds an "is a duplicate of" task link between the template and the
+        // clone. It is reconciled with the recoreco_link_copies setting by syncCloneLinks() after
+        // the spawn loop (kept when on, removed when off).
+
+        // Mark the clone: white icon + cannot itself be made recurring; record its source template.
+        $this->taskMetadataModel->save($newId, array(
+            'recoreco_clone' => 1,
+            'recoreco_source' => $template['id'],
+        ));
+
+        // Signal FinanceBuddy (advance the installment). Harmless no-op if nothing listens.
+        $payload = array('source_task_id' => (int) $template['id'], 'new_task_id' => (int) $newId);
+        $this->hook->reference('recoreco:task:spawned', $payload);
+
+        // Record the spawn in the clone's activity stream, attributed to the template's owner
+        // (creator_id has a FK to users, so a system id like 0 would silently fail the insert).
+        $this->projectActivityModel->createEvent(
+            (int) $template['project_id'],
+            $newId,
+            (int) $template['creator_id'],
+            'recoreco.task.spawn',
+            array(
+                'task' => array('id' => $newId, 'title' => $template['title']),
+                'template_id' => (int) $template['id'],
+                'template_title' => $template['title'],
+            )
+        );
+
+        return $newId;
+    }
+
+    private function calculator()
+    {
+        if ($this->calc === null) {
+            $this->calc = new OccurrenceCalculator();
+        }
+
+        return $this->calc;
+    }
+}

Plugin.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Kanboard\Plugin\Skeleton;
+namespace Kanboard\Plugin\RecoReco;
 
 use Kanboard\Core\Plugin\Base;
 
@@ -8,28 +8,51 @@ class Plugin extends Base
 {
     public function initialize()
     {
-        // 1. Render a visible word at the top of every page (the demo output).
-        $this->template->hook->attach('template:layout:top', 'skeleton:layout/header');
+        // "Recurring schedule" entry in the task Actions sidebar, right after the basic actions
+        // (next to native "Edit recurrence"). Opens the RecoReco config modal.
+        $this->template->hook->attach('template:task:sidebar:after-basic-actions', 'recoReco:task/sidebar_action');
 
-        // 2. Load the plugin stylesheet (currently empty -- proves the CSS hook fires).
-        $this->hook->on('template:layout:css', array(
-            'template' => 'plugins/Skeleton/Asset/css/skeleton.css',
-        ));
-
-        // 3. Load the plugin script (currently empty -- proves the JS hook fires).
+        // Modal JS: keep "days before" within one period of the selected frequency.
         $this->hook->on('template:layout:js', array(
-            'template' => 'plugins/Skeleton/Asset/js/skeleton.js',
+            'template' => 'plugins/RecoReco/Asset/js/recoreco-modal.js',
         ));
+
+        // Board card icon: black on a recurring template, white (inverse) on a generated copy.
+        $this->template->hook->attach('template:board:task:icons', 'recoReco:board/task_icon');
+
+        // Global settings page (Settings -> RecoReco) with a manual "Run now" button that triggers
+        // the same scheduler pass as cron. Admin-only for free via the shared 'ConfigController' ACL.
+        $this->template->hook->attach('template:config:sidebar', 'recoReco:config/sidebar');
+
+        // Activity-stream entries. The feed renders each event via event/<name-with-underscores>, so
+        // map our two event names to the plugin templates (a spawn on the new card, and the yield to
+        // native recurrence on the template). createEvent() writes the rows directly from the model.
+        $this->template->setTemplateOverride('event/recoreco_task_spawn', 'recoReco:event/recoreco_task_spawn');
+        $this->template->setTemplateOverride('event/recoreco_task_disable', 'recoReco:event/recoreco_task_disable');
+        $this->template->setTemplateOverride('event/recoreco_task_complete', 'recoReco:event/recoreco_task_complete');
+
+        // The scheduling engine runs from the CLI (cron). Registered CLI-only so web requests do
+        // not build the console app.
+        if (php_sapi_name() === 'cli') {
+            $this->container['cli']->add(new \Kanboard\Plugin\RecoReco\Console\RecoRecoCommand($this->container));
+        }
+    }
+
+    public function getHelpers()
+    {
+        return array(
+            'Plugin\RecoReco\Helper' => array('RecoRecoHelper'),
+        );
     }
 
     public function getPluginName()
     {
-        return 'Skeleton';
+        return 'RecoReco';
     }
 
     public function getPluginDescription()
     {
-        return t('Reusable skeleton/template for building Kanboard plugins.');
+        return t('Calendar-scheduled recurring cards: a template card spawns a copy on a date (yearly, monthly, weekly, daily), driven by the card due date.');
     }
 
     public function getPluginAuthor()
@@ -39,12 +62,12 @@ class Plugin extends Base
 
     public function getPluginVersion()
     {
-        return '0.1.0';
+        return '1.9.4';
     }
 
     public function getPluginHomepage()
     {
-        return 'https://code.beco.cc/beco/kanboard-plugin-skeleton';
+        return 'https://code.beco.cc/beco/RecoReco';
     }
 
     public function getCompatibleVersion()

README.md

@@ -1,66 +1,131 @@
-# Skeleton -- a Kanboard plugin template
+# RecoReco -- calendar-scheduled recurring cards
 
-A minimal, working Kanboard plugin that you copy and rename as the starting point for a
-real plugin. By itself it does only one trivial thing: it renders the word "Skeleton" at
-the top of every page. It changes no data and runs no database migration.
+Kanboard's built-in recurrence is event-triggered (a card recurs when you move or close it).
+RecoReco adds **calendar-triggered** recurrence: a card fires on a date, on its own, via cron --
+made for bills, rent, and subscriptions.
 
-## What it demonstrates
+A card marked recurring **stays** as a template; on schedule, RecoReco spawns a plain
+(non-recurring) copy into a column you choose. The template advances to the next date; the copy
+keeps the fired date.
 
-- A complete `Plugin.php` registration class with all the metadata Kanboard shows in
-  Settings -> Plugins (name, description, author, version, homepage, compatible version).
-- A template hook (`template:layout:top`) that injects a template into the page.
-- Asset hooks (`template:layout:css` and `template:layout:js`) that load a stylesheet and
-  a script. They are empty for now but prove the injection path works -- handy when a real
-  plugin needs custom CSS or JS.
-- The standard plugin directory layout, with stub folders (`Controller/`, `Model/`,
-  `Schema/`, `Locale/`, `Test/`) ready to grow into.
+> **A note on card order.** Because the template keeps its identity (and its id) for the life of the
+> plan while its due date advances, the template ends up as the *oldest* id carrying the *latest*
+> date. The spawned copies, by contrast, are ordered naturally (older copy = older id = older date).
+> This is intentional: a stable, editable template that stays in place is worth more than making the
+> one generator card sort by date. Native Kanboard recurrence avoids the mismatch only by
+> reincarnating the card every cycle, which RecoReco deliberately does not do.
+
+RecoReco is opt-in per card and inert until you mark a card, so it needs no per-board setting. It
+leaves native recurrence untouched (the two are mutually exclusive per card).
+
+## The idea
+
+- **The due date is the anchor.** All timing (day, month, weekday, time) is read from the card's
+  due date -- there are no separate date inputs. A card without a due date cannot be made recurring.
+- **Frequencies:** yearly, monthly by day, monthly by weekday, weekly, daily.
+- **Last day of the month:** an explicit checkbox (honored only when the due date is the last day,
+  or the last such weekday, of its month).
+- **Lead time:** "create the copy N days before the due date", so the card shows up early enough
+  to act on; the copy is still due on the real day.
+
+## Scheduling (cron)
+
+The engine runs from the CLI command `recoreco:run`. Add it to cron **four times a day** -- at
+05:58, 11:58, 17:58 and 23:58:
+
+```
+58 5,11,17,23 * * * cd /path/to/kanboard && php cli recoreco:run >> /var/log/recoreco.log 2>&1
+```
+
+(Point the path at your install and run it as the user that owns Kanboard's data.) Each run looks
+ahead 12 hours; the runs overlap by 6 hours, so a single missed run is covered by the next one.
+
+Each run walks a template forward from its current due date and spawns **every** occurrence whose
+fire time has arrived -- so occurrences already in the past are backfilled, not skipped. To avoid
+flooding the board when a template was set far in the past, a single run spawns at most the **12
+most recent** due occurrences; any older overflow is skipped (contiguous, no gap) and the template
+advances straight to the next future occurrence. `days before` shifts a copy earlier within the
+lead. Runs are idempotent: an occurrence is never spawned twice, so running an extra time is safe.
+
+You can trigger the exact same pass by hand -- either on the CLI (`php cli recoreco:run`) or with
+the **Run now** button under **Settings -> RecoReco** (admin only). The button and cron do the
+identical thing.
+
+## Stopping a finite plan
+
+By default a recurring card recurs forever. To make it stop, give it a **limit** in the Recurring
+schedule dialog:
+
+- **Stop after N recurrences** -- a plain count; blank or 0 means recur forever. RecoReco keeps a
+  1-based progress counter and turns the recurrence off once it passes the limit.
+- **Follow FinanceBuddy installments** -- shown only on boards where FinanceBuddy is enabled (and on
+  by default there). RecoReco reads the card's installment total and current *live* from FinanceBuddy
+  (never copied) and stops after the last installment. Because the numbers are read fresh, editing
+  them in FinanceBuddy just works: start mid-plan (enter `222/420`), re-purchase (reset the current
+  installment), or extend (raise the total) -- no RecoReco bookkeeping to keep in sync.
+
+When a followed plan ends, the parked template is left one past the last installment (`p4/3` for a
+three-installment plan) as a visible "spent" marker, its recurrence off, with an activity-stream
+entry recording the completion.
+
+## Trigger column and move-mode
+
+Two options in the Recurring schedule dialog change *where* and *how* a card recurs:
+
+- **Trigger column.** By default (`Any`) a card fires wherever it sits. Set a **Trigger column** and
+  it only fires while parked there -- so a template spawns only from its "active" column, and moving
+  it elsewhere quietly pauses it. The **`any but selected`** checkbox inverts the choice (fire in
+  every column *except* the selected one, e.g. "any but Archive"). The **target column never
+  triggers**, in any mode -- this is what lets a moved card come to rest in the target without
+  re-firing. (One edge to know: a *duplicate* template dragged into its own target column no longer
+  spawns; previously it fired from any column. Templates normally sit elsewhere, so this rarely
+  bites.)
+- **Move instead of copy.** Tick **"Move the card instead of creating a copy"** and RecoReco
+  relocates the *one* card to the target column each period instead of spawning a clone -- made for a
+  recurring chore you don't want piling up copies. Pair it with a trigger column: e.g. trigger =
+  `Done`, target = `Todo` -- cron moves the card `Done -> Todo` when it's due; you do the task and
+  drag it back to `Done`; repeat. Move-mode honors the recurrence limit (stop after N moves) but not
+  the FinanceBuddy follow (there is no copy to advance an installment on). Moves are silent (no
+  "moved to column" notification each period).
+
+## Status
+
+All five frequencies work (yearly, monthly by day, monthly by weekday, weekly, daily) with the
+last-day rule, board recurrence icons, backfill with the 12-occurrence cap, the Run-now button, a
+recurrence limit (standalone or following FinanceBuddy installments), the FinanceBuddy installment
+hand-off, a per-card trigger column, and move-mode (relocate instead of copy).
 
 ## Requirements
 
 - Kanboard >= 1.2.0
+- cron (to run `recoreco:run`)
 
 ## Installation
 
-No build step and no dependencies.
-
-1. Copy this folder into your Kanboard installation as `plugins/Skeleton/`.
-2. Reload any page. The word "Skeleton" appears at the top.
-3. Confirm it under Settings -> Plugins.
-
-To uninstall, delete `plugins/Skeleton/`. Nothing else is left behind.
-
-## Directory layout
-
-```
-Skeleton/
-  Plugin.php              Registration and hook wiring (the only required file).
-  README.md
-  LICENSE                 AGPL-3.0.
-  Template/
-    layout/header.php     The visible "Skeleton" word.
-  Asset/
-    css/skeleton.css      Loaded via template:layout:css.
-    js/skeleton.js        Loaded via template:layout:js.
-  Controller/             Stub for future request handlers.
-  Model/                  Stub for future business logic / DB access.
-  Schema/                 Stub for future database migrations.
-  Locale/                 Stub for future translations (e.g. pt_BR/, fr_FR/).
-  Test/                   Stub for future unit tests.
-```
-
-## How to fork this into a new plugin
-
-1. Copy the folder and rename it, e.g. `plugins/MyPlugin/`. The folder name must match the
-   namespace and start with a capital letter.
-2. In `Plugin.php`, change the namespace from `Kanboard\Plugin\Skeleton` to
-   `Kanboard\Plugin\MyPlugin`.
-3. Update the metadata methods (`getPluginName`, `getPluginDescription`, `getPluginAuthor`,
-   `getPluginVersion`, `getPluginHomepage`, `getCompatibleVersion`).
-4. Update the hook target paths: the lowercase prefix in `'skeleton:layout/header'` and the
-   `plugins/Skeleton/Asset/...` asset paths must match the new plugin name.
-5. Replace `Template/layout/header.php` with your real template, or attach to a different
-   hook. See the Kanboard plugin hooks documentation for the full list of hook points.
+Copy this folder into your Kanboard installation as `plugins/RecoReco/`. The directory name must be
+exactly `RecoReco` (Kanboard derives the plugin namespace from the folder name). No build step and
+no database migration. Then add the cron entry above.
 
 ## License
 
 AGPL-3.0. See LICENSE.
+
+## More Kanboard plugins by Dr. Beco
+
+All free and AGPL-3.0, at [code.beco.cc](https://code.beco.cc/beco):
+
+- **[FinanceBuddy](https://code.beco.cc/beco/FinanceBuddy)** -- attach a money value (debit/credit
+  and installments) to cards, shown on the card and totalled per column.
+- **[QualKard](https://code.beco.cc/beco/QualKard)** -- flashcard spaced repetition: grade a card by
+  dragging it to a column, and it comes back when due (needs RecoReco).
+- **[WorkspaceOrg](https://code.beco.cc/beco/WorkspaceOrg)** -- group your projects into personal
+  per-user workspaces, shown on a "My workspaces" dashboard page with a badge on each project.
+- **[OrganonTweaks](https://code.beco.cc/beco/OrganonTweaks)** -- an umbrella of small
+  quality-of-life board tweaks: remove an empty column, always show the comment icon, emphasize due
+  dates, extra search keywords and shared board filters, and more.
+- **[BulkMoveTasks](https://code.beco.cc/beco/BulkMoveTasks)** -- move every task from one board
+  column to another in a single action.
+- **[ShrinkVertically](https://code.beco.cc/beco/ShrinkVertically)** -- shrink vertically-collapsed
+  board columns so the horizontal scrollbar stays within reach.
+- **[TweakDrag](https://code.beco.cc/beco/TweakDrag)** -- board drag and touch niceties:
+  drag-to-scroll, a wider column gap, and smoother card dragging.

Template/board/task_icon.php

@@ -0,0 +1,14 @@
+<?php $type = $this->RecoRecoHelper->iconType($task) ?>
+<?php /* Calendar glyph (RecoReco is calendar recurrence), coloured by role so the template and its
+         copies are distinct at a glance, and distinct from Kanboard's native refresh recurrence icon:
+         dark blue = the recurring template (original), orange/dark-yellow = a generated copy.
+         Inline colour is CSP-safe (style-src allows 'unsafe-inline'); no stylesheet needed. */ ?>
+<?php if ($type === 'template'): ?>
+    <span title="<?= t('RecoReco: recurring template') ?>">
+        <i class="fa fa-calendar" style="color: #1f4e99;" role="img" aria-label="<?= t('RecoReco: recurring template') ?>"></i>
+    </span>
+<?php elseif ($type === 'clone'): ?>
+    <span title="<?= t('RecoReco: generated copy') ?>">
+        <i class="fa fa-calendar" style="color: #e08e0b;" role="img" aria-label="<?= t('RecoReco: generated copy') ?>"></i>
+    </span>
+<?php endif ?>

Template/config/show.php

@@ -0,0 +1,14 @@
+<div class="page-header">
+    <h2><?= t('RecoReco') ?></h2>
+</div>
+
+<p class="form-help">
+    <?= t('Run the recurring-card scheduler now. This spawns every template card whose occurrence is due, on all boards -- the same pass the cron job runs. It is safe to run at any time: an occurrence is never spawned twice.') ?>
+</p>
+
+<form method="post" action="<?= $this->url->href('ConfigController', 'run', array('plugin' => 'RecoReco')) ?>">
+    <?= $this->form->csrf() ?>
+    <div class="form-actions">
+        <button type="submit" class="btn btn-blue"><?= t('Run now') ?></button>
+    </div>
+</form>

Template/config/sidebar.php

@@ -0,0 +1,3 @@
+<li <?= $this->app->checkMenuSelection('ConfigController', 'show', 'RecoReco') ?>>
+    <?= $this->url->link(t('RecoReco'), 'ConfigController', 'show', array('plugin' => 'RecoReco')) ?>
+</li>

Template/event/recoreco_task_complete.php

@@ -0,0 +1,9 @@
+<p class="activity-title">
+    <?= e('RecoReco finished the recurrence plan on %s and turned recurrence off',
+            $this->url->link(t('#%d', $task['id']), 'TaskViewController', 'show', array('task_id' => $task['id']))
+        ) ?>
+    <small class="activity-date"><?= $this->dt->datetime($date_creation) ?></small>
+</p>
+<div class="activity-description">
+    <p class="activity-task-title"><?= $this->text->e($task['title']) ?></p>
+</div>

Template/event/recoreco_task_disable.php

@@ -0,0 +1,9 @@
+<p class="activity-title">
+    <?= e('RecoReco disabled recurrence on %s -- the card now uses Kanboard built-in recurrence',
+            $this->url->link(t('#%d', $task['id']), 'TaskViewController', 'show', array('task_id' => $task['id']))
+        ) ?>
+    <small class="activity-date"><?= $this->dt->datetime($date_creation) ?></small>
+</p>
+<div class="activity-description">
+    <p class="activity-task-title"><?= $this->text->e($task['title']) ?></p>
+</div>

Template/event/recoreco_task_spawn.php

@@ -0,0 +1,10 @@
+<p class="activity-title">
+    <?= e('RecoReco created %s from the recurring template %s',
+            $this->url->link(t('#%d', $task['id']), 'TaskViewController', 'show', array('task_id' => $task['id'])),
+            $this->url->link($this->text->e($template_title), 'TaskViewController', 'show', array('task_id' => $template_id))
+        ) ?>
+    <small class="activity-date"><?= $this->dt->datetime($date_creation) ?></small>
+</p>
+<div class="activity-description">
+    <p class="activity-task-title"><?= $this->text->e($task['title']) ?></p>
+</div>

Template/layout/header.php

@@ -1 +0,0 @@
-<div class="skeleton-plugin-marker">Skeleton</div>

Template/recurrence/edit.php

@@ -0,0 +1,106 @@
+<div class="page-header">
+    <h2>
+        <?= t('Recurring schedule') ?>
+        <?php if ($has_due_date): ?>
+            <small>(<?= $this->url->link(date('Y-m-d H:i', $task['date_due']), 'TaskModificationController', 'edit', array('task_id' => $task['id']), false, 'js-modal-large') ?>)</small>
+        <?php else: ?>
+            <small>-- <?= $this->url->link(t('set a due date'), 'TaskModificationController', 'edit', array('task_id' => $task['id']), false, 'js-modal-large') ?></small>
+        <?php endif ?>
+    </h2>
+</div>
+
+<?php if ($is_clone): ?>
+
+    <p class="alert alert-info">
+        <?= t('This card is a copy generated by RecoReco, so it cannot itself be made recurring.') ?>
+        <?php if ($source_id): ?>
+            <?= $this->url->link(t('Open the recurring template'), 'TaskViewController', 'show', array('task_id' => $source_id)) ?>
+        <?php endif ?>
+    </p>
+
+<?php else: ?>
+
+    <?php $can_recur = $has_due_date && ! $is_native && $has_target ?>
+
+    <?php if (! $has_due_date): ?>
+        <p class="alert alert-info"><?= t('Please set a due date first. RecoReco uses the card due date as the recurrence anchor.') ?></p>
+    <?php elseif ($is_native): ?>
+        <p class="alert alert-info">
+            <?= t('This card uses Kanboard built-in recurrence.') ?>
+            <?= $this->url->link(t('Edit built-in recurrence'), 'TaskRecurrenceController', 'edit', array('task_id' => $task['id']), false, 'js-modal-medium') ?>
+        </p>
+    <?php elseif (! $has_target): ?>
+        <p class="alert alert-info"><?= t('Add a target column first.') ?></p>
+    <?php endif ?>
+
+    <form method="post" action="<?= $this->url->href('RecurrenceController', 'save', array('plugin' => 'RecoReco', 'task_id' => $task['id'])) ?>" autocomplete="off" data-recoreco-current="<?= (int) $task['column_id'] ?>">
+        <?= $this->form->csrf() ?>
+
+        <?= $this->form->label(t('Make recurring'), 'recoreco_enabled') ?>
+        <div class="recoreco-radios">
+            <label style="display:inline-block; margin-right:16px;">
+                <input type="radio" name="recoreco_enabled" value="0" <?= $values['recoreco_enabled'] == 1 ? '' : 'checked="checked"' ?>> <?= t('No') ?>
+            </label>
+            <label style="display:inline-block; margin-right:16px;">
+                <input type="radio" name="recoreco_enabled" value="1" <?= $values['recoreco_enabled'] == 1 ? 'checked="checked"' : '' ?> <?= $can_recur ? '' : 'disabled="disabled"' ?>> <?= t('Yes') ?>
+            </label>
+        </div>
+
+        <?= $this->form->label(t('Target column'), 'recoreco_target_column') ?>
+        <?= $this->form->select('recoreco_target_column', $columns_list, $values) ?>
+
+        <?= $this->form->label(t('Trigger column'), 'recoreco_trigger_column') ?>
+        <div class="recoreco-trigger" style="display:flex; align-items:center; gap:8px;">
+            <?= $this->form->select('recoreco_trigger_column', array('any' => t('Any')) + $all_columns, $values) ?>
+            <label style="white-space:nowrap;">
+                <input type="checkbox" name="recoreco_trigger_invert" value="1" <?= $values['recoreco_trigger_invert'] == 1 ? 'checked="checked"' : '' ?>> <?= t('any but selected') ?>
+            </label>
+        </div>
+        <p class="form-help"><?= t('Recurrence fires only while the card sits in a triggering column; the target column never triggers.') ?></p>
+
+        <?= $this->form->checkbox('recoreco_move', t('Move the card instead of creating a copy'), 1, $values['recoreco_move'] == 1) ?>
+        <p class="form-help"><?= t('Relocate this one card to the target column each period instead of spawning a copy.') ?></p>
+
+        <?= $this->form->label(t('Frequency'), 'recoreco_frequency') ?>
+        <?= $this->form->select('recoreco_frequency', $frequency_list, $values) ?>
+
+        <div class="recoreco-lastday">
+            <?= $this->form->checkbox('recoreco_last_day', t('Fires on last day/weekday of the month'), 1, $values['recoreco_last_day'] == 1) ?>
+        </div>
+
+        <?= $this->form->label(t('Create the copy this many days before the due date'), 'recoreco_days_before') ?>
+        <input type="number" name="recoreco_days_before" min="0" value="<?= $this->text->e($values['recoreco_days_before']) ?>">
+
+        <?= $this->form->checkbox('recoreco_link_copies', t('Link copies to the template'), 1, $values['recoreco_link_copies'] == 1) ?>
+        <p class="form-help"><?= t('Links each copy back to the template (a count and quick navigation). Off by default.') ?></p>
+
+        <?php $following = $fb_enabled && $values['recoreco_follow_finance'] == 1 ?>
+        <?php $limit_display = (int) $values['recoreco_limit'] > 0 ? (int) $values['recoreco_limit'] : '' ?>
+        <div class="recoreco-limit-group"
+             data-fb-current="<?= $this->text->e($fb_current) ?>"
+             data-fb-total="<?= $this->text->e($fb_total) ?>"
+             data-rr-count="<?= (int) $values['recoreco_count'] ?>"
+             data-rr-limit="<?= $this->text->e($limit_display) ?>">
+
+            <?php if ($fb_enabled): ?>
+                <?= $this->form->checkbox('recoreco_follow_finance', t('Follow FinanceBuddy installments'), 1, $following) ?>
+                <p class="form-help"><?= t('Stop recurring when the installment plan ends, following the card total and current installment.') ?></p>
+            <?php endif ?>
+
+            <?= $this->form->label(t('Recurrence'), 'recoreco_count') ?>
+            <div class="recoreco-limit-inline" style="display:flex; align-items:center; gap:6px;">
+                <input type="number" name="recoreco_count" min="1" style="width:5em;"
+                       value="<?= $this->text->e($following ? $fb_current : $values['recoreco_count']) ?>"
+                       <?= $following ? 'disabled="disabled"' : '' ?>>
+                <span><?= t('of') ?></span>
+                <input type="number" name="recoreco_limit" min="1" style="width:5em;"
+                       value="<?= $this->text->e($following ? $fb_total : $limit_display) ?>"
+                       <?= $following ? 'disabled="disabled"' : '' ?>>
+            </div>
+            <p class="form-help"><?= t('Current recurrence and how many to run. Leave the second box empty to recur forever.') ?></p>
+        </div>
+
+        <?= $this->modal->submitButtons() ?>
+    </form>
+
+<?php endif ?>

Template/task/sidebar_action.php

@@ -0,0 +1,3 @@
+<li>
+    <?= $this->modal->medium('calendar', t('Recurring schedule'), 'RecurrenceController', 'edit', array('plugin' => 'RecoReco', 'task_id' => $task['id'])) ?>
+</li>

Test/OccurrenceCalculatorTest.php

@@ -0,0 +1,165 @@
+<?php
+
+/*
+ * Standalone test for the RecoReco date math -- no Kanboard / PHPUnit harness needed.
+ * Run with:  php Test/OccurrenceCalculatorTest.php
+ *
+ * OccurrenceCalculator is pure, so this exercises the highest-risk correctness surface (month
+ * lengths, leap years, the last-day rule, the drift-free clamp).
+ */
+
+require __DIR__.'/../Model/OccurrenceCalculator.php';
+
+use Kanboard\Plugin\RecoReco\Model\OccurrenceCalculator;
+
+date_default_timezone_set('UTC');
+
+$calc = new OccurrenceCalculator();
+$failures = 0;
+
+function ts($str)
+{
+    return strtotime($str.' UTC');
+}
+
+function check($label, $got, $expected, &$failures)
+{
+    $ok = $got === $expected;
+    $g = $got === null ? 'null' : date('Y-m-d H:i', $got);
+    $e = $expected === null ? 'null' : date('Y-m-d H:i', $expected);
+    echo ($ok ? 'PASS' : 'FAIL').'  '.$label.'  got='.$g.'  expected='.$e."\n";
+    if (! $ok) {
+        $failures++;
+    }
+}
+
+// 1. Plain day-of-month: the 15th, every month.
+check(
+    'monthly 15th, next after Jan 20',
+    $calc->occurrenceFrom(ts('2023-01-15 10:30'), 'monthly_day', false, ts('2023-01-20 00:00'), false),
+    ts('2023-02-15 10:30'),
+    $failures
+);
+
+// 2. Drift-free clamp: the 30th -> Feb clamps to 28 -> back to 30 in March (NOT 28).
+check(
+    '30th -> Feb (non-leap) clamps to 28',
+    $calc->occurrenceFrom(ts('2023-01-30 09:00'), 'monthly_day', false, ts('2023-01-30 09:00'), false),
+    ts('2023-02-28 09:00'),
+    $failures
+);
+check(
+    '30th -> March returns to 30 (no drift)',
+    $calc->occurrenceFrom(ts('2023-01-30 09:00'), 'monthly_day', false, ts('2023-02-28 09:00'), false),
+    ts('2023-03-30 09:00'),
+    $failures
+);
+
+// 3. Last-day rule: last day of each month.
+check(
+    'last-day: Jan 31 -> Feb 28 (non-leap)',
+    $calc->occurrenceFrom(ts('2023-01-31 08:00'), 'monthly_day', true, ts('2023-01-31 08:00'), false),
+    ts('2023-02-28 08:00'),
+    $failures
+);
+check(
+    'last-day: Feb -> March 31',
+    $calc->occurrenceFrom(ts('2023-01-31 08:00'), 'monthly_day', true, ts('2023-02-28 08:00'), false),
+    ts('2023-03-31 08:00'),
+    $failures
+);
+
+// 4. Leap year: last day of Feb 2024 is the 29th.
+check(
+    'last-day: Feb 2024 -> 29th (leap)',
+    $calc->occurrenceFrom(ts('2024-01-31 08:00'), 'monthly_day', true, ts('2024-02-01 00:00'), false),
+    ts('2024-02-29 08:00'),
+    $failures
+);
+
+// 5. Inclusive vs exclusive at an exact occurrence.
+check(
+    'inclusive returns the same instant',
+    $calc->occurrenceFrom(ts('2023-03-10 12:00'), 'monthly_day', false, ts('2023-03-10 12:00'), true),
+    ts('2023-03-10 12:00'),
+    $failures
+);
+check(
+    'exclusive skips to next month',
+    $calc->occurrenceFrom(ts('2023-03-10 12:00'), 'monthly_day', false, ts('2023-03-10 12:00'), false),
+    ts('2023-04-10 12:00'),
+    $failures
+);
+
+// 6. Daily: same time every day.
+check(
+    'daily -> next day same time',
+    $calc->occurrenceFrom(ts('2023-03-10 09:30'), 'daily', false, ts('2023-03-10 12:00'), false),
+    ts('2023-03-11 09:30'),
+    $failures
+);
+
+// 7. Weekly: same weekday every 7 days (2023-03-07 is a Tuesday).
+check(
+    'weekly -> +7 days on the same weekday',
+    $calc->occurrenceFrom(ts('2023-03-07 08:00'), 'weekly', false, ts('2023-03-07 08:00'), false),
+    ts('2023-03-14 08:00'),
+    $failures
+);
+
+// 8. Monthly by weekday: 2nd Tuesday (2023-03-14) -> 2nd Tuesday of April (2023-04-11).
+check(
+    'monthly-by-weekday: 2nd Tuesday -> next month 2nd Tuesday',
+    $calc->occurrenceFrom(ts('2023-03-14 07:00'), 'monthly_dow', false, ts('2023-03-14 07:00'), false),
+    ts('2023-04-11 07:00'),
+    $failures
+);
+
+// 9. Monthly by weekday, last: last Tuesday of March (2023-03-28) -> last Tuesday of April (04-25).
+check(
+    'monthly-by-weekday last: last Tue -> next month last Tue',
+    $calc->occurrenceFrom(ts('2023-03-28 07:00'), 'monthly_dow', true, ts('2023-03-28 07:00'), false),
+    ts('2023-04-25 07:00'),
+    $failures
+);
+
+// 10. Yearly: same month/day next year.
+check(
+    'yearly -> next year same date',
+    $calc->occurrenceFrom(ts('2023-03-15 10:00'), 'yearly', false, ts('2023-03-15 10:00'), false),
+    ts('2024-03-15 10:00'),
+    $failures
+);
+
+// 11. Yearly last-day on Feb 29 (leap) -> next year Feb 28.
+check(
+    'yearly last-day: 2024-02-29 -> 2025-02-28',
+    $calc->occurrenceFrom(ts('2024-02-29 08:00'), 'yearly', true, ts('2024-02-29 08:00'), false),
+    ts('2025-02-28 08:00'),
+    $failures
+);
+
+// 12. Yearly numeric Feb 29 -> clamps to 28 in a non-leap year, back to 29 in the next leap year.
+check(
+    'yearly numeric 29-Feb -> 2025 clamps to 28',
+    $calc->occurrenceFrom(ts('2024-02-29 08:00'), 'yearly', false, ts('2024-02-29 08:00'), false),
+    ts('2025-02-28 08:00'),
+    $failures
+);
+check(
+    'yearly numeric 29-Feb -> 2028 back to 29 (leap)',
+    $calc->occurrenceFrom(ts('2024-02-29 08:00'), 'yearly', false, ts('2027-03-01 00:00'), false),
+    ts('2028-02-29 08:00'),
+    $failures
+);
+
+// 13. Unknown frequency returns null.
+check(
+    'unknown frequency -> null',
+    $calc->occurrenceFrom(ts('2023-03-10 12:00'), 'nope', false, ts('2023-03-10 12:00'), false),
+    null,
+    $failures
+);
+
+echo "\n".($failures === 0 ? 'ALL PASSED' : $failures.' FAILURE(S)')."\n";
+exit($failures === 0 ? 0 : 1);

VERSION

@@ -1 +1 @@
-RecoReco v0.1
+RecoReco v1.9.4