@tangle-network/starter-foundry 0.7.2 → 0.13.0

package/registry/families/agent-runtime-wealth-manager-ts/files/agent.json

@@ -0,0 +1,38 @@
+{
+  "name": "wealth-manager",
+  "description": "Personal wealth-manager agent bundle — peer-style information on asset allocation, tax-loss harvesting, and retirement projection. Explicitly NOT a registered investment adviser, NOT a fiduciary, NOT licensed financial advice. Demonstrates the agent-runtime substrate composing on a regulated-finance role with structured-output blocks (:::artifact, :::escalation) and a hard refusal contract for actionable trade picks.",
+  "version": "0.1.0",
+  "tags": [
+    "agent-runtime",
+    "personal-finance",
+    "wealth-management",
+    "regulated-finance",
+    "cloudflare-worker"
+  ],
+  "prompt": {
+    "systemPromptFile": "AGENTS.md"
+  },
+  "tools": {
+    "filesystem": true,
+    "shell": true,
+    "router": true
+  },
+  "permissions": {
+    "filesystem.write": "ask",
+    "shell.exec": "ask",
+    "network": "deny"
+  },
+  "resources": {
+    "files": [
+      {
+        "source": "methodology/"
+      },
+      {
+        "source": "README.md"
+      },
+      {
+        "source": "TOOLS.md"
+      }
+    ]
+  }
+}

package/registry/families/agent-runtime-wealth-manager-ts/files/methodology/allocation-review.md

@@ -0,0 +1,147 @@
+---
+capability: asset-allocation-review
+status: active
+source: Bogleheads three-fund methodology; Vanguard 2025 target-date glidepath; 5/25 rebalancing rule (Larry Swedroe)
+retrieved: 2026-04-25
+---
+
+# Allocation Review & Rebalancing
+
+A methodology output for evaluating a user's current portfolio against
+a target allocation, identifying drift, and describing rebalancing
+mechanics. Output ships as a `:::artifact` block marked EDUCATIONAL.
+**No buy/sell recommendations. No specific tickers.**
+
+## When to use
+
+Trigger this template when the user asks for:
+
+- "Review my portfolio" / "is my allocation right?"
+- "Am I diversified?" / "should I rebalance?"
+- "What's a good allocation for my age?"
+
+If the user asks "should I buy/sell X?" — that's a security pick.
+Refuse and escalate per system-prompt trigger 1.
+
+## Required user inputs (open `:::question` block first)
+
+Before computing any drift, get from the user:
+
+1. Age (drives glidepath)
+2. Time horizon (years until withdrawal begins)
+3. Risk tolerance (low / moderate / high — anchored to a max
+   acceptable peak-to-trough drawdown: 20% / 35% / 50%)
+4. Account-type breakdown (taxable / Traditional IRA-401k / Roth /
+   HSA — placement matters for tax efficiency)
+5. Current holdings: each position's category (US equity, ex-US
+   equity, US bond, ex-US bond, REIT, cash, alts) + market value
+6. Anticipated contribution rate (changes the rebalance-via-flow vs.
+   rebalance-via-trade decision)
+
+If the user can't answer one, mark `OPEN-QUESTION` and refuse to
+compute lines that depend on it.
+
+## Method
+
+### Step 1 — Target allocation
+
+Anchor on age-based equity weight (commonly cited heuristic, not law):
+`equity % ≈ 110 − age` for moderate risk tolerance. Adjust:
+
+- Low tolerance: `100 − age`
+- High tolerance: `120 − age`, capped at 90%
+- Time horizon < 5 years: cap equity at 40% regardless of age
+
+Within equity, the Bogleheads three-fund split:
+- US total market: 60% of equity
+- Ex-US total market: 40% of equity (developed + emerging)
+
+Within fixed income:
+- US aggregate bond: 70% of fixed income
+- TIPS or short-duration: 30% of fixed income (inflation hedge,
+  weight up if user is in or near withdrawal phase)
+
+### Step 2 — Drift analysis (5/25 rule)
+
+For each asset class, compute current weight vs. target weight.
+Flag for rebalance if EITHER:
+
+- **Absolute drift ≥ 5 percentage points** (e.g. target 60% US
+  equity, current 66%)
+- **Relative drift ≥ 25%** of the target weight (e.g. target 10%
+  bonds, current 7.4% — drift = 2.6pp absolute, but 26% relative)
+
+The 5/25 rule catches both large-class drift and small-class drift
+that absolute thresholds miss.
+
+### Step 3 — Tax-aware location
+
+Tax-inefficient assets belong in tax-advantaged accounts:
+- Taxable bonds → Traditional IRA / 401(k) (interest taxed as
+  ordinary income anyway; deferral helps)
+- REITs → Traditional IRA / 401(k) (non-qualified dividends)
+- US total-market equity → taxable (qualified dividends + step-up
+  basis at death)
+- Roth → highest expected-return assets (growth never taxed)
+
+Surface mismatches but do not recommend specific moves — describe
+the *principle*, escalate the *trade* to a CPA/CFP.
+
+### Step 4 — Rebalance via flow vs. trade
+
+If the user's annual contribution > the dollar drift amount,
+recommend rebalancing-via-flow (direct new contributions to
+under-weight classes) — this avoids realizing taxable gains.
+Otherwise note that a rebalancing trade in a taxable account has
+tax consequences (short-term gains taxed at ordinary rates;
+long-term at 0/15/20% based on bracket) — this is where the user
+needs a CPA in the loop.
+
+## Output shape
+
+```
+:::artifact
+type: allocation-review
+status: EDUCATIONAL — not investment advice
+disclaimer: "Investment Advisers Act §202(a)(11): no advisory
+  relationship. Consult a fee-only CFP or RIA before acting."
+inputs:
+  age: <n>
+  horizon-years: <n>
+  risk-tolerance: <low|moderate|high>
+  total-portfolio: $<X>
+target-allocation:
+  us-equity: <X>%
+  ex-us-equity: <X>%
+  us-bond: <X>%
+  tips-or-short: <X>%
+  reit: <X>%
+  cash: <X>%
+current-allocation:
+  us-equity: <X>% [drift: <±X>pp / <±X>% relative]
+  ...
+flagged-for-rebalance:
+  - "<class>: <reason — 5pp absolute or 25% relative>"
+location-mismatches:
+  - "<class> in <account-type>: <principle violated>"
+rebalance-mechanic:
+  via-flow-feasible: <yes|no>
+  reason: "<contribution rate vs. drift dollars>"
+open-questions:
+  - "Are any positions concentration > 25%? (escalate if yes)"
+  - "Is the user in or near withdrawal? (changes glidepath)"
+:::
+```
+
+## Refusal mode
+
+Refuse to:
+
+- Name a specific replacement ticker for any class
+- Recommend a specific trade size or timing
+- Comment on whether the user's current adviser's fees are reasonable
+- Project future returns of any single holding
+
+If the user pushes for any of the above, emit `:::escalation` with
+the trigger cited and a fee-only-CFP-finder pointer (NAPFA, Garrett
+Planning Network, XY Planning Network).

package/registry/families/agent-runtime-wealth-manager-ts/files/methodology/index.json

@@ -0,0 +1,25 @@
+{
+  "entries": [
+    {
+      "id": "allocation-review",
+      "capability": "asset-allocation-review",
+      "path": "./allocation-review.md",
+      "tags": ["methodology", "allocation", "rebalancing", "bogleheads"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "tax-loss-harvest-protocol",
+      "capability": "tax-loss-harvesting",
+      "path": "./tax-loss-harvest-protocol.md",
+      "tags": ["methodology", "tax", "wash-sale", "irc-1091"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "retirement-projection",
+      "capability": "retirement-projection",
+      "path": "./retirement-projection.md",
+      "tags": ["methodology", "retirement", "monte-carlo", "trinity-study"],
+      "version": "0.1.0"
+    }
+  ]
+}

package/registry/families/agent-runtime-wealth-manager-ts/files/methodology/retirement-projection.md

@@ -0,0 +1,186 @@
+---
+capability: retirement-projection
+status: active
+source: Bengen 1994 (4% rule original); Trinity Study (Cooley/Hubbard/Walz 1998 + 2011 update); Pfau & Kitces 2014 (rising-equity glidepath); Milevsky on sequence-of-returns risk
+retrieved: 2026-04-25
+---
+
+# Retirement Projection
+
+A methodology output for sanity-checking a user's retirement plan
+against the published withdrawal-rate literature, running a Monte
+Carlo with assumptions surfaced, and stress-testing against
+sequence-of-returns risk. Output ships as a `:::artifact` block
+marked EDUCATIONAL. **No specific "you'll have $X at age Y"
+promise. No specific withdrawal-rate prescription.**
+
+## When to use
+
+Trigger this template when the user asks for:
+
+- "Can I retire at <age>?" / "am I on track?"
+- "How much do I need to retire?"
+- "Is the 4% rule still valid?"
+- "What's my safe withdrawal rate?"
+
+If the user asks "what should my Roth conversion amount be in
+2026?" — that's specific tax advice. Refuse and escalate per
+system-prompt trigger 3.
+
+## Required user inputs (open `:::question` block first)
+
+1. Current age + planned retirement age + planned end-of-plan age
+   (90 is a common floor; 100 for plans that need to survive
+   longevity)
+2. Current portfolio value + annual contribution + expected
+   contribution growth
+3. Target real (inflation-adjusted) annual spend in retirement
+4. Pension / Social-Security expected annual income (and start
+   age — claiming-age has its own optimization the agent does not
+   touch)
+5. Asset allocation (drives expected return + volatility
+   assumptions)
+6. Tax bracket in retirement (taxable-account spend is grossed up
+   for tax)
+
+## Method
+
+### Step 1 — 4% rule sanity check
+
+Bengen 1994 / Trinity 1998: a 4% initial withdrawal rate (adjusted
+for CPI annually), from a 50/50 to 75/25 stock/bond portfolio,
+survived 30 years in 95%+ of historical US rolling periods.
+
+Compute:
+- `target-portfolio-at-retirement = annual-spend / 0.04`
+  (the 25× rule, the inverse of 4%)
+- Compare to projected portfolio at retirement age using the
+  user's contributions + expected return
+
+State the caveats explicitly:
+- 4% is a **historical** US-equity-heavy result; forward-looking
+  research (Pfau, Morningstar 2024) suggests 3.0–3.7% is a more
+  defensible safe rate given current valuations and bond yields
+- The 4% rule does NOT survive a 50-year horizon (FIRE crowd) —
+  Bengen's window was 30 years
+- It assumes US-only equity history; non-US history is worse
+
+### Step 2 — Monte Carlo projection
+
+Simulate N=5,000 trials of portfolio paths from current age to
+end-of-plan age. For each year:
+
+- Sample real return from a distribution matching the user's
+  allocation. Conservative defaults:
+  - 100% equity: μ=5.5% real, σ=18%
+  - 60/40: μ=4.0% real, σ=11%
+  - 40/60: μ=3.0% real, σ=8%
+- Add contribution (pre-retirement) or subtract real spend net of
+  pensions/SS (post-retirement)
+- Apply Social-Security as a real annuity starting at the user's
+  claim age
+
+Report:
+- **Success rate** (% of trials where portfolio > $0 at end-of-plan)
+- **Median terminal value**
+- **5th-percentile terminal value** (the bad-case to actually plan
+  around)
+- **Median portfolio at retirement date**
+
+Surface assumptions as part of the artifact. A success rate of
+"95%" with bad assumptions is worse than 70% with conservative
+ones.
+
+### Step 3 — Sequence-of-returns risk
+
+The single biggest hidden risk in any projection: a bad return
+sequence in the **first 5–10 years of withdrawal** can sink a
+plan that the same returns in reverse order would have funded
+comfortably. Pfau-Kitces "rising-equity glidepath" (2014):
+counter-intuitively, *increasing* equity through retirement
+reduces tail risk because early-retirement bonds buffer the
+sequence.
+
+Stress test by re-running Monte Carlo conditioned on:
+- "First 5 years return = 10th-percentile of historical returns"
+- "First 10 years return = 25th-percentile"
+
+Report success rates under stress. If stress success < 70%, flag
+sequence risk as a planning gap and surface mitigation
+*concepts* (cash buffer, rising-equity glide, dynamic
+withdrawal — Guyton-Klinger guardrails) — not specific
+prescriptions.
+
+### Step 4 — Sensitivity analysis
+
+Show how success rate moves with ±1pp on each lever:
+- Real return assumption (±1pp)
+- Annual spend (±10%)
+- Retirement age (±2 years)
+- Contribution rate (±2pp of income)
+
+The largest-elasticity lever is usually the most actionable for
+the user.
+
+## Output shape
+
+```
+:::artifact
+type: retirement-projection
+status: EDUCATIONAL — not investment advice; assumptions surfaced
+disclaimer: "Investment Advisers Act §202(a)(11): projection is
+  illustrative, not a promise. Past returns do not predict
+  future results. Consult a fee-only CFP."
+inputs:
+  current-age: <n>
+  retire-age: <n>
+  end-age: <n>
+  current-portfolio: $<X>
+  annual-contribution: $<X>
+  target-real-spend: $<X>
+  allocation: <X>/<Y>/<Z>
+assumptions:
+  equity-real-return: <X>%
+  bond-real-return: <X>%
+  inflation: <X>%
+  social-security-start: <age>
+four-percent-check:
+  target-portfolio-25x: $<X>
+  projected-portfolio-at-retirement: $<X>
+  gap: $<X>
+monte-carlo:
+  trials: 5000
+  success-rate: <X>%
+  median-terminal: $<X>
+  fifth-percentile-terminal: $<X>
+sequence-risk:
+  stress-success-first-5-poor: <X>%
+  stress-success-first-10-poor: <X>%
+  flag: <none|sequence-risk-material>
+sensitivity:
+  return-+1pp: <X>% success
+  return-−1pp: <X>% success
+  spend-+10%: <X>% success
+  retire+2yr: <X>% success
+open-questions:
+  - "Is target-spend pre- or post-tax?"
+  - "Are you including LTC / unexpected medical costs?"
+  - "What's your cash-buffer plan for the first 2 years of
+    retirement spend?"
+:::
+```
+
+## Refusal mode
+
+Refuse to:
+
+- Promise a specific terminal value ("you'll have $2.4M")
+- Recommend a specific withdrawal rate ("you can safely take 4.2%")
+- Recommend a specific Social-Security claim age (CFP/SS-claiming
+  software territory)
+- Recommend a specific Roth-conversion amount or year (CPA territory)
+- Issue a "you can retire" / "you can't retire" verdict
+
+If the user pushes for any of the above, emit `:::escalation`
+citing the Investment Advisers Act + the specific trigger, with
+a fee-only-CFP-finder pointer (NAPFA, Garrett Planning Network).

package/registry/families/agent-runtime-wealth-manager-ts/files/methodology/tax-loss-harvest-protocol.md

@@ -0,0 +1,178 @@
+---
+capability: tax-loss-harvesting
+status: active
+source: IRC §1091 (wash sale); IRS Publication 550 (Investment Income and Expenses); Revenue Ruling 2008-5
+retrieved: 2026-04-25
+---
+
+# Tax-Loss Harvesting Protocol
+
+A methodology output for identifying lots with unrealized losses in
+a taxable account, evaluating wash-sale exposure, and describing
+the *category* of replacement security to maintain market exposure
+during the 30-day window. Output ships as a `:::artifact` block
+marked EDUCATIONAL. **No specific replacement tickers. No trade
+sizing. No final harvest call.**
+
+## When to use
+
+Trigger this template when the user asks for:
+
+- "Should I tax-loss harvest?" / "harvest my losses"
+- "How does TLH work?" / "wash-sale rule"
+- "Year-end tax moves" (in the harvesting context)
+
+If the user asks "what should I sell and what should I buy as the
+replacement ticker?" — that's an actionable trade recommendation.
+Refuse and escalate per system-prompt trigger 2.
+
+## Required user inputs (open `:::question` block first)
+
+1. Account type (TLH only meaningful in **taxable** accounts —
+   IRAs / 401(k)s have no realized-loss benefit and an IRA wash-sale
+   permanently disallows the loss per Rev. Rul. 2008-5)
+2. Filing status + marginal ordinary-income rate + LTCG rate
+3. Lot-level cost basis + acquisition date for each position with
+   an unrealized loss (long-term vs. short-term matters)
+4. Any purchases of the same or "substantially identical" security
+   in the **30 days before** the contemplated sale, in **any
+   account** (taxable, IRA, spouse's IRA — all count)
+5. Any pending dividend reinvestments scheduled to land within the
+   31-day window after sale
+6. State of residence (some states don't conform to federal
+   capital-loss treatment)
+
+If any of these is missing, mark `OPEN-QUESTION`. Wash-sale
+analysis without complete buy-history data is dangerous — refuse
+to proceed.
+
+## Method
+
+### Step 1 — Identify candidate lots
+
+For each position, compute lot-level unrealized P&L:
+`unrealized = current price × shares − cost basis`
+
+Flag lots with unrealized loss meeting BOTH:
+- Absolute loss ≥ $500 (below this, transaction friction wipes the
+  benefit)
+- Loss as % of position basis ≥ 5% (avoids harvesting noise)
+
+Sort by short-term first (offsets ordinary income up to $3,000/yr
+deduction limit, then carries forward), then long-term (offsets
+LTCG, then ordinary up to $3,000).
+
+### Step 2 — Wash-sale window check (IRC §1091)
+
+The wash-sale rule disallows a loss if, within **30 days before or
+after** the sale, the taxpayer:
+
+- Buys the **same** security
+- Buys a **substantially identical** security
+- Acquires it in a **fully taxable exchange**
+- Acquires a **contract or option** to buy it
+- Has it acquired in **any account they control** (including IRA
+  per Rev. Rul. 2008-5 — and the loss is *permanently* disallowed
+  in this case, not merely deferred)
+
+The window is **61 calendar days total** (30 before + sale day +
+30 after). Spouse's accounts and entities the taxpayer controls
+count.
+
+For each candidate lot, scan the user-provided buy history within
+±30 days. Flag any exposure as `WASH-SALE-RISK`.
+
+### Step 3 — Replacement security (category, not ticker)
+
+To maintain market exposure during the 30-day window, the user
+needs a security that is **not substantially identical**. The IRS
+has not published a bright-line "substantially identical" test
+for ETFs/funds — the conservative view (and the only view this
+agent will state):
+
+- Different index → not substantially identical (e.g. S&P 500
+  fund → total US market fund: different index, different
+  constituents, different weights)
+- Same index, different issuer → **probably substantially
+  identical** (two S&P 500 funds from different issuers track the
+  same underlying basket; conservative practitioners avoid this)
+- Single stock → no truly equivalent replacement; harvesting
+  single names usually means going to cash for 31 days
+
+Describe the *category* of acceptable replacement (e.g. "a total-
+US-market index fund tracking a different index than the
+harvested S&P 500 fund"). **Never name a specific ticker.** That's
+the line between methodology and security selection.
+
+### Step 4 — Tax benefit estimation
+
+Approximate harvest benefit:
+- Short-term loss × marginal-ordinary-rate (up to $3,000/yr
+  against ordinary income, remainder carries forward)
+- Long-term loss × LTCG rate (offsets LTCG first, then up to
+  $3,000 against ordinary income)
+
+State the assumption clearly: harvest benefit is real only if the
+user has gains to offset (now or in future years). For someone
+permanently in the 0% LTCG bracket, harvesting *long-term* losses
+may be value-destructive (resets basis lower for no offset).
+
+### Step 5 — Re-entry plan
+
+After the 31-day window closes, the user can repurchase the
+original security if they want. Note that the harvested cost
+basis is not preserved on the replacement — selling the
+replacement realizes its own gain/loss.
+
+## Output shape
+
+```
+:::artifact
+type: tax-loss-harvest-protocol
+status: EDUCATIONAL — not investment advice; not tax advice
+disclaimer: "Investment Advisers Act §202(a)(11) + IRC §1091:
+  wash-sale analysis depends on the user's complete buy history
+  across ALL accounts (incl. spouse + IRA). Consult a CPA before
+  executing."
+inputs:
+  account-type: <taxable|...>
+  marginal-ordinary-rate: <X>%
+  ltcg-rate: <X>%
+candidate-lots:
+  - position: <class>
+    lot-id: <id>
+    acquired: <date>
+    unrealized-loss: $<X>
+    short-or-long: <st|lt>
+    wash-sale-risk: <none|flagged: reason>
+replacement-category:
+  - description: "<index-different fund of same broad category>"
+    NOT-A-TICKER: true
+estimated-benefit:
+  short-term-offset: $<up to 3000>
+  long-term-offset: $<X>
+  carry-forward: $<X>
+open-questions:
+  - "Any buys of same/identical security in last 30 days, any
+    account, including spouse's IRA?"
+  - "Pending dividend reinvestments in the 31-day post-window?"
+  - "Are you in the 0% LTCG bracket? (if yes, LT harvesting may
+    destroy value)"
+:::
+```
+
+## Refusal mode
+
+Refuse to:
+
+- Name a specific replacement ticker
+- Confirm two specific funds are "not substantially identical"
+  (this is a fact-and-circumstances IRS judgement; CPA territory)
+- Estimate harvest benefit without complete buy history
+- Recommend harvesting in an IRA (the loss is permanently
+  disallowed — value-destructive)
+- Suggest harvesting around an upcoming distribution date
+  without surfacing the wash-sale risk
+
+If the user pushes, emit `:::escalation` with the IRC §1091 +
+Rev. Rul. 2008-5 citation and a CPA-finder pointer.