@albsugy/aos 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,80 @@
+# Changelog
+
+## 0.5.0 — 2026-07-04
+
+Public distribution via npm; source stays private.
+
+- **The npm registry is now the public channel.** The package ships only the compiled
+  bundle (`dist/aos.mjs`), the skills/templates (`assets/`), and metadata — no source.
+  `bin` points at the bundle; `yaml` moved to devDependencies (it's inlined).
+- **Two install methods, one artifact:** `npm i -g @albsugy/aos`, or
+  `curl -fsSL https://cdn.jsdelivr.net/npm/@albsugy/aos/install.sh | bash` — the
+  installer ships inside the package and is served by the jsDelivr CDN.
+- **The curl installer resolves versions from the npm registry** and verifies the
+  registry's sha-512 integrity hash before unpacking. `AOS_VERSION` pins an npm
+  version; `AOS_NPM_REGISTRY` supports mirrors; direct-URL and from-source modes remain.
+- **`aos update`** on release installs checks the npm registry (was GitHub Releases).
+- **Release workflow** publishes to npm on `v*` tags when the `NPM_TOKEN` secret is set
+  (skips with a notice otherwise) and attaches the npm-pack tarball to the GitHub release.
+
+## 0.4.0 — 2026-07-04
+
+Standard package distribution: release artifacts instead of source clones.
+
+- **Installs no longer clone the repo.** The installer downloads `aos.tar.gz` from
+  GitHub Releases (runtime only: `dist/` + `assets/` + metadata, ~150 KB), verifies
+  its **SHA-256 checksum**, unpacks, and links. git is no longer required to install.
+- **Release workflow** builds and attaches `aos.tar.gz` + `aos.tar.gz.sha256` to every
+  `v*` release after re-running both smoke suites.
+- **`aos update`** on release installs checks the latest GitHub release and only
+  downloads when newer; dev checkouts keep the `git pull` path.
+- **`AOS_VERSION=vX.Y.Z`** pins installs to a release; `AOS_TARBALL_URL` supports
+  mirrors/testing; `AOS_FROM_SOURCE=1` clones and builds for contributors.
+- Installer refuses to overwrite a dev checkout at the install path, and `aos doctor`
+  now reports the install mode (release artifact vs dev checkout) and verifies layout.
+
+## 0.3.1 — 2026-07-04
+
+CI reliability + release infrastructure.
+
+- **Fixed flaky console-UI smoke check** — `curl | grep -q` under `pipefail` races
+  (grep exits on first match → curl gets EPIPE → pipeline fails despite a match);
+  surfaced on ubuntu CI. Console checks now capture responses and match without pipes.
+- **Dist-freshness gate hardened:** also fails on *untracked* files in `dist/`,
+  which `git diff` alone cannot see.
+- **Release workflow:** pushing a `v*` tag re-verifies both suites and creates a
+  GitHub Release with generated notes.
+- **npm publish readiness:** `files` allowlist, `publishConfig.access=public`,
+  `prepublishOnly` build.
+
+## 0.3.0 — 2026-07-04
+
+Compiled installs.
+
+- **Installs ship a compiled bundle, not source:** `dist/aos.mjs` — single file, all
+  dependencies inlined, minified, built by esbuild (`npm run build`) and committed;
+  the installer links it directly. No npm download at install time.
+- **Node ≥ 22 required** (was 18) — installer, `engines`, `aos doctor`, docs, and CI updated.
+- **CI:** smoke suite runs against both source and the compiled bundle on node 22/24;
+  a dist-freshness job fails if `dist/` wasn't rebuilt with source changes.
+- **`aos update`** in compiled installs no longer touches npm at all — the pull delivers the new bundle.
+- Source entry restructured: CLI moved to `src/cli.js`; `bin/aos.js` is a thin shim for dev/npm use.
+
+## 0.2.0 — 2026-07-04
+
+Production hardening.
+
+- **Reproducible installs:** committed `package-lock.json`; installer and `aos update` use `npm ci` when the lockfile is present.
+- **Pinned installs:** `AOS_REF=<tag|branch>` selects what the installer checks out (default `main`).
+- **Console security:** project/run ids validated against path traversal; requests with a non-localhost `Host` header are refused (DNS-rebinding protection); friendly error when the port is taken.
+- **Corruption resilience:** a corrupt `registry.yaml` degrades reads with a warning and blocks writes instead of clobbering; JSON state files are written atomically.
+- **`aos doctor`:** diagnoses node version, app install, dependencies, `AOS_HOME`, registry integrity, dangling repo paths, and the current repo's hook wiring (including old-format detection).
+- **Stable hook launcher** (from 0.1.x fixes): hooks call `$HOME/.local/bin/aos` with a PATH fallback instead of a pinned install path; `aos init` migrates old entries.
+- **`aos update`** skips reinstalling dependencies when already up to date.
+- **CI:** smoke suite (26 checks) on ubuntu/macos × node 18/20/22, plus shellcheck on the installer.
+
+## 0.1.0 — 2026-07-04
+
+Initial release: file spec (`~/.aos`), policy gates, run lifecycle, audit, Claude Code
+skills (`/aos-ticket`, `/aos-verify`, `/aos-learn`, `/aos-ask`) and hooks, verification
+contracts, local console, curl installer, landing page and manual.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Medhat Albsugy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# AOS — Agent Operations Stack
+
+Operate AI coding agents like a professional: **portable memory, enforced guardrails,
+automatic audit, real verification, and a local console** — all stored as plain files you own.
+
+AOS is not an orchestration framework and not a platform. It's three thin parts:
+
+1. **The Spec** — a file convention under `~/.aos/` (context packs, policies, playbooks,
+   run records, audit logs). Readable by any agent from any provider, forever.
+2. **The Skills + Hooks** — Claude Code integration: a ticket pipeline that runs work
+   through intake → plan → implement → verify → package → learn, with hooks that enforce
+   policy and write audit *automatically*.
+3. **The Console** — a local, read-only dashboard: decision queue, run states,
+   verification verdicts, token economics, leverage ratio.
+
+The design bet: frontier labs keep making agent *execution* better and cheaper; AOS owns
+what they never will — **your** context, **your** policies, **your** audit trail, portable
+across runtimes.
+
+**Site:** [albsugy.github.io/aos](https://albsugy.github.io/aos/) · **Manual:** [docs.html](https://albsugy.github.io/aos/docs.html)
+
+## Install
+
+```bash
+curl -fsSL https://cdn.jsdelivr.net/npm/@albsugy/aos/install.sh | bash
+```
+
+Or with npm directly:
+
+```bash
+npm i -g @albsugy/aos
+```
+
+Requires Node ≥ 22 (curl path also needs curl + tar). Both channels deliver the same
+artifact: the **compiled package published on the npm registry** — the single-file
+bundle (`dist/aos.mjs`, dependencies inlined) plus the skills/templates. The curl
+installer resolves the version from the registry, **verifies the registry's sha-512
+integrity hash**, unpacks to `~/.local/share/aos`, and links `~/.local/bin/aos`.
+No source code and no git history land on your machine (the source repository is
+private; the published package is the compiled bundle). Pin with `AOS_VERSION=0.5.0`;
+update later with `aos update`.
+
+## Quickstart
+
+```bash
+cd your-repo
+aos init                # registers the project, scaffolds ~/.aos/projects/<id>/,
+                        # installs skills into .claude/skills/ and hooks into .claude/settings.json
+
+# fill in the two files that matter:
+#   ~/.aos/projects/<id>/context/pack.md   — what every agent must know
+#   ~/.aos/projects/<id>/policy.yaml       — gates + verification contracts
+
+# then, inside a Claude Code session in that repo:
+/aos-ticket LIN-482     # runs the full pipeline; ends awaiting your review
+
+aos status              # all projects: runs, states, leverage ratio, tokens
+aos console             # http://127.0.0.1:4560
+```
+
+## What the hooks do (no skill invocation needed)
+
+| Hook | Effect |
+|---|---|
+| `SessionStart` | Injects the project's context pack, recent decisions, learnings, and open runs into every new session |
+| `PreToolUse` | Gates Bash commands against `policy.yaml`: forbidden → blocked, gated → requires your approval |
+| `PostToolUse` | Appends every action to the run's `audit.jsonl` |
+| `SessionEnd` | Records token usage per session and per run |
+
+## The Spec
+
+```
+~/.aos/
+├── registry.yaml                  # project id → repo paths
+└── projects/<id>/
+    ├── context/pack.md            # the brief every agent loads
+    ├── context/decisions.md       # append-only decision log
+    ├── policy.yaml                # tiers (forbidden/gated), plan_gate, verification contracts
+    ├── learnings.md               # compounding gotchas & fixes
+    ├── playbooks/                 # extracted repeatable procedures
+    └── runs/<date>-<ticket>/
+        ├── ticket.md  plan.md  verification.md  outcome.md
+        ├── audit.jsonl            # every action, gate decision, verdict
+        └── meta.json              # state, verification, attempts, tokens
+```
+
+## Skills
+
+- `/aos-ticket <ticket>` — full pipeline, ends `awaiting-review` with a PR draft in `outcome.md`
+- `/aos-verify` — contracts + adversarial skeptic subagent, anytime
+- `/aos-learn` — distill the session into project memory
+- `/aos-ask <question>` — answer from run history with file:line citations
+
+## CLI
+
+`aos init | status | context | run start/finish/state/list | verify | find | console | projects | doctor | version | update`
+
+## Principles
+
+- **Files over platforms** — everything is markdown/YAML/JSONL in your home dir. `git init ~/.aos` if you want history.
+- **Enforced beats remembered** — guardrails and audit live in hooks, not in prompts.
+- **Don't self-certify** — verification = deterministic contracts + an adversarial reviewer.
+- **Every layer works standalone** — hooks alone are worth installing; the pipeline is optional.
+- **Local-only** — the console binds 127.0.0.1; nothing leaves your machine.
+
+## Status & roadmap
+
+v0.5 — npm-registry distribution (compiled bundle only, private source), Node ≥ 22,
+production-hardened (26 smoke tests run against both source and bundle in CI, plus
+dist-freshness gate and shellcheck). Next, in pain-order:
+mobile approvals (Telegram) · MCP adapter for non-Claude runtimes · playbook extraction
+polish · multi-operator sync · client-facing trust console.
+
+MIT © Medhat Albsugy

package/assets/skills/aos-ask/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: aos-ask
+description: Answer questions from AOS project history — past runs, decisions, learnings, audit. Use for "why did we...", "when did we...", "what happened with..." questions.
+argument-hint: <question about past work>
+---
+
+# AOS ask
+
+Answer from project memory, citing files: $ARGUMENTS
+
+1. Run `aos find "<key terms>"` (try 2-3 different terms) to locate relevant entries across
+   runs, decisions, learnings, and audit logs.
+2. Read the matching files under `~/.aos/projects/<id>/` — especially `runs/*/outcome.md`
+   (decisions + rationale per run) and `context/decisions.md`.
+3. Answer concisely and cite sources as `<file>:<line>` so the user can verify. If history
+   doesn't contain the answer, say so plainly — do not reconstruct from guesswork.

package/assets/skills/aos-learn/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: aos-learn
+description: Extract learnings, decisions, and playbook candidates from the current session into AOS project memory. Use at the end of significant work, or when the user says "remember this".
+argument-hint: [optional focus, e.g. "the deploy fix"]
+---
+
+# AOS learn
+
+Distill this session into durable project memory. Focus: $ARGUMENTS (default: whole session).
+
+1. Find the project home: `aos context` prints the project; files live under
+   `~/.aos/projects/<project-id>/`.
+2. Append to `learnings.md`: bullets only for things that would change how the next agent
+   works — gotchas hit, commands that worked, constraints discovered. No narration.
+3. For significant choices made this session, append to `context/decisions.md`:
+   `## YYYY-MM-DD — title` / **Decision:** / **Why:** / **Run:** (if applicable).
+4. If `context/pack.md` is now wrong or missing something important (new convention, new
+   boundary), update it in place.
+5. If a procedure occurred that has now happened 2+ times across runs (check recent
+   `runs/*/outcome.md`), write it as a playbook in `playbooks/<slug>.md`: trigger,
+   steps, verification. Tell the user what you extracted.

package/assets/skills/aos-ticket/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: aos-ticket
+description: Run a ticket end-to-end through the AOS pipeline — intake, plan, implement, verify, package, learn. Use when starting work on a ticket, issue, or task in an AOS-enabled repo.
+argument-hint: <ticket id, URL, or pasted ticket content>
+---
+
+# AOS ticket pipeline
+
+Work the ticket in `$ARGUMENTS` through all six AOS stages. Do not skip stages. All run
+files live in the run folder printed by `aos run start`.
+
+## 1. Intake
+
+1. Run: `aos run start --ticket "<short id>" --title "<short title>"`. Note the run folder
+   and `plan_gate` value it prints.
+2. Fill `ticket.md` in the run folder: the original ticket content (fetch it if `$ARGUMENTS`
+   is an id/URL), then an explicit **Acceptance criteria** checklist. If the criteria are
+   ambiguous, ask the user before writing code.
+
+## 2. Plan
+
+3. Write `plan.md`: approach, files you expect to touch, risks, test strategy. Keep it short.
+4. If `plan_gate` is `ask`: present the plan to the user and wait for approval before proceeding.
+
+## 3. Implement
+
+5. Create a branch named after the ticket. Implement per the plan. The AOS hooks audit your
+   actions and gate risky commands automatically — if a gate asks for approval, that is
+   expected behavior, not an error.
+
+## 4. Verify — do not self-certify
+
+6. Run `aos verify`. Fix failures and re-run until required contracts pass.
+7. Adversarial review (required unless policy sets `adversarial_review: false`): spawn a
+   subagent (Task tool) with this framing: "You are a skeptical reviewer. Try to REFUTE this
+   work against the acceptance criteria in <run>/ticket.md. Hunt for: criteria not actually
+   met, edge cases, silent failures, tests that don't test the change. Report findings with
+   file:line. Finding nothing is an acceptable answer only after a genuine hunt."
+   Append its findings and your dispositions to `verification.md`.
+8. Fix anything confirmed. Re-verify. Loop until clean or genuinely blocked
+   (if blocked: `aos run state blocked`, tell the user why, and stop).
+
+## 5. Package
+
+9. Write `outcome.md` in the run folder:
+   - **Summary** — what changed and why, 3 sentences max
+   - **Changes** — files touched, grouped by purpose
+   - **Decisions** — anything a reviewer would ask "why?" about
+   - **Risks & follow-ups**
+   - **How to test** — exact commands/steps
+   - **PR draft** — title + body ready to paste
+10. Run: `aos run finish` (state becomes `awaiting-review`). Tell the user the run is ready
+    for their review, with the run folder path and the PR draft.
+
+## 6. Learn
+
+11. Append to the project's `learnings.md` (path: `aos context` shows the project; files live
+    under `~/.aos/projects/<id>/`): 1-3 bullets of anything that would help the next agent.
+    Append significant choices to `context/decisions.md` in the decision format.
+12. If this run repeated a pattern you've seen in previous runs (check `playbooks/` and
+    recent runs), propose a playbook file in `playbooks/` and mention it to the user.

package/assets/skills/aos-verify/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: aos-verify
+description: Verify the current work against AOS policy contracts plus an adversarial review. Use standalone anytime, or as stage 4 of /aos-ticket.
+argument-hint: [what to verify — defaults to current uncommitted/branch work]
+---
+
+# AOS verification
+
+Verify $ARGUMENTS (default: the current branch's work) without self-certifying.
+
+1. Run `aos verify` — this executes the deterministic contracts from `policy.yaml` and
+   records results (into the active run's `verification.md` when a run is active).
+2. Fix any required-contract failures and re-run until they pass.
+3. Unless policy sets `adversarial_review: false`, spawn a skeptic subagent (Task tool):
+   "Try to REFUTE this work. Assume it is subtly wrong. Check: does it actually do what was
+   asked, edge cases, error paths, tests that assert nothing, unintended side effects in
+   touched files. Report file:line findings." 
+4. Triage its findings honestly — fix confirmed issues, note rejected ones with reasons.
+   If a run is active, append findings + dispositions to its `verification.md`.
+5. Report to the user: contract verdict, adversarial findings summary, and your confidence.

package/assets/templates/decisions.md

@@ -0,0 +1,10 @@
+# Decisions
+
+<!-- Append-only. One entry per decision. The last ~40 lines load into every session. -->
+
+<!-- Format:
+## YYYY-MM-DD — short title
+**Decision:** what was chosen
+**Why:** the reason that will matter in six months
+**Run:** run id (if applicable)
+-->

package/assets/templates/learnings.md

@@ -0,0 +1,4 @@
+# Learnings
+
+<!-- Append-only. Short bullets an agent can act on. The last ~30 lines load into every session. -->
+<!-- Example: - The auth tests fail if run in parallel; use `npm test -- --runInBand`. -->

package/assets/templates/pack.md

@@ -0,0 +1,25 @@
+# Context pack
+
+<!-- Everything an agent must know before touching this project.
+     Loaded automatically at every session start. Keep it dense and current. -->
+
+## What this project is
+
+(one paragraph: purpose, stage, who uses it)
+
+## Architecture & stack
+
+- (runtime, framework, database, deploy target)
+
+## Conventions
+
+- (naming, structure, commit style — only what differs from defaults)
+
+## Boundaries — never do
+
+- (e.g. never touch the billing module without a feature flag)
+- (e.g. never run migrations outside CI)
+
+## Gotchas
+
+- (the things that bite: flaky tests, env quirks, slow builds)

package/assets/templates/policy.yaml

@@ -0,0 +1,35 @@
+# AOS project policy — gates, tiers, and verification contracts.
+# Patterns are JavaScript regexes matched (case-insensitive) against Bash commands.
+version: 1
+
+# auto: agent proceeds after writing plan.md | ask: agent must get human approval of the plan
+plan_gate: auto
+
+tiers:
+  forbidden:
+    - pattern: 'push\s+[^|;&]*(--force|-f)\b'
+      reason: Force-push is forbidden by policy
+    - pattern: 'rm\s+-rf\s+(/|~)(\s|$)'
+      reason: Recursive delete of root/home is forbidden by policy
+  gated:
+    - pattern: '\bgit\s+push\b'
+      action: git-push
+    - pattern: '\bgh\s+pr\s+merge\b'
+      action: merge
+    - pattern: '\bdeploy\b'
+      action: deploy
+  # Everything not matched above is auto-approved (normal Claude Code permissions still apply).
+
+verification:
+  # When true, /aos-verify and /aos-ticket must spawn a skeptic subagent to refute the work.
+  adversarial_review: true
+  contracts:
+    # Deterministic checks that must pass before a run can reach awaiting-review.
+    # Examples:
+    # - name: tests
+    #   command: npm test
+    #   required: true
+    # - name: lint
+    #   command: npm run lint
+    #   required: false
+    []