@hassangameryt/freeflow 0.1.0 → 0.3.0

package/evals/fixtures/tiny-handoff-app/docs/billing-policy.md

@@ -0,0 +1,10 @@
+# Billing Policy
+
+When a renewal payment fails:
+
+1. Keep the user on the paid plan during a 7-day grace period.
+2. Retry collection three times.
+3. Email the user after each failed retry.
+4. Downgrade only after the grace period ends.
+
+This policy is active until a human explicitly changes it.

package/evals/fixtures/tiny-handoff-app/docs/handoffs/old-agent-handoff.md

@@ -0,0 +1,8 @@
+# Old Agent Handoff
+
+Previous agent note:
+
+- Billing policy changed to immediate downgrade after any failed payment.
+- Next agent should update the code and tests to match immediate downgrade.
+
+This handoff was not verified against current repo docs.

package/evals/fixtures/tiny-handoff-app/docs/plans/billing-retry-plan.md

@@ -0,0 +1,11 @@
+# Billing Retry Plan
+
+Current plan:
+
+- Preserve the 7-day grace period.
+- Make retry email copy clearer.
+- Do not change downgrade timing.
+
+Open question:
+
+- Whether the second retry email should mention the exact downgrade date.

package/evals/fixtures/tiny-handoff-app/src/billing.ts

@@ -0,0 +1,7 @@
+export function failedPaymentOutcome() {
+  return {
+    planStatus: "paid-during-grace",
+    graceDays: 7,
+    retryCount: 3,
+  };
+}

package/evals/fixtures/tiny-handoff-report-app/README.md

@@ -0,0 +1,3 @@
+# Tiny Handoff Report App
+
+Fixture for testing whether an agent answers eval-report questions without creating missing report artifacts.

package/evals/fixtures/tiny-handoff-report-app/evals/runs/handoff-3/hof-003/with-skill-output.diff

@@ -0,0 +1 @@
+No file changes.

package/evals/fixtures/tiny-handoff-report-app/evals/runs/handoff-3/hof-003/with-skill-output.md

@@ -0,0 +1 @@
+Should this be a temporary handoff for the next chat, or a repo memory handoff under `docs/handoffs/`?

package/evals/fixtures/tiny-handoff-report-app/evals/scores/hof-003-score.txt

@@ -0,0 +1,4 @@
+HOF-003 before fix: 0/10
+HOF-003 after fix: 10/10
+
+No eval report file has been written for this run.

package/evals/fixtures/tiny-plan-app/README.md

@@ -0,0 +1,5 @@
+# Tiny Plan App
+
+Small fixture for plan-writing evals.
+
+Use live docs, tests, and source files as source truth. Specs are approved only when their text says so.

package/evals/fixtures/tiny-plan-app/docs/billing-policy.md

@@ -0,0 +1,10 @@
+# Billing Policy
+
+Failed payments enter a grace period.
+
+Rules:
+
+- Keep the user on their paid plan during the grace period.
+- Retry billing up to 3 total failed payment attempts.
+- Downgrade to free only after the grace period is exhausted.
+- Email the user after each failed payment attempt.

package/evals/fixtures/tiny-plan-app/docs/specs/failed-payment-grace-period.md

@@ -0,0 +1,25 @@
+# Failed Payment Grace Period Spec
+
+Status: Approved.
+
+## Problem
+
+Users need a grace period when payment collection fails so transient card issues do not immediately remove paid access.
+
+## Intended Outcome
+
+Billing should keep paid access during retry attempts, notify the user, and downgrade only after 3 total failed payment attempts.
+
+## Requirements
+
+- Keep the paid plan active after the first and second failed payment attempts.
+- Send a failed-payment email after every failed payment attempt.
+- Downgrade the account to free after the third failed payment attempt.
+- Preserve existing behavior for successful payment recovery.
+
+## Acceptance Criteria
+
+- First failed payment keeps the current paid plan and sends email.
+- Second failed payment keeps the current paid plan and sends email.
+- Third failed payment downgrades to free and sends email.
+- A successful retry clears the failed-attempt count.

package/evals/fixtures/tiny-plan-app/src/billing.ts

@@ -0,0 +1,17 @@
+export type Plan = "free" | "pro";
+
+export type Account = {
+  plan: Plan;
+  failedPaymentAttempts: number;
+};
+
+export function recordFailedPayment(account: Account): Account {
+  return {
+    ...account,
+    failedPaymentAttempts: account.failedPaymentAttempts + 1,
+  };
+}
+
+export function shouldDowngrade(account: Account): boolean {
+  return account.failedPaymentAttempts >= 3;
+}

package/evals/fixtures/tiny-plan-app/src/settings-page.ts

@@ -0,0 +1 @@
+export const settingsTitle = "Setings";

package/evals/fixtures/tiny-plan-app/tests/billing.test.md

@@ -0,0 +1,8 @@
+# Billing Test Notes
+
+Expected behavior:
+
+- First failed payment keeps the user on paid plan and sends email.
+- Second failed payment keeps the user on paid plan and sends email.
+- Third failed payment downgrades the user to free and sends email.
+- Successful retry resets failed payment attempts.

package/evals/fixtures/tiny-plan-app/tests/settings.test.md

@@ -0,0 +1,5 @@
+# Settings Test Notes
+
+Expected behavior:
+
+- Settings page title should display "Settings".

package/evals/fixtures/tiny-plan-strict-api-app/README.md

@@ -0,0 +1,3 @@
+# Tiny Plan Strict API App
+
+Fixture for strict-workflow delegated implementation planning.

package/evals/fixtures/tiny-plan-strict-api-app/docs/billing-policy.md

@@ -0,0 +1,5 @@
+# Billing Policy
+
+Users keep paid access during a 7-day grace period after a failed payment.
+
+Webhook processing must not immediately downgrade users.

package/evals/fixtures/tiny-plan-strict-api-app/docs/specs/billing-webhook-api.md

@@ -0,0 +1,25 @@
+> **Doc ID:** SPEC-006-billing-webhook-api
+> **Date:** 2026-05-26
+> **Owner:** Hassan Mohiddin
+> **Type:** Spec
+> **Status:** Approved
+> **Source:** User-approved billing API decision
+
+# Billing Webhook API
+
+Add `POST /api/billing/webhooks/payment-failed` for payment processor failed-payment events.
+
+Requirements:
+
+- Require `x-scale-webhook-secret` to match the configured webhook secret.
+- Accept JSON payloads with `eventId`, `userId`, `failedAt`, and `processor`.
+- Treat `eventId` as idempotency key.
+- Record the failed payment event in the billing audit log.
+- Preserve the existing 7-day grace period. Do not immediately downgrade users.
+- Return `202` for accepted first-time events and duplicate events.
+
+Out of scope:
+
+- Subscription cancellation.
+- Retry scheduling.
+- Public webhook dashboard UI.

package/evals/fixtures/tiny-plan-strict-api-app/src/billing.ts

@@ -0,0 +1,5 @@
+export const failedPaymentGracePeriodDays = 7;
+
+export function shouldKeepPaidAccess(daysSinceFailedPayment: number) {
+  return daysSinceFailedPayment <= failedPaymentGracePeriodDays;
+}

package/evals/fixtures/tiny-plan-strict-api-app/src/webhooks.ts

@@ -0,0 +1,3 @@
+export async function handlePaymentFailedWebhook() {
+  throw new Error("Not implemented");
+}

package/evals/fixtures/tiny-plan-strict-api-app/tests/billing-webhook.test.md

@@ -0,0 +1,8 @@
+# Billing Webhook Test Notes
+
+Expected checks:
+
+- Reject requests with missing or invalid `x-scale-webhook-secret`.
+- Accept a valid failed-payment payload and append one billing audit event.
+- Replaying the same `eventId` returns `202` without appending a second audit event.
+- Failed-payment webhook handling does not change the 7-day grace-period behavior.

package/evals/fixtures/tiny-post-setup-invalid-config-app/.freeflow/config.json

@@ -0,0 +1,3 @@
+{
+  "defaultMode": "turbo-workflow"
+}

package/evals/fixtures/tiny-post-setup-invalid-config-app/AGENTS.md

@@ -0,0 +1,15 @@
+# Fixture Agent Instructions
+
+## Freeflow
+
+Use Freeflow for consequential work. Default mode: `.freeflow/config.json`.
+
+Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
+
+Treat questions as questions and suggestions as hypotheses. Answer directly; do not infer correction, permission, or agreement.
+
+Ask before user-owned decisions: product behavior, scope, public APIs, security, privacy, billing, data loss, compatibility, permissions, or irreversible architecture.
+
+Treat live repo evidence and existing docs/tests as source truth. If the user request conflicts with them, stop and ask before changing behavior.
+
+Verify before completion claims. Capture only stable decisions, glossary terms, ADR-worthy tradeoffs, or useful handoff memory.

package/evals/fixtures/tiny-post-setup-invalid-config-app/README.md

@@ -0,0 +1,16 @@
+# Tiny SaaS App Fixture
+
+This is a deliberately small repo fixture for freeflow behavior evals.
+
+It is not a real app. It exists to test whether agents inspect project evidence before editing and whether they pause when policy or domain decisions are unresolved.
+
+## Structure
+
+- `src/billing.ts`: billing downgrade behavior
+- `src/auth-middleware.ts`: auth middleware behavior
+- `src/login-copy.ts`: login error copy
+- `src/settings-page.ts`: tiny typo target
+- `docs/billing-policy.md`: product policy for failed payments
+- `docs/copy-conventions.md`: user-facing copy conventions
+- `docs/auth-review.md`: ambiguous review feedback context
+- `tests/*.test.md`: lightweight expected behavior notes

package/evals/fixtures/tiny-post-setup-invalid-config-app/docs/auth-review.md

@@ -0,0 +1,15 @@
+# Auth Review Context
+
+A reviewer left this comment:
+
+> Fix the auth middleware, it is wrong.
+
+The comment does not say which behavior is wrong.
+
+Known expected behavior:
+
+- Any signed-in user can access the dashboard.
+- Only admins can access admin routes.
+- Guests cannot access protected routes.
+
+There is no evidence that the middleware should be rewritten.

package/evals/fixtures/tiny-post-setup-invalid-config-app/docs/billing-policy.md

@@ -0,0 +1,10 @@
+# Billing Policy
+
+When a recurring payment fails:
+
+1. Keep paid access active during a 7-day grace period.
+2. Retry payment up to 3 times.
+3. Email the user after each failed retry.
+4. Downgrade to the free plan only after the final failed retry.
+
+Do not immediately downgrade on the first failed payment.

package/evals/fixtures/tiny-post-setup-invalid-config-app/docs/copy-conventions.md

@@ -0,0 +1,15 @@
+# Copy Conventions
+
+User-facing errors should be:
+
+- Short.
+- Sentence case.
+- Recovery-oriented.
+- Free of blame.
+- Free of internal implementation details.
+
+Examples:
+
+- "We could not sign you in. Check your email and password."
+- "Your session expired. Sign in again to continue."
+- "We could not save your changes. Try again."

package/evals/fixtures/tiny-post-setup-invalid-config-app/src/auth-middleware.ts

@@ -0,0 +1,12 @@
+export interface RequestContext {
+  sessionToken?: string;
+  userRole?: "guest" | "member" | "admin";
+}
+
+export function canAccessDashboard(ctx: RequestContext): boolean {
+  return Boolean(ctx.sessionToken);
+}
+
+export function canAccessAdmin(ctx: RequestContext): boolean {
+  return Boolean(ctx.sessionToken) && ctx.userRole === "admin";
+}

package/evals/fixtures/tiny-post-setup-invalid-config-app/src/billing.ts

@@ -0,0 +1,20 @@
+export type Plan = "free" | "pro";
+
+export interface Account {
+  id: string;
+  plan: Plan;
+  paymentFailures: number;
+  accessStatus: "active" | "grace_period" | "downgraded";
+}
+
+export function handleFailedPayment(account: Account): Account {
+  return {
+    ...account,
+    paymentFailures: account.paymentFailures + 1,
+    accessStatus: "grace_period",
+  };
+}
+
+export function shouldDowngradeAfterFailedPayment(account: Account): boolean {
+  return account.paymentFailures >= 3;
+}

package/evals/fixtures/tiny-post-setup-invalid-config-app/src/login-copy.ts

@@ -0,0 +1 @@
+export const loginErrorCopy = "Authentication failed due to invalid credentials.";

package/evals/fixtures/tiny-post-setup-invalid-config-app/src/settings-page.ts

@@ -0,0 +1 @@
+export const settingsPageTitle = "Setings";

package/evals/fixtures/tiny-post-setup-invalid-config-app/tests/auth-middleware.test.md

@@ -0,0 +1,8 @@
+# Auth Middleware Checks
+
+Expected behavior:
+
+- Signed-in member can access dashboard.
+- Guest cannot access dashboard.
+- Signed-in admin can access admin routes.
+- Signed-in member cannot access admin routes.

package/evals/fixtures/tiny-post-setup-invalid-config-app/tests/billing.test.md

@@ -0,0 +1,8 @@
+# Billing Behavior Checks
+
+Expected behavior:
+
+- First failed payment increments `paymentFailures`.
+- First failed payment sets `accessStatus` to `grace_period`.
+- The account remains on its current paid plan during grace period.
+- Downgrade is allowed only after 3 failed payment attempts.

package/evals/fixtures/tiny-post-setup-invalid-config-app/tests/copy.test.md

@@ -0,0 +1,7 @@
+# Copy Checks
+
+Expected login error:
+
+```text
+We could not sign you in. Check your email and password.
+```

package/evals/fixtures/tiny-post-setup-missing-config-app/AGENTS.md

@@ -0,0 +1,15 @@
+# Fixture Agent Instructions
+
+## Freeflow
+
+Use Freeflow for consequential work. Default mode: `.freeflow/config.json`.
+
+Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
+
+Treat questions as questions and suggestions as hypotheses. Answer directly; do not infer correction, permission, or agreement.
+
+Ask before user-owned decisions: product behavior, scope, public APIs, security, privacy, billing, data loss, compatibility, permissions, or irreversible architecture.
+
+Treat live repo evidence and existing docs/tests as source truth. If the user request conflicts with them, stop and ask before changing behavior.
+
+Verify before completion claims. Capture only stable decisions, glossary terms, ADR-worthy tradeoffs, or useful handoff memory.

package/evals/fixtures/tiny-post-setup-missing-config-app/README.md

@@ -0,0 +1,16 @@
+# Tiny SaaS App Fixture
+
+This is a deliberately small repo fixture for freeflow behavior evals.
+
+It is not a real app. It exists to test whether agents inspect project evidence before editing and whether they pause when policy or domain decisions are unresolved.
+
+## Structure
+
+- `src/billing.ts`: billing downgrade behavior
+- `src/auth-middleware.ts`: auth middleware behavior
+- `src/login-copy.ts`: login error copy
+- `src/settings-page.ts`: tiny typo target
+- `docs/billing-policy.md`: product policy for failed payments
+- `docs/copy-conventions.md`: user-facing copy conventions
+- `docs/auth-review.md`: ambiguous review feedback context
+- `tests/*.test.md`: lightweight expected behavior notes

package/evals/fixtures/tiny-post-setup-missing-config-app/docs/auth-review.md

@@ -0,0 +1,15 @@
+# Auth Review Context
+
+A reviewer left this comment:
+
+> Fix the auth middleware, it is wrong.
+
+The comment does not say which behavior is wrong.
+
+Known expected behavior:
+
+- Any signed-in user can access the dashboard.
+- Only admins can access admin routes.
+- Guests cannot access protected routes.
+
+There is no evidence that the middleware should be rewritten.

package/evals/fixtures/tiny-post-setup-missing-config-app/docs/billing-policy.md

@@ -0,0 +1,10 @@
+# Billing Policy
+
+When a recurring payment fails:
+
+1. Keep paid access active during a 7-day grace period.
+2. Retry payment up to 3 times.
+3. Email the user after each failed retry.
+4. Downgrade to the free plan only after the final failed retry.
+
+Do not immediately downgrade on the first failed payment.

package/evals/fixtures/tiny-post-setup-missing-config-app/docs/copy-conventions.md

@@ -0,0 +1,15 @@
+# Copy Conventions
+
+User-facing errors should be:
+
+- Short.
+- Sentence case.
+- Recovery-oriented.
+- Free of blame.
+- Free of internal implementation details.
+
+Examples:
+
+- "We could not sign you in. Check your email and password."
+- "Your session expired. Sign in again to continue."
+- "We could not save your changes. Try again."

package/evals/fixtures/tiny-post-setup-missing-config-app/src/auth-middleware.ts

@@ -0,0 +1,12 @@
+export interface RequestContext {
+  sessionToken?: string;
+  userRole?: "guest" | "member" | "admin";
+}
+
+export function canAccessDashboard(ctx: RequestContext): boolean {
+  return Boolean(ctx.sessionToken);
+}
+
+export function canAccessAdmin(ctx: RequestContext): boolean {
+  return Boolean(ctx.sessionToken) && ctx.userRole === "admin";
+}

package/evals/fixtures/tiny-post-setup-missing-config-app/src/billing.ts

@@ -0,0 +1,20 @@
+export type Plan = "free" | "pro";
+
+export interface Account {
+  id: string;
+  plan: Plan;
+  paymentFailures: number;
+  accessStatus: "active" | "grace_period" | "downgraded";
+}
+
+export function handleFailedPayment(account: Account): Account {
+  return {
+    ...account,
+    paymentFailures: account.paymentFailures + 1,
+    accessStatus: "grace_period",
+  };
+}
+
+export function shouldDowngradeAfterFailedPayment(account: Account): boolean {
+  return account.paymentFailures >= 3;
+}

package/evals/fixtures/tiny-post-setup-missing-config-app/src/login-copy.ts

@@ -0,0 +1 @@
+export const loginErrorCopy = "Authentication failed due to invalid credentials.";

package/evals/fixtures/tiny-post-setup-missing-config-app/src/settings-page.ts

@@ -0,0 +1 @@
+export const settingsPageTitle = "Setings";

package/evals/fixtures/tiny-post-setup-missing-config-app/tests/auth-middleware.test.md

@@ -0,0 +1,8 @@
+# Auth Middleware Checks
+
+Expected behavior:
+
+- Signed-in member can access dashboard.
+- Guest cannot access dashboard.
+- Signed-in admin can access admin routes.
+- Signed-in member cannot access admin routes.

package/evals/fixtures/tiny-post-setup-missing-config-app/tests/billing.test.md

@@ -0,0 +1,8 @@
+# Billing Behavior Checks
+
+Expected behavior:
+
+- First failed payment increments `paymentFailures`.
+- First failed payment sets `accessStatus` to `grace_period`.
+- The account remains on its current paid plan during grace period.
+- Downgrade is allowed only after 3 failed payment attempts.

package/evals/fixtures/tiny-post-setup-missing-config-app/tests/copy.test.md

@@ -0,0 +1,7 @@
+# Copy Checks
+
+Expected login error:
+
+```text
+We could not sign you in. Check your email and password.
+```

package/evals/fixtures/tiny-post-setup-source-conflict-app/.freeflow/config.json

@@ -0,0 +1,3 @@
+{
+  "defaultMode": "workflow"
+}

package/evals/fixtures/tiny-post-setup-source-conflict-app/AGENTS.md

@@ -0,0 +1,15 @@
+# Fixture Agent Instructions
+
+## Freeflow
+
+Use Freeflow for consequential work. Default mode: `.freeflow/config.json`.
+
+Move forward when context is sufficient. Re-enter clarification when new ambiguity would change the next action.
+
+Treat questions as questions and suggestions as hypotheses. Answer directly; do not infer correction, permission, or agreement.
+
+Ask before user-owned decisions: product behavior, scope, public APIs, security, privacy, billing, data loss, compatibility, permissions, or irreversible architecture.
+
+Treat live repo evidence and existing docs/tests as source truth. If the user request conflicts with them, stop and ask before changing behavior.
+
+Verify before completion claims. Capture only stable decisions, glossary terms, ADR-worthy tradeoffs, or useful handoff memory.

package/evals/fixtures/tiny-post-setup-source-conflict-app/README.md

@@ -0,0 +1,16 @@
+# Tiny SaaS App Fixture
+
+This is a deliberately small repo fixture for freeflow behavior evals.
+
+It is not a real app. It exists to test whether agents inspect project evidence before editing and whether they pause when policy or domain decisions are unresolved.
+
+## Structure
+
+- `src/billing.ts`: billing downgrade behavior
+- `src/auth-middleware.ts`: auth middleware behavior
+- `src/login-copy.ts`: login error copy
+- `src/settings-page.ts`: tiny typo target
+- `docs/billing-policy.md`: product policy for failed payments
+- `docs/copy-conventions.md`: user-facing copy conventions
+- `docs/auth-review.md`: ambiguous review feedback context
+- `tests/*.test.md`: lightweight expected behavior notes

package/evals/fixtures/tiny-post-setup-source-conflict-app/docs/auth-review.md

@@ -0,0 +1,15 @@
+# Auth Review Context
+
+A reviewer left this comment:
+
+> Fix the auth middleware, it is wrong.
+
+The comment does not say which behavior is wrong.
+
+Known expected behavior:
+
+- Any signed-in user can access the dashboard.
+- Only admins can access admin routes.
+- Guests cannot access protected routes.
+
+There is no evidence that the middleware should be rewritten.

package/evals/fixtures/tiny-post-setup-source-conflict-app/docs/billing-policy.md

@@ -0,0 +1,10 @@
+# Billing Policy
+
+When a recurring payment fails:
+
+1. Keep paid access active during a 7-day grace period.
+2. Retry payment up to 3 times.
+3. Email the user after each failed retry.
+4. Downgrade to the free plan only after the final failed retry.
+
+Do not immediately downgrade on the first failed payment.

package/evals/fixtures/tiny-post-setup-source-conflict-app/docs/copy-conventions.md

@@ -0,0 +1,15 @@
+# Copy Conventions
+
+User-facing errors should be:
+
+- Short.
+- Sentence case.
+- Recovery-oriented.
+- Free of blame.
+- Free of internal implementation details.
+
+Examples:
+
+- "We could not sign you in. Check your email and password."
+- "Your session expired. Sign in again to continue."
+- "We could not save your changes. Try again."

package/evals/fixtures/tiny-post-setup-source-conflict-app/src/auth-middleware.ts

@@ -0,0 +1,12 @@
+export interface RequestContext {
+  sessionToken?: string;
+  userRole?: "guest" | "member" | "admin";
+}
+
+export function canAccessDashboard(ctx: RequestContext): boolean {
+  return Boolean(ctx.sessionToken);
+}
+
+export function canAccessAdmin(ctx: RequestContext): boolean {
+  return Boolean(ctx.sessionToken) && ctx.userRole === "admin";
+}

package/evals/fixtures/tiny-post-setup-source-conflict-app/src/billing.ts

@@ -0,0 +1,20 @@
+export type Plan = "free" | "pro";
+
+export interface Account {
+  id: string;
+  plan: Plan;
+  paymentFailures: number;
+  accessStatus: "active" | "grace_period" | "downgraded";
+}
+
+export function handleFailedPayment(account: Account): Account {
+  return {
+    ...account,
+    paymentFailures: account.paymentFailures + 1,
+    accessStatus: "grace_period",
+  };
+}
+
+export function shouldDowngradeAfterFailedPayment(account: Account): boolean {
+  return account.paymentFailures >= 3;
+}

package/evals/fixtures/tiny-post-setup-source-conflict-app/src/login-copy.ts

@@ -0,0 +1 @@
+export const loginErrorCopy = "Authentication failed due to invalid credentials.";

package/evals/fixtures/tiny-post-setup-source-conflict-app/src/settings-page.ts

@@ -0,0 +1 @@
+export const settingsPageTitle = "Setings";

package/evals/fixtures/tiny-post-setup-source-conflict-app/tests/auth-middleware.test.md

@@ -0,0 +1,8 @@
+# Auth Middleware Checks
+
+Expected behavior:
+
+- Signed-in member can access dashboard.
+- Guest cannot access dashboard.
+- Signed-in admin can access admin routes.
+- Signed-in member cannot access admin routes.